qnx.ui.listClasses.List

	Property	Defined 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
		containment : 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
		size : Number Gets or sets the size for this component (as a percentage of the container's size, or in pixels).	UIComponent
		sizeMode : String Gets or sets the size mode for this component.	UIComponent
		sizeUnit : String Gets or sets the unit of measure for the size property.	UIComponent

	Method	Defined By
		List() 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
		destroy():void Call this method when you want to have your object collected by the garbage collector.	UIComponent
		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
		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
		setPosition(x:Number, y:Number):void Sets the x and y position of the component.	UIComponent
		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

	Method	Defined By
		callLater(method:Function):void Calls the specified method on the next frame or the next render, which ever happens first.	UIComponent
		createInstance(linkage:Object):DisplayObject Calling this method will attempt to create a DisplayObject instance based on the value of the linkage parameter.	UIComponent
		draw():void Called every time you set the width and height of the component.	UIComponent
		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
		onAdded():void Called when the instance is added to the stage.	UIComponent
		onRemoved():void Called when the instance is removed from the stage.	UIComponent
		setEnabled(val:Boolean):void Called when the enabled property changes.	UIComponent
		validate(property:String = all):void Lets the component know that the specified property has been validated.	UIComponent

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

Property Detail

allowDeselect

property

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

property

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

property

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

enableShadows

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

property

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

()

Constructor

public function List()

Instantiates a List object.

Method Detail

addItem

()

method

public function addItem(item:Object):void

Appends an item to the end of the list.

Parameters

item:Object — The item to add.

addItemAt

()

method

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

()

method

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

()

method

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

()

method

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

()

method

protected function mouseWheel(event:MouseEvent):void

Parameters

event:MouseEvent

removeAll

()

method

public function removeAll():void

Removes all the items from the list.

removeItem

()

method

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

()

method

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

()

method

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

()

method

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

()

method

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

()

method

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

()

method

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

()

method

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

()

method

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

()

method

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

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

Dispatched when a change has occurred in the DataProvider.

listItemClicked

Event

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

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

Dispatched when scrolling begins.

scrollEnd

Event

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

Dispatched when scrolling ends.

scrollMove

Event

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...");            
        }        
    }
}

BlackBerry® Tablet OS SDK for Adobe® AIR® API Reference v 2.0 Beta	All Packages \| All Classes \| Index \| Frames No Frames
List	Properties \| Methods \| Events \| Examples

Package	qnx.ui.listClasses
Class	public class List
Inheritance	List UIComponent flash.display.MovieClip
Implements	IDataViewer
Subclasses	RoundList, SectionList, TileList