RowPresenter

abstract class RowPresenter : Presenter

Known direct subclasses
AbstractMediaItemPresenter

Abstract Presenter class for rendering media items in a playlist format.

AbstractMediaListHeaderPresenter

Abstract presenter class for rendering the header for a list of media items in a playlist.

DetailsOverviewRowPresenter

This class is deprecated.

Use FullWidthDetailsOverviewRowPresenter

FullWidthDetailsOverviewRowPresenter

Renders a DetailsOverviewRow to display an overview of an item.

ListRowPresenter

ListRowPresenter renders ListRow using a HorizontalGridView hosted in a ListRowView.

PlaybackRowPresenter

Subclass of RowPresenter that can define the desired behavior when the view reappears.

Known indirect subclasses
PlaybackControlsRowPresenter

A PlaybackControlsRowPresenter renders a PlaybackControlsRow to display a series of playback control buttons.

PlaybackTransportRowPresenter

A PlaybackTransportRowPresenter renders a PlaybackControlsRow to display a series of playback control buttons.


An abstract Presenter that renders an Object in RowsFragment, the object can be subclass Row or a generic one. When the object is not Row class, getRow returns null.

Customize UI widgets

When a subclass of RowPresenter adds UI widgets, it should subclass RowPresenter.ViewHolder and override createRowViewHolder and initializeRowViewHolder. The subclass must use layout id "row_content" for the widget that will be aligned to the title of any HeadersFragment that may exist in the parent fragment. RowPresenter contains an optional and replaceable RowHeaderPresenter that renders the header. You can disable the default rendering or replace the Presenter with a new header presenter by calling setHeaderPresenter.

UI events from fragments

RowPresenter receives calls from its parent (typically a Fragment) when:
  • A row is selected via setRowViewSelected. The event is triggered immediately when there is a row selection change before the selection animation is started. Selected status may control activated status of the row (see "Activated status" below). Subclasses of RowPresenter may override onRowViewSelected.
  • A row is expanded to full height via setRowViewExpanded when BrowseFragment hides fast lane on the left. The event is triggered immediately before the expand animation is started. Row title is shown when row is expanded. Expanded status may control activated status of the row (see "Activated status" below). Subclasses of RowPresenter may override onRowViewExpanded.

Activated status

The activated status of a row is applied to the row view and its children via setActivated. The activated status is typically used to control BaseCardView info region visibility. The row's activated status can be controlled by selected status and/or expanded status. Call setSyncActivatePolicy and choose one of the four policies:

User events

RowPresenter provides OnItemViewSelectedListener and OnItemViewClickedListener. If a subclass wants to add its own View.OnFocusChangeListener or View.OnClickListener, it must do that in createRowViewHolder to be properly chained by the library. Adding View listeners after createRowViewHolder is undefined and may result in incorrect behavior by the library's listeners.

Selection animation

When a user scrolls through rows, a fragment will initiate animation and call setSelectLevel with float value between 0 and 1. By default, the RowPresenter draws a dim overlay on top of the row view for views that are not selected. Subclasses may override this default effect by having isUsingDefaultSelectEffect return false and overriding onSelectLevelChanged to apply a different selection effect.

Call setSelectEffectEnabled to enable/disable the select effect, This will not only enable/disable the default dim effect but also subclasses must respect this flag as well.

Summary

Nested types

A ViewHolder for a Row.

Constants

const Int

Don't synchronize row view activated status with selected status or expanded status, application will do its own through setActivated.

const Int

Synchronizes row view's activated status to expand status of the row view holder.

const Int

Sets the row view's activated status to true when both expand and selected are true.

const Int

Synchronizes row view's activated status to selected status of the row view holder.

Public constructors

Constructs a RowPresenter.

Public functions

Unit

Freezes/unfreezes the row, typically used when a transition starts/ends.

RowHeaderPresenter!

Returns the Presenter used for rendering the header, or null if none has been set.

RowPresenter.ViewHolder!

Returns the RowPresenter.ViewHolder from the given RowPresenter ViewHolder.

Boolean

Returns true if the row selection effect is enabled.

Float

Returns the current select level.

Int

