Merge "docs: Updating GuidedStepFragment for 23.2, new action types" into mnc-io-docs

page.title=Adding a Guided Step

page.tags=tv, guided step

page.tags=tv,guided step,GuidedStepFragment,GuidedAction

page.keywords=tv,GuidedStepFragment,GuidedAction

helpoutsWidget=true

trainingnavtop=true

  <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="#sequence">Group Guided Steps Into a Guided Sequence</a></li>

    <li><a href="#presentation">Customize Step Presentation</a></li>

  </ol>

  <h2>Try it out</h2>

<pre>

@Override

public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {

public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {

    // Add "Continue" user action for this step

    actions.add(new GuidedAction.Builder()

           .id(CONTINUE)

</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:

Actions aren't limited to single-line selections. Here are additional types of

actions you can create:

</p>

<ul>

<li>

Add a information label action by setting

Add an 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.

If you set <code>infoOnly</code> to true, the user can't select the action. To

provide additional information about user choices, use label actions.

</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.

remote or a connected keyboard. Override

{@link android.support.v17.leanback.app.GuidedStepFragment#onGuidedActionEdited

onGuidedActionEdited()} or

{@code onGuidedActionEditedAndProceed()} to get the modified text the user entered.

</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

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.

</li>

<li>

Add a date-picker action by using

{@code GuidedDatePickerAction.Builder}

instead of

{@link android.support.v17.leanback.widget.GuidedAction.Builder} in

{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateActions

onCreateActions()}. Override

{@link android.support.v17.leanback.app.GuidedStepFragment#onGuidedActionEdited

onGuidedActionEdited()} or

{@code onGuidedActionEditedAndProceed()} to get the modified date value the user entered.

</li>

<li>

Add an action that uses subactions to let the user pick from an extended list of

choices. Subactions are described in <a href="#subactions">Add subactions</a>.

</li>

<li>

Add a button action that appears to the right of the actions list and is easily

accessible. Button actions are described in <a href="#buttonactions">Add button

actions</a>.</li>

</ul>

<p>

You can also add a visual indicator that indicates selecting the action leads to a new step by

setting

You can also add a visual indicator—to indicate that 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.

For all the different attributes that you can set, see

{@link android.support.v17.leanback.widget.GuidedAction}.

</p>

<p>

examining {@link android.support.v17.leanback.widget.GuidedAction#getId GuidedAction.getId()}.

</p>

<h3 id="subactions">Add subactions</h3>

<p>

Some actions might require giving the user an additional set of choices. A

{@link android.support.v17.leanback.widget.GuidedAction} can specify a list of

subactions that get displayed as a drop-down list of child actions.

</p>

<img src="{@docRoot}images/training/tv/playback/guided-step-subaction.png"

srcset="{@docRoot}images/training/tv/playback/guided-step-subaction.png 1x,

{@docRoot}images/training/tv/playback/guided-step-subaction-2x.png 2x" />

<p class="img-caption"><strong>Figure 2.</strong> Guided step subactions.</p>

<p>

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.

</p>

<p>

To add subactions, first create and populate a list of

{@link android.support.v17.leanback.widget.GuidedAction GuidedActions} that will

act as subactions:

</p>

<pre>

List<GuidedAction> subActions = new ArrayList<GuidedAction>();

subActions.add(new GuidedAction.Builder()

       .id(SUBACTION1)

       .title(getString(R.string.guidedstep_subaction1_title))

       .description(getString(R.string.guidedstep_subaction1_desc))

       .build());

...

</pre>

<p>

In {@link android.support.v17.leanback.app.GuidedStepFragment#onCreateActions

onCreateActions()}, create a top-level

{@link android.support.v17.leanback.widget.GuidedAction} that will display the

list of subactions when selected:

</p>

<pre>

@Override

public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {

...

    actions.add(new GuidedAction.Builder()

           .id(SUBACTIONS)

           .title(getString(R.string.guidedstep_subactions_title))

           .description(getString(R.string.guidedstep_subactions_desc))

           <b>.subActions(subActions)</b>

           .build());

...

}

</pre>

<p>

Finally, respond to subaction selections by overriding

{@code onSubGuidedActionClicked()}:

</p>

<pre>

@Override

public boolean onSubGuidedActionClicked(GuidedAction action) {

   // Check for which action was clicked, and handle as needed

   if (action.getId() == SUBACTION1) {

       // Subaction 1 selected

   }

   // Return true to collapse the subactions drop-down list, or

   // false to keep the drop-down list expanded.

   return true;

}

</pre>

<h3 id="buttonactions">Add button actions</h3>

<p>

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.

</p>

<img src="{@docRoot}images/training/tv/playback/guided-step-buttonaction.png"

srcset="{@docRoot}images/training/tv/playback/guided-step-buttonaction.png 1x,

{@docRoot}images/training/tv/playback/guided-step-buttonaction-2x.png 2x" />

<p class="img-caption"><strong>Figure 3.</strong> Guided step button actions.</p>

<p>

Button actions are created and handled just like regular actions, but you create

button actions in

{@code onCreateButtonActions()} instead of

{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateActions

onCreateActions()}. Respond to button actions in

{@link android.support.v17.leanback.app.GuidedStepFragment#onGuidedActionClicked

onGuidedActionClicked()}.

</p>

<p>

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.

</p>

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

<p>

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()}.

If you need to return the user to an even earlier step in the sequence, use

{@code popBackStackToGuidedStepFragment()} to return to a specific

{@link android.support.v17.leanback.app.GuidedStepFragment} in the fragment stack.

</p>

<p>

When the user has finished the last step in the sequence, use

{@code finishGuidedStepFragments()} to remove all

{@link android.support.v17.leanback.app.GuidedStepFragment GuidedStepFragments}

from the current stack and return to the original parent activity. If the

first {@link android.support.v17.leanback.app.GuidedStepFragment} was added

using {@link android.support.v17.leanback.app.GuidedStepFragment#addAsRoot

addAsRoot()}, calling

{@code finishGuidedStepFragments()} will also close the parent activity.

</p>

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

{@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.

activity 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

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.