android_frameworks_base/docs/html/preview/tv/ui/navigation.jd

page.title=Navigation for TV

@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#d-pad-navigation">D-pad Navigation</a></li>
    <li><a href="#focus-selection">Focus and Selection</a></li>
  </ol>

</div>
</div>

<p>TV devices provide a limited set of navigation controls for apps. Creating an effective
  navigation scheme for your TV app depends on understanding these limited controls and the limits
  of users' perception while operating your app. As you build your Android app for TVs,
  you should pay special attention to how the user actually navigates around your app
  when using remote control buttons instead of a touch screen.</p>

<p>This guide shows you how to build an effective navigation scheme for your TV app.</p>


<h2 id="d-pad-navigation">D-pad Navigation</h2>

<p>On a TV device, users navigate with controls on a remote control device, using either a
  directional pad (D-pad) or arrow keys. This type of control limits movement to up, down, left,
  and right. To build a great TV-optimized app, you must provide a navigation scheme where
  the user can quickly learn how to navigate your app using these limited controls.</p>

<p>Follow these guidelines to build a navigation system that works well with a D-pad on a TV device:
</p>

<ul>
  <li>Ensure that the D-pad can navigate to all the visible controls on the screen.</li>
  <li>For scrolling lists with focus, D-pad up/down keys scroll the list, and the Enter key selects
    an item in the list. Ensure that users can select an element in the list and that the list still
    scrolls when an element is selected.</li>
  <li>Ensure that movement between controls is straightforward and predictable.</li>
</ul>

<p>The Android framework handles directional navigation between layout elements automatically, so
  you typically do not need to do anything extra for your app. However, you should thoroughly test
  navigation with a D-pad control to discover any navigation problems. If you discover that your
  screen layout makes navigation difficult, or if you want users to move through the layout in a
  specific way, you can set up explicit directional navigation for your controls. The following
  code sample shows how to define the next control to receive focus for a
  {@link android.widget.TextView} layout object:</p>

<pre>
&lt;TextView android:id="&#64;+id/Category1"
             android:nextFocusDown="&#64;+id/Category2"\&gt;
</pre>

<p>The following table lists all of the available navigation attributes for Android user interface
widgets:</p>

<table>
  <tr>
    <th>Attribute</th>
    <th>Function</th>
  </tr>
  <tr>
    <td>{@link android.R.attr#nextFocusDown}</td>
    <td>Defines the next view to receive focus when the user navigates down.</td>
  </tr>
  <tr>
    <td>{@link android.R.attr#nextFocusLeft}</td>
    <td>Defines the next view to receive focus when the user navigates left.</td>
  </tr>
  <tr>
    <td>{@link android.R.attr#nextFocusRight}</td>
    <td>Defines the next view to receive focus when the user navigates right.</td>
  </tr>
  <tr>
    <td>{@link android.R.attr#nextFocusUp}</td>
    <td>Defines the next view to receive focus when the user navigates up.</td>
  </tr>
</table>

<p>To use one of these explicit navigation attributes, set the value to the ID ({@code android:id}
  value) of another widget in the layout. You should set up the navigation order as a loop, so that
  the last control directs focus back to the first one.</p>

<p class="note">
  <strong>Note:</strong> You should only use these attributes to modify the navigation order if the
  default order that the system applies does not work well.
</p>


<h2 id="focus-selection">Focus and Selection</h2>

<p>The success of a navigation scheme on TV devices is strongly dependent on how easy it is for a
  user to determine what user interface element is in focus on screen. If you do not provide clear
  indications of what is in focus on screen (and therefore what item they can take action on),
  users can quickly become frustrated and exit your app. By the same token, it is important
  to always have an item in focus that a user can take action on immediately after your app starts,
  and any time your app is not playing content.</p>

<p>Your app layout and implementation should use color, size, animation, or a combination of
  these attributes to help users easily determine what actions they can take next. Use a uniform
  scheme for indicating focus across your application.</p>

<p>Android provides <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">
Drawable State List Resources</a> to implement highlights for selected and focused controls. The
following code example demonstrates how to indicate selection of a button object:
</p>

<pre>
&lt;!-- res/drawable/button.xml --&gt;
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;selector xmlns:android="http://schemas.android.com/apk/res/android"&gt;
    &lt;item android:state_pressed="true"
          android:drawable="@drawable/button_pressed" /&gt; &lt;!-- pressed --&gt;
    &lt;item android:state_focused="true"
          android:drawable="@drawable/button_focused" /&gt; &lt;!-- focused --&gt;
    &lt;item android:state_hovered="true"
          android:drawable="@drawable/button_focused" /&gt; &lt;!-- hovered --&gt;
    &lt;item android:drawable="@drawable/button_normal" /&gt; &lt;!-- default --&gt;
&lt;/selector&gt;
</pre>

<p>
This layout XML applies the above state list drawable to a {@link android.widget.Button}:
</p>
<pre>
&lt;Button
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:background="@drawable/button" /&gt;
</pre>

<p>Make sure to provide sufficient padding within the focusable and selectable controls so that
  the highlights around them are clearly visible.</p>