DropDown
Properties | Methods | Events | Examples
Package | qnx.ui.listClasses |
Class | public class DropDown |
Inheritance | DropDown ![]() ![]() |
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:

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

Class information: |
---|
PlayBook Tablet OS Version: 1.0.6 |
See also
Public Properties
Property | Defined By | ||
---|---|---|---|
button : LabelButton [read-only]
Returns a reference to the button of the DropDown component. | DropDown | ||
![]() | containment : 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 | ||
![]() | size : Number
Gets or sets the size for this component (as a percentage of the
container's size, or in pixels). | UIComponent | |
![]() | sizeMode : String
Gets or sets the size mode for this component. | UIComponent | |
![]() | sizeUnit : String
Gets or sets the unit of measure for the size property. | UIComponent |
Public Methods
Method | Defined By | ||
---|---|---|---|
DropDown()
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 | ||
![]() | destroy():void
Call this method when you want to have your object collected by the garbage collector. | UIComponent | |
![]() | drawNow():void
Calls the draw() method. | UIComponent | |
getItemAt(index:int):Object
Returns the item in the DataProvider at the specified index. | DropDown | ||
![]() | 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 | ||
![]() | setPosition(x:Number, y:Number):void
Sets the x and y position of the component. | UIComponent | |
![]() | 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
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
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
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
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
):

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

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
Event Detail
close
flash.events.Event
Event.type property =
flash.events.Event.CLOSE
Dispatched when the drop down list is closed.
open
flash.events.Event
Event.type property =
flash.events.Event.OPEN
Dispatched when the drop down list is opened.
select
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); } } }