Zebra API Doc

zebra.ui.List Class

The class is list component implementation that visualizes zebra.data.ListModel. It is supposed the model can have any type of items. Visualization of the items is customized by defining a view provider.

The general use case:

   // create list component that contains three item 
   var list = new zebra.ui.List([
       "Item 1",
       "Item 2",
       "Item 3"
   ]);

   ...
   // add new item
   list.model.add("Item 4");

   ...
   // remove first item
   list.model.removeAt(0);

To customize list items views you can redefine item view provider as following:

   // suppose every model item is an array that contains two elements,
   // first element points to the item icon and the second element defines
   // the list item text 
   var list = new zebra.ui.List([
       [ "icon1.gif", "Caption 1" ],
       [ "icon2.gif", "Caption 1" ],
       [ "icon3.gif", "Caption 1" ]
   ]); 

   // define new list item views provider that represents every 
   // list model item as icon with a caption 
   list.setViewProvider(new zebra.ui.List.ViewProvider([
       function getView(target, value, i) {
           var caption = value[1];
           var icon    = value[0];
           return new zebra.ui.CompRender(new zebra.ui.ImageLabel(caption, icon));
       }
   ]));

Constructor

zebra.ui.List

(
  • [model]
  • [isComboMode]
)

Parameters:

  • [model] zebra.data.ListModel | Array optional

    a list model that should be passed as an instance of zebra.data.ListModel or as an array.

  • [isComboMode] Boolean optional

    true if the list navigation has to be triggered by mouse cursor moving

Methods

$select

(
  • o
)
protected

Inherited from zebra.ui.BaseList:

Select the given list item. The method is called when an item selection is triggered by a user interaction: key board, or mouse

Parameters:

  • o Integer

    an item index

calcMaxItemSize

() Integer protected

Inherited from zebra.ui.BaseList:

Calculate maximal width and maximal height the items in the list have


Return: Integer

a max items size

drawView

(
  • g
  • id
  • x
  • y
  • w
  • h
)
protected

Inherited from zebra.ui.BaseList:

Draw the given list view element identified by the given id at the specified location.

Parameters:

  • g 2DGraphics

    a graphical context

  • id String

    a view id

  • x Integer

    a x coordinate the view has to be drawn

  • y Integer

    a y coordinate the view has to be drawn

  • w Integer

    a view width

  • h Integer

    a view height

drawViewAt

(
  • g
  • id
  • index
)
protected

Inherited from zebra.ui.BaseList:

Draw the given list view element identified by the given id on the given list item.

Parameters:

  • g 2DGraphics

    a graphical context

  • id String

    a view id

  • index Integer

    a list item index

findSelectable

(
  • off
  • d
)
Integer protected

Inherited from zebra.ui.BaseList:

Find a next selectable list item starting from the given offset with the specified direction

Parameters:

  • off Integer

    a start item index to perform search

  • d Integer

    a direction increment. Cam be -1 or 1


Return: Integer

a next selectable item index

fireSelected

(
  • prev
)
protected

Inherited from zebra.ui.BaseList:

Fire selected event

Parameters:

  • prev Integer | Null

    a previous selected item index. null if the same item has been re-selected

getItemIdxAt

(
  • x
  • y
)
Integer

Inherited from zebra.ui.BaseList:

Detect an item by the specified location

Parameters:

  • x Integer

    a x coordinate

  • y Integer

    a y coordinate


Return: Integer

a list item that is located at the given position. -1 if no any list item can be found.

getItemLocation

(
  • i
)
Object

Inherited from zebra.ui.BaseList:

Return the given list item location.

Parameters:

  • i Integer

    a list item index


Return: Object

a location of the list item. The result is object that has the following structure: { x:{Integer}, y:{Integer} }

getItemSize

(
  • i
)
Object

Inherited from zebra.ui.BaseList:

Return the given list item size.

Parameters:

  • i Integer

    a list item index


Return: Object

a size of the list item. The result is object that has the following structure: { width:{Integer}, height:{Integer} }

getSelected

() Object

Inherited from zebra.ui.BaseList:

Get selected list item


Return: Object

an item

