I heard you like settings..

The Leanback Support Library offers a variety of widgets that help us displaying multimedia content in a pleasing fashion. It basically rethinks what we’re used to on Android for smartphones/tablets (like ListViews, GridViews, NavigationDrawers, ..) and brings it to a big TV screen

, allowing users to navigate inside the app with its somewhat clumsy TV remote. What Leanback was missing is a way of guiding the user through a series of configurations steps: the app’s settings is the first example that comes to mind, but an introductory wizard may as well be another valid one.

This shortcoming has been addressed by

the latest version of the Support Library (22.1.+), by adding the GuidedStepFragment component. Its main purpose, according to the official docs, consists in “guiding the user through a decision or series of decisions”.

This is how GuidedStepFragment looks like in action (taken from Android TV’s own settings):

Using it is as easy as it looks. First things first, create a fragment that extends GuidedStepFragment:

public class SettingsFragment extends GuidedStepFragment {
  ..
}

Then, override the onCreateGuidance method and return a new Guidance instance:

@NonNull
@Override
public GuidanceStylist.Guidance onCreateGuidance(Bundle savedInstanceState) {
    return new GuidanceStylist.Guidance("Settings", null, "Demo", null);
}

Moving on, override the onCreateActions method and provide your own actions:

@Override
public void onCreateActions(@NonNull List<GuidedAction> actions, Bundle savedInstanceState) {
    actions.add(new GuidedAction.Builder()
            .id(R.id.settings_category_id)
            .infoOnly(true)
            .title("General Settings")
            .build());

    actions.add(new GuidedAction.Builder()
            .id(R.id.settings_action_id)
            .title("First action")
            .description("Some action")
            .build());
}

And finally, override the onGuidedActionClicked to actually do something when the user selects that action:

@Override
public void onGuidedActionClicked(GuidedAction action) {
    switch ((int) action.getId()) {
        case R.id.settings_action_id :
            // do something (anything, really) 
            break;
        default :
            break;
    }

You’re all set! One small thing that you need to be sure of is that GuidedStepFragment uses the Theme_Leanback_GuidedStep theme. The docs specify that there are several ways of doing so, but if you’re simply using Theme_Leanback, you’re good to go! Wondering why?

<style name="Theme.Leanback" parent="Theme.LeanbackBase">

..

<style name="Theme.LeanbackBase" parent="..">
    <item name="guidedStepTheme">@style/Theme.Leanback.GuidedStep</item>
</style>

..

<style name="Theme.Leanback.GuidedStep" parent="Theme.LeanbackBase">

You can customize nearly every aspect of GuidedStepFragment, by means of the *Stylist objects (e.g., GuidanceStylist), and you can even build a chain of steps to create some sort of wizard. If you’re interested, be sure to take a look at Google’s Leanback sample code!