Merge "docs: Adding new page on using GuidedStepFragment" into mnc-docs

docs/html/training/training_toc.cs

@@ -1084,6 +1084,10 @@
                ja-lang="再生中カードを表示する">
               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>

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>
+&#64;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>
+&#64;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>
+&#64;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>

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>

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>