1b10b48f62d3cac684424e4181d4e8ec61f227e95Scott Mainpage.title=Input Events 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectparent.title=User Interface 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectparent.link=index.html 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project@jd:body 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<div id="qv-wrapper"> 79066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<div id="qv"> 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <h2>In this document</h2> 99066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <ol> 109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><a href="#EventListeners">Event Listeners</a></li> 119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><a href="#EventHandlers">Event Handlers</a></li> 129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><a href="#TouchMode">Touch Mode</a></li> 139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><a href="#HandlingFocus">Handling Focus</a></li> 149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project </ol> 159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</div> 179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</div> 189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>On Android, there's more than one way to intercept the events from a user's interaction with your application. 209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectWhen considering events within your user interface, the approach is to capture the events from 219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectthe specific View object that the user interacts with. The View class provides the means to do so.</p> 229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>Within the various View classes that you'll use to compose your layout, you may notice several public callback 249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectmethods that look useful for UI events. These methods are called by the Android framework when the 259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectrespective action occurs on that object. For instance, when a View (such as a Button) is touched, 269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectthe <code>onTouchEvent()</code> method is called on that object. However, in order to intercept this, you must extend 27f90178d08d3a6cdb500a6f4d1069c38036b3db69Scott Mainthe class and override the method. However, extending every View object 28f90178d08d3a6cdb500a6f4d1069c38036b3db69Scott Mainin order to handle such an event would not be practical. This is why the View class also contains 299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projecta collection of nested interfaces with callbacks that you can much more easily define. These interfaces, 309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectcalled <a href="#EventListeners">event listeners</a>, are your ticket to capturing the user interaction with your UI.</p> 319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>While you will more commonly use the event listeners to listen for user interaction, there may 339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectcome a time when you do want to extend a View class, in order to build a custom component. 349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectPerhaps you want to extend the {@link android.widget.Button} 359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectclass to make something more fancy. In this case, you'll be able to define the default event behaviors for your 369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectclass using the class <a href="#EventHandlers">event handlers</a>.</p> 379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<h2 id="EventListeners">Event Listeners</h2> 409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>An event listener is an interface in the {@link android.view.View} class that contains a single 429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectcallback method. These methods will be called by the Android framework when the View to which the listener has 439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectbeen registered is triggered by user interaction with the item in the UI.</p> 449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>Included in the event listener interfaces are the following callback methods:</p> 469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<dl> 489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dt><code>onClick()</code></dt> 499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dd>From {@link android.view.View.OnClickListener}. 509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This is called when the user either touches the item 519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project (when in touch mode), or focuses upon the item with the navigation-keys or trackball and 529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project presses the suitable "enter" key or presses down on the trackball.</dd> 539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dt><code>onLongClick()</code></dt> 549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dd>From {@link android.view.View.OnLongClickListener}. 559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This is called when the user either touches and holds the item (when in touch mode), or 569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project focuses upon the item with the navigation-keys or trackball and 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project presses and holds the suitable "enter" key or presses and holds down on the trackball (for one second).</dd> 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dt><code>onFocusChange()</code></dt> 599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dd>From {@link android.view.View.OnFocusChangeListener}. 609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This is called when the user navigates onto or away from the item, using the navigation-keys or trackball.</dd> 619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dt><code>onKey()</code></dt> 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dd>From {@link android.view.View.OnKeyListener}. 63405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalard This is called when the user is focused on the item and presses or releases a hardware key on the device.</dd> 649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dt><code>onTouch()</code></dt> 659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dd>From {@link android.view.View.OnTouchListener}. 669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This is called when the user performs an action qualified as a touch event, including a press, a release, 679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project or any movement gesture on the screen (within the bounds of the item).</dd> 689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dt><code>onCreateContextMenu()</code></dt> 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <dd>From {@link android.view.View.OnCreateContextMenuListener}. 709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This is called when a Context Menu is being built (as the result of a sustained "long click"). See the discussion 71b10b48f62d3cac684424e4181d4e8ec61f227e95Scott Main on context menus in the <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a> 72b10b48f62d3cac684424e4181d4e8ec61f227e95Scott Main developer guide.</dd> 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</dl> 749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>These methods are the sole inhabitants of their respective interface. To define one of these methods 769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectand handle your events, implement the nested interface in your Activity or define it as an anonymous class. 779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectThen, pass an instance of your implementation 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectto the respective <code>View.set...Listener()</code> method. (E.g., call 799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code> 809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectand pass it your implementation of the {@link android.view.View.OnClickListener OnClickListener}.)</p> 819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>The example below shows how to register an on-click listener for a Button. </p> 839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project// Create an anonymous implementation of OnClickListener 869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectprivate OnClickListener mCorkyListener = new OnClickListener() { 879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onClick(View v) { 889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // do something when the button is clicked 899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project}; 919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectprotected void onCreate(Bundle savedValues) { 939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... 949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // Capture our button from layout 959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Button button = (Button)findViewById(R.id.corky); 969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // Register the onClick listener with the implementation above 979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project button.setOnClickListener(mCorkyListener); 989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... 999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 1009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 1019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1027f877069274c94b373478a8d0c969c9cfd93864fElliott Hughes<p>You may also find it more convenient to implement OnClickListener as a part of your Activity. 1039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectThis will avoid the extra class load and object allocation. For example:</p> 1049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 1059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic class ExampleActivity extends Activity implements OnClickListener { 1069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project protected void onCreate(Bundle savedValues) { 1079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... 1089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Button button = (Button)findViewById(R.id.corky); 1099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project button.setOnClickListener(this); 1109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // Implement the OnClickListener callback 1139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void onClick(View v) { 1149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // do something when the button is clicked 1159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... 1179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 1189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 1199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>Notice that the <code>onClick()</code> callback in the above example has 1219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectno return value, but some other event listener methods must return a boolean. The reason 1229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectdepends on the event. For the few that do, here's why:</p> 1239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<ul> 1249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View.OnLongClickListener#onLongClick(View) onLongClick()}</code> - 1259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This returns a boolean to indicate whether you have consumed the event and it should not be carried further. 1269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project That is, return <em>true</em> to indicate that you have handled the event and it should stop here; 1279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return <em>false</em> if you have not handled it and/or the event should continue to any other 1289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project on-click listeners.</li> 1299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View.OnKeyListener#onKey(View,int,KeyEvent) onKey()}</code> - 1309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This returns a boolean to indicate whether you have consumed the event and it should not be carried further. 1319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project That is, return <em>true</em> to indicate that you have handled the event and it should stop here; 1329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return <em>false</em> if you have not handled it and/or the event should continue to any other 1339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project on-key listeners.</li> 1349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View.OnTouchListener#onTouch(View,MotionEvent) onTouch()}</code> - 1359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project This returns a boolean to indicate whether your listener consumes this event. The important thing is that 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project this event can have multiple actions that follow each other. So, if you return <em>false</em> when the 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project down action event is received, you indicate that you have not consumed the event and are also 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project not interested in subsequent actions from this event. Thus, you will not be called for any other actions 1397f877069274c94b373478a8d0c969c9cfd93864fElliott Hughes within the event, such as a finger gesture, or the eventual up action event.</li> 1409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</ul> 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 142405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalard<p>Remember that hardware key events are always delivered to the View currently in focus. They are dispatched starting from the top 1439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectof the View hierarchy, and then down, until they reach the appropriate destination. If your View (or a child of your View) 1449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectcurrently has focus, then you can see the event travel through the <code>{@link android.view.View#dispatchKeyEvent(KeyEvent) 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectdispatchKeyEvent()}</code> method. As an alternative to capturing key events through your View, you can also receive 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectall of the events inside your Activity with <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code> 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectand <code>{@link android.app.Activity#onKeyUp(int,KeyEvent) onKeyUp()}</code>.</p> 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 149405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalard<p>Also, when thinking about text input for your application, remember that many devices only have software input 150405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalardmethods. Such methods are not required to be key-based; some may use voice input, handwriting, and so on. Even if 151405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalardan input method presents a keyboard-like interface, it will generally <strong>not</strong> trigger the 152405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalard<code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code> family of events. You should never 153405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalardbuild a UI that requires specific key presses to be controlled unless you want to limit your application to devices 154405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalardwith a hardware keyboard. In particular, do not rely on these methods to validate input when the user presses the 155405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalardreturn key; instead, use actions like {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} to signal the 156405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalardinput method how your application expects to react, so it may change its UI in a meaningful way. Avoid assumptions 157405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalardabout how a software input method should work and just trust it to supply already formatted text to your application.</p> 158405bc51c5dc73846a4abdc325cd234eb2d37469fJean Chalard 1599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p class="note"><strong>Note:</strong> Android will call event handlers first and then the appropriate default 1609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projecthandlers from the class definition second. As such, returning <em>true</em> from these event listeners will stop 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectthe propagation of the event to other event listeners and will also block the callback to the 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectdefault event handler in the View. So be certain that you want to terminate the event when you return <em>true</em>.</p> 1639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<h2 id="EventHandlers">Event Handlers</h2> 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>If you're building a custom component from View, then you'll be able to define several callback methods 1689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectused as default event handlers. 169b10b48f62d3cac684424e4181d4e8ec61f227e95Scott MainIn the document about <a href="{@docRoot}guide/topics/ui/custom-components.html">Custom 170b10b48f62d3cac684424e4181d4e8ec61f227e95Scott MainComponents</a>, you'll learn see some of the common callbacks used for event handling, 171b10b48f62d3cac684424e4181d4e8ec61f227e95Scott Mainincluding:</p> 1729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<ul> 1739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View#onKeyDown}</code> - Called when a new key event occurs.</li> 1749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View#onKeyUp}</code> - Called when a key up event occurs.</li> 1759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View#onTrackballEvent}</code> - Called when a trackball motion event occurs.</li> 1769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View#onTouchEvent}</code> - Called when a touch screen motion event occurs.</li> 1779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.View#onFocusChanged}</code> - Called when the view gains or loses focus.</li> 1789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</ul> 1797f877069274c94b373478a8d0c969c9cfd93864fElliott Hughes<p>There are some other methods that you should be aware of, which are not part of the View class, 1809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectbut can directly impact the way you're able to handle events. So, when managing more complex events inside 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projecta layout, consider these other methods:</p> 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<ul> 1839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.app.Activity#dispatchTouchEvent(MotionEvent) 1849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project Activity.dispatchTouchEvent(MotionEvent)}</code> - This allows your {@link 1859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project android.app.Activity} to intercept all touch events before they are dispatched to the window.</li> 1869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.ViewGroup#onInterceptTouchEvent(MotionEvent) 1879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ViewGroup.onInterceptTouchEvent(MotionEvent)}</code> - This allows a {@link 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project android.view.ViewGroup} to watch events as they are dispatched to child Views.</li> 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li><code>{@link android.view.ViewParent#requestDisallowInterceptTouchEvent(boolean) 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ViewParent.requestDisallowInterceptTouchEvent(boolean)}</code> - Call this 1919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project upon a parent View to indicate that it should not intercept touch events with <code>{@link 1929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project android.view.ViewGroup#onInterceptTouchEvent(MotionEvent)}</code>.</li> 1939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</ul> 1949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<h2 id="TouchMode">Touch Mode</h2> 1969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p> 1979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectWhen a user is navigating a user interface with directional keys or a trackball, it is 1989066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectnecessary to give focus to actionable items (like buttons) so the user can see 1999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectwhat will accept input. If the device has touch capabilities, however, and the user 2009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectbegins interacting with the interface by touching it, then it is no longer necessary to 2019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projecthighlight items, or give focus to a particular View. Thus, there is a mode 2029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectfor interaction named "touch mode." 2039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</p> 2049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p> 2059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectFor a touch-capable device, once the user touches the screen, the device 2069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectwill enter touch mode. From this point onward, only Views for which 2079066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project{@link android.view.View#isFocusableInTouchMode} is true will be focusable, such as text editing widgets. 2089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectOther Views that are touchable, like buttons, will not take focus when touched; they will 2099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectsimply fire their on-click listeners when pressed. 2109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</p> 2119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p> 2129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectAny time a user hits a directional key or scrolls with a trackball, the device will 2139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectexit touch mode, and find a view to take focus. Now, the user may resume interacting 2149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectwith the user interface without touching the screen. 2159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</p> 2169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p> 2179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectThe touch mode state is maintained throughout the entire system (all windows and activities). 2189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectTo query the current state, you can call 2199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project{@link android.view.View#isInTouchMode} to see whether the device is currently in touch mode. 2209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</p> 2219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<h2 id="HandlingFocus">Handling Focus</h2> 2249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2259066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>The framework will handle routine focus movement in response to user input. 2269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectThis includes changing the focus as Views are removed or hidden, or as new 2279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectViews become available. Views indicate their willingness to take focus 2289066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectthrough the <code>{@link android.view.View#isFocusable()}</code> method. To change whether a View can take 2299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectfocus, call <code>{@link android.view.View#setFocusable(boolean) setFocusable()}</code>. When in touch mode, 2309066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectyou may query whether a View allows focus with <code>{@link android.view.View#isFocusableInTouchMode()}</code>. 2319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectYou can change this with <code>{@link android.view.View#setFocusableInTouchMode(boolean) setFocusableInTouchMode()}</code>. 2329066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</p> 2339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>Focus movement is based on an algorithm which finds the nearest neighbor in a 2359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectgiven direction. In rare cases, the default algorithm may not match the 2369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectintended behavior of the developer. In these situations, you can provide 2379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectexplicit overrides with the following XML attributes in the layout file: 2389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<var>nextFocusDown</var>, <var>nextFocusLeft</var>, <var>nextFocusRight</var>, and 2399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<var>nextFocusUp</var>. Add one of these attributes to the View <em>from</em> which 2409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectthe focus is leaving. Define the value of the attribute to be the id of the View 2419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<em>to</em> which focus should be given. For example:</p> 2429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 2439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<LinearLayout 2449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project android:orientation="vertical" 2459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... > 2469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <Button android:id="@+id/top" 2479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project android:nextFocusUp="@+id/bottom" 2489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... /> 2499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <Button android:id="@+id/bottom" 2509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project android:nextFocusDown="@+id/top" 2519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... /> 2529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</LinearLayout> 2539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 2549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>Ordinarily, in this vertical layout, navigating up from the first Button would not go 2569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectanywhere, nor would navigating down from the second Button. Now that the top Button has 2579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectdefined the bottom one as the <var>nextFocusUp</var> (and vice versa), the navigation focus will 2589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectcycle from top-to-bottom and bottom-to-top.</p> 2599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>If you'd like to declare a View as focusable in your UI (when it is traditionally not), 2619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectadd the <code>android:focusable</code> XML attribute to the View, in your layout declaration. 2629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source ProjectSet the value <var>true</var>. You can also declare a View 2639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectas focusable while in Touch Mode with <code>android:focusableInTouchMode</code>.</p> 2649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>To request a particular View to take focus, call <code>{@link android.view.View#requestFocus()}</code>.</p> 2659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>To listen for focus events (be notified when a View receives or looses focus), use 2669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<code>{@link android.view.View.OnFocusChangeListener#onFocusChange(View,boolean) onFocusChange()}</code>, 2679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectas discussed in the <a href="#EventListeners">Event Listeners</a> section, above.</p> 2689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<!-- 2729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<h2 is="EventCycle">Event Cycle</h2> 2739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <p>The basic cycle of a View is as follows:</p> 2749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <ol> 2759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li>An event comes in and is dispatched to the appropriate View. The View 2769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project handles the event and notifies any listeners.</li> 2779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li>If, in the course of processing the event, the View's bounds may need 2789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project to be changed, the View will call {@link android.view.View#requestLayout()}.</li> 2799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li>Similarly, if in the course of processing the event the View's appearance 2809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project may need to be changed, the View will call {@link android.view.View#invalidate()}.</li> 2819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <li>If either {@link android.view.View#requestLayout()} or {@link android.view.View#invalidate()} were called, 2829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project the framework will take care of measuring, laying out, and drawing the tree 2839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project as appropriate.</li> 2849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project </ol> 2859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <p class="note"><strong>Note:</strong> The entire View tree is single threaded. You must always be on 2879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project the UI thread when calling any method on any View. 2889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project If you are doing work on other threads and want to update the state of a View 2899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project from that thread, you should use a {@link android.os.Handler}. 2909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project </p> 2919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project--> 292