diff options
| -rw-r--r-- | docs/html/images/training/tv/playback/guided-step-screen-2x.png | bin | 0 -> 45186 bytes | |||
| -rw-r--r-- | docs/html/images/training/tv/playback/guided-step-screen.png | bin | 0 -> 18205 bytes | |||
| -rw-r--r-- | docs/html/training/training_toc.cs | 4 | ||||
| -rw-r--r-- | docs/html/training/tv/playback/guided-step.jd | 259 | ||||
| -rw-r--r-- | docs/html/training/tv/playback/index.jd | 4 | ||||
| -rw-r--r-- | docs/html/training/tv/publishing/checklist.jd | 5 | ||||
| -rw-r--r-- | docs/image_sources/training/tv/playback/guided-step-screen-orig.png | bin | 0 -> 46793 bytes |
7 files changed, 272 insertions, 0 deletions
diff --git a/docs/html/images/training/tv/playback/guided-step-screen-2x.png b/docs/html/images/training/tv/playback/guided-step-screen-2x.png Binary files differnew file mode 100644 index 000000000000..e13d97a9ee8f --- /dev/null +++ b/docs/html/images/training/tv/playback/guided-step-screen-2x.png diff --git a/docs/html/images/training/tv/playback/guided-step-screen.png b/docs/html/images/training/tv/playback/guided-step-screen.png Binary files differnew file mode 100644 index 000000000000..3025fe1f210d --- /dev/null +++ b/docs/html/images/training/tv/playback/guided-step-screen.png diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 5b0d60344a9b..9dbbe241bcbd 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -1085,6 +1085,10 @@ Displaying a Now Playing Card</a> </li> <li> + <a href="<?cs var:toroot ?>training/tv/playback/guided-step.html"> + Adding a Guided Step</a> + </li> + <li> <a href="<?cs var:toroot ?>training/tv/playback/options.html"> Enabling Background Playback</a> </li> diff --git a/docs/html/training/tv/playback/guided-step.jd b/docs/html/training/tv/playback/guided-step.jd new file mode 100644 index 000000000000..121961f03a73 --- /dev/null +++ b/docs/html/training/tv/playback/guided-step.jd @@ -0,0 +1,259 @@ +page.title=Adding a Guided Step +page.tags=tv, guided step +helpoutsWidget=true + +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + <h2>This lesson teaches you to</h2> + <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="#presentation">Customize Step Presentation</a></li> + </ol> + <h2>Try it out</h2> + <ul> + <li><a class="external-link" href="https://github.com/googlesamples/androidtv-Leanback">Android + Leanback sample app</a></li> + </ul> +</div> +</div> + +<p> +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. +</p> + +<p> +The <a href= +"{@docRoot}tools/support-library/features.html#v17-leanback">v17 Leanback support library</a> +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. +</p> + +<h2 id="details">Provide Details for a Step</h2> + +<p> +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. +</p> + +<img src="{@docRoot}images/training/tv/playback/guided-step-screen.png" +srcset="{@docRoot}images/training/tv/playback/guided-step-screen.png 1x, +{@docRoot}images/training/tv/playback/guided-step-screen-2x.png 2x" /> +<p class="img-caption"><strong>Figure 1.</strong> An example guided step.</p> + +<p> +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. +</p> + +<pre> +@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); +} +</pre> + +<p> +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. +</p> + +<p class="note"<strong>Note:</strong> Add +{@link android.support.v17.leanback.app.GuidedStepFragment} objects programmatically +and not in your layout XML files.</p> + +<h2 id="actions">Create and Handle User Actions</h2> + +<p> +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. +</p> + +<pre> +@Override +public void onCreateActions(List<GuidedAction> 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()); +... +</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: +</p> + +<ul> +<li> +Add a 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. +</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. +</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 +action becomes checked, while all other actions become unchecked. +</li> +</ul> + +<p> +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. +</p> + +<p> +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()}. +</p> + +<h2 id="sequence">Group Guided Steps Into a Guided Sequence</h2> + +<p> +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. +</p> + +<pre> +@Override +public void onGuidedActionClicked(GuidedAction action) { + FragmentManager fm = getFragmentManager(); + if (action.getId() == CONTINUE) { + GuidedStepFragment.add(fm, new SecondStepFragment()); + } +... +</pre> + +<p> +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()}. +</p> + +<h2 id="presentation">Customize Step Presentation</h2> + +<p> +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}. +</p> + +<p> +To apply a custom theme to your GuidedStepFragment, do one of the following: +</p> + +<ul> +<li> +Apply the theme to the parent activity by setting the <code>android:theme</code> attribute 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. +</li> +<li> +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. +</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 +visual theme across all steps, override +{@link android.support.v17.leanback.app.GuidedStepFragment#onProvideTheme +GuidedStepFragment.onProvideTheme()} and return your custom theme. +</li> +</ul> + +<p> +For more information on how to add styles and themes, see +<a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>. +</p> + +<p> +The {@link android.support.v17.leanback.app.GuidedStepFragment} class uses special +<em>stylist classes</em> 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. +</p> + +<p> +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}. +</p>
\ 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 43c6d41e09c1..d5e4e6712b05 100644 --- a/docs/html/training/tv/playback/index.jd +++ b/docs/html/training/tv/playback/index.jd @@ -65,6 +65,10 @@ startpage=true <dt><b><a href="now-playing.html">Displaying a Now Playing Card</a></b></dt> <dd>Learn how to use a MediaSession to display a Now Playing card on the home screen.</dd> + <dt><b><a href="guided-step.html">Adding a Guided Step</a></b></dt> + <dd>Learn how to use the Leanback support library to guide a user through a series of + decisions.</dd> + <dt><b><a href="options.html">Enabling Background Playback</a></b></dt> <dd>Learn how to continue playback when the user clicks on <strong>Home</strong>.</dd> </dl> diff --git a/docs/html/training/tv/publishing/checklist.jd b/docs/html/training/tv/publishing/checklist.jd index 6259721c2550..c044f0e0c482 100644 --- a/docs/html/training/tv/publishing/checklist.jd +++ b/docs/html/training/tv/publishing/checklist.jd @@ -137,6 +137,11 @@ page.article=true <p>See <a href="{@docRoot}training/tv/start/layouts.html#advertising">Provide Effective Advertising</a>.</p> </li> +<li> + Use the Leanback library for guiding the user through a series of decisions. + <p>See <a href="{@docRoot}training/tv/playback/guided-step.html">Adding a Guided Step</a>.</p> +</li> + </ol> diff --git a/docs/image_sources/training/tv/playback/guided-step-screen-orig.png b/docs/image_sources/training/tv/playback/guided-step-screen-orig.png Binary files differnew file mode 100644 index 000000000000..c39099c9734b --- /dev/null +++ b/docs/image_sources/training/tv/playback/guided-step-screen-orig.png |
