docs/html/training/tv/playback/guided-step.jd

page.title=Adding a Guided Step
page.tags=tv, guided step
helpoutsWidget=true

trainingnavtop=true

@jd:body

<div id="tb-wrapper">
<div id="tb">
  <h2>This lesson teaches you to</h2>
  <ol>
    <li><a href="#details">Provide Details for a Step</a></li>
    <li><a href="#actions">Create and Handle User Actions</a></li>
    <li><a href="#sequence">Group Guided Steps Into a Sequence</a></li>
    <li><a href="#presentation">Customize Step Presentation</a></li>
  </ol>
  <h2>Try it out</h2>
  <ul>
    <li><a class="external-link" href="https://github.com/googlesamples/androidtv-Leanback">Android
    Leanback sample app</a></li>
  </ul>
</div>
</div>

<p>
Your application might have multi-step tasks for users. For example, your app might need to guide
users through purchasing additional content, or setting up a complex configuration setting, or
simply confirming a decision. All of these tasks require walking users through one or more ordered
steps or decisions.
</p>

<p>
The <a href=
"{@docRoot}tools/support-library/features.html#v17-leanback">v17 Leanback support library</a>
provides classes to implement multi-step user tasks. This lesson discusses how to use the
{@link android.support.v17.leanback.app.GuidedStepFragment} class to guide a user through a series
of decisions to accomplish a task. {@link android.support.v17.leanback.app.GuidedStepFragment} uses
TV UI best practices to make multi-step tasks easy to understand and navigate on TV devices.
</p>

<h2 id="details">Provide Details for a Step</h2>

<p>
A {@link android.support.v17.leanback.app.GuidedStepFragment} represents a single step in a series
of steps. Visually it provides a guidance view on the left with step information. On the right,
{@link android.support.v17.leanback.app.GuidedStepFragment} provides a view containing a
list of possible actions or decisions for this step.
</p>

<img src="{@docRoot}images/training/tv/playback/guided-step-screen.png"
srcset="{@docRoot}images/training/tv/playback/guided-step-screen.png 1x,
{@docRoot}images/training/tv/playback/guided-step-screen-2x.png 2x" />
<p class="img-caption"><strong>Figure 1.</strong> An example guided step.</p>

<p>
For each step in your multi-step task, extend
{@link android.support.v17.leanback.app.GuidedStepFragment} and provide context information about
the step and actions the user can take. Override
{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateGuidance onCreateGuidance()}
and return a new
{@link android.support.v17.leanback.widget.GuidanceStylist.Guidance} that contains context
information, such as the step title, description, and icon.
</p>

<pre>
&#64;Override
public GuidanceStylist.Guidance onCreateGuidance(Bundle savedInstanceState) {
    String title = getString(R.string.guidedstep_first_title);
    String breadcrumb = getString(R.string.guidedstep_first_breadcrumb);
    String description = getString(R.string.guidedstep_first_description);
    Drawable icon = getActivity().getDrawable(R.drawable.guidedstep_main_icon_1);
    return new GuidanceStylist.Guidance(title, description, breadcrumb, icon);
}
</pre>

