Aspire UI Components (Flash ActionScript 3.0) Docs
[ Aspire UI ]
 
Trace: » uiToggleFrame » uiSkins » Aspire UI Components » uiMenuBar » uiText » uiTabView » uiTextStyles » uiListBox
You are here: Aspire UI Components » Usage » uiListBox
Table of Contents

uiListBox

The uiListBox component is used to display a list of items within a scrollable area.


Using uiListBox

ActionScript 3.0 Example

 1: import com.ghostwire.ui.controls.uiListBox;
 2: import com.ghostwire.ui.data.uiModel;
 3:
 4: // ** data model **
 5: var model:uiModel = new uiModel();
 6: model.addItem({label:"Item 1",data:"http://url1.com"});
 7: model.addItem({label:"Item 2",data:"http://url2.com"});
 8: model.addItem({label:"Item 3",data:"http://url3.com"});
 9: model.addItem({label:"Item 4",data:"http://url4.com"});
10: model.addItem({label:"Item 5",data:"http://url5.com"});
11: model.addItem({label:"Item 6",data:"http://url6.com"});
12: model.addItem({label:"Item 7",data:"http://url7.com"});
13: model.addItem({label:"Item 8",data:"http://url8.com"});
14: model.addItem({label:"Item 9",data:"http://url9.com"});
15: model.addItem({label:"Item 10",data:"http://url10.com"});
16:
17: // ** listbox **
18: var lbox:uiListBox = new uiListBox();
19: lbox.model = model;
20:
21: // ** add to display list **
22: addChild(lbox);

uiListBox example


Content

As shown in the example code above, the content of a uiListBox control is defined using a uiModel object. 

16: lbox.model = model;

The data model is accessed via the model property. To modify the data model, you must use members of the uiModel object directly; components in the Aspire UI library generally do not implement members that are already implemented in the data model.

For example, to remove all items from the uiListBox instance: 

lbox.model.removeAll();


ItemRenderer

Each item in the list is rendered using a pre-defined uiComponent subclass wrapped within an uiInteractiveItem instance. The renderer is by default, the uiText class. This can be modified using the itemRenderer property. To be very clear, we do not change the uiInteractiveItem, we only change the class used to paint the “face” of each of these uiInteractiveItem instances.

For example, to display icons and text as the labels (instead of just text) for the items in the list, we will need to use the uiLabel class:

ActionScript 3.0 Example

import com.ghostwire.ui.controls.uiLabel;
import com.ghostwire.ui.controls.uiListBox;
import com.ghostwire.ui.data.uiModel;
 
// ** data model **
var model:uiModel = new uiModel();
model.addItem({label:"Item 1",image:"star.png",data:"http://url1.com"});
model.addItem({label:"Item 2",image:"star.png",data:"http://url2.com"});
model.addItem({label:"Item 3",image:"star.png",data:"http://url3.com"});
model.addItem({label:"Item 4",image:"star.png",data:"http://url4.com"});
model.addItem({label:"Item 5",image:"star.png",data:"http://url5.com"});
model.addItem({label:"Item 6",image:"star.png",data:"http://url6.com"});
model.addItem({label:"Item 7",image:"star.png",data:"http://url7.com"});
model.addItem({label:"Item 8",image:"star.png",data:"http://url8.com"});
model.addItem({label:"Item 9",image:"star.png",data:"http://url9.com"});
model.addItem({label:"Item 10",image:"star.png",data:"http://url10.com"});
 
var lbox:uiListBox = new uiListBox();
lbox.model = model;
lbox.rowWidth = 100;
lbox.itemRenderer = uiLabel;
 
// ** add to display list **
addChild(lbox);

Using icons and text as the labels

The dataMap property is used to map properties in the itemRenderer class to the properties of the objects in the data model. For example, to change the textPosition, we need to do some mapping:

ActionScript 3.0 Example

import com.ghostwire.ui.controls.uiLabel;
import com.ghostwire.ui.controls.uiListBox;
import com.ghostwire.ui.data.uiModel;
import com.ghostwire.ui.enums.POSITION;
 
// ** data model **
var model:uiModel = new uiModel();
model.addItem({label:"Item 1",image:"star.png",data:"http://url1.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 2",image:"star.png",data:"http://url2.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 3",image:"star.png",data:"http://url3.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 4",image:"star.png",data:"http://url4.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 5",image:"star.png",data:"http://url5.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 6",image:"star.png",data:"http://url6.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 7",image:"star.png",data:"http://url7.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 8",image:"star.png",data:"http://url8.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 9",image:"star.png",data:"http://url9.com",pos:POSITION.BOTTOM});
model.addItem({label:"Item 10",image:"star.png",data:"http://url10.com",pos:POSITION.BOTTOM});
 
