Package | com.ghostwire.ui.controls |
Class | public class uiListBox |
Inheritance | uiListBox ![]() ![]() ![]() |
Subclasses | uiCheckListBox |
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 ~
Property | Defined by | ||
---|---|---|---|
![]() | alignX : Number
Indicates how the component would like to be aligned horizontally within its allocated space.
| uiComponent | |
![]() | alignY : Number
Indicates how the component would like to be aligned vertically within its allocated space.
| uiComponent | |
![]() | background : Object
Indicates the style of the background for this component.
| uiComponent | |
![]() | container : 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 | ||
![]() | depth : int
Indicates how deep the component is in the containment hierarchy.
| uiComponent | |
![]() | desiredAllocationHeight : int
Indicates the vertical space this component would like to be allocated.
| uiComponent | |
![]() | desiredAllocationWidth : int
Indicates the horizontal space this component would like to be allocated.
| uiComponent | |
![]() | enabled : Boolean
Indicates whether the component is enabled for user interaction.
| uiComponent | |
![]() | fillX : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated
horizontal space.
| uiComponent | |
![]() | fillY : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated
vertical space.
| uiComponent | |
![]() | focusPadding : Object
Indicates the thickness of the interior space from the edge of the component to the focus
rectangle.
| uiComponent | |
![]() | focusRect : Object
Indicates the class to use when rendering the rectangle around the component to indicate that it
is in focus.
| uiComponent | |
![]() | height : Number
Indicates the current
height of the component. | uiComponent | |
![]() | hScrollPolicy : 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 | ||
![]() | margin : Object
Indicates the thickness of the space surrounding the component.
| uiComponent | |
![]() | maxHeight : int
Indicates the upper limit for
height . | uiComponent | |
![]() | maxWidth : int
Indicates the upper limit for
width . | uiComponent | |
![]() | minHeight : int
Indicates the lower limit for
height . | uiComponent | |
![]() | minWidth : 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 | ||
![]() | padding : 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 | |
![]() | rangeH : uiRange
Returns the
uiRange object used to represent the horizontal scroll range. | uiScrollable | |
![]() | rangeV : 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 | ||
![]() | scrollX : Number
Indicates the horizontal scroll position.
| uiScrollable | |
![]() | scrollY : 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 | ||
![]() | skin : String
Indicates the name of the skin to use for this component instance.
| uiComponent | |
![]() | stretch : Boolean
Indicates whether surplus space available in the parent container should be allocated to this
component.
| uiComponent | |
![]() | textStyle : String
Indicates the style to use for
uiText instances contained in this component. | uiComponent | |
![]() | toolTip : Object
Indicates the content (text) of the tooltip that should be shown when the mouse hovers
over this control.
| uiComponent | |
![]() | uihscrollbar : uiScrollBar
Returns the
uiScrollBar instance used in this component. | uiScrollable | |
![]() | uiskin : uiBitmapImage
Returns the
uiBitmapImage rendered as the skin - for advanced users only. | uiComponent | |
![]() | uivscrollbar : uiVScrollBar
Returns the
uiVScrollBar instance used in this component. | uiScrollable | |
![]() | visible : Boolean
Indicates whether or not the component is visible within its container.
| uiComponent | |
![]() | vScrollPolicy : String
A
String value indicating if the vertical scroll bar should be shown. | uiScrollable | |
![]() | width : Number
Indicates the current
width of the component. | uiComponent |
Method | Defined by | ||
---|---|---|---|
uiListBox(items:Object = null)
Constructor - creates a new
uiListBox instance. | uiListBox | ||
getLabel(item:Object):String
Returns the text displayed by an item.
| uiListBox | ||
![]() |
invalidate(type:String):void
Invalidates this component's "size", "display", "layout" or "textstyle".
| uiComponent | |
![]() |
move(x:Number, y:Number, noEvent:Boolean = false):void
Moves the component to the specified position, disregarding its allocation.
| uiComponent | |
![]() |
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 | ||
![]() |
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 | |
![]() |
setScrollPosition(x:int, y:int, noEvent:Boolean = false):void
Sets the
scrollX and scrollY positions, dispatching a "scroll" event. | uiScrollable | |
![]() |
setSize(width:Number, height:Number, noEvent:Boolean = false):void
Sets this component's size to the specified
width and height . | uiComponent | |
![]() |
setVisible(value:Boolean, noEvent:Boolean = false):void
Sets the visibility of this component instance, dispatching a "show" or "hide" event accordingly.
| uiComponent | |
![]() |
validateNow():void
Validates and render the component instance, and any component instances with
depth higher than itself in the validation queue, immediately. | uiComponent |
Event | Summary | Defined by | ||
---|---|---|---|---|
Dispatched when the selection in the list has changed. | uiListBox | |||
![]() |
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 | |||
![]() |
Dispatched when the component's position within its parent container has changed via calling the
move() method. | uiComponent | ||
![]() |
Dispatched when the component's size has changed via calling the setSize() method. | uiComponent | ||
![]() | Dispatched when the scroll position of a scrollable component has changed. | uiScrollable | ||
![]() |
Dispatched when the component's visible property is changed from false to
true via calling the setVisible() method. | uiComponent |
dataMap | property |
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
itemRenderer | property |
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
.
public function get itemRenderer():Class
public function set itemRenderer(value:Class):void
See also
model | property |
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
.
public function get model():uiModel
public function set model(value:uiModel):void
See also
multipleSelect | property |
multipleSelect:Boolean
[read-write]Indicates whether multiple items can be selected.
The default value is false
.
public function get multipleSelect():Boolean
public function set multipleSelect(value:Boolean):void
rowCount | property |
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
.
public function get rowCount():int
public function set rowCount(value:int):void
rowHeight | property |
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
.
public function get rowHeight():int
public function set rowHeight(value:int):void
rowWidth | property |
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
.
public function get rowWidth():int
public function set rowWidth(value:int):void
selectable | property |
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
selectedIndex | property |
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
.
public function get selectedIndex():int
public function set selectedIndex(value:int):void
selectedIndices | property |
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
.
public function get selectedIndices():Array
public function set selectedIndices(value:Array):void
selectedItem | property |
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
.
public function get selectedItem():Object
public function set selectedItem(value:Object):void
selectedItems | property |
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
.
public function get selectedItems():Array
public function set selectedItems(value:Array):void
selectedValue | property |
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
.
public function get selectedValue():Object
See also
uiListBox | () | constructor |
public function uiListBox(items:Object = null)
Constructor - creates a new uiListBox
instance.
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.
|
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).
item:Object |
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.
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.
change | event |
interaction | event |
com.ghostwire.ui.events.uiInteractiveItemEvent
Dispatched whenever the user interacts with any item in the list.