<p>
Add your {@link android.support.v17.leanback.app.GuidedStepFragment} subclass to your desired
activity by calling
{@link android.support.v17.leanback.app.GuidedStepFragment#add GuidedStepFragment.add()}
in your activity’s {@link android.app.Activity#onCreate onCreate()} method.

If your activity contains only {@link android.support.v17.leanback.app.GuidedStepFragment}
objects, use {@link android.support.v17.leanback.app.GuidedStepFragment#addAsRoot
GuidedStepFragment.addAsRoot()} instead of
{@link android.support.v17.leanback.app.GuidedStepFragment#add add()} to add the first
{@link android.support.v17.leanback.app.GuidedStepFragment}. Using
{@link android.support.v17.leanback.app.GuidedStepFragment#addAsRoot
addAsRoot()} ensures that if the user presses the Back button on the TV remote when viewing
the first {@link android.support.v17.leanback.app.GuidedStepFragment}, both the
{@link android.support.v17.leanback.app.GuidedStepFragment} and the parent activity will close.
</p>

<p class="note"<strong>Note:</strong> Add
{@link android.support.v17.leanback.app.GuidedStepFragment} objects programmatically
and not in your layout XML files.</p>

<h2 id="actions">Create and Handle User Actions</h2>

<p>
Add user actions by overriding
{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateActions onCreateActions()}.
In your override, add a new {@link android.support.v17.leanback.widget.GuidedAction} for each
action item, and provide the action string, description, and ID. Use
{@link android.support.v17.leanback.widget.GuidedAction.Builder} to add new actions.
</p>

<pre>
&#64;Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
    // Add "Continue" user action for this step
    actions.add(new GuidedAction.Builder()
           .id(CONTINUE)
           .title(getString(R.string.guidedstep_continue))
           .description(getString(R.string.guidedstep_letsdoit))
           .hasNext(true)
           .build());
...
</pre>

<p>
Actions aren’t limited to single-line selections. Use
{@link android.support.v17.leanback.widget.GuidedAction} attributes
to add the following additional types of actions:
</p>

<ul>
<li>
Add a information label action by setting
{@link android.support.v17.leanback.widget.GuidedAction.Builder#infoOnly infoOnly(true)}.
If <code>infoOnly</code> is set to true, the action can't be selected by the user. Use label
actions to provide additional information about user choices.
</li>
<li>
Add an editable text action by setting
{@link android.support.v17.leanback.widget.GuidedAction.Builder#editable editable(true)}. If
<code>editable</code> is true, when the action is selected the user can enter text using the
remote or a connected keyboard.
</li>
<li>
Add a set of actions that behave as checkable radio buttons by using
{@link android.support.v17.leanback.widget.GuidedAction.Builder#checkSetId checkSetId()}
with a common ID value to group actions into a set. All actions in the same list with the same
check-set ID are considered linked. When one of the actions within that set is selected, that
action becomes checked, while all other actions become unchecked.
</li>
</ul>

<p>
You can also add a visual indicator that indicates selecting the action leads to a new step by
setting
{@link android.support.v17.leanback.widget.GuidedAction#hasNext hasNext(true)}.
See {@link android.support.v17.leanback.widget.GuidedAction} for all the different attributes
you can set.
</p>

<p>
To respond to actions, override
{@link android.support.v17.leanback.app.GuidedStepFragment#onGuidedActionClicked
onGuidedActionClicked()} and process the passed-in
{@link android.support.v17.leanback.widget.GuidedAction}. Identify the selected action by
examining {@link android.support.v17.leanback.widget.GuidedAction#getId GuidedAction.getId()}.
</p>

<h2 id="sequence">Group Guided Steps Into a Guided Sequence</h2>

<p>
A {@link android.support.v17.leanback.app.GuidedStepFragment} represents a single step, however
you might have several steps in an ordered sequence. Group multiple
{@link android.support.v17.leanback.app.GuidedStepFragment} objects together by using
{@link android.support.v17.leanback.app.GuidedStepFragment#add GuidedStepFragment.add()} to add
the next step in the sequence to the fragment stack.
</p>

<pre>
&#64;Override
public void onGuidedActionClicked(GuidedAction action) {
    FragmentManager fm = getFragmentManager();
    if (action.getId() == CONTINUE) {
       GuidedStepFragment.add(fm, new SecondStepFragment());
    }
...
</pre>

<p>
If the user presses the Back button on the TV remote, the device shows the previous
{@link android.support.v17.leanback.app.GuidedStepFragment} on the fragment stack. If you
decide to provide your own {@link android.support.v17.leanback.widget.GuidedAction} that
returns to the previous step, you can implement the Back behavior by calling
{@link android.app.FragmentManager#popBackStack getFragmentManager().popBackStack()}.
</p>

<h2 id="presentation">Customize Step Presentation</h2>

<p>
The {@link android.support.v17.leanback.app.GuidedStepFragment} class can use custom
themes that control presentation aspects such as title text formatting or step transition
animations. Custom themes must inherit from
{@link android.support.v17.leanback.R.style#Theme_Leanback_GuidedStep}, and can provide
overriding values for attributes defined in
{@link android.support.v17.leanback.widget.GuidanceStylist} and
{@link android.support.v17.leanback.widget.GuidedActionsStylist}.
</p>

<p>
To apply a custom theme to your GuidedStepFragment, do one of the following:
</p>

<ul>
<li>
Apply the theme to the parent activity by setting the <code>android:theme</code> attribute to the
activity element in the Android manifest. Setting this attribute applies the theme to all child
views and is the easiest way to apply a custom theme if the parent activity contains only
{@link android.support.v17.leanback.app.GuidedStepFragment} objects.
</li>
<li>
If your activity already uses a custom theme and you don’t want to apply
{@link android.support.v17.leanback.app.GuidedStepFragment} styles to other views in the activity,
add the
{@link android.support.v17.leanback.R.styleable#LeanbackGuidedStepTheme_guidedStepTheme}
attribute to your existing custom activity theme. This attribute points to the custom theme that
only the {@link android.support.v17.leanback.app.GuidedStepFragment} objects in your
activity will use.
</li>
<li>
If you use {@link android.support.v17.leanback.app.GuidedStepFragment} objects in different
activities that are part of the same overall multi-step task, and want to use a consistent
visual theme across all steps, override
{@link android.support.v17.leanback.app.GuidedStepFragment#onProvideTheme
GuidedStepFragment.onProvideTheme()} and return your custom theme.
</li>
</ul>

<p>
For more information on how to add styles and themes, see
<a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.
</p>

<p>
The {@link android.support.v17.leanback.app.GuidedStepFragment} class uses special
<em>stylist classes</em> to access and apply theme attributes.
The {@link android.support.v17.leanback.widget.GuidanceStylist} class uses theme information
to control presentation of the left guidance view, while the
{@link android.support.v17.leanback.widget.GuidedActionsStylist} class uses theme information
to control presentation of the right actions view.
</p>

<p>
To customize the visual style of your steps beyond what theme customization can provide, subclass
{@link android.support.v17.leanback.widget.GuidanceStylist} or
{@link android.support.v17.leanback.widget.GuidedActionsStylist} and return your subclass in
{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateGuidanceStylist
GuidedStepFragment.onCreateGuidanceStylist()} or
{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateActionsStylist
GuidedStepFragment.onCreateActionsStylist()}.
For details on what you can customize in these subclasses, see the documentation on
{@link android.support.v17.leanback.widget.GuidanceStylist} and
{@link android.support.v17.leanback.widget.GuidedActionsStylist}.
</p>