// ** listbox **
var lbox:uiListBox = new uiListBox();
lbox.model = model;
lbox.rowWidth = 100;
lbox.itemRenderer = uiLabel;
lbox.dataMap = {text:"label",image:"image",textPosition:"pos"};
 
// ** add to display list **
addChild(lbox);

textPosition set to POSITION.BOTTOM


ScrollBars

var lbox:uiListBox = new uiListBox();
lbox.hScrollPolicy = SCROLLBAR.ON;
lbox.vScrollPolicy = SCROLLBAR.ON;

The hScrollPolicy property indicates whether a horizontal scroll bar should be shown (anchored at the bottom of the component instance). Qualified values are SCROLLBAR.ON (always shown), SCROLLBAR.OFF (never shown), or SCROLLBAR.AUTO (shown when it is needed/hidden when it is not needed)1). Any other values will set the property to SCROLLBAR.AUTO. The default value is SCROLLBAR.AUTO. Setting this property to SCROLLBAR.ON can improve performance.

In order for the horizontal scroll bar to appear, the width of the uiListBox instance must be greater than the desired width of the scroll bar (enough space to show the left/right arrow buttons).

The vScrollPolicy property indicates whether a vertical scroll bar should be shown (anchored on the right-hand-side of the component instance). Qualified values are as for hScrollPolicy. The default value is SCROLLBAR.AUTO. Setting this property to SCROLLBAR.ON can improve performance.

In order for the vertical scroll bar to appear, the height of the uiListBox instance must be greater than the desired height of the scroll bar (enough space to show the up/down arrow buttons).

NOTE: The scroll bars are updated automatically during run-time as the list changes. However, to improve performance, the component does not attempt to compute the horizontal scroll width until the items are rendered. As the user scrolls through the list, the horizontal scroll bar may be updated if necessary.


Size

The default desired size of a uiListBox instance is computed heuristically when the component is realized (added to the display list). The default height is affected by the rowHeight and rowCount properties. The default width is affected by the rowWidth value. If the list is empty when it is realized, it will use a default width of 100 if rowWidth is set to zero (which is the default value, zero indicating that the rowWidth should be computed heuristically based on the provided data model).

You can also use the setSize(width,height) method to set preferred dimensions. 

var lbox:uiListBox = new uiListBox();
lbox.setSize(80,150);

The component will allocate enough space to the scroll bars first; the balance is then allocated to the content area.


User Interaction

The list of items in a uiListBox instance has a “focus caret” - this is the item in the list that is currently focused or last had focus. Only this item is included in the tab focus chain. The component remembers this item even if it is off-screen due to scrolling. If this item has focus but is off-screen when the Spacebar or Tab key is pressed, the component will scroll to this item.

When an item in the list is focused, the user can use the following keys to interact with the component:

KeyAction
Alphanumeric keysJumps to the next item with the first character of its label matching the key.
Ctrl+ASelects all items in the list if multipleSelect is true.
Down ArrowSelects next item in the list.
EndSelects the last item.
HomeSelects the first item.
Left ArrowScrolls left if applicable.
Page DownSelects item one page down on the list.
Page UpSelects item one page up on the list.
Right ArrowScrolls right if applicable.
Shift+TabMoves focus to previous UI control in the tab focus chain.
SpacebarScrolls to selected item.
TabMoves focus to next UI control in the tab focus chain.
Up ArrowSelects previous item in the list.

If the multipleSelect property is set to true, the CTRL key can be used to toggle selections and the SHIFT key can be used to add selections contiguously from one item to another item. The CTRL and SHIFT keys can be used together to make non-contiguous selections. The user can also use the mouse and drag-select the items.


ListBoxDemo

