Handling UI Events

On Android, there's more than one way to intercept the events from a user's interaction with your application. When considering events within your user interface, the approach is to capture the events from the specific View object that the user interacts with. The View class provides the means to do so.

Within the various View classes that you'll use to compose your layout, you may notice several public callback methods that look useful for UI events. These methods are called by the Android framework when the respective action occurs on that object. For instance, when a View (such as a Button) is touched, the onTouchEvent() method is called on that object. However, in order to intercept this, you must extend the class and override the method. However, extending every View object in order to handle such an event would not be practical. This is why the View class also contains a collection of nested interfaces with callbacks that you can much more easily define. These interfaces, called event listeners, are your ticket to capturing the user interaction with your UI.

While you will more commonly use the event listeners to listen for user interaction, there may come a time when you do want to extend a View class, in order to build a custom component. Perhaps you want to extend the Button class to make something more fancy. In this case, you'll be able to define the default event behaviors for your class using the class event handlers.

Event Listeners

An event listener is an interface in the View class that contains a single callback method. These methods will be called by the Android framework when the View to which the listener has been registered is triggered by user interaction with the item in the UI.

Included in the event listener interfaces are the following callback methods:

onClick()

From View.OnClickListener. This is called when the user either touches the item (when in touch mode), or focuses upon the item with the navigation-keys or trackball and presses the suitable "enter" key or presses down on the trackball.

onLongClick()

From View.OnLongClickListener. This is called when the user either touches and holds the item (when in touch mode), or focuses upon the item with the navigation-keys or trackball and presses and holds the suitable "enter" key or presses and holds down on the trackball (for one second).

onFocusChange()

From View.OnFocusChangeListener. This is called when the user navigates onto or away from the item, using the navigation-keys or trackball.

onKey()

From View.OnKeyListener. This is called when the user is focused on the item and presses or releases a key on the device.

onTouch()

From View.OnTouchListener. This is called when the user performs an action qualified as a touch event, including a press, a release, or any movement gesture on the screen (within the bounds of the item).

onCreateContextMenu()

From View.OnCreateContextMenuListener. This is called when a Context Menu is being built (as the result of a sustained "long click"). See the discussion on context menus in Creating Menus for more information.

onClick()

View.OnClickListener로부터 콜백됨. 이것은 터치모드일 때 사용자가 아이템을 터치하거나 또는 네비게이션 키나 트랙볼trackball로 그 아이템을 포커스하여 “enter” 키를 누르거나 트랙볼을 눌렀을 때 호출된다.

onLongClick()

View.OnFocusChangeListener로부터 콜백됨. 이것은 터치모드일 때 사용자가 아이템을 터치해서 잡거나 또는 네비게이션-키나 트랙볼trackball로 해당 아이템을 포커스하여 적당한 “enter” 키를 누르고 있거나 또는 1초동안 트랙볼을 누르고 있을 때 호출된다.

onFocusChange()

View.OnFocusChangeListener로부터 콜백됨. 이것은 사용자가 네비게이션-키 또는 트랙볼trackball을 사용하여 아이템 위로 움직이거나, 또는 그것으로부터 벗어날 때 호출된다.

onKey()

View.OnKeyListener로부터 콜백됨. 이것은 사용자가 아이템을 포커스를 하여, 디바이스에 있는 키를 누르거나 놓았을 때 호출된다.

onTouch()

View.OnTouchListener로부터 콜백됨. 이것은 사용자가 아이템의 경계내에서 스크린을 누르고, 놓고, 또는 어떤 움직임 행위를 포함하는 터치 이벤트로써 적격한 액션을 수행할 때 호출된다.

onCreateContextMenu()

View.OnCreateContextMenuListener로부터 콜백됨. 이것은 일관된 “오랜시간 클릭long click”의 결과로, 컨텍스트 메뉴가 만들어져 있을 때 호출된다. 컨텍스트 메뉴에 대한 더 많은 정보에 대해서는 “메뉴 생성하기”를 보라.

These methods are the sole inhabitants of their respective interface. To define one of these methods and handle your events, implement the nested interface in your Activity or define it as an anonymous class. Then, pass an instance of your implementation to the respective View.set...Listener() method. (E.g., call setOnClickListener() and pass it your implementation of the OnClickListener.)

The example below shows how to register an on-click listener for a Button.

// Create an anonymous implementation of OnClickListener
private OnClickListener mCorkyListener = new OnClickListener() {
    public void onClick(View v) {
      // do something when the button is clicked
    }
};

