Class “CollectionView”

Object > NativeObject > Widget > Composite > CollectionView

A scrollable list that displays data items in cells, one per row. Cells are created on demand by the createCell callback and reused on scrolling.

CollectionView on Android
Android
CollectionView on iOS
iOS
TypeScript type CollectionView<Cell extends Widget> extends Composite<Cell>
Constructor public
Singleton No
Namespace tabris
Direct subclasses None
JSX support Element: <CollectionView/>
Parent element: <Composite/> and any widget extending Composite
Child elements: None
Text content: Not supported

Example

import {CollectionView, contentView, TextView} from 'tabris';

const items = ['Apple', 'Banana', 'Cherry'];

new CollectionView({
  left: 0, top: 0, right: 0, bottom: 0,
  itemCount: items.length,
  createCell: () => new TextView(),
  updateCell: (view, index) =>  {
    view.text = items[index];
  }
}).appendTo(contentView);

See also:

JSX Creating a simple CollectionView
JSX Creating a CollectionView with multiple cell types
JSX Creating a CollectionView with pull-to-refresh support
JSX Creating a CollectionView with sticky headers
JSX Creating a CollectionView with dynamic column count
JSX collectionview-cellheightauto.jsx
TSX collectionview-cellheightauto.tsx
TSX collectionview-celltype-ts.tsx
TSX collectionview-scroll-ts.tsx
JSX collectionview-swipe-to-dismiss.jsx
TSX collectionview-ts.tsx

Constructor

new CollectionView(properties?)

Parameter Type Optional Description
properties Properties<CollectionView<Cell>> & Partial<Pick<CollectionView<Cell>, 'cellHeight' | 'cellType' | 'createCell' | 'updateCell'>> Yes Sets all key-value pairs in the properties object as widget properties.

Methods

cellByItemIndex(itemIndex)

Returns the cell currently associated with the given item index. Returns null if the item is not currently displayed.

Parameter Type Optional Description
itemIndex number No The index of the item as given in updateCell.

Returns Cell | null

insert(index, count?)

Inserts one or more items at the given index. When no count is specified, a single item will be added at the given index. New cells may be created if needed. The updateCell callback will only be called for those new items that become immediately visible. Note that inserting new items changes the index of all subsequent items. This operation will update the itemCount property.

Parameter Type Optional Description
index number No  
count number Yes The position to insert the items at. A negative index is interpreted as relative to the end. If the given index is greater than the item count, new items will be appended at the end.

Returns void

itemIndex(widget)

Determines the item index currently associated with the given cell.

Parameter Type Optional Description
widget Widget No A widget instance created by createCell, or a child of that widget.

Returns number

load(itemCount)

Loads a new model with the given itemCount. This operation will update the itemCount property.

Parameter Type Optional Description
itemCount number No The number of items in the model to load.

Returns void

refresh(index?)

Triggers an update of the item at the given index by calling the updateCell callback of the corresponding. If no index is given, all visible items will be updated.

Parameter Type Optional Description
index number Yes The index of the item that was changed.

Returns void

remove(index, count?)

Removes one or more items beginning with the given index. When no count is given, only the item at index will be removed. Note that this changes the index of all subsequent items, however. This operation will update the itemCount property.

Parameter Type Optional Description
index number No The index of the first item to remove. A negative value is interpreted as relative to the end.
count number Yes The number of items to remove.

Returns void

reveal(index)

Scrolls the item with the given index into view.

Parameter Type Optional Description
index number No The index of the item to reveal. If this is negative, it is interpreted as relative to the end

Returns void

set(properties)

Sets all key-value pairs in the properties object as widget properties.

Important TypeScript note: When called on this you may need to specify your custom type like this: this.set<MyComponent>({propA: valueA});

Parameter Type Optional Description
properties Properties<T> & Partial<Pick<this, 'cellHeight' | 'cellType' | 'createCell'>> No  

Returns this

Properties

cellHeight

The height of a collection cell. If set to "auto", the cell height will be calculated individually for each cell. If set to a function, this function will be called for every item, providing the item index and the cell type as parameters, and must return the cell height for the given item. Note: On iOS "auto" may cause significant performance downgrade as it requires additional layouting passes to calculate cell height internally. If possible please use a combination of fixed itemHeight and cellType properties to specify different height for different cells.