Returns the policy of updating row view activated status.

Boolean

Returns true if this RowPresenter is using the default dimming effect.

Unit
onBindViewHolder(viewHolder: Presenter.ViewHolder, item: Any?)

Binds a View to an item.

Presenter.ViewHolder!

Creates a new View.

Unit

Unbinds a View from an item.

Unit

Called when a view created by this presenter has been attached to a window.

Unit

Called when a view created by this presenter has been detached from its window.

Unit
setEntranceTransitionState(
    holder: RowPresenter.ViewHolder,
    afterEntrance: Boolean
)

Changes the visibility of views.

Unit

Sets the Presenter used for rendering the header.

Unit

Sets the expanded state of a Row view.

Unit

Sets the selected state of a Row view.

Unit
setSelectEffectEnabled(applyDimOnSelect: Boolean)

Enables or disables the row selection effect.

Unit

Sets the current select level to a value between 0 (unselected) and 1 (selected).

Unit
setSyncActivatePolicy(syncActivatePolicy: Int)

Sets the policy of updating row view activated status.

Protected functions

abstract RowPresenter.ViewHolder

Called to create a ViewHolder object for a Row.

Unit

This method is only called from onRowViewSelected onRowViewSelected.

Unit

Called after a RowPresenter.ViewHolder is created for a Row.

Boolean

Returns true if the Row view should clip its children.

Unit

Binds the given row object to the given ViewHolder.

Unit

Invoked when the row view is attached to the window.

Unit

Invoked when the row view is detached from the window.

Unit

Called when the row view's expanded state changes.

Unit

Called when the given row view changes selection state.

Unit

Callback when the select level changes.

Unit

Unbinds the given ViewHolder.

Inherited functions

From androidx.leanback.widget.FacetProvider
abstract Any?
getFacet(facetClass: Class<Any!>)

Queries optional implemented facet.

From androidx.leanback.widget.Presenter
java-static Unit

Utility method for removing all running animations on a view.

Any!
getFacet(facetClass: Class<Any!>!)

Queries optional implemented facet.

Unit
onBindViewHolder(
    viewHolder: Presenter.ViewHolder,
    item: Any,
    payloads: (Mutable)List<Any!>
)

Binds a View to an item with a list of payloads.

Unit
setFacet(facetClass: Class<Any!>!, facetImpl: Any!)

Sets dynamic implemented facet in addition to basic Presenter functions.

Unit
setOnClickListener(
    holder: Presenter.ViewHolder!,
    listener: View.OnClickListener!
)

Called to set a click listener for the given view holder.

Constants

SYNC_ACTIVATED_CUSTOM

Added in 1.1.0
const val SYNC_ACTIVATED_CUSTOM = 0: Int

Don't synchronize row view activated status with selected status or expanded status, application will do its own through setActivated.

SYNC_ACTIVATED_TO_EXPANDED

Added in 1.1.0
const val SYNC_ACTIVATED_TO_EXPANDED = 1: Int

Synchronizes row view's activated status to expand status of the row view holder.

SYNC_ACTIVATED_TO_EXPANDED_AND_SELECTED

Added in 1.1.0
const val SYNC_ACTIVATED_TO_EXPANDED_AND_SELECTED = 3: Int

Sets the row view's activated status to true when both expand and selected are true.

SYNC_ACTIVATED_TO_SELECTED

Added in 1.1.0
const val SYNC_ACTIVATED_TO_SELECTED = 2: Int

Synchronizes row view's activated status to selected status of the row view holder.

Public constructors

RowPresenter

Added in 1.1.0
RowPresenter()

Constructs a RowPresenter.

Public functions

freeze

Added in 1.1.0
fun freeze(holder: RowPresenter.ViewHolder, freeze: Boolean): Unit

Freezes/unfreezes the row, typically used when a transition starts/ends. This method is called by the fragment, it should not call it directly by the application.

getHeaderPresenter

Added in 1.1.0
fun getHeaderPresenter(): RowHeaderPresenter!

Returns the Presenter used for rendering the header, or null if none has been set.

getRowViewHolder

Added in 1.1.0
fun getRowViewHolder(holder: Presenter.ViewHolder!): RowPresenter.ViewHolder!

