Packageqnx.ui.listClasses
Classpublic class DropDown
InheritanceDropDown Inheritance UIComponent Inheritance flash.display.MovieClip
Implements IDataViewer

The DropDown class provides drop down list functionality. When the user taps the drop down, the list expands to provide options that a user can select from.

The following image shows a DropDown instance in the closed state:

A closed drop down list.

The following image shows a DropDown instance in the open state, after a user has touched the control:

An open drop down list.

View the examples

See also

DropDownCellRenderer
List


Public Properties
 PropertyDefined By
  button : LabelButton
[read-only] Returns a reference to the button of the DropDown component.
DropDown
 Inheritedcontainment : String
Gets or sets a property that determines how a component is contained within a parent container.
UIComponent
  dataProvider : IDataProvider
Gets and sets the DataProvider for the DropDown list.
DropDown
  dropDownParent : DisplayObjectContainer
Gets or sets the property that determines the parent for the drop down list.
DropDown
  isOpen : Boolean
[read-only] Returns true if the list is open in the DropDown.
DropDown
  list : List
[read-only] Returns a reference to the list of the DropDown component.
DropDown
  prompt : String
Gets or sets the prompt that appears in the drop down.
DropDown
  rowCount : int
Gets or sets the number of visible rows in the drop down list.
DropDown
  rowHeight : int
Gets and sets the row height for the drop down list.
DropDown
  selectedIndex : int
Gets or sets the index of the currently selected item in the drop down.
DropDown
  selectedItem : Object
Gets or sets the currently selected item.
DropDown
  showListAbove : Boolean
Determines if the drop down list will expand above or below the drop down button.
DropDown
 Inheritedsize : Number
