This lesson teaches you to
+-
+
- Provide Details for a Step +
- Create and Handle User Actions +
- Group Guided Steps Into a Sequence +
- Customize Step Presentation +
Try it out
+ ++Your application might have multi-step tasks for users. For example, your app might need to guide +users through purchasing additional content, or setting up a complex configuration setting, or +simply confirming a decision. All of these tasks require walking users through one or more ordered +steps or decisions. +
+ ++The v17 Leanback support library +provides classes to implement multi-step user tasks. This lesson discusses how to use the +{@link android.support.v17.leanback.app.GuidedStepFragment} class to guide a user through a series +of decisions to accomplish a task. {@link android.support.v17.leanback.app.GuidedStepFragment} uses +TV UI best practices to make multi-step tasks easy to understand and navigate on TV devices. +
+ +Provide Details for a Step
+ ++A {@link android.support.v17.leanback.app.GuidedStepFragment} represents a single step in a series +of steps. Visually it provides a guidance view on the left with step information. On the right, +{@link android.support.v17.leanback.app.GuidedStepFragment} provides a view containing a +list of possible actions or decisions for this step. +
+ +
+Figure 1. An example guided step.
+ ++For each step in your multi-step task, extend +{@link android.support.v17.leanback.app.GuidedStepFragment} and provide context information about +the step and actions the user can take. Override +{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateGuidance onCreateGuidance()} +and return a new +{@link android.support.v17.leanback.widget.GuidanceStylist.Guidance} that contains context +information, such as the step title, description, and icon. +
+ +
+@Override
+public GuidanceStylist.Guidance onCreateGuidance(Bundle savedInstanceState) {
+ String title = getString(R.string.guidedstep_first_title);
+ String breadcrumb = getString(R.string.guidedstep_first_breadcrumb);
+ String description = getString(R.string.guidedstep_first_description);
+ Drawable icon = getActivity().getDrawable(R.drawable.guidedstep_main_icon_1);
+ return new GuidanceStylist.Guidance(title, description, breadcrumb, icon);
+}
+
+
++Add your {@link android.support.v17.leanback.app.GuidedStepFragment} subclass to your desired +activity by calling +{@link android.support.v17.leanback.app.GuidedStepFragment#add GuidedStepFragment.add()} +in your activity’s {@link android.app.Activity#onCreate onCreate()} method. + +If your activity contains only {@link android.support.v17.leanback.app.GuidedStepFragment} +objects, use {@link android.support.v17.leanback.app.GuidedStepFragment#addAsRoot +GuidedStepFragment.addAsRoot()} instead of +{@link android.support.v17.leanback.app.GuidedStepFragment#add add()} to add the first +{@link android.support.v17.leanback.app.GuidedStepFragment}. Using +{@link android.support.v17.leanback.app.GuidedStepFragment#addAsRoot +addAsRoot()} ensures that if the user presses the Back button on the TV remote when viewing +the first {@link android.support.v17.leanback.app.GuidedStepFragment}, both the +{@link android.support.v17.leanback.app.GuidedStepFragment} and the parent activity will close. +
+ +Note: Add +{@link android.support.v17.leanback.app.GuidedStepFragment} objects programmatically +and not in your layout XML files.
+ +Create and Handle User Actions
+ ++Add user actions by overriding +{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateActions onCreateActions()}. +In your override, add a new {@link android.support.v17.leanback.widget.GuidedAction} for each +action item, and provide the action string, description, and ID. Use +{@link android.support.v17.leanback.widget.GuidedAction.Builder} to add new actions. +
+ ++@Override +public void onCreateActions(List+ +actions, Bundle savedInstanceState) { + // Add "Continue" user action for this step + actions.add(new GuidedAction.Builder() + .id(CONTINUE) + .title(getString(R.string.guidedstep_continue)) + .description(getString(R.string.guidedstep_letsdoit)) + .hasNext(true) + .build()); +... +
+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: +
+ +-
+
-
+Add a information label action by setting
+{@link android.support.v17.leanback.widget.GuidedAction.Builder#infoOnly infoOnly(true)}.
+If
infoOnlyis set to true, the action can't be selected by the user. Use label +actions to provide additional information about user choices. +
+ -
+Add an editable text action by setting
+{@link android.support.v17.leanback.widget.GuidedAction.Builder#editable editable(true)}. If
+
editableis true, when the action is selected the user can enter text using the +remote or a connected keyboard. +
+ - +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 +action becomes checked, while all other actions become unchecked. + +
+You can also add a visual indicator that indicates 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. +
+ ++To respond to actions, override +{@link android.support.v17.leanback.app.GuidedStepFragment#onGuidedActionClicked +onGuidedActionClicked()} and process the passed-in +{@link android.support.v17.leanback.widget.GuidedAction}. Identify the selected action by +examining {@link android.support.v17.leanback.widget.GuidedAction#getId GuidedAction.getId()}. +
+ +Group Guided Steps Into a Guided Sequence
+ ++A {@link android.support.v17.leanback.app.GuidedStepFragment} represents a single step, however +you might have several steps in an ordered sequence. Group multiple +{@link android.support.v17.leanback.app.GuidedStepFragment} objects together by using +{@link android.support.v17.leanback.app.GuidedStepFragment#add GuidedStepFragment.add()} to add +the next step in the sequence to the fragment stack. +
+ +
+@Override
+public void onGuidedActionClicked(GuidedAction action) {
+ FragmentManager fm = getFragmentManager();
+ if (action.getId() == CONTINUE) {
+ GuidedStepFragment.add(fm, new SecondStepFragment());
+ }
+...
+
+
++If the user presses the Back button on the TV remote, the device shows the previous +{@link android.support.v17.leanback.app.GuidedStepFragment} on the fragment stack. If you +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()}. +
+ +Customize Step Presentation
+ ++The {@link android.support.v17.leanback.app.GuidedStepFragment} class can use custom +themes that control presentation aspects such as title text formatting or step transition +animations. Custom themes must inherit from +{@link android.support.v17.leanback.R.style#Theme_Leanback_GuidedStep}, and can provide +overriding values for attributes defined in +{@link android.support.v17.leanback.widget.GuidanceStylist} and +{@link android.support.v17.leanback.widget.GuidedActionsStylist}. +
+ ++To apply a custom theme to your GuidedStepFragment, do one of the following: +
+ +-
+
-
+Apply the theme to the parent activity by setting the
android:themeattribute to the +activity element in the Android manifest. Setting this attribute applies the theme to all child +views and is the easiest way to apply a custom theme if the parent activity contains only +{@link android.support.v17.leanback.app.GuidedStepFragment} objects. +
+ - +If your activity already uses a custom theme and you don’t want to apply +{@link android.support.v17.leanback.app.GuidedStepFragment} styles to other views in the activity, +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. + +
- +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 +visual theme across all steps, override +{@link android.support.v17.leanback.app.GuidedStepFragment#onProvideTheme +GuidedStepFragment.onProvideTheme()} and return your custom theme. + +
+For more information on how to add styles and themes, see +Styles and Themes. +
+ ++The {@link android.support.v17.leanback.app.GuidedStepFragment} class uses special +stylist classes to access and apply theme attributes. +The {@link android.support.v17.leanback.widget.GuidanceStylist} class uses theme information +to control presentation of the left guidance view, while the +{@link android.support.v17.leanback.widget.GuidedActionsStylist} class uses theme information +to control presentation of the right actions view. +
+ ++To customize the visual style of your steps beyond what theme customization can provide, subclass +{@link android.support.v17.leanback.widget.GuidanceStylist} or +{@link android.support.v17.leanback.widget.GuidedActionsStylist} and return your subclass in +{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateGuidanceStylist +GuidedStepFragment.onCreateGuidanceStylist()} or +{@link android.support.v17.leanback.app.GuidedStepFragment#onCreateActionsStylist +GuidedStepFragment.onCreateActionsStylist()}. +For details on what you can customize in these subclasses, see the documentation on +{@link android.support.v17.leanback.widget.GuidanceStylist} and +{@link android.support.v17.leanback.widget.GuidedActionsStylist}. +
\ No newline at end of file diff --git a/docs/html/training/tv/playback/index.jd b/docs/html/training/tv/playback/index.jd index 43c6d41e09c19..d5e4e6712b053 100644 --- a/docs/html/training/tv/playback/index.jd +++ b/docs/html/training/tv/playback/index.jd @@ -65,6 +65,10 @@ startpage=true