docs: Updating GuidedStepFragment for 23.2, new action types

Adding docs for some updates for GuidedStepFragment and GuidedAction
done in support lib v23.2. Includes docs on date picker actions,
subactions (new subsection), button actions (new subsection).
Adding docs for popBackStackToGuidedStepFragment and
finishGuidedStepFragments convenience methods.
Also updating page keywords so this page has better search
discoverability.

Staged: https://android-dot-devsite.googleplex.com/training/tv/playback/guided-step.html

Bug: 26902886
Original SHA1: I792bbe6696cd144dbb6319b3c4eb44e67390217d

Change-Id: I57aeb9deb59bb2cdf5a062b24916b625e1553cf0

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.