Add a guided step

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.

The v17 Leanback support library
provides classes to implement multi-step user tasks. This lesson discusses how to use the
GuidedStepFragment class to guide a user through a series
of decisions to accomplish a task. GuidedStepFragment uses
TV UI best practices to make multi-step tasks easy to understand and navigate on TV devices.

Provide details for a step

A 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,
GuidedStepFragment provides a view containing a
list of possible actions or decisions for this step.

Actions aren't limited to single-line selections. Here are additional types of
actions you can create:

Add an information label action by setting
infoOnly(true).
If you set infoOnly to true, the user can't select the action. To
provide additional information about user choices, use label actions.

Add an editable text action by setting
editable(true). If
editable is true, when the action is selected the user can enter text using the
remote or a connected keyboard. Override
onGuidedActionEdited() or
onGuidedActionEditedAndProceed() to get the modified text the user entered.

Add a set of actions that behave as checkable radio buttons by using
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 the user selects one of the actions within that set, that
action becomes checked, while all other actions become unchecked.

Add subactions

Some actions might require giving the user an additional set of choices. A
GuidedAction can specify a list of
subactions that get displayed as a drop-down list of child actions.

Figure 2. Guided step subactions.

The subaction list can contain regular actions or radio button actions, but
not date-picker or editable text actions. Also, a subaction cannot have its own
set of subactions as the system does not support more than one level of subactions.
Deeply nested sets of actions create a poor user experience.

To add subactions, first create and populate a list of
GuidedActions that will
act as subactions:

Add button actions

If your guided step has a large list of actions, users may have to scroll through the list
to access the most commonly used actions. Use button actions to separate
commonly used actions from the action list. Button actions appear to the right
of the action list and are easy to navigate to.

Figure 3. Guided step button actions.

Button actions are created and handled just like regular actions, but you create
button actions in
onCreateButtonActions() instead of
onCreateActions(). Respond to button actions in
onGuidedActionClicked().

Use button actions for simple actions, such as navigation actions between steps.
Don't use the date-picker action or other editable actions as button actions.
Also, button actions cannot have subactions.

If the user presses the Back button on the TV remote, the device shows the previous
GuidedStepFragment on the fragment stack. If you
decide to provide your own GuidedAction that
returns to the previous step, you can implement the Back behavior by calling
getFragmentManager().popBackStack().
If you need to return the user to an even earlier step in the sequence, use
popBackStackToGuidedStepFragment() to return to a specific
GuidedStepFragment in the fragment stack.

When the user has finished the last step in the sequence, use
finishGuidedStepFragments() to remove all
GuidedStepFragments
from the current stack and return to the original parent activity. If the
first GuidedStepFragment was added
using addAsRoot(), calling
finishGuidedStepFragments() will also close the parent activity.

To apply a custom theme to your GuidedStepFragment, do one of the following:

Apply the theme to the parent activity by setting the android:theme 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
GuidedStepFragment objects.

The GuidedStepFragment class uses special
stylist classes to access and apply theme attributes.
The GuidanceStylist class uses theme information
to control presentation of the left guidance view, while the
GuidedActionsStylist class uses theme information
to control presentation of the right actions view.