Navigating Around Your Application

It is all about the interaction 

Reacting to user input engages the customer and gives your application a sense of interaction. To accomplish this, your application responds to direct interactions, such as key presses and screen touches, as captured events. Devices in the marketplace today are configured with a combination of touch screens, keyboards, and trackballs all of which can handle UI events slightly differently. With the introduction of five-way keys we need a way of accommodating the different mechanisms in some sort of uniform way.

Working across multiple devices

Ideally you want to write your application in a way that maximizes reuse on many Android-based devices. To that end we have written our sample application to handle navigation as a key press event.  If the event is not consumed, the framework handles both five-way key presses and trackball movement as DPAD events.

Leveraging the custom toast example provided in the Android 1.5 SDK documentation (Creating  a Custom Toast View) we modified it to display a positional toast reflecting the direction selected. For instance, pressing the left or right arrow, or rolling the trackball to the left/right, displays the toast on the far left or right.

The simplest way to code this for both five-way key presses and trackball motion is to override the onKeyDown() event handler to process specific key codes.

public class Navigation extends Activity (

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
  }

  public void showCustomToast () (
    // code to display toast
  }

  @Override
  public boolean onKeyDown(int keyCode, KeyEvent event) {
    CharSequence dialogString;
    switch (keyCode) {
        case KeyEvent.KEYCODE_DPAD_CENTER: {
            // display the custom toast in the middle
            break;
        }
        case KeyEvent.KEYCODE_DPAD_LEFT: {
            // display the custom toast to the left
            break;
        }
        case KeyEvent.KEYCODE_DPAD_RIGHT: {
            // display the custom toast to the right
            break;
        }
        case KeyEvent.KEYCODE_DPAD_UP: {
            // display the custom toast at the top
            break;
        }
        case KeyEvent.KEYCODE_DPAD_DOWN: {
            // display the custom toast at the bottom
            break;
        }
        case KeyEvent.KEYCODE_BACK: {
            finish();
        }
    }
    return true;
  }
}

For a more detailed approach to coding for navigation, watch for part two of "Navigating Your Application".

Configuring for device dependence

Now that you have written your application to handle multiple input mechanisms in a generic way, how do you ensure that the directional control is available? One way to do this is to limit the devices your application is installed on to those that provide directional navigation. The <uses-configuration> element in the application manifest file defines the specific requirements.

The two properties related to navigation are reqFiveWayNav and reqNavigation.

<uses-configuration android:reqFiveWayNav=["true" | "false"]
                    android:reqNavigation=["undefined" | "nonav" | "dpad" | 
                                           "trackball" | "wheel"]
                    ... />

Set the reqFiveWayNav property to “true” if you want to ensure that a directional pad (like five-way keypad), trackball, or other device that supports up, down, left, right, and selection are available.

<uses-configuration android:reqFiveWayNav="true" />

For specific control over the type of navigation, ignore the reqFiveWayNav property and set the reqNavigation property to the desired input.

<uses-configuration android:reqNavigation="dpad" />

If your application supports multiple navigation types, you must specify each type on a separate line. For example to support both five-way keys and a trackball but not a wheel, the <uses-configuration> is written as follows:

<uses-configuration android:reqNavigation="dpad"/>
<uses-configuration android:reqNavigation="trackball"/>

See http://developer.android.com/guide/topics/manifest/uses-configuration-element.html for more information on this element. 

Tips on handling focus

Normally the UI framework handles switching focus in response to user input, including five-way navigation. According to the Android SDK documentation on Handling Focus the movement is based on finding the nearest neighbor in a given direction. The default behavior, however, does not change focus on the “outer-most” UI elements when there are no elements to move to. For instance, what happens when the top button on a screen has focus and the user presses the up key on the five-way keypad? The button has no neighbors above it so focus stays on the current element. You can change this behavior by defining a “next element” for each of the UI elements that bookend the form. The example provided in the documentation shows you how to set the XML attributes to move focus when directionally there are no elements to move to.

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

Working with rotation

Five-way navigation works in either portrait or landscape mode.  However, the five-way keys may not be available unless the keyboard is open.  Once you open the keyboard the screen, by default, rotates to landscape.  If you need your application to remain in portrait mode with the keyboard open, you can override this behavior by specifying "portrait" in the manifest file.

<activity android:name=".Navigation"
                  android:label="@string/app_name"
                  android:screenOrientation="portrait"

The five-way key mappings also rotate, so pressing the left key — which was the down key in landscape mode — now goes left.