qnx.fuse.ui.listClasses.List

	Property	Defined By
		allowDeselect : Boolean Determines if a selected cell in the list can be deselected when pressed.	List
		cellRenderer : Object Sets the cell renderer to use to populate the list.	List
		columnWidth : int Gets or sets the width of each column in the list.	List
		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
		explicitHeight : Number [read-only]	UIComponent
		explicitWidth : Number [read-only]	UIComponent
		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
		includeInLayout : Boolean Specifies if the component should be included in it's parent containers layout.	UIComponent
		lastVisibleItem : ICellRenderer [read-only] Returns the last visible item in the view port area as defined by the width and height	List
		layoutData : Object Returns the layout data for the object.	UIComponent
		minHeight : Number Sets the minimum preferred height of the control.	UIComponent
		minWidth : Number Sets the minimum preferred width of the control.	UIComponent
		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 : uint 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 or 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

	Property	Defined By
		displayListIsInvalid : Boolean = false	UIComponent
		propertiesAreInvalid : Boolean = false	UIComponent
		sizeChange : Boolean	UIComponent
		stateChanged : Boolean	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
		childChanged(resizedChild:DisplayObject = null):Boolean [override] Notifies the UIComponent that one or more of its children has changed in a manner that may affect this object's layout.	List
		destroy():void Call this method when you want to have your object collected by the garbage collector.	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
		getSizeOptions():int [override] Returns a flag indicating whether or not the list can grow vertically or horizontally.	List
		invalidateDisplayList():void Calling this method results in a call to the components validateDisplayList() method before the display list is rendered.	UIComponent
		invalidateProperties():void Calling this method results in a call to the components validateProperties() method before the display list is rendered.	UIComponent
		measure(availableWidth:Number, availableHeight:Number):LayoutMeasurement	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
		setActualSize(w:Number, h:Number):void Sets the width and height of the object without setting the explicitWidth and explicitHeight.	UIComponent
		setLayoutBounds(bounds:Rectangle):void Sets the receiver's size and location to the rectangular area specified by the arguments.	UIComponent
		setPosition(x:Number, y:Number):void Sets the x and y position of the component.	UIComponent
		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
		validateDisplayList():void Validates the display list of the component by calling the updateDisplayList().	UIComponent
		validateNow():void Validates the component immediately by calling validateProperties(), validateSizes(), and validateDisplayList() if necessary.	UIComponent
		validateProperties():void Validates the properties of the component by calling the commitProperties() method.	UIComponent

	Method	Defined By
		commitProperties():void Process properties of the component.	UIComponent
		commitState():void Process the state of the component.	UIComponent
		doMeasure(availableX:Number, availableY:Number):LayoutMeasurement [override]	List
		flushCache():void Invoked as part of parentLayoutChanged.	UIComponent
		onAdded():void Called when the instance is added to the stage.	UIComponent
		onRemoved():void Called when the instance is removed from the stage.	UIComponent
		parentLayoutChanged():void Invalidates the parent's size and display list if includeInLayout property is set to true.	UIComponent
		updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void Sets the size and position of the children of the component.	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

cellRenderer

property

cellRenderer:Object

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.cellRenderer = MyCustomCellRenderer;

The default value is AlternatingCellRenderer.

Implementation
public function get cellRenderer():Object
public function set cellRenderer(value:Object):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

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.

If the list is scrolled beyond the first item when set to false, the list will be scrolled back to the beginning.

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:uint

Gets or sets the color of the scroll bar.

The default value is 0x737a80.

Implementation
public function get scrollBarColor():uint
public function set scrollBarColor(value:uint):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 or 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()

childChanged

()

method

override public function childChanged(resizedChild:DisplayObject = null):Boolean

Notifies the UIComponent that one or more of its children has changed in a manner that may affect this object's layout. Subclasses may override this method to clear any cached information about their children or to opt out of changing their parent.

Parameters

resizedChild:DisplayObject (default = null) — if this is non-null, it indicates specifically that the getSizeOptions() or measure() method for the given child has changed. If this is null, it indicates any other kind of change that may affect this layout, including children being added, removed, reordered, a change in layout data or a change in the layout itself.

Returns

Boolean — true if this change may have an effect on the receiver's getSizeOptions or measure method. false if there is no chance of this change having any effect on the receiver's getSizeOptions or measure method.

doMeasure

()

method

override protected function doMeasure(availableX:Number, availableY:Number):LayoutMeasurement

Parameters

	`availableX:Number`

	`availableY:Number`

Returns

LayoutMeasurement

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.

getSizeOptions

()

method

override public function getSizeOptions():int

Returns a flag indicating whether or not the list can grow vertically or horizontally.

The flag has the following possible values:

SizeOptions.RESIZE_VERTICAL indicates that the list can grow vertically.
SizeOptions.RESIZE_HORIZONTAL indicates that the list can grow horizontally.

Returns

int — A bitwise combination of constants indicating whether or not this control can resize in a given direction.

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.

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.fuse.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.fuse.ui.events.ScrollEvent
ScrollEvent.type property = qnx.ui.events.ScrollEvent.SCROLL_BEGIN

Dispatched when scrolling begins.

scrollEnd

Event

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

Dispatched when scrolling ends.

scrollMove

Event

Event Object Type: qnx.fuse.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.fuse.ui.events.ListEvent;
    import qnx.fuse.ui.events.ScrollEvent;
    import qnx.fuse.ui.listClasses.List;
    import qnx.fuse.ui.listClasses.ListSelectionMode;
    import qnx.fuse.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.fuse.ui.listClasses
Class	public class List
Inheritance	List UIComponent flash.display.MovieClip
Implements	IDataViewer
Subclasses	RoundList, SectionList, TileList