protected void onCreate(Bundle savedValues) {
    ...
    // Capture our button from layout
    Button button = (Button)findViewById(R.id.corky);
    // Register the onClick listener with the implementation above
    button.setOnClickListener(mCorkyListener);
    ...
}

You may also find it more convenient to implement OnClickListener as a part of your Activity. This will avoid the extra class load and object allocation. For example:

public class ExampleActivity extends Activity implements OnClickListener {
    protected void onCreate(Bundle savedValues) {
        ...
        Button button = (Button)findViewById(R.id.corky);
        button.setOnClickListener(this);
    }

    // Implement the OnClickListener callback
    public void onClick(View v) {
      // do something when the button is clicked
    }
    ...
}

Notice that the onClick() callback in the above example has no return value, but some other event listener methods must return a boolean. The reason depends on the event. For the few that do, here's why:

• onLongClick() - This returns a boolean to indicate whether you have consumed the event and it should not be carried further. That is, return true to indicate that you have handled the event and it should stop here; return false if you have not handled it and/or the event should continue to any other on-click listeners.
• onKey() - This returns a boolean to indicate whether you have consumed the event and it should not be carried further. That is, return true to indicate that you have handled the event and it should stop here; return false if you have not handled it and/or the event should continue to any other on-key listeners.
• onTouch() - This returns a boolean to indicate whether your listener consumes this event. The important thing is that this event can have multiple actions that follow each other. So, if you return false when the down action event is received, you indicate that you have not consumed the event and are also not interested in subsequent actions from this event. Thus, you will not be called for any other actions within the event, such as a fingure gesture, or the eventual up action event.

onLongClick() - 이것은 여러분이 그 이벤트를 소비해서 그것이 더 이상 전달되어서는 안되는지 여부를 가리키는 불리언Boolean 값을 리턴한다. 그것은 여러분이 그 이벤트를 처리해서 그것이 여기에서 멈춰야 한다는 것을 가리키기 위해서는 참true을 리턴한다. 만약 여러분이 그것을 처리하지 않았다면, 그리고/또는 그 이벤트가 어떤 다른 on-click 리스너에게 계속되어야 한다면 거짓false을 리턴한다.
onKey() - 이것은 여러분이 그 이벤트를 소비해서 그것이 더 이상 전달되어서는 안되는지 여부를 가리키는 불리언Boolean 값을 리턴한다. 그것은 여러분이 해당 이벤트를 처리해서 그것이 여기에서 멈춰야한다는 것을 가리키기 위해서는 참true를 리턴한다. 만약 여러분이 그것을 처리하지 않았다면, 그리고/또는 그 이벤트가 어떤 다른 on-key 리스너에게 계속되어야 한다면 거짓false를 리턴한다.
onTouch() - 이것은 여러분이 그 이벤트를 사용했는지 여부를 가리키는 불리언Boolean 값을 리턴한다. 중요한 것은, 이 이벤트는 각기 다른 것을 수반하는 복수의 액션을 가질 수 있다는 것이다. 그러므로 여러분이 다운down 액션 이벤트가 수신될 때 거짓false을 리턴하면, 여러분은 그 이벤트를 사용하지 않았고, 또한 이 이벤트에 수반되는 액션에 관심이 없음을 가리킨다. 따라서, 여러분은 손가락 제스쳐gesture나 업up 액션 이벤트와 같은 어떤 다른 액션도 그 이벤트 내에서 호출받지 못할 것이다.

Remember that key events are always delivered to the View currently in focus. They are dispatched starting from the top of the View hierarchy, and then down, until they reach the appropriate destination. If your View (or a child of your View) currently has focus, then you can see the event travel through the dispatchKeyEvent() method. As an alternative to capturing key events through your View, you can also receive all of the events inside your Activity with onKeyDown() and onKeyUp().

Note: Android will call event handlers first and then the appropriate default handlers from the class definition second. As such, returning true from these event listeners will stop the propagation of the event to other event listeners and will also block the callback to the default event handler in the View. So be certain that you want to terminate the event when you return true.

Event Handlers

If you're building a custom component from View, then you'll be able to define several callback methods used as default event handlers. In the document on Building Custom Components, you'll learn see some of the common callbacks used for event handling, including:

• onKeyDown(int, KeyEvent) - Called when a new key event occurs.
• onKeyUp(int, KeyEvent) - Called when a key up event occurs.
• onTrackballEvent(MotionEvent) - Called when a trackball motion event occurs.
• onTouchEvent(MotionEvent) - Called when a touch screen motion event occurs.
• onFocusChanged(boolean, int, Rect) - Called when the view gains or loses focus.

