qnx.ui.listClasses.List

List

Properties | Methods | Events | Examples


Packageqnx.ui.listClasses
Classpublic class List
InheritanceList Inheritance UIComponent Inheritance flash.display.MovieClip
Implements IDataViewer
Subclasses RoundList, SectionList, TileList

The List class enables you to display cells in a vertical or horizontal scrolling list. You can define the appearance of the list, the scrolling behavior of the list, and the list selection mode, which determines how he user interacts with each cell in the list.

The following image shows a List instance:

A list.

Each cell has a default look and feel, however you can create a custom cell renderer by calling the setSkin method. Your custom cell renderers must implement the ICellRenderer interface. Each cell is laid out by using the rowHeight property for vertical lists, and columnWidth for horizontal lists. If your custom cells are larger than the default value, you should set the rowHeight or the columnWidth property to the desired size.



Class information:
PlayBook Tablet OS Version:   1.0.6

View the examples

See also

setSkin()
rowHeight
columnWidth
SectionList
TileList
DropDown



Public Properties

 PropertyDefined By
  allowDeselect : Boolean
Determines if a selected cell in the list can be deselected when pressed.
List
  columnWidth : int
Gets or sets the width of each column in the list.
List
 Inheritedcontainment : String
Gets or sets a property that determines how a component is contained within a parent container.
UIComponent
  dataProvider : IDataProvider
Gets or sets the DataProvider instance for the list.
List
  enableShadows : Boolean
Sets or gets whether the scroll shadows should be shown.
List
  firstVisibleItem : ICellRenderer
[read-only] Returns the first visible item in the view port area as defined by the width and height
List
  footerView : DisplayObject
Gets or sets the footer view.
List
  lastVisibleItem : ICellRenderer
[read-only] Returns the last visible item in the view port area as defined by the width and height
List
  rowHeight : int
Gets or sets the height of each row in the list.
List
  scrollable : Boolean
Gets or sets a value that determines whether a list can be scrolled.
List
  scrollBarAlpha : Number
Gets or sets the opacity value for the scroll bar on the list.
List
  scrollBarColor : Number
Gets or sets the color of the scroll bar.
List
  scrollBarOffset : int
Gets or sets the x or y postion of the scrollbar, in pixels.
List
  scrollDirection : String
Gets and sets the scroll direction of the list.
List
  selectedIndex : int
Gets or sets the index of the currently selected item in a single-selection list.
List
  selectedIndices : Array
Gets or sets the selected cells at the specified indices in a multi-selectable list.
List
  selectedItem : Object
Gets or sets the currently selected item in a single-selectable list.
List
  selectedItems : Array
Gets or sets the group of selected items (selectedItems) in a multi-selectable list.
List
  selectionMode : int
Gets or sets a value that determines whether or not selection mode is enabled.
List
 Inheritedsize : Number
