Google is committed to advancing racial equity for Black communities. See how.

RowPresenter

abstract class RowPresenter : Presenter
kotlin.Any
   ↳ androidx.leanback.widget.Presenter
   ↳ androidx.leanback.widget.RowPresenter

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, ViewHolder#getRow() returns null.

Customize UI widgets

When a subclass of RowPresenter adds UI widgets, it should subclass RowPresenter.ViewHolder and override createRowViewHolder(ViewGroup) and initializeRowViewHolder(ViewHolder). 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(RowHeaderPresenter).

UI events from fragments

RowPresenter receives calls from its parent (typically a Fragment) when:

Activated status

The activated status of a row is applied to the row view and its children via View#setActivated(boolean). 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(int) 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(ViewGroup) to be properly chained by the library. Adding View listeners after createRowViewHolder(ViewGroup) 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(Presenter.ViewHolder, float) 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(ViewHolder) to apply a different selection effect.

Call setSelectEffectEnabled(boolean) 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 classes
open

A ViewHolder for a Row.

Constants
static Int

Don't synchronize row view activated status with selected status or expanded status, application will do its own through RowPresenter.ViewHolder#setActivated(boolean).
static Int

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

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

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

Public constructors

Constructs a RowPresenter.

Public methods
open 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.
open Boolean

Returns true if this RowPresenter is using the default dimming effect.
Unit
onBindViewHolder(viewHolder: Presenter.ViewHolder!, item: Any!)
Presenter.ViewHolder!

Unit

Unit

Unit

open Unit

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 methods
abstract RowPresenter.ViewHolder!

Called to create a ViewHolder object for a Row.
open Unit

This method is only called from onRowViewSelected(ViewHolder, boolean) onRowViewSelected.
open Unit

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

Returns true if the Row view should clip its children.
open Unit

Binds the given row object to the given ViewHolder.
open Unit

Invoked when the row view is attached to the window.
open Unit

Invoked when the row view is detached from the window.
open Unit

Called when the row view's expanded state changes.
open Unit

Called when the given row view changes selection state.
open Unit

Callback when the select level changes.
open Unit

Unbinds the given ViewHolder.

Inherited functions

Constants

SYNC_ACTIVATED_CUSTOM

static val SYNC_ACTIVATED_CUSTOM: Int

Don't synchronize row view activated status with selected status or expanded status, application will do its own through RowPresenter.ViewHolder#setActivated(boolean).

Value: 0

SYNC_ACTIVATED_TO_EXPANDED

static val SYNC_ACTIVATED_TO_EXPANDED: Int

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

Value: 1

SYNC_ACTIVATED_TO_EXPANDED_AND_SELECTED

static val SYNC_ACTIVATED_TO_EXPANDED_AND_SELECTED: Int

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

Value: 3

SYNC_ACTIVATED_TO_SELECTED

static val SYNC_ACTIVATED_TO_SELECTED: Int

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

Value: 2

Public constructors

<init>

RowPresenter()

Constructs a RowPresenter.

Public methods

freeze

open 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

fun getHeaderPresenter(): RowHeaderPresenter!

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

getRowViewHolder

fun getRowViewHolder(holder: Presenter.ViewHolder!): RowPresenter.ViewHolder!

Returns the RowPresenter.ViewHolder from the given RowPresenter ViewHolder.

getSelectEffectEnabled

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

fun getSelectLevel(vh: Presenter.ViewHolder!): Float

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

getSyncActivatePolicy

fun getSyncActivatePolicy(): Int

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

  • Default value SYNC_ACTIVATED_TO_EXPANDED
  • SYNC_ACTIVATED_TO_SELECTED
  • SYNC_ACTIVATED_TO_EXPANDED_AND_SELECTED
  • SYNC_ACTIVATED_CUSTOM

    • isUsingDefaultSelectEffect

    open fun isUsingDefaultSelectEffect(): Boolean

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

    onBindViewHolder

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

    onCreateViewHolder

    fun onCreateViewHolder(parent: ViewGroup!): Presenter.ViewHolder!

    onUnbindViewHolder

    fun onUnbindViewHolder(viewHolder: Presenter.ViewHolder!): Unit

    onViewAttachedToWindow

    fun onViewAttachedToWindow(holder: Presenter.ViewHolder!): Unit

    onViewDetachedFromWindow

    fun onViewDetachedFromWindow(holder: Presenter.ViewHolder!): Unit

    setEntranceTransitionState

    open 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

    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

    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

    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

    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

    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(ViewHolder) to respond to changes in the selected level.

    setSyncActivatePolicy

    fun setSyncActivatePolicy(syncActivatePolicy: Int): Unit

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

  • Default value SYNC_ACTIVATED_TO_EXPANDED
  • SYNC_ACTIVATED_TO_SELECTED
  • SYNC_ACTIVATED_TO_EXPANDED_AND_SELECTED
  • SYNC_ACTIVATED_CUSTOM

    • Protected methods

    createRowViewHolder

    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.
    Return
    RowPresenter.ViewHolder! A ViewHolder for the Row's View.

    dispatchItemSelectedListener

    protected open fun dispatchItemSelectedListener(
        vh: RowPresenter.ViewHolder!, 
        selected: Boolean
    ): Unit

    This method is only called from onRowViewSelected(ViewHolder, boolean) 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

    protected open 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

    protected open fun isClippingChildren(): Boolean

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

    onBindRowViewHolder

    protected open fun onBindRowViewHolder(
        vh: RowPresenter.ViewHolder!, 
        item: Any!
    ): Unit

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

    onRowViewAttachedToWindow

    protected open fun onRowViewAttachedToWindow(vh: RowPresenter.ViewHolder!): Unit

    Invoked when the row view is attached to the window.

    onRowViewDetachedFromWindow

    protected open fun onRowViewDetachedFromWindow(vh: RowPresenter.ViewHolder!): Unit

    Invoked when the row view is detached from the window.

    onRowViewExpanded

    protected open 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

    protected open 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

    protected open fun onSelectLevelChanged(vh: RowPresenter.ViewHolder!): Unit

    Callback when the select level changes. The default implementation applies the select level to RowHeaderPresenter#setSelectLevel(RowHeaderPresenter.ViewHolder, float) 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

    protected open fun onUnbindRowViewHolder(vh: RowPresenter.ViewHolder!): Unit

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