qnx.ui.listClasses.DropDown

DropDown

Properties | Methods | Events | Examples


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.

Class information:
PlayBook Tablet OS Version:   1.0.6

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 = all, 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 = all):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

button


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

setButtonSkin()


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 );
            }
        

dataProvider


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

DataProvider

dropDownParent


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

isOpen


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

list


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

setListSkin()

prompt


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

rowCount


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

rowHeight


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

selectedIndex


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

selectedItem


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

showListAbove


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()


public function DropDown()

Creates a new DropDown instance.

Method Detail

addItem()


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()


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()


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

addItem()
addItemAt()

close()


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()


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()


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()


public function removeAll():void

Removes all the items from the list.

removeItem()


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()


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()


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()


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()


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()


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()


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()


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()


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()


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

updateItem()
updateItemAt()

Event Detail

close


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

Dispatched when the drop down list is closed.

open


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

Dispatched when the drop down list is opened.

select


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);
            
            
        }
        
    
    }
}