1page.title=Touch Mode 2@jd:body 3 4<p>This article explains the <em>touch mode</em>, one of the most 5important principles of Android's UI toolkit.</p> 6 7<p>The touch mode is a state of the view hierarchy that depends solely on the 8user interaction with the phone. By itself, the touch mode is something very 9easy to understand as it simply indicates whether the last user interaction was 10performed with the touch screen. For example, if you are using an 11Android-powered device, selecting a widget with the trackball will take you out 12of touch mode; however, if you touch a button on the screen with your finger, 13you will enter touch mode. When the user is not in touch mode, we talk about the 14trackball mode, navigation mode or keyboard navigation, so do not be surprised 15if you encounter these terms. </p> 16 17<p>There is only one API directly related to touch mode, 18{@link android.view.View#isInTouchMode() View.isInTouchMode()}.</p> 19 20<p>Sounds easy enough, right? Oddly enough, touch mode is deceivingly simple and 21the consequences of entering touch mode are far greater than you might 22think. Let's look at some of the reasons why.</p> 23 24<h4>Touch Mode, Selection, and Focus</h4> 25 26<p>Designing a UI toolkit for mobile devices is difficult because of the various 27interaction mechanisms they provide. Some devices offer only 12 keys, some have 28a touch screen, some require a stylus, some have both a touch screen and a 29keyboard. Based on the hardware capabilities of the he user can interact with 30your application using different mechanisms, so we had to think very hard about 31all the possible issues that could arise. One issue led us to create the touch 32mode.</p> 33 34<p>Imagine a simple application, <a href="{@docRoot}resources/samples/index.html">ApiDemos</a> 35for example, that shows a list of text items. The user can freely 36navigate through the list using the trackball but also, alternatively, scroll 37and fling the list using the touch screen. The issue in this scenario is 38how to handle the selection properly when the user manipulates the list 39through the touch screen. </p> 40 41<p>In this case, if the user selects an item at the top of the list and then 42flings the list towards the bottom, what should happen to the selection? Should 43it remain on the item and scroll off the screen? What should happen if the user 44then decided to move the selection with the trackball? Or worse, what should 45happen if the user presses the trackball to act upon the currently selected 46item, which is not shown on screen anymore? </p> 47 48<p>After careful consideration, we decided to remove the selection altogether, 49when the user manipulates the UI through the touch screen.</p> 50 51<p>In touch mode, there is no focus and no selection. Any selected item in a 52list of in a grid becomes unselected as soon as the user enters touch 53mode. Similarly, any focused widgets become unfocused when the user 54enters touch mode. The image below illustrates what happens when the 55user touches a list after selecting an item with the trackball.</p> 56 57<img style="margin: 0px 7px;" src="images/list02.png" alt="" id="BLOGGER_PHOTO_ID_5272753165743060962" border="0"> 58<img style="margin: 0px 7px;" src="images/list01.png" alt="" id="BLOGGER_PHOTO_ID_5272753357441963442" border="0"> 59 60<p>To 61make things more natural for the user, the framework knows how to 62resurrect the selection/focus whenever the user leaves touch mode. For 63instance, in the example above, if the user were to use the trackball 64again, the selection would reappear on the previously-selected item. 65This is why some developers are confused when they create a custom view 66and start receiving key events only after moving the trackball once: 67their application is in touch mode, and they need to use the trackball 68to exit touch mode and resurrect the focus.</p> 69 70<p>The relationship between touch mode, selection, and focus means you must not 71rely on selection and/or focus to exist in your application. A very common 72problem with new Android developers is to rely on 73{@link android.widget.AdapterView#getSelectedItemPosition() ListView.getSelectedItemPosition()}. 74In touch mode, this method will return 75{@link android.widget.AdapterView#INVALID_POSITION INVALID_POSITION}. 76 You should instead use click listeners (see 77{@link android.widget.AdapterView#setOnItemClickListener(android.widget.AdapterView.OnItemClickListener)}) 78or the choice mode (see 79{@link android.widget.ListView#setChoiceMode(int)}).</p> 80 81<h4>Focusable in Touch Mode</h4> 82 83<p>In general, focus doesn't exist in touch mode. However, focus can exist in 84touch mode in a very special way called <em>focusable</em>. This special mode 85was created for widgets that receive text input, such as 86{@link android.widget.EditText} or, when filtering is enabled, 87{@link android.widget.ListView}. The focusable mode is what lets the user enter text 88inside a text field on the screen, without first selecting it with the trackball 89or their finger.</p> 90 91<p>When a user 92touches the screen, the application will enter touch mode if it wasn't 93in touch mode already. What happens during the transition to 94touch mode depends on what the user touched, and what currently has 95focus. If the user touches a widget that is focusable in touch 96mode, that widget will receive focus. Otherwise, any currently 97focused widget will not retain focus unless it is focusable in touch 98mode. For instance, in the picture below, when the user touches 99the screen, the input text field receives the focus.</p> 100 101<img style="margin: 0px 7px;" src="images/text_field.png" alt="" id="BLOGGER_PHOTO_ID_5272755475757779154" border="0"> 102 103<p>Fousable in touch mode (see 104{@link android.view.View#setFocusableInTouchMode(boolean) View.setFocusableInTouchMode}) 105 is a property that you can set yourself, either from code or from XML. 106However, you should use it sparingly and only in very specific situations, 107because it breaks consistency with the normal behavior of the Android UI. A game 108is a good example of an application that could make good use of the focusable in 109touch mode property. MapView, if used in fullscreen as in Google Maps, is 110another good example of where you can use focusable in touch mode correctly.</p> 111 112<p>Below is another example of a focusable in touch mode widget. When the user 113taps an <code>AutoCompleteTextView</code> suggestion with his finger, the focus 114remains on the input text field:</p> 115 116<img style="margin: 0px 7px;" src="images/search01.png" alt="" id="BLOGGER_PHOTO_ID_5272756689821626962" border="0"> 117<img style="margin: 0px 7px;" src="images/search02.png" alt="" id="BLOGGER_PHOTO_ID_5272756246104676754" border="0"> 118 119<p>Developers new to Android often think that focusable in touch mode is the 120solution they need to "fix" the problem of "disappearing" selection/focus. We 121really encourage you to think very hard before using it. If used incorrectly, it 122can make your application behave differently from the rest of the system and 123simply throw off the user's habits. The Android framework contains all the tools 124you need to handle user interactions without using focusable in touch mode. For 125example, instead of trying to make <code>ListView</code> always keep its 126selection, simply use the appropriate choice mode, as shown in 127{@link android.widget.ListView#setChoiceMode(int)}. 128 129<h4>Touch Mode Cheat Sheet</h4> 130 131<p>Do:</p> 132<ul> 133<li>Remain consistent with the core applications</li><li>Use the appropriate feature if you need persistent selection (radio button, check box, the <code>ListView</code> choice mode, etc.)</li> 134<li>Use focusable in touch mode if you write a game</li> 135</ul> 136 137<p>Don't:</p> 138<ul><li>Do not try to keep the focus or selection in touch mode</li></ul> 139
