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
JSX Data Binding Example
TSX Examples with various cell types and selection events (TypeScript variant)
TSX Data Binding Example (TypeScript variant)
JS Examples with various cell types and selection events (Plain JavaScript - some features not supported)

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.