Gets or sets the size for this component (as a percentage of the container's size, or in pixels).
UIComponent
 InheritedsizeMode : String
Gets or sets the size mode for this component.
UIComponent
 InheritedsizeUnit : String
Gets or sets the unit of measure for the size property.
UIComponent

Public Methods

 MethodDefined By
  
Instantiates a List object.
List
  
addItem(item:Object):void
Appends an item to the end of the list.
List
  
addItemAt(item:Object, index:int):void
Adds an item to the list at the specified index.
List
  
addItemsAt(items:Array, index:int):void
Adds an array item at the specified index.
List
 Inherited
destroy():void
Call this method when you want to have your object collected by the garbage collector.
UIComponent
 Inherited
drawNow():void
Calls the draw() method.
UIComponent
  
getIsCellVisibleAtIndex(index:int):Boolean
Returns a Boolean indicating whether or not a cell at a given index is visible in the virtual area.
List
  
getItemAt(index:int):Object
Returns the item in the DataProvider at the specified index.
List
 Inherited
invalidate(property:String = all, invalidateNow:Boolean = false):void
Marks the property as invalid and the draw() method is called on the next frame or the next render, whichever comes first.
UIComponent
  
removeAll():void
Removes all the items from the list.
List
  
removeItem(item:Object):void
Removes a given item from the list.
List
  
removeItemAt(index:int):void
Removes an item from list at the specified index.
List
  
replaceItem(item:Object, oldObject:Object):void
Replaces an item, given the new item object and the old item.
List
  
replaceItemAt(item:Object, index:int):void
Replaces the item in the list at the specified index with a new item.
List
  
scrollIndexVisible(index:int, seconds:Number = 1):void
Scrolls a given item into view, given an index and an animation duration (in seconds).
List
  
scrollToIndex(index:int, seconds:Number = 1):void
Animates the cell at the specified index into view.
List
 Inherited
setPosition(x:Number, y:Number):void
Sets the x and y position of the component.
UIComponent
 Inherited
setSize(w:Number, h:Number):void
Sets the width and height of the component.
UIComponent
  
setSkin(skin:Object):void
Sets the cell renderer to use to populate the list.
List
  
updateItem(value:Object, oldObject:Object):void
Updates an item in the list, given the new item and the item to update.
List
  
updateItemAt(item:Object, index:int):void
Updates the item in the list at the specified index, given the new item.
List
  
updateItemsAt(items:Array, index:int):void
Updates the items starting at the specified index with new items.
List

Protected Methods

 MethodDefined By
 Inherited
callLater(method:Function):void
Calls the specified method on the next frame or the next render, which ever happens first.
UIComponent
 Inherited
createInstance(linkage:Object):DisplayObject
Calling this method will attempt to create a DisplayObject instance based on the value of the linkage parameter.
UIComponent
 Inherited
draw():void
Called every time you set the width and height of the component.
UIComponent
 Inherited
isInvalid(property:String, ... properties):Boolean
Checks to see if the property is invalid and returns true if it is.
UIComponent
  
mouseWheel(event:MouseEvent):void
List
 Inherited
onAdded():void
Called when the instance is added to the stage.
UIComponent
 Inherited
onRemoved():void
Called when the instance is removed from the stage.
UIComponent
 Inherited
setEnabled(val:Boolean):void
Called when the enabled property changes.
UIComponent
 Inherited
validate(property:String = all):void
Lets the component know that the specified property has been validated.
UIComponent

Events

 Event Summary Defined By
  Dispatched when a change has occurred in the DataProvider.List
   Dispatched when a cell renderer is clicked.List
   Dispatched when scrolling begins.List
   Dispatched when scrolling ends.List
   Dispatched when scrolling occurs.List

Property Detail

allowDeselect


allowDeselect:Boolean

Determines if a selected cell in the list can be deselected when pressed.

The default value is true - By default, cells can be deselected..


Implementation

public function get allowDeselect():Boolean
public function set allowDeselect(value:Boolean):void

columnWidth


columnWidth:int

Gets or sets the width of each column in the list.

This value is used in order to lay out the cells in a horizontal list. This value is passed to each renderer, to ensure that a renderer does not draw beyond this value.

The default value is 0.


Implementation

public function get columnWidth():int
public function set columnWidth(value:int):void

dataProvider


dataProvider:IDataProvider

Gets or sets the DataProvider instance for the list. The DataProvider must be of type IDataProvider.

When the data is updated, an Event.CHANGE is dispatched from the list. If set to null, the list creates an empty DataProvider instance and all current items are removed. You can also use the IDataViewer API in order to modify the data in the list.


Implementation

public function get dataProvider():IDataProvider
public function set dataProvider(value:IDataProvider):void

See also

addItem()
addItemAt()
removeItem()
removeItemAt()
getItemAt()
replaceItemAt()
DataProvider

enableShadows


enableShadows:Boolean

Sets or gets whether the scroll shadows should be shown. The scroll shadows appear on the edge of the right edge of the list when the list is scrolled. The scroll shadows provide the user with some context about the length of the list, and the amount of data that is outside of the viewport.

The default value is true.


Implementation

public function get enableShadows():Boolean
public function set enableShadows(value:Boolean):void

firstVisibleItem


firstVisibleItem:ICellRenderer  [read-only]

Returns the first visible item in the view port area as defined by the width and height


Implementation

public function get firstVisibleItem():ICellRenderer

See also

qnx.ui.listClasses.ICellRenderer

footerView


footerView:DisplayObject

Gets or sets the footer view.

A footer view is any display object that can be anchored to the last item in the list. You can add a footer view to add items to a list, such as a "Load More" button at the end of a list. The footer view has an x position value set to 0, can be any DisplayObject, and does not have to implement the ICellRenderer interface. Because the footer view can be any DisplayObject, the list does not resize it to match the dimensions of the list.

To remove the current footer view from the list, set the footerView property to null.

The following listing sets a labelButton instance to the footerView property of the list.

        var myList:List = new List();            
        myList.setPosition(100, 100);            
        myList.width = 300;            
        myList.height = 400;
        myList.columnWidth = 100;
        
        //set the dataProvider
        myList.selectionMode = ListSelectionMode.MULTIPLE;            
        myList.dataProvider = new DataProvider(arrMonth);
        
        var myButton:LabelButton = new LabelButton();
        myButton.label = "Submit";
        myButton.width = 300;
        myList.footerView = myButton;
        

The code listing above produces the following footer:

A footer view in a list.


Implementation

public function get footerView():DisplayObject
public function set footerView(value:DisplayObject):void

lastVisibleItem


lastVisibleItem:ICellRenderer  [read-only]

Returns the last visible item in the view port area as defined by the width and height


Implementation

public function get lastVisibleItem():ICellRenderer

See also

ICellRenderer

rowHeight


rowHeight:int

Gets or sets the height of each row in the list.

This value is used in order to lay out the cells in a vertical list. This value is passed to each renderer, to ensure that a renderer does not draw beyond this value.

The default value is 47.


Implementation

public function get rowHeight():int
public function set rowHeight(value:int):void

scrollable


scrollable:Boolean

Gets or sets a value that determines whether a list can be scrolled.

When set to true the list can be scrolled. When set to false the list will not scroll, however cells can still be selected.


Implementation

public function get scrollable():Boolean
public function set scrollable(value:Boolean):void

scrollBarAlpha


scrollBarAlpha:Number

Gets or sets the opacity value for the scroll bar on the list.

When the list is pressed it reveals the scroll bar. The scroll bar alpha determines the opacity of the scroll bar when it is revealed.

The default value is 0.5.


Implementation

public function get scrollBarAlpha():Number
public function set scrollBarAlpha(value:Number):void

scrollBarColor


scrollBarColor:Number

Gets or sets the color of the scroll bar.

The default value is 0x737a80.


Implementation

public function get scrollBarColor():Number
public function set scrollBarColor(value:Number):void

See also

scrollBarAlpha

scrollBarOffset


scrollBarOffset:int

Gets or sets the x or y postion of the scrollbar, in pixels.

The offset value is relative to the scrollDirection property and is used to position the scrollbar relative to the edge of the list. For example, if a list scrolls vertically, the offset value is relative to the right edge of the list, since the scroll bar appears on the right side of the list. If a list scrolls horizontally, the offset value is relative to the bottom edge of the list.

The default value is 10.


Implementation

public function get scrollBarOffset():int
public function set scrollBarOffset(value:int):void

See also

scrollDirection

scrollDirection


scrollDirection:String

Gets and sets the scroll direction of the list.

There are two directions a list can be scrolled. These are defined in ScrollDirection class:

  • ScrollDirection.HORIZONTAL - indicates horizontal scrolling
  • ScrollDirection.VERTICAL - indicates vertical scrolling

The default value is ScrollDirection.VERTICAL.


Implementation

public function get scrollDirection():String
public function set scrollDirection(value:String):void

See also

ScrollDirection

selectedIndex


selectedIndex:int

Gets or sets the index of the currently selected item in a single-selection list.

In a single-selection list, only one item can be selected at a time. A value of -1 indicates that no item is selected. If multiple selections are made, this value is equal to the index of the item that was selected last in the group of selected items.

When the selection is changed programmatically, the item at the specified index replaces the current selection. A change event object is not dispatched.


Implementation

public function get selectedIndex():int
public function set selectedIndex(value:int):void

selectedIndices


selectedIndices:Array

Gets or sets the selected cells at the specified indices in a multi-selectable list.


Implementation

public function get selectedIndices():Array
public function set selectedIndices(value:Array):void

selectedItem


selectedItem:Object

Gets or sets the currently selected item in a single-selectable list.


Implementation

public function get selectedItem():Object
public function set selectedItem(value:Object):void

Throws
ArgumentError — thrown if the specified item is not currently in the dataProvider of the list.

See also

selectedIndex

selectedItems


selectedItems:Array

Gets or sets the group of selected items (selectedItems) in a multi-selectable list.


Implementation

public function get selectedItems():Array
public function set selectedItems(value:Array):void

Throws
ArgumentError — thrown if one of the specified item is not currently in the DataProvider of the list.

selectionMode


selectionMode:int

Gets or sets a value that determines whether or not selection mode is enabled.

Selection mode determines how a user interacts with a list by controlling how items are selected and unselected when clicked. For example, depending on the selection mode a user can select multiple items or only a single item at any one time.

Valid values are:

  • ListSelectionMode.NONE - indicates that cells are not selected when pressed
  • ListSelectionMode.SINGLE - indicates that only a single cell can be selected at a given time
  • ListSelectionMode.MULTIPLE - indicates that multiple cells can be selected at any given time

If the selectionMode property is changed at runtime, the current list selection will be cleared.

The default value is ListSelectionMode.NONE. Default is no selection.


Implementation

public function get selectionMode():int
public function set selectionMode(value:int):void

See also

ListSelectionMode

Constructor Detail

List()


public function List()

Instantiates a List object.

Method Detail

addItem()


public function addItem(item:Object):void

Appends an item to the end of the list.

Parameters

item:Object — The item to add.

addItemAt()


public function addItemAt(item:Object, index:int):void

Adds an item to the list at the specified index.

Parameters

item:Object — The item to add.
index:int — The offset value at which to add the item.


Throws

RangeError — thrown if the specified index is less than 0 or greater than or equal to the length of the DataProvider.

addItemsAt()


public function addItemsAt(items:Array, index:int):void

Adds an array item at the specified index.

Parameters

items:Array — The array of items to add.
index:int — The index, or offset, at which to add the items.


Throws

RangeError — Thrown if the specified index is less than 0, or greater than or equal to the length of the DataProvider.

See also

addItem()
addItemAt()

getIsCellVisibleAtIndex()


public function getIsCellVisibleAtIndex(index:int):Boolean

Returns a Boolean indicating whether or not a cell at a given index is visible in the virtual area.

This includes cells which are not fully in the view of the list.

Parameters

index:int — The index of the cell to check against.

Returns

Boolean — Boolean A Boolean indicating whether or not the cell is visible.

getItemAt()


public function getItemAt(index:int):Object

Returns the item in the DataProvider at the specified index.

Parameters

index:int — The index of the item to return.

Returns

Object — The item at the specified index.

Throws

RangeError — thrown if the specified index is less than 0 or greater than or equal to the length of the DataProvider.

mouseWheel()


protected function mouseWheel(event:MouseEvent):void

Parameters

event:MouseEvent

removeAll()


public function removeAll():void

Removes all the items from the list.

removeItem()


public function removeItem(item:Object):void

Removes a given item from the list.

Parameters

item:Object — The item to remove.


Throws

ArgumentError — thrown if the item could not be found in the current DataProvider.

removeItemAt()


public function removeItemAt(index:int):void

Removes an item from list at the specified index.

Parameters

index:int — The index of the object to remove.


Throws

RangeError — thrown if the specified index is less than 0 or greater than or equal to the length of the DataProvider.

replaceItem()


public function replaceItem(item:Object, oldObject:Object):void

Replaces an item, given the new item object and the old item.

Parameters

item:Object — The new item object data.
oldObject:Object — The item to replace.

replaceItemAt()


public function replaceItemAt(item:Object, index:int):void

Replaces the item in the list at the specified index with a new item.

Parameters

item:Object — The new item.
index:int — The index of the item to replace.


Throws

RangeError — thrown if the specified index is less than 0 or greater than or equal to the length of the DataProvider.

scrollIndexVisible()


public function scrollIndexVisible(index:int, seconds:Number = 1):void

Scrolls a given item into view, given an index and an animation duration (in seconds).

This function checks to see if the cell is currently visible before scrolling it into view. If the cell is not fully visible within the viewport of the list, it will scroll it into the viewport. If the cell is fully visible in the viewport, the list will not scroll.

Parameters

index:int — The index of the cell to animate into view.
seconds:Number (default = 1) — The duration of the animation in seconds. Default is 1 second.

scrollToIndex()


public function scrollToIndex(index:int, seconds:Number = 1):void

Animates the cell at the specified index into view.

Parameters

index:int — The index of the cell to animate into view.
seconds:Number (default = 1) — The duration of the animation in seconds. Default is 1 second.

setSkin()


public function setSkin(skin:Object):void

Sets the cell renderer to use to populate the list.

You can pass in a qualified class name String, or the actual class. In either instance the class that is used must implement the ICellRenderer interface.

Note: Do not pass in an instance of a skin class. This may cause unexpected behavior.

In the following example, the setSkin method is called using the class reference "MyCustomCellRenderer".

myList.setPosition(100, 200);
myList.width = 300;
myList.height = 300;
myList.selectionMode = ListSelectionMode.MULTIPLE;
myList.dataProvider = new DataProvider(arrItems);
myList.setSkin(MyCustomCellRenderer);
        

Parameters

skin:Object — The cellrenderer skin class.

updateItem()


public function updateItem(value:Object, oldObject:Object):void

Updates an item in the list, given the new item and the item to update.

Parameters

value:Object — The new, or updated item.
oldObject:Object — The item to update.

updateItemAt()


public function updateItemAt(item:Object, index:int):void

Updates the item in the list at the specified index, given the new item.

Parameters

item:Object — The new, or updated, item.
index:int — The index of the item to update.


Throws

RangeError — thrown if the specified index is less than 0 or greater than or equal to the length of the DataProvider.

updateItemsAt()


public function updateItemsAt(items:Array, index:int):void

Updates the items starting at the specified index with new items.

Parameters

items:Array — The new items to be updated.
index:int — The start index to update the items


Throws

RangeError — Thrown if the specified index is less than 0, or greater than or equal to the length of the data provider.

See also

updateItem()
updateItemAt()

Event Detail

change


Event Object Type: flash.events.Event
Event.type property = flash.events.Event.CHANGE

Dispatched when a change has occurred in the DataProvider.

listItemClicked


Event Object Type: qnx.ui.events.ListEvent
ListEvent.type property = qnx.ui.events.ListEvent.ITEM_CLICKED

Dispatched when a cell renderer is clicked.

scrollBegin


Event Object Type: qnx.ui.events.ScrollEvent
ScrollEvent.type property = qnx.ui.events.ScrollEvent.SCROLL_BEGIN

Dispatched when scrolling begins.

scrollEnd


Event Object Type: qnx.ui.events.ScrollEvent
ScrollEvent.type property = qnx.ui.events.ScrollEvent.SCROLL_END

Dispatched when scrolling ends.

scrollMove


Event Object Type: qnx.ui.events.ScrollEvent
ScrollEvent.type property = qnx.ui.events.ScrollEvent.SCROLL_MOVE

Dispatched when scrolling occurs.

Examples

In the following example, a simple List instance is created. Event listeners are added to the list to capture scroll and click events.
package
{
    import flash.display.Sprite;
    
    import qnx.ui.data.DataProvider;
    import qnx.ui.events.ListEvent;
    import qnx.ui.events.ScrollEvent;
    import qnx.ui.listClasses.List;
    import qnx.ui.listClasses.ListSelectionMode;
    import qnx.ui.listClasses.ScrollDirection;    
    
    [SWF(height="600", width="1024", frameRate="30", backgroundColor="#FFFFFF")]
    public class listSample extends Sprite
    {
        public function listSample()
        {
            initializeUI();
        }
        
        private function initializeUI():void
        {
            
            var arrMonth:Array=[];
            // add objects with a label property
            arrMonth.push({label: "January"});
            arrMonth.push({label: "February"});
            arrMonth.push({label: "March"});
            arrMonth.push({label: "April"});
            arrMonth.push({label: "May"});
            arrMonth.push({label: "June"});
            arrMonth.push({label: "July"});
            arrMonth.push({label: "August"});
            arrMonth.push({label: "September"});
            arrMonth.push({label: "October"});
            arrMonth.push({label: "November"});
            arrMonth.push({label: "December"});
            
            var myList:List = new List();            
            myList.setPosition(100, 100);            
            myList.width = 300;            
            myList.height = 400;
            myList.columnWidth = 100;
            
            //set the dataProvider
            myList.selectionMode = ListSelectionMode.MULTIPLE;
            myList.scrollDirection = ScrollDirection.VERTICAL;
            myList.dataProvider = new DataProvider(arrMonth);
                        
            myList.addEventListener(ListEvent.ITEM_CLICKED, onListClick);
            myList.addEventListener(ScrollEvent.SCROLL_END, onScroll);
            myList.addEventListener(ScrollEvent.SCROLL_BEGIN, onScrollStart);
            
            this.addChild(myList);
            
        }
        
        private function onListClick(event:ListEvent):void {
            
            trace("Item clicked: " + event.data.label);
            trace("Index clicked: " + event.index);
        }
        
        private function onScroll(event:ScrollEvent):void {
            
            trace("Finished scrolling...");            
        }
        
        private function onScrollStart(event:ScrollEvent):void {
            
            trace("Start scrolling...");            
        }        
    }
}