java.lang.Object | ||
↳ | android.app.Fragment | |
↳ | android.support.v17.leanback.app.GuidedStepFragment |
A GuidedStepFragment is used to guide the user through a decision or series of decisions. It is composed of a guidance view on the left and a view on the right containing a list of possible actions.
Clients of GuidedStepFragment typically create a custom subclass to attach to their Activities. This custom subclass provides the information necessary to construct the user interface and respond to user actions. At a minimum, subclasses should override:
onCreateGuidance(Bundle)
, to provide instructions to the useronCreateActions(List, Bundle)
, to provide a set of GuidedAction
s the user can takeonGuidedActionClicked(GuidedAction)
, to respond to those actions
GuidedStepFragment delegates its visual styling to classes called stylists. The GuidanceStylist
is responsible for the left guidance view, while the GuidedActionsStylist
is responsible for the right actions view. The stylists use theme
attributes to derive values associated with the presentation, such as colors, animations, etc.
Most simple visual aspects of GuidanceStylist and GuidedActionsStylist can be customized
via theming; see their documentation for more information.
GuidedStepFragments must have access to an appropriate theme in order for the stylists to
function properly. Specifically, the fragment must receive Theme_Leanback_GuidedStep
, or a theme whose parent is
is set to that theme. Themes can be provided in one of three ways:
LeanbackGuidedStepTheme_guidedStepTheme
. If present,
this theme will be used by GuidedStepFragment as an overlay to the Activity's theme.onProvideTheme()
method. This can be useful if a subclass is used across multiple
Activities.If the theme is provided in multiple ways, the onProvideTheme override has priority, followed by the Activty's theme. (Themes whose parent theme is already set to the guided step theme do not need to set the guidedStepTheme attribute; if set, it will be ignored.)
If themes do not provide enough customizability, the stylists themselves may be subclassed and
provided to the GuidedStepFragment through the onCreateGuidanceStylist()
and onCreateActionsStylist()
methods. The stylists have simple hooks so that subclasses
may override layout files; subclasses may also have more complex logic to determine styling.
GuidedStepFragments can be grouped together to provide a guided sequence. GuidedStepFragments
grouped as a sequence use custom animations provided by GuidanceStylist
and
GuidedActionsStylist
(or subclasses) during transitions between steps. Clients
should use add(FragmentManager, GuidedStepFragment)
to place subsequent GuidedFragments onto the fragment stack so that
custom animations are properly configured. (Custom animations are triggered automatically when
the fragment stack is subsequently popped by any normal mechanism.)
Note: Currently GuidedStepFragments grouped in this way must all be defined programmatically, rather than in XML. This restriction may be removed in the future.
XML Attributes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
android.support.v17.leanback:guidedStepTheme | Theme attribute for the overall theme used in a GuidedStepFragment. |
[Expand]
Inherited XML Attributes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Fragment
|
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From interface
android.content.ComponentCallbacks2
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds the specified GuidedStepFragment to the fragment stack, replacing any existing
GuidedStepFragments in the stack, and configuring the fragment-to-fragment custom animations.
| |||||||||||
Returns the view corresponding to the action at the indicated position in the list of
actions for this fragment.
| |||||||||||
Returns the list of GuidedActions that the user may take in this fragment.
| |||||||||||
Returns the current GuidedStepFragment on the fragment transaction stack.
| |||||||||||
Returns the GuidanceStylist that displays guidance information for the user.
| |||||||||||
Returns the GuidedActionsStylist that displays the actions the user may take.
| |||||||||||
Returns the position if the currently selected GuidedAction.
| |||||||||||
Called to do initial creation of a fragment.
| |||||||||||
Fills out the set of actions available to the user.
| |||||||||||
Creates the presenter used to style the guided actions panel.
| |||||||||||
Called when a fragment loads an animation.
| |||||||||||
Returns the information required to provide guidance to the user.
| |||||||||||
Creates the presenter used to style the guidance panel.
| |||||||||||
Called to have the fragment instantiate its user interface view.
| |||||||||||
Callback invoked when an action is taken by the user.
| |||||||||||
Callback invoked when an action is focused (made to be the current selection) by the user.
| |||||||||||
Returns the theme used for styling the fragment.
| |||||||||||
Called to ask the fragment to save its current dynamic state, so it
can later be reconstructed in a new instance of its process is
restarted.
| |||||||||||
Called when the Fragment is visible to the user.
| |||||||||||
Sets the list of GuidedActions that the user may take in this fragment.
| |||||||||||
Scrolls the action list to the position indicated, selecting that action's view.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns whether entry transitions are enabled for this fragment.
| |||||||||||
Sets whether entry transitions are enabled for this fragment.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Fragment
| |||||||||||
From class
java.lang.Object
| |||||||||||
From interface
android.content.ComponentCallbacks2
| |||||||||||
From interface
android.view.View.OnCreateContextMenuListener
| |||||||||||
From interface
android.support.v17.leanback.app.GuidedActionAdapter.ClickListener
| |||||||||||
From interface
android.support.v17.leanback.app.GuidedActionAdapter.FocusListener
| |||||||||||
From interface
android.content.ComponentCallbacks
|
Theme attribute for the overall theme used in a GuidedStepFragment. The Leanback themes
set the default for this, but a custom theme that does not derive from a leanback theme
can set this to @style/Theme.Leanback.GuidedStep
in order to specify the
default GuidedStepFragment styles.
Must be a reference to another resource, in the form "@[+][package:]type:name
"
or to a theme attribute in the form "?[package:][type:]name
".
This is a private symbol.
Adds the specified GuidedStepFragment to the fragment stack, replacing any existing GuidedStepFragments in the stack, and configuring the fragment-to-fragment custom animations.
Note: currently fragments added using this method must be created programmatically rather than via XML.
fragmentManager | The FragmentManager to be used in the transaction. |
---|---|
fragment | The GuidedStepFragment to be inserted into the fragment stack. |
Returns the view corresponding to the action at the indicated position in the list of actions for this fragment.
position | The integer position of the action of interest. |
---|
Returns the list of GuidedActions that the user may take in this fragment.
Returns the current GuidedStepFragment on the fragment transaction stack.
Returns the GuidanceStylist that displays guidance information for the user.
Returns the GuidedActionsStylist that displays the actions the user may take.
Returns the position if the currently selected GuidedAction.
Called to do initial creation of a fragment. This is called after
onAttach(Activity)
and before
onCreateView(LayoutInflater, ViewGroup, Bundle)
.
Note that this can be called while the fragment's activity is
still in the process of being created. As such, you can not rely
on things like the activity's content view hierarchy being initialized
at this point. If you want to do work once the activity itself is
created, see onActivityCreated(Bundle)
.
savedInstanceState | If the fragment is being re-created from a previous saved state, this is the state. |
---|
Fills out the set of actions available to the user. This hook is called during onCreate(Bundle)
. The default leaves the list of actions empty; subclasses should override.
actions | A non-null, empty list ready to be populated. |
---|---|
savedInstanceState | The saved instance state from onCreate. |
Creates the presenter used to style the guided actions panel. The default implementation returns a basic GuidedActionsStylist.
Called when a fragment loads an animation.
Returns the information required to provide guidance to the user. This hook is called during
onCreateView(LayoutInflater, ViewGroup, Bundle)
. May be overridden to return a custom subclass of GuidanceStylist.Guidance
for use in a subclass of GuidanceStylist
. The default
returns a Guidance object with empty fields; subclasses should override.
savedInstanceState | The saved instance state from onCreateView. |
---|
Creates the presenter used to style the guidance panel. The default implementation returns a basic GuidanceStylist.
Called to have the fragment instantiate its user interface view.
This is optional, and non-graphical fragments can return null (which
is the default implementation). This will be called between
onCreate(Bundle)
and onActivityCreated(Bundle)
.
If you return a View from here, you will later be called in
onDestroyView()
when the view is being released.
inflater | The LayoutInflater object that can be used to inflate any views in the fragment, |
---|---|
container | If non-null, this is the parent view that the fragment's UI should be attached to. The fragment should not add the view itself, but this can be used to generate the LayoutParams of the view. |
savedInstanceState | If non-null, this fragment is being re-constructed from a previous saved state as given here. |
Callback invoked when an action is taken by the user. Subclasses should override in order to act on the user's decisions.
action | The chosen action. |
---|
Callback invoked when an action is focused (made to be the current selection) by the user.
Returns the theme used for styling the fragment. The default returns -1, indicating that the host Activity's theme should be used.
Called to ask the fragment to save its current dynamic state, so it
can later be reconstructed in a new instance of its process is
restarted. If a new instance of the fragment later needs to be
created, the data you place in the Bundle here will be available
in the Bundle given to onCreate(Bundle)
,
onCreateView(LayoutInflater, ViewGroup, Bundle)
, and
onActivityCreated(Bundle)
.
This corresponds to Activity.onSaveInstanceState(Bundle)
and most of the discussion there
applies here as well. Note however: this method may be called
at any time before onDestroy()
. There are many situations
where a fragment may be mostly torn down (such as when placed on the
back stack with no UI showing), but its state will not be saved until
its owning activity actually needs to save its state.
outState | Bundle in which to place your saved state. |
---|
Called when the Fragment is visible to the user. This is generally
tied to Activity.onStart
of the containing
Activity's lifecycle.
Sets the list of GuidedActions that the user may take in this fragment.
actions | The list of GuidedActions for this fragment. |
---|
Scrolls the action list to the position indicated, selecting that action's view.
position | The integer position of the action of interest. |
---|
Returns whether entry transitions are enabled for this fragment.
Sets whether entry transitions are enabled for this fragment.
enabled | Whether to enable entry transitions for this fragment. |
---|