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

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

@@ -1,5 +1,6 @@
 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
@@ -12,7 +13,7 @@ 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>
@@ -107,7 +108,7 @@ action item, and provide the action string, description, and ID. Use
 
 <pre>
 &#64;Override
-public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
+public void onCreateActions(List&lt;GuidedAction&gt; actions, Bundle savedInstanceState) {
     // Add "Continue" user action for this step
     actions.add(new GuidedAction.Builder()
            .id(CONTINUE)
@@ -119,39 +120,60 @@ public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceStat
 </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&mdash;to indicate that selecting the action
+leads to a new step&mdash;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>
@@ -162,6 +184,111 @@ onGuidedActionClicked()} and process the passed-in
 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&lt;GuidedAction&gt; subActions = new ArrayList&lt;GuidedAction&gt;();
+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>
+&#64;Override
+public void onCreateActions(List&lt;GuidedAction&gt; 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>
+&#64;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>
@@ -188,6 +315,20 @@ If the user presses the Back button on the TV remote, the device shows the previ
 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>
@@ -220,11 +361,11 @@ 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.
+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.