ActionScript 3.0 ListBoxDemo class

  1: package
  2: {
  3:     import com.ghostwire.ui.containers.uiBox;
  4:     import com.ghostwire.ui.controls.uiCheckBox;
  5:     import com.ghostwire.ui.controls.uiLabel;
  6:     import com.ghostwire.ui.controls.uiListBox;
  7:     import com.ghostwire.ui.controls.uiTextArea;
  8:     import com.ghostwire.ui.data.uiModel;
  9:     import com.ghostwire.ui.enums.POSITION;
 10:     import com.ghostwire.ui.managers.uiSkins;
 11:
 12:     import flash.display.Sprite;
 13:     import flash.events.Event;
 14:
 15:     public class ListBoxDemo extends Sprite
 16:     {
 17:         // ** instances **
 18:         private var multiCheck:uiCheckBox;
 19:         private var selectCheck:uiCheckBox;
 20:         private var lbox:uiListBox;
 21:         private var urlText:uiTextArea;
 22:
 23:         public function ListBoxDemo()
 24:         {
 25:             addEventListener(Event.ADDED_TO_STAGE,init);
 26:         }
 27:
 28:         private function init(evt:Event):void
 29:         {
 30:             // ** optional but recommended **
 31:             stage.scaleMode    = "noScale";
 32:             stage.align        = "TL";
 33:
 34:             // ** uncomment to use "classic" theme **
 35:             // uiSkins.initialize("classic");
 36:
 37:             // ** optional but recommended **
 38:             // ** let assets preload before starting application **
 39:             uiSkins.manager.addEventListener(Event.INIT,main);
 40:         }
 41:
 42:         private function main(evt:Event):void
 43:         {
 44:             // ** main application code **
 45:             // ** data model **
 46:             var model:uiModel = new uiModel();
 47:             model.addItem({label:"Item 1",image:"star.png",data:"http://url1.com",pos:POSITION.LEFT});
 48:             model.addItem({label:"Item 2",image:"star.png",data:"http://url2.com",pos:POSITION.LEFT});
 49:             model.addItem({label:"Item 3",image:"star.png",data:"http://url3.com",pos:POSITION.LEFT});
 50:             model.addItem({label:"Item 4",image:"star.png",data:"http://url4.com",pos:POSITION.LEFT});
 51:             model.addItem({label:"Item 5",image:"star.png",data:"http://url5.com",pos:POSITION.LEFT});
 52:             model.addItem({label:"Item 6",image:"star.png",data:"http://url6.com",pos:POSITION.LEFT});
 53:             model.addItem({label:"Item 7",image:"star.png",data:"http://url7.com",pos:POSITION.LEFT});
 54:             model.addItem({label:"Item 8",image:"star.png",data:"http://url8.com",pos:POSITION.LEFT});
 55:             model.addItem({label:"Item 9",image:"star.png",data:"http://url9.com",pos:POSITION.LEFT});
 56:             model.addItem({label:"Item 10",image:"star.png",data:"http://url10.com",pos:POSITION.LEFT});
 57:             // ** image file "star.png" must exist in "assets/images" **
 58:
 59:             // ** list box **
 60:             lbox = new uiListBox();
 61:             lbox.model = model;
 62:             lbox.itemRenderer = uiLabel;
 63:             //lbox.dataMap = {text:"label",image:"image",textPosition:"pos"};
 64:             lbox.rowWidth = 80;
 65:             lbox.addEventListener(Event.CHANGE,on_listChange);
 66:
 67:             // ** multipleSelect toggle checkbox **
 68:             multiCheck = new uiCheckBox("multipleSelect");
 69:             multiCheck.addEventListener(Event.CHANGE,on_multiCheckChange);
 70:
 71:             // ** selectable toggle checkbox **
 72:             selectCheck = new uiCheckBox("selectable");
 73:             selectCheck.selected = lbox.selectable;
 74:             selectCheck.addEventListener(Event.CHANGE,on_selectCheckChange);
 75:
 76:             // ** displays selection **
 77:             urlText = new uiTextArea();
 78:             urlText.editable = false;
 79:             urlText.fillX = urlText.fillY = true;
 80:
 81:             // ** box for layout **
 82:             var box:uiBox = new uiBox();
 83:             box.spacing = 4;
 84:             box.vertical = true;
 85:             box.addChild(lbox);
 86:             box.addChild(multiCheck);
 87:             box.addChild(selectCheck);
 88:
 89:             var hbox:uiBox = new uiBox();
 90:             hbox.spacing = 10;
 91:             hbox.addChild(box);
 92:             hbox.addChild(urlText);
 93:
 94:             // ** add to display list **
 95:             addChild(hbox);
 96:         }
 97:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 98:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 99:
100:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
101:         // EVENT HANDLERS
102:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
103:         // handle lbox selection change **
104:         private function on_listChange(evt:Event):void
105:         {
106:             var items:Array = lbox.selectedItems;
107:             var j:int = items.length;
108:             urlText.text = "";
109:             while (j--)
110:             {
111:                 urlText.text += items[j].data + "\n";
112:             }
113:         }
114:
115:         // ** handle multiCheck toggle **
116:         private function on_multiCheckChange(evt:Event):void
117:         {
118:             lbox.multipleSelect = multiCheck.selected;
119:         }
120:
121:         // ** handle selectCheck toggle **
122:         private function on_selectCheckChange(evt:Event):void
123:         {
124:             lbox.selectable = selectCheck.selected;
125:         }
126:
127:     }
128: }

ListBoxDemo.as

ListBoxDemo


API Reference

For more information on the members of the com.ghostwire.ui.controls.uiListBox class, please refer to the API Reference.


1) Import com.ghostwire.ui.enums.SCROLLBAR
 
You are here: Aspire UI Components » Usage » uiListBox
 
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki