GuidedActionsStylist

class GuidedActionsStylist : 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:

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

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:

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

Summary

Nested types

ViewHolder caches information about the action item layouts' subviews.

Constants

const Int

ViewType for DatePicker.

const Int

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

Public constructors

Public functions

Unit
collapseAction(withTransition: Boolean)

Collapse expanded action.

Unit
expandAction(action: GuidedAction, withTransition: Boolean)

Expand an action.

VerticalGridView?

Returns the VerticalGridView that displays the list of GuidedActions.

GuidedAction?
Int

Return view type of action, each different type can have differently associated layout Id.

VerticalGridView?

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

Boolean
Boolean
Boolean

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

Boolean

Returns if expand/collapse animation is supported.

Boolean
Boolean

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

Boolean
Unit

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

Unit

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

Unit

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

Unit

Resets the view holder's view to unpressed state.

Unit

Performs binding activator view value to action.

Unit

Sets states of check mark view, called by onBindViewHolder when action's checkset Id is other than NO_CHECK_SET.

Unit

Sets states of chevron view, called by onBindViewHolder.

Unit

Binds a ViewHolder to a particular GuidedAction.

View
onCreateView(inflater: LayoutInflater, container: ViewGroup)

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

GuidedActionsStylist.ViewHolder

Constructs a ViewHolder capable of representing GuidedActions.

GuidedActionsStylist.ViewHolder
onCreateViewHolder(parent: ViewGroup, viewType: Int)

Constructs a ViewHolder capable of representing GuidedActions.

Unit

Called when destroy the View created by GuidedActionsStylist.

Unit

Animates the fragment in response to the IME appearing.

Unit

Animates the fragment in response to the IME disappearing.

Int

Provides the resource ID of the layout defining the view for an individual guided actions.

Int

Provides the resource ID of the layout defining the view for an individual guided actions.

Int

Provides the resource ID of the layout defining the host view for the list of guided actions.

Boolean

Performs updating GuidedAction from activator view.

Unit

Expand or collapse GuidedActionStylist.

Unit

Switches action to edit mode and pops up the keyboard.

Unit

Choose the layout resource for button actions in onProvideLayoutId.

Unit

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

Unit

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

Unit
setEditingMode(
    vh: GuidedActionsStylist.ViewHolder!,
    action: GuidedAction!,
    editing: Boolean
)

This function is deprecated.

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

Unit

This function is deprecated.

use expandAction and collapseAction

Unit

This function is deprecated.

use expandAction and collapseAction

Protected functions

Unit
onEditingModeChange(
    vh: GuidedActionsStylist.ViewHolder!,
    action: GuidedAction!,
    editing: Boolean
)

This function is deprecated.

Use onEditingModeChange.

Unit
@CallSuper
onEditingModeChange(
    vh: GuidedActionsStylist.ViewHolder,
    editing: Boolean,
    withTransition: Boolean
)

Called when editing mode of an ViewHolder is changed.

Unit

Called by onBindViewHolder to setup IME options.

Constants

VIEW_TYPE_DATE_PICKER

Added in 1.1.0
const val VIEW_TYPE_DATE_PICKER = 1: Int

ViewType for DatePicker.

VIEW_TYPE_DEFAULT

Added in 1.1.0
const val VIEW_TYPE_DEFAULT = 0: Int

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

Public constructors

GuidedActionsStylist

Added in 1.1.0
GuidedActionsStylist()

Public functions

collapseAction

Added in 1.1.0
fun collapseAction(withTransition: Boolean): Unit

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

Parameters
withTransition: Boolean

True to run transition animation, false otherwsie.

expandAction

Added in 1.1.0
fun expandAction(action: GuidedAction, withTransition: Boolean): Unit

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

Parameters
action: GuidedAction

Action to expand.

withTransition: Boolean

True to run transition animation, false otherwsie.

getActionsGridView

Added in 1.1.0
fun getActionsGridView(): VerticalGridView?

Returns the VerticalGridView that displays the list of GuidedActions.

Returns
VerticalGridView?

The VerticalGridView for this presenter.

getExpandedAction

Added in 1.1.0
fun getExpandedAction(): GuidedAction?
Returns
GuidedAction?

Current expanded GuidedAction or null if not expanded.

getItemViewType

Added in 1.1.0
fun getItemViewType(action: GuidedAction): Int

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

Parameters
action: GuidedAction

The action object.

Returns
Int

View type that used in onProvideItemLayoutId.

getSubActionsGridView

Added in 1.1.0
fun getSubActionsGridView(): VerticalGridView?

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

Returns
VerticalGridView?

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

isBackKeyToCollapseActivatorView

Added in 1.1.0
fun isBackKeyToCollapseActivatorView(): Boolean
Returns
Boolean

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

isBackKeyToCollapseSubActions

Added in 1.1.0
fun isBackKeyToCollapseSubActions(): Boolean
Returns
Boolean

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

isButtonActions

Added in 1.1.0
fun isButtonActions(): Boolean

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
fun isExpandTransitionSupported(): Boolean

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
fun isExpanded(): Boolean
Returns
Boolean

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

isInExpandTransition

Added in 1.1.0
fun isInExpandTransition(): Boolean

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
fun isSubActionsExpanded(): Boolean
Returns
Boolean

True if sub actions list is expanded.

onAnimateItemChecked

Added in 1.1.0
fun onAnimateItemChecked(
    vh: GuidedActionsStylist.ViewHolder,
    checked: Boolean
): Unit

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
vh: GuidedActionsStylist.ViewHolder

The view holder associated with the relevant action.

checked: Boolean

True if the action has become checked, false if it has become unchecked.

onAnimateItemFocused

Added in 1.1.0
fun onAnimateItemFocused(
    vh: GuidedActionsStylist.ViewHolder,
    focused: Boolean
): Unit

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

Parameters
vh: GuidedActionsStylist.ViewHolder

The view holder associated with the relevant action.

focused: Boolean

True if the action has become focused, false if it has lost focus.

onAnimateItemPressed

Added in 1.1.0
fun onAnimateItemPressed(
    vh: GuidedActionsStylist.ViewHolder,
    pressed: Boolean
): Unit

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

Parameters
vh: GuidedActionsStylist.ViewHolder

The view holder associated with the relevant action.

pressed: Boolean

True if the action has been pressed, false if it has been unpressed.

onAnimateItemPressedCancelled

Added in 1.1.0
fun onAnimateItemPressedCancelled(vh: GuidedActionsStylist.ViewHolder): Unit

Resets the view holder's view to unpressed state.

Parameters
vh: GuidedActionsStylist.ViewHolder

The view holder associated with the relevant action.

onBindActivatorView

Added in 1.1.0
fun onBindActivatorView(
    vh: GuidedActionsStylist.ViewHolder,
    action: GuidedAction
): Unit

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

Parameters
vh: GuidedActionsStylist.ViewHolder

ViewHolder of activator view.

action: GuidedAction

GuidedAction to bind.

onBindCheckMarkView

Added in 1.1.0
fun onBindCheckMarkView(
    vh: GuidedActionsStylist.ViewHolder,
    action: GuidedAction
): Unit

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
vh: GuidedActionsStylist.ViewHolder

The view holder associated with the relevant action.

action: GuidedAction

The GuidedAction object to bind to.

onBindChevronView

Added in 1.1.0
fun onBindChevronView(
    vh: GuidedActionsStylist.ViewHolder,
    action: GuidedAction
): Unit

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

Parameters
vh: GuidedActionsStylist.ViewHolder

The view holder associated with the relevant action.

action: GuidedAction

The GuidedAction object to bind to.

onBindViewHolder

Added in 1.1.0
fun onBindViewHolder(
    vh: GuidedActionsStylist.ViewHolder,
    action: GuidedAction
): Unit

Binds a ViewHolder to a particular GuidedAction.

Parameters
vh: GuidedActionsStylist.ViewHolder

The view holder to be associated with the given action.

action: GuidedAction

The guided action to be displayed by the view holder's view.

Returns
Unit

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

onCreateView

Added in 1.1.0
fun onCreateView(inflater: LayoutInflater, container: ViewGroup): View

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
inflater: LayoutInflater

The layout inflater to be used when constructing the view.

container: ViewGroup

The view group to be passed in the call to LayoutInflater.inflate.

Returns
View

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

onCreateViewHolder

Added in 1.1.0
fun onCreateViewHolder(parent: ViewGroup): GuidedActionsStylist.ViewHolder

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
parent: ViewGroup

The view group to be used as the parent of the new view.

Returns
GuidedActionsStylist.ViewHolder

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

onCreateViewHolder

Added in 1.1.0
fun onCreateViewHolder(parent: ViewGroup, viewType: Int): GuidedActionsStylist.ViewHolder

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
parent: ViewGroup

The view group to be used as the parent of the new view.

viewType: Int

The viewType returned by getItemViewType

Returns
GuidedActionsStylist.ViewHolder

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

onDestroyView

Added in 1.1.0
fun onDestroyView(): Unit

Called when destroy the View created by GuidedActionsStylist.

onImeAppearing

Added in 1.2.0-alpha04
fun onImeAppearing(animators: (Mutable)List<Animator!>): Unit

Animates the fragment in response to the IME appearing.

onImeDisappearing

Added in 1.2.0-alpha04
fun onImeDisappearing(animators: (Mutable)List<Animator!>): Unit

Animates the fragment in response to the IME disappearing.

onProvideItemLayoutId

Added in 1.1.0
fun onProvideItemLayoutId(): Int

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
fun onProvideItemLayoutId(viewType: Int): Int

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:

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
viewType: Int

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
fun onProvideLayoutId(): Int

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
fun onUpdateActivatorView(
    vh: GuidedActionsStylist.ViewHolder,
    action: GuidedAction
): Boolean

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

Parameters
vh: GuidedActionsStylist.ViewHolder

ViewHolder of activator view.

action: GuidedAction

GuidedAction to update.

Returns
Boolean

True if value has been updated, false otherwise.

onUpdateExpandedViewHolder

Added in 1.1.0
fun onUpdateExpandedViewHolder(avh: GuidedActionsStylist.ViewHolder?): Unit

Expand or collapse GuidedActionStylist.

Parameters
avh: GuidedActionsStylist.ViewHolder?

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
fun openInEditMode(action: GuidedAction): Unit

Switches action to edit mode and pops up the keyboard.

setAsButtonActions

Added in 1.1.0
fun setAsButtonActions(): Unit

Choose the layout resource for button actions in onProvideLayoutId.

setBackKeyToCollapseActivatorView

Added in 1.1.0
fun setBackKeyToCollapseActivatorView(backToCollapse: Boolean): Unit

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

Parameters
backToCollapse: Boolean

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

setBackKeyToCollapseSubActions

Added in 1.1.0
fun setBackKeyToCollapseSubActions(backToCollapse: Boolean): Unit

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

Parameters
backToCollapse: Boolean

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

setEditingMode

Added in 1.1.0
Deprecated in 1.1.0
fun setEditingMode(
    vh: GuidedActionsStylist.ViewHolder!,
    action: GuidedAction!,
    editing: Boolean
): Unit

setExpandedViewHolder

Added in 1.1.0
Deprecated in 1.1.0
fun setExpandedViewHolder(avh: GuidedActionsStylist.ViewHolder!): Unit

Expands or collapse the sub actions list view with transition animation

Parameters
avh: GuidedActionsStylist.ViewHolder!

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
fun startExpandedTransition(avh: GuidedActionsStylist.ViewHolder!): Unit

Start transition to expand or collapse GuidedActionStylist.

Parameters
avh: GuidedActionsStylist.ViewHolder!

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

Protected functions

onEditingModeChange

Added in 1.1.0
Deprecated in 1.1.0
protected fun onEditingModeChange(
    vh: GuidedActionsStylist.ViewHolder!,
    action: GuidedAction!,
    editing: Boolean
): Unit

onEditingModeChange

Added in 1.1.0
@CallSuper
protected fun onEditingModeChange(
    vh: GuidedActionsStylist.ViewHolder,
    editing: Boolean,
    withTransition: Boolean
): Unit

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

Parameters
vh: GuidedActionsStylist.ViewHolder

ViewHolder to change editing mode.

editing: Boolean

True to enable editing, false to stop editing

withTransition: Boolean

True to run expand transiiton, false otherwise.

setupImeOptions

Added in 1.1.0
protected fun setupImeOptions(
    vh: GuidedActionsStylist.ViewHolder,
    action: GuidedAction
): Unit

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

Parameters
vh: GuidedActionsStylist.ViewHolder

The view holder to be associated with the given action.

action: GuidedAction

The guided action to be displayed by the view holder's view.