Gets or sets the size for this component (as a percentage of the container's size, or in pixels).
UIComponent
 InheritedsizeMode : String
Gets or sets the size mode for this component.
UIComponent
 InheritedsizeUnit : String
Gets or sets the unit of measure for the size property.
UIComponent
Public Methods
 MethodDefined By
  
Creates a new DropDown instance.
DropDown
  
addItem(item:Object):void
Adds an item to the list.
DropDown
  
addItemAt(item:Object, index:int):void
Adds an item to the list at the specified index.
DropDown
  
addItemsAt(items:Array, index:int):void
Adds an array item at the specified index.
DropDown
  
close():void
Closes the list of the DropDown component if it is open.
DropDown
 Inherited
destroy():void
Call this method when you want to have your object collected by the garbage collector.
UIComponent
 Inherited
drawNow():void
Calls the draw() method.
UIComponent
  
getItemAt(index:int):Object
Returns the item in the DataProvider at the specified index.
DropDown
 Inherited
invalidate(property:String, invalidateNow:Boolean = false):void
Marks the property as invalid and the draw() method is called on the next frame or the next render, whichever comes first.
UIComponent
  
open():void
Opens the list of the DropDown component if it is closed.
DropDown
  
removeAll():void
Removes all the items from the list.
DropDown
  
removeItem(item:Object):void
Removes the item from the list.
DropDown
  
removeItemAt(index:int):void
Removes an item from list at the specified index.
DropDown
  
replaceItem(item:Object, oldObject:Object):void
Replaces an item, given the new item object and the old item.
DropDown
  
replaceItemAt(item:Object, index:int):void
Replaces the item in the list at the specified index, given the new item.
DropDown
  
setBackgroundSkin(skin:Object):void
Sets the skin for the List background.
DropDown
  
setButtonSkin(skin:Object):void
Sets the skin for the drop down button.
DropDown
  
setListSkin(skin:Object):void
Sets the CellRenderer for the List.
DropDown
 Inherited
setPosition(x:Number, y:Number):void
Sets the x and y position of the component.
UIComponent
 Inherited
setSize(w:Number, h:Number):void
Sets the width and height of the component.
UIComponent
  
updateItem(value:Object, oldObject:Object):void
Updates the item in the list.
DropDown
  
updateItemAt(item:Object, index:int):void
Updates the item in the list at the specified index.
DropDown
  
updateItemsAt(items:Array, index:int):void
Updates the items starting at the specified index with new items.
DropDown
Protected Methods
 MethodDefined By
 Inherited
callLater(method:Function):void
Calls the specified method on the next frame or the next render, which ever happens first.
UIComponent
 Inherited
createInstance(linkage:Object):DisplayObject
Calling this method will attempt to create a DisplayObject instance based on the value of the linkage parameter.
UIComponent
 Inherited
draw():void
Called every time you set the width and height of the component.
UIComponent
 Inherited
isInvalid(property:String, ... properties):Boolean
Checks to see if the property is invalid and returns true if it is.
UIComponent
 Inherited
onAdded():void
Called when the instance is added to the stage.
UIComponent
 Inherited
onRemoved():void
Called when the instance is removed from the stage.
UIComponent
 Inherited
setEnabled(val:Boolean):void
Called when the enabled property changes.
UIComponent
 Inherited
validate(property:String):void
Lets the component know that the specified property has been validated.
UIComponent
Events
 Event Summary Defined By
  Dispatched when the drop down list is closed.DropDown
  Dispatched when the drop down list is opened.DropDown
  Dispatched when an item in the drop down list is selected.DropDown
Property Detail
buttonproperty
button:LabelButton  [read-only]

Returns a reference to the button of the DropDown component. This allows you to modify certain properties of the button, such as text formats.

If you want to set the skin of the button, make sure to use the setButtonSkin() method.


Implementation
    public function get button():LabelButton

See also


Example

The following example shows you how to set the text format of the label on the button.

            var dd:DropDown = new DropDown();
            dd.dataProvider = DataProviderUtils.createDataProvider();
            addChild( dd );
            
            var button:LabelButton = dd.button;
            formatText( SkinStates.UP, button );
            formatText( SkinStates.DOWN, button );
            formatText( SkinStates.DOWN_SELECTED, button );
            formatText( SkinStates.SELECTED, button );
            formatText( SkinStates.DISABLED, button );
            formatText( SkinStates.DISABLED_SELECTED, button );
            
            function formatText( state:String, button:LabelButton ):void
            {
                var format:TextFormat;
                
                switch( state )
                {
                    case SkinStates.UP:
                        format = ThemeGlobals.getTextFormat( ThemeGlobals.BUTTON_FORMAT_OUT );
                        format.color = 0xFF0000;
                        break;
                    case SkinStates.DOWN:
                        format = ThemeGlobals.getTextFormat( ThemeGlobals.BUTTON_FORMAT_DOWN );
                        format.color = 0xFF000;
                        break;
                    case SkinStates.DOWN_SELECTED:
                        format = ThemeGlobals.getTextFormat( ThemeGlobals.BUTTON_FORMAT_DOWN );
                        format.color = 0x000000;
                        break;
                    case SkinStates.SELECTED:
                        format = ThemeGlobals.getTextFormat( ThemeGlobals.BUTTON_FORMAT_SELECTED );
                        format.color = 0x000000;
                        break;
                    case SkinStates.DISABLED:
                        format = ThemeGlobals.getTextFormat( ThemeGlobals.BUTTON_FORMAT_DISABLED );
                        format.color = 0x333333;
                        break;
                    case SkinStates.DISABLED_SELECTED:
                        format = ThemeGlobals.getTextFormat( ThemeGlobals.BUTTON_FORMAT_SELECTED_DISABLED );
                        format.color = 0x333333;
                        break;
                    default:
                        format = ThemeGlobals.getTextFormat( ThemeGlobals.BUTTON_FORMAT_OUT );
                }
                
                button.setTextFormatForState( format, state );
            }
        
dataProviderproperty 
dataProvider:IDataProvider

Gets and sets the DataProvider for the DropDown list.


Implementation
    public function get dataProvider():IDataProvider
    public function set dataProvider(value:IDataProvider):void

See also

dropDownParentproperty 
dropDownParent:DisplayObjectContainer

Gets or sets the property that determines the parent for the drop down list.

The default value is the DropDown component itself.


Implementation
    public function get dropDownParent():DisplayObjectContainer
    public function set dropDownParent(value:DisplayObjectContainer):void
isOpenproperty 
isOpen:Boolean  [read-only]

Returns true if the list is open in the DropDown.

The default value is false.


Implementation
    public function get isOpen():Boolean
listproperty 
list:List  [read-only]

Returns a reference to the list of the DropDown component. You can also use the setListSkin() method in order to update the skin of the list.


Implementation
    public function get list():List

See also

promptproperty 
prompt:String

Gets or sets the prompt that appears in the drop down.

The prompt is shown as the default message in the drop down when the selectedIndex value is set to -1. For example, the String "Select an item" prompts the user to select an item from the drop down list. If no prompt is set, the selectedIndex value is set to 0 and the first item in the DataProvider is displayed in the drop down.


Implementation
    public function get prompt():String
    public function set prompt(value:String):void
rowCountproperty 
rowCount:int

Gets or sets the number of visible rows in the drop down list.


Implementation
    public function get rowCount():int
    public function set rowCount(value:int):void
rowHeightproperty 
rowHeight:int

Gets and sets the row height for the drop down list.

The row height represents ths height of each item in the list (in pixels).


Implementation
    public function get rowHeight():int
    public function set rowHeight(value:int):void
selectedIndexproperty 
selectedIndex:int

Gets or sets the index of the currently selected item in the drop down.


Implementation
    public function get selectedIndex():int
    public function set selectedIndex(value:int):void
selectedItemproperty 
selectedItem:Object

Gets or sets the currently selected item.

In the included example, an event listener calls the function below to return information about the currently selected cell:

         private function onSelect(event:Event):void {
         
                 trace("selected index: " + event.target.selectedIndex);
         
                 var myObj:Object = new Object();
                 myObj = event.target.selectedItem;
                 trace("Selected Item: " + myObj.label);
         }
         


Implementation
    public function get selectedItem():Object
    public function set selectedItem(value:Object):void
showListAboveproperty 
showListAbove:Boolean

Determines if the drop down list will expand above or below the drop down button.

In the following image, the drop down list expands above the drop down button (the showListAbove property is set to true):

A drop down list expanding up.

The default value is false.


Implementation
    public function get showListAbove():Boolean
    public function set showListAbove(value:Boolean):void
Constructor Detail
DropDown()Constructor
public function DropDown()

Creates a new DropDown instance.

Method Detail
addItem()method
public function addItem(item:Object):void

Adds an item to the list.

Parameters

item:Object — The item to add.


Throws
RangeError — thrown if the specified index is less than 0 or greater than or equal to the length of the DataProvider.
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 index, or offset 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 data provider.

See also

close()method 
public function close():void

Closes the list of the DropDown component if it is open. Calling this method will not fire a Event.CLOSE event.

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.
open()method 
public function open():void

Opens the list of the DropDown component if it is closed. Calling this method will not fire a Event.OPEN event.

removeAll()method 
public function removeAll():void

Removes all the items from the list.

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

Removes the 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, given the 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.
setBackgroundSkin()method 
public function setBackgroundSkin(skin:Object):void

Sets the skin for the List background.

This method takes a DisplayObject class.

Parameters

skin:Object — The List background skin.

setButtonSkin()method 
public function setButtonSkin(skin:Object):void

Sets the skin for the drop down button.

You can pass in a qualified class name String, or the actual class. In either instance the class that is used must implement the ISkin interface.

Note: Do not pass in an instance of a skin class. This may cause unexpected behavior.

Parameters

skin:Object — The button skin.

setListSkin()method 
public function setListSkin(skin:Object):void

Sets the CellRenderer for the List.

By default, the DropDown class uses the CellRenderer class to render the cells in the list. In the example below, the AlternatingCellRenderer class is passed in to the setListSkin method to provide alternating colors (grey and white) for the adjacent cells in the list.

         var myDDList:DropDown = new DropDown();
         myDDList.setPosition(100, 400);
         myDDList.prompt = "Intramurals";
         myDDList.showListAbove = true;
         myDDList.setListSkin(AlternatingCellRenderer);
         
A drop down list expanding up.

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.

Parameters

skin:Object — The skin instance.

updateItem()method 
public function updateItem(value:Object, oldObject:Object):void

Updates the item in the list.

Parameters

value:Object — The item to update.
 
oldObject:Object — old item, or the item to update.

updateItemAt()method 
public function updateItemAt(item:Object, index:int):void

Updates the item in the list at the specified index.

Parameters

item:Object — The 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 DataProvider.

See also

Event Detail
close Event
Event Object Type: flash.events.Event
Event.type property = flash.events.Event.CLOSE

Dispatched when the drop down list is closed.

open Event  
Event Object Type: flash.events.Event
Event.type property = flash.events.Event.OPEN

Dispatched when the drop down list is opened.

select Event  
Event Object Type: flash.events.Event
Event.type property = flash.events.Event.SELECT

Dispatched when an item in the drop down list is selected.

Examples

The following example creates a simple DropDown instance. The dropdown uses event listeners to capture user interaction.

package
{
    import flash.display.Sprite;
    import flash.events.Event;
    
    import qnx.ui.data.DataProvider;
    import qnx.ui.listClasses.DropDown;
    
    [SWF(height="600", width="1024", 
    frameRate="30", backgroundColor="#FFFFFF")]
    
    public class MyDropDownExample extends Sprite
    {
        public function MyDropDownExample()
        {
            initializeUI();
        }
        
        private function initializeUI():void
        {
            
            var arrMonth:Array=[];
            // add objects with a label property
            arrMonth.push({label: "Hockey"});
            arrMonth.push({label: "Baseball"});
            arrMonth.push({label: "Football"});
            arrMonth.push({label: "Golf"});
            arrMonth.push({label: "Basketball"});
                
            var myDDList:DropDown = new DropDown();            
            myDDList.setPosition(100, 100);    
            myDDList.prompt = "Intramurals";
    
            
            //set the dataProvider
            myDDList.dataProvider = new DataProvider(arrMonth);
            
            myDDList.addEventListener(Event.SELECT, onSelect);
            this.addChild(myDDList);
            
        }
        
        private function onSelect(event:Event):void {
            
            trace("selected index: " + event.target.selectedIndex);
            
            var myObj:Object = new Object();
            myObj = event.target.selectedItem;
            trace("Selected Item: " + myObj.label);
            
            
        }
        
    
    }
}