Merge "docs: Updating GuidedStepFragment for 23.2, new action types" into mnc-io-docs
diff --git a/docs/html/images/training/tv/playback/guided-step-buttonaction-2x.png b/docs/html/images/training/tv/playback/guided-step-buttonaction-2x.png
new file mode 100644
index 0000000..059cf0a
--- /dev/null
+++ b/docs/html/images/training/tv/playback/guided-step-buttonaction-2x.png
Binary files differ
diff --git a/docs/html/images/training/tv/playback/guided-step-buttonaction.png b/docs/html/images/training/tv/playback/guided-step-buttonaction.png
new file mode 100644
index 0000000..aacb844
--- /dev/null
+++ b/docs/html/images/training/tv/playback/guided-step-buttonaction.png
Binary files differ
diff --git a/docs/html/images/training/tv/playback/guided-step-subaction-2x.png b/docs/html/images/training/tv/playback/guided-step-subaction-2x.png
new file mode 100644
index 0000000..411bee4
--- /dev/null
+++ b/docs/html/images/training/tv/playback/guided-step-subaction-2x.png
Binary files differ
diff --git a/docs/html/images/training/tv/playback/guided-step-subaction.png b/docs/html/images/training/tv/playback/guided-step-subaction.png
new file mode 100644
index 0000000..5b004d5
--- /dev/null
+++ b/docs/html/images/training/tv/playback/guided-step-subaction.png
Binary files differ
diff --git a/docs/html/training/tv/playback/guided-step.jd b/docs/html/training/tv/playback/guided-step.jd
index 121961f..99e5c08 100644
--- a/docs/html/training/tv/playback/guided-step.jd
+++ b/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 @@
<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 @@
<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)
@@ -119,39 +120,60 @@
</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>
@@ -162,6 +184,111 @@
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>
@@ -188,6 +315,20 @@
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 @@
{@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.