Returns the RowPresenter.ViewHolder from the given RowPresenter ViewHolder.

getSelectEffectEnabled

Added in 1.1.0
fun getSelectEffectEnabled(): Boolean

Returns true if the row selection effect is enabled. This value not only determines whether the default dim implementation is used, but subclasses must also respect this flag.

getSelectLevel

Added in 1.1.0
fun getSelectLevel(vh: Presenter.ViewHolder!): Float

Returns the current select level. The value will be between 0 (unselected) and 1 (selected).

getSyncActivatePolicy

Added in 1.1.0
fun getSyncActivatePolicy(): Int

Returns the policy of updating row view activated status. Can be one of:

isUsingDefaultSelectEffect

Added in 1.1.0
fun isUsingDefaultSelectEffect(): Boolean

Returns true if this RowPresenter is using the default dimming effect. A subclass may (most likely) return false and override onSelectLevelChanged.

onBindViewHolder

Added in 1.2.0-alpha04
fun onBindViewHolder(viewHolder: Presenter.ViewHolder, item: Any?): Unit

Binds a View to an item.

onCreateViewHolder

Added in 1.2.0-alpha04
fun onCreateViewHolder(parent: ViewGroup!): Presenter.ViewHolder!

Creates a new View.

onUnbindViewHolder

Added in 1.2.0-alpha04
fun onUnbindViewHolder(viewHolder: Presenter.ViewHolder): Unit

Unbinds a View from an item. Any expensive references may be released here, and any fields that are not bound for every item should be cleared here.

onViewAttachedToWindow

Added in 1.2.0-alpha04
fun onViewAttachedToWindow(holder: Presenter.ViewHolder): Unit

Called when a view created by this presenter has been attached to a window.

This can be used as a reasonable signal that the view is about to be seen by the user. If the adapter previously freed any resources in onViewDetachedFromWindow those resources should be restored here.

Parameters
holder: Presenter.ViewHolder

Holder of the view being attached

onViewDetachedFromWindow

Added in 1.2.0-alpha04
fun onViewDetachedFromWindow(holder: Presenter.ViewHolder): Unit

Called when a view created by this presenter has been detached from its window.

Becoming detached from the window is not necessarily a permanent condition; the consumer of an presenter's views may choose to cache views offscreen while they are not visible, attaching and detaching them as appropriate.

Any view property animations should be cancelled here or the view may fail to be recycled.
Parameters
holder: Presenter.ViewHolder

Holder of the view being detached

setEntranceTransitionState

Added in 1.1.0
fun setEntranceTransitionState(
    holder: RowPresenter.ViewHolder,
    afterEntrance: Boolean
): Unit

Changes the visibility of views. The entrance transition will be run against the views that change visibilities. A subclass may override and begin with calling super.setEntranceTransitionState(). This method is called by the fragment, it should not be called directly by the application.

Parameters
holder: RowPresenter.ViewHolder

The ViewHolder of the row.

afterEntrance: Boolean

true if children of row participating in entrance transition should be set to visible, false otherwise.

setHeaderPresenter

Added in 1.1.0
fun setHeaderPresenter(headerPresenter: RowHeaderPresenter!): Unit

Sets the Presenter used for rendering the header. Can be null to disable header rendering. The method must be called before creating any Row Views.

setRowViewExpanded

Added in 1.1.0
fun setRowViewExpanded(holder: Presenter.ViewHolder!, expanded: Boolean): Unit

Sets the expanded state of a Row view.

Parameters
holder: Presenter.ViewHolder!

The Row ViewHolder to set expanded state on.

expanded: Boolean

True if the Row is expanded, false otherwise.

setRowViewSelected

Added in 1.1.0
fun setRowViewSelected(holder: Presenter.ViewHolder!, selected: Boolean): Unit

Sets the selected state of a Row view.

Parameters
holder: Presenter.ViewHolder!

The Row ViewHolder to set expanded state on.

selected: Boolean

True if the Row is expanded, false otherwise.

setSelectEffectEnabled

Added in 1.1.0
fun setSelectEffectEnabled(applyDimOnSelect: Boolean): Unit

