@Override -public void onCreateActions(Listactions, 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 @@ public void onCreateActions(List actions, Bundle savedInstanceStat
-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:
infoOnly 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 infoOnly to true, the user can't select the action. To
+provide additional information about user choices, use label actions.
editable 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.
-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}.
@@ -162,6 +184,111 @@ onGuidedActionClicked()} and process the passed-in examining {@link android.support.v17.leanback.widget.GuidedAction#getId GuidedAction.getId()}.
++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. +
+ +
+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 +{@link android.support.v17.leanback.widget.GuidedAction GuidedActions} that will +act as subactions: +
+ ++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()); +... ++ +
+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: +
+ +
+@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))
+ .subActions(subActions)
+ .build());
+...
+}
+
+
++Finally, respond to subaction selections by overriding +{@code onSubGuidedActionClicked()}: +
+ +
+@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;
+}
+
+
++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 +{@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()}. +
+ ++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. +
+@@ -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. +
+ ++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.