GuidedActionsStylist

Artifact: androidx.leanback:leanback

View Source

Added in 1.1.0

---

Kotlin |Java

public class GuidedActionsStylist implements FragmentAnimationProvider

---

GuidedActionsStylist is used within a androidx.leanback.app.GuidedStepFragment to supply the right-side panel where users can take actions. It consists of a container for the list of actions, and a stationary selector view that indicates visually the location of focus. GuidedActionsStylist has two different layouts: default is for normal actions including text, radio, checkbox, DatePicker, etc, the other when setAsButtonActions is called is recommended for button actions such as "yes", "no".

Many aspects of the base GuidedActionsStylist can be customized through theming; see the theme attributes below. Note that these attributes are not set on individual elements in layout XML, but instead would be set in a custom theme. See Styles and Themes for more information.

If these hooks are insufficient, this class may also be subclassed. Subclasses may wish to override the onProvideLayoutId method to change the layout used to display the list container and selector; override onProvideItemLayoutId and getItemViewType method to change the layout used to display each action.

To support a "click to activate" view similar to DatePicker, app needs:

• Override onProvideItemLayoutId and getItemViewType, provides a layout id for the action.
• The layout must include a widget with id "guidedactions_activator_item", the widget is toggled edit mode by setActivated.
• Override onBindActivatorView to populate values into View.
• Override onUpdateActivatorView to update action.

Note: If an alternate list layout is provided, the following view IDs must be supplied:

• guidedactions_list

These view IDs must be present in order for the stylist to function. The list ID must correspond to a VerticalGridView or subclass.

If an alternate item layout is provided, the following view IDs should be used to refer to base elements:

• guidedactions_item_content
• guidedactions_item_title
• guidedactions_item_description
• guidedactions_item_icon
• guidedactions_item_checkmark
• guidedactions_item_chevron

These view IDs are allowed to be missing, in which case the corresponding views in will be null.

In order to support editable actions, the view associated with guidedactions_item_title should be a subclass of android.widget.EditText, and should satisfy the interface and GuidedActionAutofillSupport interface. guidedStepImeAppearingAnimationguidedStepImeDisappearingAnimationguidedActionsSelectorDrawableguidedActionsListStyleguidedSubActionsListStyleguidedButtonActionsListStyleguidedActionItemContainerStyleguidedActionItemCheckmarkStyleguidedActionItemIconStyleguidedActionItemContentStyleguidedActionItemTitleStyleguidedActionItemDescriptionStyleguidedActionItemChevronStyleguidedActionPressedAnimationguidedActionUnpressedAnimationguidedActionEnabledChevronAlphaguidedActionDisabledChevronAlphaguidedActionTitleMinLinesguidedActionTitleMaxLinesguidedActionDescriptionMinLinesguidedActionVerticalPadding

See also
listChoiceIndicatorSingle
listChoiceIndicatorMultiple
GuidedStepFragment
GuidedAction

Summary

Nested types
public class GuidedActionsStylist.ViewHolder extends RecyclerView.ViewHolder implements FacetProvider ViewHolder caches information about the action item layouts' subviews.

Constants
static final int	VIEW_TYPE_DATE_PICKER = 1 ViewType for DatePicker.
static final int	VIEW_TYPE_DEFAULT = 0 Default viewType that associated with default layout Id for the action item.

Public constructors
GuidedActionsStylist()

Public methods
void	collapseAction(boolean withTransition) Collapse expanded action.
void	expandAction(@NonNull GuidedAction action, boolean withTransition) Expand an action.
@Nullable VerticalGridView	getActionsGridView() Returns the VerticalGridView that displays the list of GuidedActions.
@Nullable GuidedAction	getExpandedAction()
int	getItemViewType(@NonNull GuidedAction action) Return view type of action, each different type can have differently associated layout Id.
@Nullable VerticalGridView	getSubActionsGridView() Returns the VerticalGridView that displays the sub actions list of an expanded action.
final boolean	isBackKeyToCollapseActivatorView()
final boolean	isBackKeyToCollapseSubActions()
boolean	isButtonActions() Returns true if it is button actions list, false for normal actions list.
boolean	isExpandTransitionSupported() Returns if expand/collapse animation is supported.
boolean	isExpanded()
boolean	isInExpandTransition() Returns true if it is running an expanding or collapsing transition, false otherwise.
boolean	isSubActionsExpanded()
void	onAnimateItemChecked(     @NonNull GuidedActionsStylist.ViewHolder vh,     boolean checked ) Animates the view holder's view (or subviews thereof) when the action has had its check state changed.
void	onAnimateItemFocused(     @NonNull GuidedActionsStylist.ViewHolder vh,     boolean focused ) Animates the view holder's view (or subviews thereof) when the action has had its focus state changed.
void	onAnimateItemPressed(     @NonNull GuidedActionsStylist.ViewHolder vh,     boolean pressed ) Animates the view holder's view (or subviews thereof) when the action has had its press state changed.
void	onAnimateItemPressedCancelled(     @NonNull GuidedActionsStylist.ViewHolder vh ) Resets the view holder's view to unpressed state.
void	onBindActivatorView(     @NonNull GuidedActionsStylist.ViewHolder vh,     @NonNull GuidedAction action ) Performs binding activator view value to action.
void	onBindCheckMarkView(     @NonNull GuidedActionsStylist.ViewHolder vh,     @NonNull GuidedAction action ) Sets states of check mark view, called by onBindViewHolder when action's checkset Id is other than NO_CHECK_SET.
void	onBindChevronView(     @NonNull GuidedActionsStylist.ViewHolder vh,     @NonNull GuidedAction action ) Sets states of chevron view, called by onBindViewHolder.
void	onBindViewHolder(     @NonNull GuidedActionsStylist.ViewHolder vh,     @NonNull GuidedAction action ) Binds a ViewHolder to a particular GuidedAction.
@NonNull View	onCreateView(     @NonNull LayoutInflater inflater,     @NonNull ViewGroup container ) Creates a view appropriate for displaying a list of GuidedActions, using the provided inflater and container.
@NonNull GuidedActionsStylist.ViewHolder	onCreateViewHolder(@NonNull ViewGroup parent) Constructs a ViewHolder capable of representing GuidedActions.
@NonNull GuidedActionsStylist.ViewHolder	onCreateViewHolder(@NonNull ViewGroup parent, int viewType) Constructs a ViewHolder capable of representing GuidedActions.
void	onDestroyView() Called when destroy the View created by GuidedActionsStylist.
void	onImeAppearing(@NonNull List<Animator> animators) Animates the fragment in response to the IME appearing.
void	onImeDisappearing(@NonNull List<Animator> animators) Animates the fragment in response to the IME disappearing.
int	onProvideItemLayoutId() Provides the resource ID of the layout defining the view for an individual guided actions.
int	onProvideItemLayoutId(int viewType) Provides the resource ID of the layout defining the view for an individual guided actions.
int	onProvideLayoutId() Provides the resource ID of the layout defining the host view for the list of guided actions.
boolean	onUpdateActivatorView(     @NonNull GuidedActionsStylist.ViewHolder vh,     @NonNull GuidedAction action ) Performs updating GuidedAction from activator view.
void	onUpdateExpandedViewHolder(     @Nullable GuidedActionsStylist.ViewHolder avh ) Expand or collapse GuidedActionStylist.
void	openInEditMode(@NonNull GuidedAction action) Switches action to edit mode and pops up the keyboard.
void	setAsButtonActions() Choose the layout resource for button actions in onProvideLayoutId.
final void	setBackKeyToCollapseActivatorView(boolean backToCollapse) Enable or disable using BACK key to collapse GuidedAction with editable activator view.
final void	setBackKeyToCollapseSubActions(boolean backToCollapse) Enable or disable using BACK key to collapse sub actions list.
void	setEditingMode(     GuidedActionsStylist.ViewHolder vh,     GuidedAction action,     boolean editing ) This method is deprecated. This method is for internal library use only and should not be called directly.
void	setExpandedViewHolder(GuidedActionsStylist.ViewHolder avh) This method is deprecated. use expandAction and collapseAction
void	startExpandedTransition(GuidedActionsStylist.ViewHolder avh) This method is deprecated. use expandAction and collapseAction

Protected methods
void	onEditingModeChange(     GuidedActionsStylist.ViewHolder vh,     GuidedAction action,     boolean editing ) This method is deprecated. Use onEditingModeChange.
void	@CallSuper onEditingModeChange(     @NonNull GuidedActionsStylist.ViewHolder vh,     boolean editing,     boolean withTransition ) Called when editing mode of an ViewHolder is changed.
void	setupImeOptions(     @NonNull GuidedActionsStylist.ViewHolder vh,     @NonNull GuidedAction action ) Called by onBindViewHolder to setup IME options.

Constants

VIEW_TYPE_DATE_PICKER

Added in 1.1.0

public static final int VIEW_TYPE_DATE_PICKER = 1

ViewType for DatePicker.

VIEW_TYPE_DEFAULT

Added in 1.1.0

public static final int VIEW_TYPE_DEFAULT = 0

Default viewType that associated with default layout Id for the action item.

See also
getItemViewType
onProvideItemLayoutId
onCreateViewHolder

Public constructors

GuidedActionsStylist

Added in 1.1.0

public GuidedActionsStylist()

Public methods

collapseAction

Added in 1.1.0

public void collapseAction(boolean withTransition)

Collapse expanded action. Do nothing if it is in animation or there is no action expanded.

Parameters
boolean withTransition	True to run transition animation, false otherwsie.

expandAction

Added in 1.1.0

public void expandAction(@NonNull GuidedAction action, boolean withTransition)

Expand an action. Do nothing if it is in animation or there is action expanded.

Parameters
@NonNull GuidedAction action	Action to expand.
boolean withTransition	True to run transition animation, false otherwsie.

getActionsGridView

Added in 1.1.0

public @Nullable VerticalGridView getActionsGridView()

Returns the VerticalGridView that displays the list of GuidedActions.

Returns
@Nullable VerticalGridView	The VerticalGridView for this presenter.

getExpandedAction

Added in 1.1.0

public @Nullable GuidedAction getExpandedAction()

Returns
@Nullable GuidedAction	Current expanded GuidedAction or null if not expanded.

getItemViewType

Added in 1.1.0

public int getItemViewType(@NonNull GuidedAction action)

Return view type of action, each different type can have differently associated layout Id. Default implementation returns VIEW_TYPE_DEFAULT.

Parameters
@NonNull GuidedAction action	The action object.

Returns
int	View type that used in onProvideItemLayoutId.

getSubActionsGridView

Added in 1.1.0

public @Nullable VerticalGridView getSubActionsGridView()

Returns the VerticalGridView that displays the sub actions list of an expanded action.

Returns
@Nullable VerticalGridView	The VerticalGridView that displays the sub actions list of an expanded action.

isBackKeyToCollapseActivatorView

Added in 1.1.0

public final boolean isBackKeyToCollapseActivatorView()

Returns
boolean	True if using BACK key to collapse GuidedAction with editable activator view, false otherwise. Default value is true.

See also
hasEditableActivatorView

isBackKeyToCollapseSubActions

Added in 1.1.0

public final boolean isBackKeyToCollapseSubActions()

Returns
boolean	True if using BACK key to collapse sub actions list, false otherwise. Default value is true.

See also
hasSubActions
getSubActions

isButtonActions

Added in 1.1.0

public boolean isButtonActions()

Returns true if it is button actions list, false for normal actions list.

Returns
boolean	True if it is button actions list, false for normal actions list.

isExpandTransitionSupported

Added in 1.1.0

public boolean isExpandTransitionSupported()

