Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit eefe46cd authored by Daniel Yu's avatar Daniel Yu
Browse files

docs: Adding new page on using GuidedStepFragment 

Adding information on how to use GuidedStepFragment to implement
a multi-step user UI on Android TV.
Updated with suggestions from Joe, Andrew, Dmitry and Dake.

Bug: 21209200
Change-Id: I8c1064b593466bf1373ed6c169343fe21afcaf9d
parent c9722f83

docs/html/images/training/tv/playback/guided-step-screen-2x.png

0 → 100644
+44.1 KiB
Loading image diff...

docs/html/images/training/tv/playback/guided-step-screen.png

0 → 100644
+17.8 KiB
Loading image diff...

docs/html/training/training_toc.cs

+4 −0
Original line number Diff line number Diff line
@@ -1098,6 +1098,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 → 100644
+259 −0
Original line number Diff line number Diff line 
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>
 
 No newline at end of file

docs/html/training/tv/playback/index.jd

+4 −0
Original line number Diff line number Diff line
@@ -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>