onKeyDown(int, KeyEvent) - 신규 키 이벤트가 발생할 때 호출된다.
onKeyUp(int, KeyEvent) - 키 업(up) 이벤트가 발생할 때 호출된다.
onTrackballEvent(MotionEvent) - 트랙볼trackball 모션 이벤트가 발생할 때 호출된다.
onTouchEvent(MotionEvent) - 터치 스크린 모션 이벤트가 발생할 때 호출된다.
onFocusChanged(boolean, int, Rect) - 뷰가 포커스를 얻거나 잃게될 때 호출된다.

There are some other methods that you should be aware of, which are not part of the View class, but can directly impact the way you're able to handle events. So, when managing more complex events inside a layout, consider these other methods:

• Activity.dispatchTouchEvent(MotionEvent) - This allows your Activity to intercept all touch events before they are dispatched to the window.
• ViewGroup.onInterceptTouchEvent(MotionEvent) - This allows a ViewGroup to watch events as they are dispatched to child Views.
• ViewParent.requestDisallowInterceptTouchEvent(boolean) - Call this upon a parent View to indicate that it should not intercept touch events with onInterceptTouchEvent(MotionEvent).

Activity.dispatchTouchEvent(MotionEvent) - 이것은 터치 이벤트가 윈도우로 전달되기 전에 여러분의 액티비티가 그것들을 가로채는 것을 허용한다.
ViewGroup.onInterceptTouchEvent(MotionEvent) - 이것은 이벤트가 자식child 뷰에게 전달될 때 해당 이벤트를 그것의 부모parent 뷰가 감시하는 것을 허용한다.
ViewParent.requestDisallowInterceptTouchEvent(boolean) - 부모 뷰가 onInterceptTouchEvent(MotionEvent)를 사용해서 터치 이벤트를 가로채서는 안된다는 것을 가리키기 위해서는 이것을 호출하라.

Touch Mode

When a user is navigating a user interface with directional keys or a trackball, it is necessary to give focus to actionable items (like buttons) so the user can see what will accept input. If the device has touch capabilities, however, and the user begins interacting with the interface by touching it, then it is no longer necessary to highlight items, or give focus to a particular View. Thus, there is a mode for interaction named "touch mode."

For a touch-capable device, once the user touches the screen, the device will enter touch mode. From this point onward, only Views for which isFocusableInTouchMode() is true will be focusable, such as text editing widgets. Other Views that are touchable, like buttons, will not take focus when touched; they will simply fire their on-click listeners when pressed.

Any time a user hits a directional key or scrolls with a trackball, the device will exit touch mode, and find a view to take focus. Now, the user may resume interacting with the user interface without touching the screen.

The touch mode state is maintained throughout the entire system (all windows and activities). To query the current state, you can call isInTouchMode() to see whether the device is currently in touch mode.

Handling Focus

The framework will handle routine focus movement in response to user input. This includes changing the focus as Views are removed or hidden, or as new Views become available. Views indicate their willingness to take focus through the isFocusable() method. To change whether a View can take focus, call setFocusable(). When in touch mode, you may query whether a View allows focus with isFocusableInTouchMode(). You can change this with setFocusableInTouchMode().

Focus movement is based on an algorithm which finds the nearest neighbor in a given direction. In rare cases, the default algorithm may not match the intended behavior of the developer. In these situations, you can provide explicit overrides with the following XML attributes in the layout file: nextFocusDown, nextFocusLeft, nextFocusRight, and nextFocusUp. Add one of these attributes to the View from which the focus is leaving. Define the value of the attribute to be the id of the View to which focus should be given. For example:

<LinearLayout
    android:orientation="vertical"
    ... >
  <Button android:id="@+id/top"
          android:nextFocusUp="@+id/bottom"
          ... />
  <Button android:id="@+id/bottom"
          android:nextFocusDown="@+id/top"
          ... />
</LinearLayout>

Ordinarily, in this vertical layout, navigating up from the first Button would not go anywhere, nor would navigating down from the second Button. Now that the top Button has defined the bottom one as the nextFocusUp (and vice versa), the navigation focus will cycle from top-to-bottom and bottom-to-top.

If you'd like to declare a View as focusable in your UI (when it is traditionally not), add the android:focusable XML attribute to the View, in your layout declaration. Set the value true. You can also declare a View as focusable while in Touch Mode with android:focusableInTouchMode.

To request a particular View to take focus, call requestFocus().

To listen for focus events (be notified when a View receives or looses focus), use onFocusChange(), as discussed in the Event Listeners section, above.