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

    Public constructors
    <init>(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

    Creates a Picker widget.

    Public methods
    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}.

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

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

    MutableList<CharSequence!>!

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

    open Unit
    setActivated(activated: Boolean)

    Int

    Classes extending Picker can choose to override this method to supply the Picker's item's layout id

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

    Unit

    Sets the list of separators that will be populated between the Picker columns.

    open Int

    Get current activated column index.

    open Int

    Get number of PickerColumns.

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

    Manually set current value of a column.

    Unit

    Sets separator String between Picker columns.

    CharSequence!

    Gets separator string between columns.

    open Unit
    setSelectedColumn(columnIndex: Int)

    Change current selected column.

    open Boolean

    open Unit

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

    open Float

    Returns number of visible items showing in a column when it's activated.

    open Float

    Returns number of visible items showing in a column when it's not activated.

    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 Unit

    Remove a previously installed value changed callback

    open Unit
    setVisibleItemCount(pickerItems: Float)

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

    open Unit

    Set columns and create Views.

    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 PickerColumn!
    getColumnAt(colIndex: Int)

    Get nth PickerColumn.

    Protected methods
    open Boolean
    onRequestFocusInDescendants(direction: Int, previouslyFocusedRect: Rect!)

    open Int

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

    Public constructors

    <init>

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

    Creates a Picker widget.

    Public methods

    setPickerItemTextViewId

    fun setPickerItemTextViewId(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.

    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.

    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.

    setActivated

    open fun setActivated(activated: Boolean): Unit

    getPickerItemLayoutId

    fun getPickerItemLayoutId(): Int

    Classes extending Picker can choose to override this method to supply the Picker's item's layout id

    requestChildFocus

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

    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.

    getSelectedColumn

    open fun getSelectedColumn(): Int

    Get current activated column index.

    Return
    Int: Current activated column index.

    getColumnsCount

    open fun getColumnsCount(): Int

    Get number of PickerColumns.

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

    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 Int: True to scroll to the value or false otherwise.

    setSeparator

    fun setSeparator(separator: CharSequence!): Unit

    Sets separator String between Picker columns.

    Parameters
    separator CharSequence!: Separator String between Picker columns.

    getSeparator

    fun getSeparator(): CharSequence!

    Gets separator string between columns.

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

    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.

    dispatchKeyEvent

    open fun dispatchKeyEvent(event: KeyEvent!): Boolean

    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

    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.

    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.

    getPickerItemTextViewId

    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}.

    removeOnValueChangedListener

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

    Remove a previously installed value changed callback

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

    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.

    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).

    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 Int: New column to update.

    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.

    Protected methods

    onRequestFocusInDescendants

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

    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.