getValue

() Object

Inherited from zebra.ui.BaseList:

Get the list component selected item


Return: Object

a selected item

isItemSelectable

(
  • i
)
Boolean

Inherited from zebra.ui.BaseList:

Test if the given item is selectable.

Parameters:

  • i Integer

    an item index


Return: Boolean

true if the given item is selectable

isSelected

(
  • i
)
Boolean

Inherited from zebra.ui.BaseList:

Test if the given list item is selected

Parameters:

  • i Integer

    an item index


Return: Boolean

true if the item with the given index is selected

keyTyped

(
  • e
)

Inherited from zebra.ui.BaseList:

Define key typed events handler

Parameters:

pageSize

(
  • d
)
Integer protected

Inherited from zebra.ui.BaseList:

The method returns the page size that has to be scroll up or down

Parameters:

  • d Integer

    a scrolling direction. -1 means scroll up, 1 means scroll down


Return: Integer

a number of list items to be scrolled

pointerMoved

(
  • x
  • y
)
protected

Inherited from zebra.ui.BaseList:

Called when a pointer (mouse or finger on touch screen) is moved to a new location

Parameters:

  • x Integer

    a pointer x coordinate

  • y Integer

    a pointer y coordinate

repaintByOffsets

(
  • p
  • n
)
protected

Inherited from zebra.ui.BaseList:

Force repainting of the given list items

Parameters:

  • p Integer

    an index of the first list item to be repainted

  • n Integer

    an index of the second list item to be repainted

select

(
  • index
)

Inherited from zebra.ui.BaseList:

Select the given list item

Parameters:

  • index Integer

    an item index to be selected

setItemGap

(
  • g
)

Set the left, right, top and bottom a list item paddings

Parameters:

  • g Integer

    a left, right, top and bottom a list item paddings

setModel

(
  • m
)
chainable

Inherited from zebra.ui.BaseList:

Set the list model to be rendered with the list component

Parameters:

setPosition

(
  • c
)

Inherited from zebra.ui.BaseList:

Set the given position controller. List component uses position to track virtual cursor.

Parameters:

setValue

(
  • v
)
Integer

Inherited from zebra.ui.BaseList:

Select the specified list item.

Parameters:

  • v Object

    a list item to be selected. Use null as the parameter value to clean an item selection


Return: Integer

an index of a selected item

setViewProvider

(
  • v
)

Inherited from zebra.ui.BaseList:

Set the list items view provider. Defining a view provider allows developers to customize list item rendering.

Parameters:

  • v Object | Function

    a view provider class instance or a function that says which view has to be used for the given list model data. The function has to satisfy the following method signature: "function(list, modelItem, index)"

setViews

(
  • views
)

Inherited from zebra.ui.BaseList:

Sets the views for the list visual elements. The following elements are supported:

   - "select" -  a selection view element   
   - "top.marker" - a position marker view element that is rendered  on top of list item
   - "marker" - a position marker view element

Parameters:

  • views Object

    view elements

Attributes

firstVisible

Integer private readonly

Index of the first visible list item

firstVisibleY

Integer private readonly

Y coordinate of the first visible list item

gap

Inetger readonly

Extra list item side gaps

Default: 2

isComboMode

Boolean readonly

Inherited from zebra.ui.BaseList:

Indicate the current mode the list items selection has to work

Default: false

model

zebra.data.ListModel readonly

Inherited from zebra.ui.BaseList

List model the component visualizes

scrollManager

zebra.ui.ScrollManager protected readonly

Inherited from zebra.ui.BaseList:

Scroll manager

selectedIndex

Integer readonly

Inherited from zebra.ui.BaseList:

Currently selected list item index

Default: -1

visValid

Boolean private

Internal flag to track list items visibility status. It is set to false to trigger list items metrics and visibility recalculation

Events

selected

Inherited from zebra.ui.BaseList:

Fire when a list item has been selected:

   list.bind(function (src, prev) {
       ...
   });

Event Parameters:

  • src zebra.ui.BaseList

    a list that triggers the event

  • prev Integer | Object

    a previous selected index, return null if the selected item has been re-selected