Packagecom.ghostwire.ui.controls
Classpublic class uiListBox
InheritanceuiListBox Inheritance uiScrollable Inheritance uiComponent Inheritance flash.display.Sprite
SubclassesuiCheckListBox

The uiListBox displays a list of items within a scrollable area.

"skin" Property
The default value is "ListBox" and the asset(s) used are:

 ListBox.png
 ListBoxItem.png
 

~ This class is available in Aspire UI Components Lite Edition ~



Public Properties
 PropertyDefined by
 InheritedalignX : Number
Indicates how the component would like to be aligned horizontally within its allocated space.
uiComponent
 InheritedalignY : Number
Indicates how the component would like to be aligned vertically within its allocated space.
uiComponent
 Inheritedbackground : Object
Indicates the style of the background for this component.
uiComponent
 Inheritedcontainer : uiComponent
Indicates the uiComponent instance that contains this instance.
uiComponent
  dataMap : Object
Indicates an object used to map properties in the renderers to properties in the data objects (items).
uiListBox
 Inheriteddepth : int
Indicates how deep the component is in the containment hierarchy.
uiComponent
 InheriteddesiredAllocationHeight : int
Indicates the vertical space this component would like to be allocated.
uiComponent
 InheriteddesiredAllocationWidth : int
Indicates the horizontal space this component would like to be allocated.
uiComponent
 Inheritedenabled : Boolean
Indicates whether the component is enabled for user interaction.
uiComponent
 InheritedfillX : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated horizontal space.
uiComponent
 InheritedfillY : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated vertical space.
uiComponent
 InheritedfocusPadding : Object
Indicates the thickness of the interior space from the edge of the component to the focus rectangle.
uiComponent
 InheritedfocusRect : Object
Indicates the class to use when rendering the rectangle around the component to indicate that it is in focus.
uiComponent
 Inheritedheight : Number
Indicates the current height of the component.
uiComponent
 InheritedhScrollPolicy : String
A String value indicating if the horizontal scroll bar should be shown.
uiScrollable
  itemRenderer : Class
Indicates the class to use to paint the "face" of the item.
uiListBox
 Inheritedmargin : Object
Indicates the thickness of the space surrounding the component.
uiComponent
 InheritedmaxHeight : int
Indicates the upper limit for height.
uiComponent
 InheritedmaxWidth : int
Indicates the upper limit for width.
uiComponent
 InheritedminHeight : int
Indicates the lower limit for height.
uiComponent
 InheritedminWidth : int
Indicates the lower limit for width.
uiComponent
  model : uiModel
Indicates the uiModel that holds the items of this uiListBox.
uiListBox
  multipleSelect : Boolean
Indicates whether multiple items can be selected.
uiListBox
 Inheritedpadding : Object
Indicates the thickness of the interior space from the edge of the component to the content area, which is where child components, if any, are contained.
uiComponent
 InheritedrangeH : uiRange
Returns the uiRange object used to represent the horizontal scroll range.
uiScrollable
 InheritedrangeV : uiRange
Returns the uiRange object used to represent the vertical scroll range.
uiScrollable
  rowCount : int
Indicates the preferred number of rows to display.
uiListBox
  rowHeight : int
Indicates the fixed value to be used for the height of every row in the list.
uiListBox
  rowWidth : int
Indicates the fixed value to be used for the width of every item in the list.
uiListBox
 InheritedscrollX : Number
Indicates the horizontal scroll position.
uiScrollable
 InheritedscrollY : Number
Indicates the vertical scroll position.
uiScrollable
  selectable : Boolean
Indicates whether items in this list are selectable.
uiListBox
  selectedIndex : int
Indicates the index position of the last selected item.
uiListBox
  selectedIndices : Array
Returns an array of index positions of the selected items.
uiListBox
  selectedItem : Object
Indicates the last selected item.
uiListBox
  selectedItems : Array
Gets or sets an array containing the selected items.
uiListBox
  selectedValue : Object
[read-only] Indicates the value associated with the last selected item.
uiListBox
 Inheritedskin : String
Indicates the name of the skin to use for this component instance.
uiComponent
 Inheritedstretch : Boolean
Indicates whether surplus space available in the parent container should be allocated to this component.
uiComponent
 InheritedtextStyle : String
Indicates the style to use for uiText instances contained in this component.
uiComponent
 InheritedtoolTip : Object
Indicates the content (text) of the tooltip that should be shown when the mouse hovers over this control.
uiComponent
 Inheriteduihscrollbar : uiScrollBar
Returns the uiScrollBar instance used in this component.
uiScrollable
 Inheriteduiskin : uiBitmapImage