Returns if expand/collapse animation is supported. When this method returns true, startExpandedTransition will be used. When this method returns false, onUpdateExpandedViewHolder will be called.

Returns
boolean	True if it is running an expanding or collapsing transition, false otherwise.

isExpanded

Added in 1.1.0

public boolean isExpanded()

Returns
boolean	True if there is getExpandedAction is not null, false otherwise.

isInExpandTransition

Added in 1.1.0

public boolean isInExpandTransition()

Returns true if it is running an expanding or collapsing transition, false otherwise.

Returns
boolean	True if it is running an expanding or collapsing transition, false otherwise.

isSubActionsExpanded

Added in 1.1.0

public boolean isSubActionsExpanded()

Returns
boolean	True if sub actions list is expanded.

onAnimateItemChecked

Added in 1.1.0

public void onAnimateItemChecked(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    boolean checked
)

Animates the view holder's view (or subviews thereof) when the action has had its check state changed. Default implementation calls setChecked() if getCheckmarkView is instance of Checkable.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder associated with the relevant action.
boolean checked	True if the action has become checked, false if it has become unchecked.

See also
onBindCheckMarkView

onAnimateItemFocused

Added in 1.1.0

public void onAnimateItemFocused(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    boolean focused
)

Animates the view holder's view (or subviews thereof) when the action has had its focus state changed.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder associated with the relevant action.
boolean focused	True if the action has become focused, false if it has lost focus.

onAnimateItemPressed

Added in 1.1.0

public void onAnimateItemPressed(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    boolean pressed
)

Animates the view holder's view (or subviews thereof) when the action has had its press state changed.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder associated with the relevant action.
boolean pressed	True if the action has been pressed, false if it has been unpressed.

onAnimateItemPressedCancelled

Added in 1.1.0

public void onAnimateItemPressedCancelled(
    @NonNull GuidedActionsStylist.ViewHolder vh
)

Resets the view holder's view to unpressed state.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder associated with the relevant action.

onBindActivatorView

Added in 1.1.0

public void onBindActivatorView(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    @NonNull GuidedAction action
)

Performs binding activator view value to action. Default implementation supports GuidedDatePickerAction, subclass may override to add support of other views.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	ViewHolder of activator view.
@NonNull GuidedAction action	GuidedAction to bind.

onBindCheckMarkView

Added in 1.1.0

public void onBindCheckMarkView(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    @NonNull GuidedAction action
)

Sets states of check mark view, called by onBindViewHolder when action's checkset Id is other than NO_CHECK_SET. Default implementation assigns drawable loaded from theme attribute listChoiceIndicatorMultiple for checkbox or listChoiceIndicatorSingle for radio button. Subclass rarely needs override the method, instead app can provide its own drawable that supports transition animations, change theme attributes listChoiceIndicatorMultiple and listChoiceIndicatorSingle in {androidx.leanback.R. styleable#LeanbackGuidedStepTheme}.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder associated with the relevant action.
@NonNull GuidedAction action	The GuidedAction object to bind to.

See also
onAnimateItemChecked

onBindChevronView

Added in 1.1.0

public void onBindChevronView(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    @NonNull GuidedAction action
)

Sets states of chevron view, called by onBindViewHolder. Subclass may override.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder associated with the relevant action.
@NonNull GuidedAction action	The GuidedAction object to bind to.

onBindViewHolder

Added in 1.1.0

public void onBindViewHolder(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    @NonNull GuidedAction action
)

Binds a ViewHolder to a particular GuidedAction.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder to be associated with the given action.
@NonNull GuidedAction action	The guided action to be displayed by the view holder's view.

Returns
void	The view to be added to the caller's view hierarchy.

onCreateView

Added in 1.1.0

public @NonNull View onCreateView(
    @NonNull LayoutInflater inflater,
    @NonNull ViewGroup container
)

Creates a view appropriate for displaying a list of GuidedActions, using the provided inflater and container.

Note: Does not actually add the created view to the container; the caller should do this.

