Picker

open class Picker : FrameLayout
kotlin.Any
   ↳ android.view.View
   ↳ android.view.ViewGroup
   ↳ android.widget.FrameLayout
   ↳ androidx.leanback.widget.picker.Picker

Picker is a widget showing multiple customized PickerColumns. The PickerColumns are initialized in setColumns(List). Call setColumnAt(int, PickerColumn) if the column value range or labels change. Call setColumnValue(int, int, boolean) to update the current value of PickerColumn.

Picker has two states and will change height:

  • isActivated() is true: Picker shows typically three items vertically (see getActivatedVisibleItemCount()}. Columns other than getSelectedColumn() still shows one item if the Picker is focused. On a touch screen device, the Picker will not get focus so it always show three items on all columns. On a non-touch device (a TV), the Picker will show three items only on currently activated column. If the Picker has focus, it will intercept DPAD directions and select activated column.
  • isActivated() is false: Picker shows one item vertically (see getVisibleItemCount()) on all columns. The size of Picker shrinks.

    • Summary

    Nested classes
    abstract

    Listener for Picker value changes.
    Public constructors
    <init>(context: Context!, attributeSet: AttributeSet!)

    Creates a Picker widget.
    <init>(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

    Creates a Picker widget.
    Public methods
    open Unit

    Register a callback to be invoked when the picker's value has changed.
    open Boolean

    open Float

    Returns number of visible items showing in a column when it's activated.
    open PickerColumn!
    getColumnAt(colIndex: Int)

    Get nth PickerColumn.
    open Int

    Get number of PickerColumns.
    Int

    Classes extending Picker can call setPickerItemLayoutId(int) to supply the Picker's item's layout id
    Int

    Returns the Picker's item's TextView's id from within the layout provided by Picker#getPickerItemLayoutId() or 0 if the layout provided by Picker#getPickerItemLayoutId() is a {link TextView}.
    open Int

    Get current activated column index.
    CharSequence!

    Gets separator string between columns.
    MutableList<CharSequence!>!

    Returns the list of separators that will be populated between the picker column fields.
    open Float

    Returns number of visible items showing in a column when it's not activated.
    open Unit
    onColumnValueChanged(columnIndex: Int, newValue: Int)

    Classes extending Picker can override this function to supply the behavior when a list has been scrolled.
    open Unit

    Remove a previously installed value changed callback
    open Unit
    requestChildFocus(child: View!, focused: View!)
    open Unit
    setActivated(activated: Boolean)
    open Unit
    setActivatedVisibleItemCount(visiblePickerItems: Float)

    Changes number of visible items showing in a column when it's activated.
    open Unit
    setColumnAt(columnIndex: Int, column: PickerColumn!)

    When column labels change or column range changes, call this function to re-populate the selection list.
    open Unit
    setColumnValue(columnIndex: Int, value: Int, runAnimation: Boolean)

    Manually set current value of a column.
    open Unit

    Set columns and create Views.
    Unit
    setPickerItemLayoutId(@LayoutRes pickerItemLayoutId: Int)

    Sets the layout to use for picker items.
    Unit
    setPickerItemTextViewId(@IdRes textViewId: Int)

    Sets the Picker's item's TextView's id from within the layout provided by Picker#getPickerItemLayoutId() or 0 if the layout provided by Picker#getPickerItemLayoutId() is a {link TextView}.
    open Unit
    setSelectedColumn(columnIndex: Int)

    Change current selected column.
    Unit

    Sets separator String between Picker columns.
    Unit

    Sets the list of separators that will be populated between the Picker columns.
    open Unit
    setVisibleItemCount(pickerItems: Float)

    Changes number of visible items showing in a column when it's not activated.
    Protected methods
    open Int

    Classes extending Picker can choose to override this method to supply the Picker's column's single item height in pixels.
    open Boolean
    onRequestFocusInDescendants(direction: Int, previouslyFocusedRect: Rect!)

    Public constructors

    <init>

    Picker(
        context: Context!, 
        attributeSet: AttributeSet!)

    Creates a Picker widget.

    <init>

    Picker(
        context: Context!, 
        attrs: AttributeSet!, 
        defStyleAttr: Int)

    Creates a Picker widget.

    Public methods

    addOnValueChangedListener

    open fun addOnValueChangedListener(listener: Picker.PickerValueListener!): Unit

    Register a callback to be invoked when the picker's value has changed.

    Parameters
    listener Picker.PickerValueListener!: The callback to ad

    dispatchKeyEvent

    open fun dispatchKeyEvent(event: KeyEvent!): Boolean

    getActivatedVisibleItemCount

    open fun getActivatedVisibleItemCount(): Float

    Returns number of visible items showing in a column when it's activated. The default value is 3.

    Return
    Float Number of visible items showing in a column when it's activated.

    getColumnAt

    open fun getColumnAt(colIndex: Int): PickerColumn!

    Get nth PickerColumn.

    Parameters
    colIndex Int: Index of PickerColumn.
    Return
    PickerColumn! PickerColumn at colIndex or null if setColumns(List) is not called yet.

    getColumnsCount

    open fun getColumnsCount(): Int

    Get number of PickerColumns.

    Return
    Int Number of PickerColumns or 0 if setColumns(List) is not called yet.

    getPickerItemLayoutId

    @LayoutRes fun getPickerItemLayoutId(): Int

    Classes extending Picker can call setPickerItemLayoutId(int) to supply the Picker's item's layout id

    getPickerItemTextViewId

    @IdRes fun getPickerItemTextViewId(): Int

    Returns the Picker's item's TextView's id from within the layout provided by Picker#getPickerItemLayoutId() or 0 if the layout provided by Picker#getPickerItemLayoutId() is a {link TextView}.

    getSelectedColumn

    open fun getSelectedColumn(): Int

    Get current activated column index.

    Return
    Int Current activated column index.

    getSeparator

    fun getSeparator(): CharSequence!

    Deprecated: Use getSeparators()

    Gets separator string between columns.

    Return
    CharSequence! The separator that will be populated between all the Picker columns.

    getSeparators

    fun getSeparators(): MutableList<CharSequence!>!

    Returns the list of separators that will be populated between the picker column fields.

    Return
    MutableList<CharSequence!>! The list of separators populated between the picker column fields.

    getVisibleItemCount

    open fun getVisibleItemCount(): Float

    Returns number of visible items showing in a column when it's not activated. The default value is 1.

    Return
    Float Number of visible items showing in a column when it's not activated.

    onColumnValueChanged

    open fun onColumnValueChanged(
        columnIndex: Int, 
        newValue: Int
    ): Unit

    Classes extending Picker can override this function to supply the behavior when a list has been scrolled. Subclass may call setColumnValue(int, int, * boolean) and or setColumnAt(int, PickerColumn). Subclass should not directly call PickerColumn#setCurrentValue(int) which does not update internal state or notify listeners.

    Parameters
    columnIndex Int: index of which column was changed.
    newValue Int: A new value desired to be set on the column.

    removeOnValueChangedListener

    open fun removeOnValueChangedListener(listener: Picker.PickerValueListener!): Unit

    Remove a previously installed value changed callback

    Parameters
    listener Picker.PickerValueListener!: The callback to remove.

    requestChildFocus

    open fun requestChildFocus(
        child: View!, 
        focused: View!
    ): Unit

    setActivated

    open fun setActivated(activated: Boolean): Unit

    setActivatedVisibleItemCount

    open fun setActivatedVisibleItemCount(visiblePickerItems: Float): Unit

    Changes number of visible items showing in a column when it's activated. The default value is 3.

    Parameters
    visiblePickerItems Float: Number of visible items showing in a column when it's activated.

    setColumnAt

    open fun setColumnAt(
        columnIndex: Int, 
        column: PickerColumn!
    ): Unit

    When column labels change or column range changes, call this function to re-populate the selection list. Note this function cannot be called from RecyclerView layout/scroll pass.

    Parameters
    columnIndex Int: Index of column to update.
    column PickerColumn!: New column to update.

    setColumnValue

    open fun setColumnValue(
        columnIndex: Int, 
        value: Int, 
        runAnimation: Boolean
    ): Unit

    Manually set current value of a column. The function will update UI and notify listeners.

    Parameters
    columnIndex Int: Index of column to update.
    value Int: New value of the column.
    runAnimation Boolean: True to scroll to the value or false otherwise.

    setColumns

    open fun setColumns(columns: MutableList<PickerColumn!>!): Unit

    Set columns and create Views.

    Parameters
    columns MutableList<PickerColumn!>!: The actual focusable columns of a picker which are scrollable if the field takes more than one value (e.g. for a DatePicker, day, month, and year fields and for TimePicker, hour, minute, and am/pm fields form the columns).

    setPickerItemLayoutId

    fun setPickerItemLayoutId(@LayoutRes pickerItemLayoutId: Int): Unit

    Sets the layout to use for picker items.

    Parameters
    pickerItemLayoutId Int: Layout resource id to use for picker items.

    setPickerItemTextViewId

    fun setPickerItemTextViewId(@IdRes textViewId: Int): Unit

    Sets the Picker's item's TextView's id from within the layout provided by Picker#getPickerItemLayoutId() or 0 if the layout provided by Picker#getPickerItemLayoutId() is a {link TextView}.

    Parameters
    textViewId Int: View id of TextView inside a Picker item, or 0 if the Picker item is a TextView.

    setSelectedColumn

    open fun setSelectedColumn(columnIndex: Int): Unit

    Change current selected column. Picker shows multiple items on selected column if Picker has focus. Picker shows multiple items on all column if Picker has no focus (e.g. a Touchscreen screen).

    Parameters
    columnIndex Int: Index of column to activate.

    setSeparator

    fun setSeparator(separator: CharSequence!): Unit

    Sets separator String between Picker columns.

    Parameters
    separator CharSequence!: Separator String between Picker columns.

    setSeparators

    fun setSeparators(separators: MutableList<CharSequence!>!): Unit

    Sets the list of separators that will be populated between the Picker columns. The number of the separators should be either 1 indicating the same separator used between all the columns fields (and nothing will be placed before the first and after the last column), or must be one unit larger than the number of columns passed to setColumns(List). In the latter case, the list of separators corresponds to the positions before the first column all the way to the position after the last column. An empty string for a given position indicates no separators needs to be placed for that position, otherwise a TextView with the given String will be created and placed there.

    Parameters
    separators MutableList<CharSequence!>!: The list of separators to be populated between the Picker columns.

    setVisibleItemCount

    open fun setVisibleItemCount(pickerItems: Float): Unit

    Changes number of visible items showing in a column when it's not activated. The default value is 1.

    Parameters
    pickerItems Float: Number of visible items showing in a column when it's not activated.

    Protected methods

    getPickerItemHeightPixels

    protected open fun getPickerItemHeightPixels(): Int

    Classes extending Picker can choose to override this method to supply the Picker's column's single item height in pixels.

    onRequestFocusInDescendants

    protected open fun onRequestFocusInDescendants(
        direction: Int, 
        previouslyFocusedRect: Rect!
    ): Boolean