Returns the uiBitmapImage rendered as the skin - for advanced users only.
uiComponent
 Inheriteduivscrollbar : uiVScrollBar
Returns the uiVScrollBar instance used in this component.
uiScrollable
 Inheritedvisible : Boolean
Indicates whether or not the component is visible within its container.
uiComponent
 InheritedvScrollPolicy : String
A String value indicating if the vertical scroll bar should be shown.
uiScrollable
 Inheritedwidth : Number
Indicates the current width of the component.
uiComponent
Public Methods
 MethodDefined by
  
uiListBox(items:Object = null)
Constructor - creates a new uiListBox instance.
uiListBox
  
getLabel(item:Object):String
Returns the text displayed by an item.
uiListBox
 Inherited
invalidate(type:String):void
Invalidates this component's "size", "display", "layout" or "textstyle".
uiComponent
 Inherited
move(x:Number, y:Number, noEvent:Boolean = false):void
Moves the component to the specified position, disregarding its allocation.
uiComponent
 Inherited
removeAllChildren(all:Boolean = false):void
Removes all children from this component.
uiComponent
  
scrollToItem(item:Object):void
Scrolls to the indicated item in the list.
uiListBox
  
selectAll():void
Selects all items in this list.
uiListBox
 Inherited
setFocus(flag:Boolean = true):void
Gives this component instance the focus; the component must be on the display list and has its tabEnabled property set to true, otherwise this method will fail silently.
uiComponent
 Inherited
setScrollPosition(x:int, y:int, noEvent:Boolean = false):void
Sets the scrollX and scrollY positions, dispatching a "scroll" event.
uiScrollable
 Inherited
setSize(width:Number, height:Number, noEvent:Boolean = false):void
Sets this component's size to the specified width and height.
uiComponent
 Inherited
setVisible(value:Boolean, noEvent:Boolean = false):void
Sets the visibility of this component instance, dispatching a "show" or "hide" event accordingly.
uiComponent
 Inherited
validateNow():void
Validates and render the component instance, and any component instances with depth higher than itself in the validation queue, immediately.
uiComponent
Events
 EventSummaryDefined by
   Dispatched when the selection in the list has changed.uiListBox
 Inherited Dispatched when the component's visible property is changed from true to false via calling the setVisible() method.uiComponent
   Dispatched whenever the user interacts with any item in the list.uiListBox
 Inherited Dispatched when the component's position within its parent container has changed via calling the move() method.uiComponent
 Inherited Dispatched when the component's size has changed via calling the setSize() method.uiComponent
 Inherited Dispatched when the scroll position of a scrollable component has changed.uiScrollable
 Inherited Dispatched when the component's visible property is changed from false to true via calling the setVisible() method.uiComponent
Property detail
dataMapproperty
dataMap:Object  [read-write]

Indicates an object used to map properties in the renderers to properties in the data objects (items).

For example, if you are using uiLabel as the renderer, you can map the image property of the uiLabel to an image property in the item, and the text property in uiLabel to a label property in the item, as follows:
myListBox.dataMap = {text:"label",image:"image"};

The above example happens to describe the default dataMap used if none is specified (property set to null).

Instead of mapping to a property in the data object, you can also map to a custom callback function. The function must accept one single parameter (the data object used to describe the item) and must return the value to be used for the specified property in the renderer.

Implementation
    public function get dataMap():Object
    public function set dataMap(value:Object):void
itemRendererproperty 
itemRenderer:Class  [read-write]

Indicates the class to use to paint the "face" of the item. Suitable classes include uiText, uiLabel and uiImage, or any custom uiComponent subclasses made for this purpose. Renderer classes do not need to implement any special interfaces, as long as their "rendering" properties, such as the text or image properties, are mapped accordingly via the dataMap property.

When set to null (default value), the uiText class is used.

Note that the renderer is exactly just that - the renderer of the "face". This is not the same as the renderer container, which is the uiInteractiveItem, responsible for the keyboard and mouse events. In this way, when implementing renderers we do not need to worry about uiInteractiveItem responsibilities. This also makes it possible to use components such as the uiText and uiImage as the renderer without having to subclass them and/or implement additional interfaces.

The default value is null.

Implementation
    public function get itemRenderer():Class
    public function set itemRenderer(value:Class):void

See also

modelproperty 
model:uiModel  [read-write]

Indicates the uiModel that holds the items of this uiListBox.

Setting this property to null will set it to a new empty uiModel.

The default value is an empty uiModel object.

Implementation
    public function get model():uiModel
    public function set model(value:uiModel):void

See also

multipleSelectproperty 
multipleSelect:Boolean  [read-write]