Parameters
@NonNull LayoutInflater inflater	The layout inflater to be used when constructing the view.
@NonNull ViewGroup container	The view group to be passed in the call to LayoutInflater.inflate.

Returns
@NonNull View	The view to be added to the caller's view hierarchy.

onCreateViewHolder

Added in 1.1.0

public @NonNull GuidedActionsStylist.ViewHolder onCreateViewHolder(@NonNull ViewGroup parent)

Constructs a ViewHolder capable of representing GuidedActions. Subclasses may choose to return a subclass of ViewHolder. To support different view types, override onCreateViewHolder

Note: Should not actually add the created view to the parent; the caller will do this.

Parameters
@NonNull ViewGroup parent	The view group to be used as the parent of the new view.

Returns
@NonNull GuidedActionsStylist.ViewHolder	The view to be added to the caller's view hierarchy.

onCreateViewHolder

Added in 1.1.0

public @NonNull GuidedActionsStylist.ViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType)

Constructs a ViewHolder capable of representing GuidedActions. Subclasses may choose to return a subclass of ViewHolder.

Note: Should not actually add the created view to the parent; the caller will do this.

Parameters
@NonNull ViewGroup parent	The view group to be used as the parent of the new view.
int viewType	The viewType returned by getItemViewType

Returns
@NonNull GuidedActionsStylist.ViewHolder	The view to be added to the caller's view hierarchy.

onDestroyView

Added in 1.1.0

public void onDestroyView()

Called when destroy the View created by GuidedActionsStylist.

onImeAppearing

Added in 1.2.0-alpha04

public void onImeAppearing(@NonNull List<Animator> animators)

Animates the fragment in response to the IME appearing.

onImeDisappearing

Added in 1.2.0-alpha04

public void onImeDisappearing(@NonNull List<Animator> animators)

Animates the fragment in response to the IME disappearing.

onProvideItemLayoutId

Added in 1.1.0

public int onProvideItemLayoutId()

Provides the resource ID of the layout defining the view for an individual guided actions. Subclasses may override to provide their own customized layouts. The base implementation returns lb_guidedactions_item. If overridden, the substituted layout should contain matching IDs for any views that should be managed by the base class; this can be achieved by starting with a copy of the base layout file. Note that in order for the item to support editing, the title view should both subclass and implement ImeKeyMonitor, GuidedActionAutofillSupport; see . To support different types of Layouts, override onProvideItemLayoutId.

Returns
int	The resource ID of the layout to be inflated to define the view to display an individual GuidedAction.

onProvideItemLayoutId

Added in 1.1.0

public int onProvideItemLayoutId(int viewType)

Provides the resource ID of the layout defining the view for an individual guided actions. Subclasses may override to provide their own customized layouts. The base implementation supports:

• lb_guidedactions_item
• {lb_guidedactions_datepicker_item.

If overridden, the substituted layout should contain matching IDs for any views that should be managed by the base class; this can be achieved by starting with a copy of the base layout file. Note that in order for the item to support editing, the title view should both subclass android.widget.EditText and implement ImeKeyMonitor; see GuidedActionEditText.

Parameters
int viewType	View type returned by getItemViewType

Returns
int	The resource ID of the layout to be inflated to define the view to display an individual GuidedAction.

onProvideLayoutId

Added in 1.1.0

public int onProvideLayoutId()

Provides the resource ID of the layout defining the host view for the list of guided actions. Subclasses may override to provide their own customized layouts. The base implementation returns lb_guidedactions or lb_guidedbuttonactions if isButtonActions is true. If overridden, the substituted layout should contain matching IDs for any views that should be managed by the base class; this can be achieved by starting with a copy of the base layout file.

Returns
int	The resource ID of the layout to be inflated to define the host view for the list of GuidedActions.

onUpdateActivatorView

Added in 1.1.0

public boolean onUpdateActivatorView(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    @NonNull GuidedAction action
)

Performs updating GuidedAction from activator view. Default implementation supports GuidedDatePickerAction, subclass may override to add support of other views.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	ViewHolder of activator view.
@NonNull GuidedAction action	GuidedAction to update.

Returns
boolean	True if value has been updated, false otherwise.

onUpdateExpandedViewHolder

Added in 1.1.0

public void onUpdateExpandedViewHolder(
    @Nullable GuidedActionsStylist.ViewHolder avh
)

Expand or collapse GuidedActionStylist.

Parameters
@Nullable GuidedActionsStylist.ViewHolder avh	When not null, the GuidedActionStylist expands the sub actions of avh. When null the GuidedActionStylist will collapse sub actions.

openInEditMode

Added in 1.1.0

public void openInEditMode(@NonNull GuidedAction action)

Switches action to edit mode and pops up the keyboard.

setAsButtonActions

Added in 1.1.0

public void setAsButtonActions()

Choose the layout resource for button actions in onProvideLayoutId.

setBackKeyToCollapseActivatorView

Added in 1.1.0

public final void setBackKeyToCollapseActivatorView(boolean backToCollapse)

Enable or disable using BACK key to collapse GuidedAction with editable activator view. Default is enabled.

Parameters
boolean backToCollapse	True to enable using BACK key to collapse GuidedAction with editable activator view.

See also
hasEditableActivatorView

setBackKeyToCollapseSubActions

Added in 1.1.0

public final void setBackKeyToCollapseSubActions(boolean backToCollapse)

Enable or disable using BACK key to collapse sub actions list. Default is enabled.

Parameters
boolean backToCollapse	True to enable using BACK key to collapse sub actions list, false to disable.

See also
hasSubActions
getSubActions

setEditingMode

Added in 1.1.0

Deprecated in 1.1.0

public void setEditingMode(
    GuidedActionsStylist.ViewHolder vh,
    GuidedAction action,
    boolean editing
)

This method is deprecated.

This method is for internal library use only and should not be called directly.

setExpandedViewHolder

Added in 1.1.0

Deprecated in 1.1.0

public void setExpandedViewHolder(GuidedActionsStylist.ViewHolder avh)

This method is deprecated.

use expandAction and collapseAction

Expands or collapse the sub actions list view with transition animation

Parameters
GuidedActionsStylist.ViewHolder avh	When not null, fill sub actions list of this ViewHolder into sub actions list and hide the other items in main list. When null, collapse the sub actions list.

startExpandedTransition

Added in 1.1.0

Deprecated in 1.1.0

public void startExpandedTransition(GuidedActionsStylist.ViewHolder avh)

This method is deprecated.

use expandAction and collapseAction

Start transition to expand or collapse GuidedActionStylist.

Parameters
GuidedActionsStylist.ViewHolder avh	When not null, the GuidedActionStylist expands the sub actions of avh. When null the GuidedActionStylist will collapse sub actions.

Protected methods

onEditingModeChange

Added in 1.1.0

Deprecated in 1.1.0

protected void onEditingModeChange(
    GuidedActionsStylist.ViewHolder vh,
    GuidedAction action,
    boolean editing
)

This method is deprecated.

Use onEditingModeChange.

onEditingModeChange

Added in 1.1.0

@CallSuper
protected void onEditingModeChange(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    boolean editing,
    boolean withTransition
)

Called when editing mode of an ViewHolder is changed. Subclass must call super.onEditingModeChange(vh,editing,withTransition).

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	ViewHolder to change editing mode.
boolean editing	True to enable editing, false to stop editing
boolean withTransition	True to run expand transiiton, false otherwise.

setupImeOptions

Added in 1.1.0

protected void setupImeOptions(
    @NonNull GuidedActionsStylist.ViewHolder vh,
    @NonNull GuidedAction action
)

Called by onBindViewHolder to setup IME options. Default implementation assigns IME_ACTION_DONE. Subclass may override.

Parameters
@NonNull GuidedActionsStylist.ViewHolder vh	The view holder to be associated with the given action.
@NonNull GuidedAction action	The guided action to be displayed by the view holder's view.