Class “ListView”
Object > NativeObject > Widget > Composite > CollectionView > ListView
| Type: | ListView<ItemType> extends CollectionView<Cell> |
| Generics: | ItemType: any |
| Constructor: | public |
| Singleton: | No |
| Module: | tabris-decorators |
| Direct subclasses: | None |
| JSX Support: | Element: <ListView/>Parent Elements: <Canvas/>, <Cell/>, <Composite/>, <Page/>, <RefreshComposite/>, <Row/>, <ScrollView/>, <Stack/>, <Tab/>Child Elements: <Cell/> |
ListView is a high-level extension of the low-level CollectionView widget. It provides additional API to make usage more convenient, but does not add any new features.
ListView is optimized for JSX and data binding. It can be used in plain JavaScript, but in this case some features do not work, as noted below.
In contrast to CollectionView it features an items property and requires no callbacks to create or populate cells, and no explicit item position/content updates: The load(), insert(), remove() and refresh()) methods are called implicitly when the items property value changes or mutates. For this to work as expected the items property must either be set a List instance, or to a series of immutable arrays. Any change to a List will be recognized immediately, while an items array must to be entirely replaced without modifying the previous one. ListView will then compute the difference between the old and new array automatically.
To define the look of a ListView it requires one or more <Cell> child elements containing widgets that bind themselves to the cell’s item. These cells act as templates for all Cell instances needed by ListView to display the items. If multiple cell templates are present, their itemType and/or itemCheck properties are used to determine which cell template to use for which item.
Note that this mechanism ONLY works in JSX, but ListView can still be used without templates by setting the createCell, cellType and cellHeight properties instead. You may want to do this if you are using plain JavaScript project setup. In this scenario the Cell properties itemType, itemCheck and selectable are not supported.
ListView is not exported by the tabris module, but by tabris-decorators, which needs to be installed separately.
Examples
JSX
contentView.append(
<ListView stretch items={items}>
<Cell padding={8} height={52}>
<TextView centerY bind-text='item.text' font='24px'/>
</Cell>
</ListView>
);
See also:
JSX Examples with various cell types and selection events
TSX Examples with various cell types and selection events (TypeScript variant)
TSX Data Binding Example (TypeScript variant)
Constructor
new ListView(properties?)
| Parameter | Type | Description |
|---|---|---|
| properties | Properties<ListView> |
Sets all key-value pairs in the properties object as widget properties. Optional. |
Static Methods
select(ev, action?)
This is a helper method intended to be used in an event listener of any event of Cell or its children. It triggers a select event on the ListView containing the cell. The action value is set on the resulting ListViewSelectEvent event object.
Example usage: onTap={ev => ListView.select(ev, someNumber)}.
Use selectPrimary, selectSecondary, selectToggle or selectDismiss as a shorthand to trigger select with a specific value for action, or just set the selectable property of Cell.
| Parameter | Type | Description |
|---|---|---|
| ev | EventObject |
|
| action | number |
A numeric value passed on to the select event object, defaults to 0. Optional. |
Returns: undefined
selectDismiss(ev)
This is a helper method intended to be used directly as an event listener of any event of Cell or its children. Like the select method it triggers a select event on the ListView containing the cell. This difference is only semantic: The action value on the ListViewSelectEvent event object will be set to ItemAction.Dismiss (i.e. 4), typically indicating the item should be removed .
Example usage:onSomeEvent={ListView.selectDismiss}.
| Parameter | Type | Description |
|---|---|---|
| ev | EventObject |
Returns: undefined
selectPrimary(ev)
This is a helper method intended to be used directly as an event listener of any event of Cell or its children. Like the select method it triggers a select event on the ListView containing the cell. This difference is only semantic: The action value on the ListViewSelectEvent event object will be set to ItemAction.Primary (i.e. 1), indicating a ‘normal’ selection.
Example usage: onTap={ListView.selectPrimary}.
| Parameter | Type | Description |
|---|---|---|
| ev | EventObject |
Returns: undefined
selectSecondary(ev)
This is a helper method intended to be used directly as an event listener of any event of Cell or its children. Like the select method it triggers a select event on the ListView containing the cell. This difference is only semantic: The action value on the ListViewSelectEvent event object will be set to ItemAction.Secondary (i.e. 2), indicating some alternative kind of selection.
Example usage: onSomeEvent={ListView.selectSecondary}.
| Parameter | Type | Description |
|---|---|---|
| ev | EventObject |
Returns: undefined
selectToggle(ev)
This is a helper method intended to be used directly as an event listener of any event of Cell or its children. Like the select method it triggers a select event on the ListView containing the cell. This difference is only semantic: The action value on the ListViewSelectEvent event object will be set to ItemAction.Toggle (i.e. 3), typically indicating the item should be marked as checked or unchecked.
Example usage: onSomeEvent={ListView.selectToggle}.
| Parameter | Type | Description |
|---|---|---|
| ev | EventObject |
Returns: undefined
Properties
items
List or Array containing the items that to be displayed. If a List is used any changes to the list (items added/removed/replaced) the ListView updates itself automatically. The updated will be animated if possible.
| Type: | List<ItemType> | ItemType[] |
| Settable: | Yes |
| Change Event: | itemsChanged |
Events
select
An event that may be triggered by a Cell as the result of any kind of user interaction. By default cells do not trigger select events, they have to be explicitly configured to do so. This can be done via the selectable property on Cell or the static select trigger methods.
EventObject Type: ListViewSelectEvent<ListView>
| Property | Type | Description |
|---|---|---|
| action | number |
A general-purpose parameter passed on when the event was triggered by one of the static select methods. This is meant to be used by the application to differentiate between different kind of interactions. It can be safely ignored if there is only one kind of selection, such as tapping a cell. tabris-decorators exports a ItemAction enum defining 4 pre-defined values for use with this property: Primary, Secondary, Toggle and Dismiss. These are set when using the corresponding trigger methods. |
| item | ItemType |
The item currently associated with the Cell that triggered the event. |
| itemIndex | number |
The index of the item within the items list/array. |
| originalEvent | EventObject |
The event that was the cause of this select event. |
Change Events
itemsChanged
Fired when the items property has changed.
EventObject Type: PropertyChangedEvent<ListView, List | Array>
| Property | Type | Description |
|---|---|---|
| value | List<ItemType> | ItemType[] |
The new value of items. |