Enables or disables the row selection effect. This will not only affect the default dim effect, but subclasses must respect this flag as well.

setSelectLevel

Added in 1.1.0
fun setSelectLevel(vh: Presenter.ViewHolder!, level: Float): Unit

Sets the current select level to a value between 0 (unselected) and 1 (selected). Subclasses may override onSelectLevelChanged to respond to changes in the selected level.

setSyncActivatePolicy

Added in 1.1.0
fun setSyncActivatePolicy(syncActivatePolicy: Int): Unit

Sets the policy of updating row view activated status. Can be one of:

Protected functions

createRowViewHolder

Added in 1.1.0
protected abstract fun createRowViewHolder(parent: ViewGroup): RowPresenter.ViewHolder

Called to create a ViewHolder object for a Row. Subclasses will override this method to return a different concrete ViewHolder object.

Parameters
parent: ViewGroup

The parent View for the Row's view holder.

Returns
RowPresenter.ViewHolder

A ViewHolder for the Row's View.

dispatchItemSelectedListener

Added in 1.1.0
protected fun dispatchItemSelectedListener(
    vh: RowPresenter.ViewHolder!,
    selected: Boolean
): Unit

This method is only called from onRowViewSelected onRowViewSelected. The default behavior is to signal row selected events with a null item parameter. A Subclass of RowPresenter having child items should override this method and dispatch events with item information.

initializeRowViewHolder

Added in 1.1.0
protected fun initializeRowViewHolder(vh: RowPresenter.ViewHolder!): Unit

Called after a RowPresenter.ViewHolder is created for a Row. Subclasses may override this method and start by calling super.initializeRowViewHolder(ViewHolder).

Parameters
vh: RowPresenter.ViewHolder!

The ViewHolder to initialize for the Row.

isClippingChildren

Added in 1.1.0
protected fun isClippingChildren(): Boolean

Returns true if the Row view should clip its children. The clipChildren flag is set on view in initializeRowViewHolder. Note that Slide transition or explode transition need turn off clipChildren. Default value is false.

onBindRowViewHolder

Added in 1.1.0
protected fun onBindRowViewHolder(vh: RowPresenter.ViewHolder, item: Any): Unit

Binds the given row object to the given ViewHolder. Derived classes of RowPresenter overriding onBindRowViewHolder must call through the super class's implementation of this method.

onRowViewAttachedToWindow

Added in 1.1.0
protected fun onRowViewAttachedToWindow(vh: RowPresenter.ViewHolder): Unit

Invoked when the row view is attached to the window.

onRowViewDetachedFromWindow

Added in 1.1.0
protected fun onRowViewDetachedFromWindow(vh: RowPresenter.ViewHolder): Unit

Invoked when the row view is detached from the window.

onRowViewExpanded

Added in 1.1.0
protected fun onRowViewExpanded(vh: RowPresenter.ViewHolder!, expanded: Boolean): Unit

Called when the row view's expanded state changes. A subclass may override this method to respond to expanded state changes of a Row. The default implementation will hide/show the header view. Subclasses may make visual changes to the Row View but must not create animation on the Row view.

onRowViewSelected

Added in 1.1.0
protected fun onRowViewSelected(vh: RowPresenter.ViewHolder, selected: Boolean): Unit

Called when the given row view changes selection state. A subclass may override this to respond to selected state changes of a Row. A subclass may make visual changes to Row view but must not create animation on the Row view.

onSelectLevelChanged

Added in 1.1.0
protected fun onSelectLevelChanged(vh: RowPresenter.ViewHolder!): Unit

Callback when the select level changes. The default implementation applies the select level to setSelectLevel when getSelectEffectEnabled is true. Subclasses may override this function and implement a different select effect. In this case, the method isUsingDefaultSelectEffect should also be overridden to disable the default dimming effect.

onUnbindRowViewHolder

Added in 1.1.0
protected fun onUnbindRowViewHolder(vh: RowPresenter.ViewHolder): Unit

Unbinds the given ViewHolder. Derived classes of RowPresenter overriding onUnbindRowViewHolder must call through the super class's implementation of this method.