List class

Inheritance UIObject > UIComponent > View > ScrollView > ScrollSelectList > List

ActionScript Class Namespace mx.controls.List

The List component is composed of three parts:

Items
Rows
A data provider

An item is an ActionScript object used for storing the units of information in the list. A list can be thought of as an array; each indexed space of the array is an item. An item is an object that typically has a label property that is displayed and a data property that is used for storing data.

A row is a component that is used to display an item. Rows are either supplied by default by the list (the SelectableRow class is used), or you can supply them, usually as a subclass of the SelectableRow class. The SelectableRow class implements the CellRenderer interface, which is the set of properties and methods that allow the list to manipulate each row and send data and state information (for example, highlighted, selected, and so on) to the row for display.

A data provider is a data model of the list of items in a list. Any array in the same frame as a list is automatically given methods that allow you to manipulate data and broadcast changes to multiple views. You can build an Array instance or get one from a server and use it as a data model for multiple Lists, ComboBoxes, DataGrids, and so on. The List component has a set of methods that proxy to its data provider (for example, addItem() and removeItem()). If no external data provider is provided to the list, these methods create a data provider instance automatically, which is exposed through List.dataProvider.

To add a List component to the tab order of an application, set its tabIndex property (see UIComponent.tabIndex). The List component uses the FocusManager to override the default Flash Player focus rectangle and draw a custom focus rectangle with rounded corners. For more information, see Creating custom focus navigation.

Each component class has a version property which is a class property. Class properties are only available on the class itself. The version property returns a string that indicates the version of the component. To access the version property, use the following code:

trace(mx.controls.List.version);

Note: The following code returns undefined: trace(myListInstance.version);.

Method summary for the List class

Method	Description
`List.addItem()`	Adds an item to the end of the list.
`List.addItemAt()`	Adds an item to the list at the specified index.
`List.getItemAt()`	Returns the item at the specified index.
`List.removeAll()`	Removes all items from the list.
`List.removeItemAt()`	Removes the item at the specified index.
`List.replaceItemAt()`	Replaces the item at the specified index with another item.
`List.setPropertiesAt()`	Applies the specified properties to the specified item.
`List.sortItems()`	Sorts the items in the list according to the specified compare function.
`List.sortItemsBy()`	Sorts the items in the list according to a specified property.

Inherits all methods from UIObject class and UIComponent class.

Property summary for the List class

Property	Description
`List.cellRenderer`	Assigns the cellRenderer to use for each row of the list.
`List.dataProvider`	The source of the list items.
`List.hPosition`	The horizontal position of the list.
`List.hScrollPolicy`	Indicates whether the horizontal scroll bar is displayed (`"on"`) or not (`"off"`).
`List.iconField`	A field within each item to be used to specify icons.
`List.iconFunction`	A function that determines which icon to use.
`List.labelField`	Specifies a field of each item to be used as label text.
`List.labelFunction`	A function that determines which fields of each item to use for the label text.
`List.length`	The length of the list in items. This property is read-only.
`List.maxHPosition`	Specifies the number of pixels the list can scroll to the right, when `List.hScrollPolicy` is set to `"on"`.
`List.multipleSelection`	Indicates whether multiple selection is allowed in the list (`true`) or not (`false`).
`List.rowCount`	The number of rows that are at least partially visible in the list.
`List.rowHeight`	The pixel height of every row in the list.
`List.selectable`	Indicates whether the list is selectable (`true`) or not (`false`).
`List.selectedIndex`	The index of a selection in a single-selection list.
`List.selectedIndices`	An array of the selected items in a multiple-selection list.
`List.selectedItem`	The selected item in a single-selection list. This property is read-only.
`List.selectedItems`	The selected item objects in a multiple-selection list. This property is read-only.
`List.vPosition`	Scrolls the list so the topmost visible item is the number assigned.
`List.vScrollPolicy`	Indicates whether the vertical scroll bar is displayed (`"on"`), not displayed(`"off"`), or displayed when needed (`"auto"`).

Inherits all properties from UIObject class and UIComponent class.

Event summary for the List class

Event	Description
`List.change`	Broadcast whenever the selection changes due to user interaction.
`List.itemRollOut`	Broadcast when list items are rolled over and then off by the pointer.
`List.itemRollOver`	Broadcast when list items are rolled over by the pointer.
`List.scroll`	Broadcast when a list is scrolled.

Inherits all events from UIObject class and UIComponent class.