Type number | "auto" | ((index: number, cellType: string) => number | "auto")
Default auto
Settable Yes
Change events Yes

cellType

The name of the cell type to use for the item at the given index. This name will be passed to the createCell and cellHeight callbacks. Cells will be reused only for those items that map to the same cell type. If set to a function, this function will be called for every item, providing the item index as a parameter, and must return a unique name for the cell type to use for the given item.

Type string | ((index: number) => string) | null
Settable Yes
Change events Yes

See also:

TSX collectionview-celltype-ts.tsx
JSX collectionview-celltype.jsx

columnCount

The number of columns to display in the collection view. If set to a value n > 1, each row will contain n items. The available space will be equally distributed between columns.

Type number
Default 1
Settable Yes
Change events Yes

See also:

JSX collectionview-columncount.jsx

createCell

A callback used to create a new reusable cell widget for a given type. This callback will be called by the framework and the created cell will be reused for different items. The created widget should be populated in the updateCell function.

Type (cellType: string) => Cell
Settable Yes
Change events Yes

firstVisibleIndex

The index of the first item that is currently visible on screen.

Type number
Settable No
Change events Yes

itemCount

The number of items to display. To add or remove items later, use the methods insert() and remove() instead of setting the itemCount. To display a new list of items, use the load() method.

Type number
Settable Yes
Change events Yes

lastVisibleIndex

The index of the last item that is currently visible on screen.

Type number
Settable No
Change events Yes

refreshEnabled

Enables the user to trigger a refresh by using the pull-to-refresh gesture.

Type boolean
Default false
Settable Yes
Change events Yes

See also:

JSX collectionview-refreshenabled.jsx

refreshIndicator

Whether the refresh indicator is currently visible. Will be set to true when a refresh event is triggered. Reset it to false when the refresh is finished.

Type boolean
Default false
Settable Yes
Change events Yes

refreshMessage

iOS

The message text displayed together with the refresh indicator.

Type string
Default '""'
Settable Yes
Change events Yes

updateCell

A callback used to update a given cell widget to display the item with the given index. This callback will be called by the framework.

Type (cell: Cell, index: number) => void
Settable Yes
Change events Yes

Events

refresh

Fired when the user requested a refresh. An event listener should reset the refreshIndicator property when refresh is finished.

scroll

Fired while the collection view is scrolling.

Parameter Type Description
deltaX number Currently always 0.
deltaY number The delta of the scroll position. Positive when scrolling up and negative when scrolling down.

See also:

TSX collectionview-scroll-ts.tsx
JSX collectionview-scroll.jsx

Change Events

cellHeightChanged

Fired when the cellHeight property has changed.

Parameter Type Description
value number | "auto" | ((index: number, cellType: string) => number | "auto") The new value of cellHeight.

itemCountChanged

Fired when the itemCount property has changed.

Parameter Type Description
value number The new value of itemCount.

createCellChanged

Fired when the createCell property has changed.

Parameter Type Description
value (cellType: string) => Cell The new value of createCell.

updateCellChanged

Fired when the updateCell property has changed.

Parameter Type Description
value (cell: Cell, index: number) => void The new value of updateCell.

cellTypeChanged

Fired when the cellType property has changed.

Parameter Type Description
value string | ((index: number) => string) | null The new value of cellType.

refreshEnabledChanged

Fired when the refreshEnabled property has changed.

Parameter Type Description
value boolean The new value of refreshEnabled.

refreshIndicatorChanged

Fired when the refreshIndicator property has changed.

Parameter Type Description
value boolean The new value of refreshIndicator.

refreshMessageChanged

Fired when the refreshMessage property has changed.

Parameter Type Description
value string The new value of refreshMessage.

firstVisibleIndexChanged

Fired when the firstVisibleIndex property has changed.

Parameter Type Description
value number The new value of firstVisibleIndex.

lastVisibleIndexChanged

Fired when the lastVisibleIndex property has changed.

Parameter Type Description
value number The new value of lastVisibleIndex.

columnCountChanged

Fired when the columnCount property has changed.

Parameter Type Description
value number The new value of columnCount.