Indicates whether multiple items can be selected.

The default value is false.

Implementation
    public function get multipleSelect():Boolean
    public function set multipleSelect(value:Boolean):void
rowCountproperty 
rowCount:int  [read-write]

Indicates the preferred number of rows to display. This may be different from actual number of rows rendered due to actual height of the component instance.

The default value is 8.

Implementation
    public function get rowCount():int
    public function set rowCount(value:int):void
rowHeightproperty 
rowHeight:int  [read-write]

Indicates the fixed value to be used for the height of every row in the list.

If set to 0 (default value), the height of the first item in the model will be applied to every row. For most cases, where the height is expected to be the same for every row, this should be the value to use. In this way, if you change the font size (or renderer or anything else that affects sizing), you do not need to manually change this property.

The default value is 0.

Implementation
    public function get rowHeight():int
    public function set rowHeight(value:int):void
rowWidthproperty 
rowWidth:int  [read-write]

Indicates the fixed value to be used for the width of every item in the list.

If set to 0, the value will increase dynamically to accomodate the widest item in the list. The value is reset to zero only if the list is emptied.

To improve performance, set this property to a fixed positive value. If you know the widest item in the list, use the expected width of that item.

The default value is 0.

Implementation
    public function get rowWidth():int
    public function set rowWidth(value:int):void
selectableproperty 
selectable:Boolean  [read-write]

Indicates whether items in this list are selectable.

Implementation
    public function get selectable():Boolean
    public function set selectable(value:Boolean):void
selectedIndexproperty 
selectedIndex:int  [read-write]

Indicates the index position of the last selected item.

Setting this property selects the item at the indicated index position. If you set this property to a negative number, it means counting from the end of the list (-1 being the last item, -2 the last second item, and so on). To clear all selection, set this property to -1.

Setting this property does not dispatch any change event.

The default value is -1.

Implementation
    public function get selectedIndex():int
    public function set selectedIndex(value:int):void
selectedIndicesproperty 
selectedIndices:Array  [read-write]

Returns an array of index positions of the selected items.

Setting this property selects the items at the indicated positions. To clear all selection, set this property to null.

Setting this property does not dispatch any change event.

Note: negative index positions indicate counting from the end of the list (-1 being the last item, -2 the last second item, and so on). For convenience, you can use negative numbers when setting this property, but the property will only return positive integers when reporting the indices.

The default value is null.

Implementation
    public function get selectedIndices():Array
    public function set selectedIndices(value:Array):void
selectedItemproperty 
selectedItem:Object  [read-write]

Indicates the last selected item.

This property returns null if no item has been selected.

Setting this property selects the indicated item. To clear all selection, set this property to null.

Setting this property does not dispatch any change event.

The default value is null.

Implementation
    public function get selectedItem():Object
    public function set selectedItem(value:Object):void
selectedItemsproperty 
selectedItems:Array  [read-write]

Gets or sets an array containing the selected items.

This property returns null if no item has been selected.

Setting this property changes the selection to the indicated array of items. To clear all selection, set this property to null.

Setting this property does not dispatch any change event.

The default value is null.

Implementation
    public function get selectedItems():Array
    public function set selectedItems(value:Array):void
selectedValueproperty 
selectedValue:Object  [read-only]

Indicates the value associated with the last selected item. If the item has a data property defined, that data property is returned. Otherwise, the text label associated with the item (retrieved via the getLabel() method) is returned.

This property returns null if no item has been selected.

The default value is null.

Implementation
    public function get selectedValue():Object

See also

Constructor detail
uiListBox()constructor
public function uiListBox(items:Object = null)

Constructor - creates a new uiListBox instance.

Parameters
items:Object (default = null) — The list of item(s) to populate the model. You can specify an array of data objects (duplicates will be ignored), an array of strings, or an XML object.
Method detail
getLabel()method
public function getLabel(item:Object):String

Returns the text displayed by an item. This text is usually the label property in the data object, but this default behavior can be overridden via the dataMap property (must be mapped to "text" property).

Parameters
item:Object

Returns
String

See also

scrollToItem()method 
public function scrollToItem(item:Object):void

Scrolls to the indicated item in the list. You can also indicate the index position instead of the item itself.

Parameters
item:Object — The data object used to describe the item. You can specify the item itself, or the index position of the item.
selectAll()method 
public function selectAll():void

Selects all items in this list.

Event detail
changeevent 
Event object type: flash.events.Event

Dispatched when the selection in the list has changed.

interactionevent  
Event object type: com.ghostwire.ui.events.uiInteractiveItemEvent

Dispatched whenever the user interacts with any item in the list.