Class “ItemPicker”

Object > NativeObject > Widget > Picker > ItemPicker

Type:	`ItemPicker<ItemType> extends Picker`
Generics:	ItemType: `any`
Constructor:	public
Singleton:	No
Module:	tabris-decorators
Direct subclasses:	None
JSX Support:	Element: `<ItemPicker/>` Parent Elements: `<Canvas/>`, `<Cell/>`, `<Composite/>`, `<Page/>`, `<RefreshComposite/>`, `<Row/>`, `<ScrollView/>`, `<Stack/>`, `<Tab/>` Child Elements: Not Supported Element content sets: `items`

ItemPicker is a high-level extension of the low-level Picker widget. It provides additional API to make usage more convenient, but does not add any new features.

In contrast to Picker, it has an items property (taking either an array or a List) and does not necessarily require a callback to determine the text of a list entry. Instead the items can be strings themselves, implement a toString() method, or provide a specific property containing the text. This item property may be given via textSource.

ListView is not exported by the tabris module, but by tabris-decorators, which needs to be installed separately.

Examples

JSX

contentView.append(
  <ItemPicker stretchX textSource='name'>
    {[
      {name: 'Paul', id: 'person#101'},
      {name: 'Amanda', id: 'person#102'},
      {name: 'Jessica', id: 'person#103'}
    ]}
  </ItemPicker>
);

Constructor

new ItemPicker(properties?)

Parameter	Type	Description
properties	`Properties<ItemPicker>`	Sets all key-value pairs in the properties object as widget properties. Optional.

Properties

items

List or Array containing the items that can be selected. If a List is used any changes to the list (items added/removed/replaced) are applied to the ItemPicker automatically.

When items changes - either by modifying List or setting a new Array - the selection state will be preserved if the index currently selected item remains unchanged.

Items can also be provided as an array literal (within curly braces) or plain text with the <ItemPicker> JSX element. If text is given it will be interpreted as a comma separated list.

Type:	`List<ItemType> \| ItemType[]`
Default:	`null`
Settable:	Yes
Change Event:	`itemsChanged`
JSX Content Type:	`List<ItemType> \| ItemType[]`

When using ItemPicker as an JSX element the elements content value is mapped to this property.

selection

The currently selected item. Corresponds to the itemIndex property. The value is adjusted automatically if items is manipulated. In this case a selectionChanged event is fired, but no select event.

Type:	`ItemType`
Settable:	Yes
Change Event:	`selectionChanged`

textSource

Controls how the text representing an item is determined.

If this property is not set, the item is simply stringified. This works best when the item is a string already or implements a toString() method.

If the value is a string, it is interpreted as the name of a property of the item object. That property is used as the text. The string can also point to a sub-property, like a data binding path. If the property is @property-decorated, changes will be applied automatically.

Lastly, a path string can be combined with a converter function in a plain object.

Type:	`null \| string \| {path: string, converter: Function}`
Default:	`null`
Settable:	Yes
Change Event:	`textSourceChanged`

Events

itemSelect

Fired when an item was selected by the user. Same as the select event, except that it provides not just the item index, but also the item and the item text.

EventObject Type: ItemPickerItemSelectEvent<ItemPicker>

Property	Type	Description
item	`ItemType`
itemIndex	`number`
itemText	`string`

Change Events

itemsChanged

Fired when the items property has changed.

EventObject Type: PropertyChangedEvent<ItemPicker, List | Array>

Property	Type	Description
value	`List<ItemType> \| ItemType[]`	The new value of items.

selectionChanged

Fired when the selection property has changed.

EventObject Type: PropertyChangedEvent<ItemPicker, ItemType>

Property	Type	Description
value	`ItemType`	The new value of selection.

textSourceChanged

Fired when the textSource property has changed.

EventObject Type: PropertyChangedEvent<ItemPicker, null | string | Object>

Property	Type	Description
value	`null \| string \| {path: string, converter: Function}`	The new value of textSource.

Tabris.js 3.4