qnx.fuse.ui.listClasses.DropDown

DropDown

Properties | Methods | Events | Examples


Packageqnx.fuse.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
DropDownCellRenderer
List



Public Properties

 PropertyDefined By
  autoPositionList : Boolean
Automatically sets showListAbove based on where the DropDown is on the stage.
DropDown
  dataProvider : IDataProvider
Gets or 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
 InheritedexplicitHeight : Number
[read-only] Returns the explicit height (actual height, in pixels) of the UI component.
UIComponent
 InheritedexplicitWidth : Number
[read-only] Returns the explicit width (actual width, in pixels) of the UI component.
UIComponent
 InheritedincludeInLayout : Boolean
Specifies whether or not the component should be included in its parent container's layout.
UIComponent
  isOpen : Boolean
[read-only] Returns true if the list is open in the DropDown.
DropDown
 InheritedlayoutData : Object
Returns the layout data for the object.
UIComponent
  listWidthOffset : Number
Gets or sets the drop down list width offset from the width of the button.
DropDown
  listYOffset : Number
Gets or sets the drop down list y coordinate offset.
DropDown
  measureContents : Boolean
DropDown
 InheritedminHeight : Number
Gets or sets the minimum preferred height of the control.
UIComponent
 InheritedminWidth : Number
Gets or sets the minimum preferred width of the control.
UIComponent
  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 or 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

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
 Inherited
childChanged(resizedChild:DisplayObject = null):Boolean
Notifies the UIComponent that one or more of its children has changed in a manner that may affect this object's layout.
UIComponent
  
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
  
getItemAt(index:int):Object
Returns the item in the DataProvider at the specified index.
DropDown
 Inherited
Returns the size options for the given control.
UIComponent
 Inherited
Calling this method results in a call to the components validateDisplayList() method before the display list is rendered.
UIComponent
 Inherited
Calling this method results in a call to the components validateProperties() method before the display list is rendered.
UIComponent
 Inherited
measure(availableWidth:Number, availableHeight:Number):LayoutMeasurement
This method calls doMeasure() in order to calculate the preferred size of the control.
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
  
setAboveBackgroundSkin(skin:Object):void
Sets the skin for the List background.
DropDown
  
setAboveButtonSkin(skin:Object):void
Sets the skin for the drop down button when list expands upward.
DropDown
  
setAboveListSkin(skin:Object):void
Sets the CellRenderer for the List when list expands upward.
DropDown
 Inherited
setActualSize(w:Number, h:Number):void
Sets the width and height of the object without setting the explicitWidth and explicitHeight.
UIComponent
  
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
 Inherited
setLayoutBounds(bounds:Rectangle):void
Sets the receiver's size and location to the rectangular area specified by the arguments.
UIComponent
  
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
  
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
 Inherited
Validates the display list of the component by calling the updateDisplayList().
UIComponent
 Inherited
Validates the component immediately by calling validateProperties(), validateSizes(), and validateDisplayList() if necessary.
UIComponent
 Inherited
Validates the properties of the component by calling the commitProperties() method.
UIComponent

Protected Methods

 MethodDefined By
 Inherited
Process properties of the component.
UIComponent
 Inherited
Process the state of the component.
UIComponent
 Inherited
doMeasure(availableWidth:Number, availableHeight:Number):LayoutMeasurement
Performs a measurement on the control, and returns a LayoutMeasurement instance containing the available width and height within the layout.
UIComponent
 Inherited
flushCache():void
Invoked as part of parentLayoutChanged.
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
Invalidates the parent's size and display list if includeInLayout property is set to true.
UIComponent
 Inherited
updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void
Sets the size and position of the children of the component.
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

autoPositionList


autoPositionList:Boolean

Automatically sets showListAbove based on where the DropDown is on the stage. If when the DropDown opens the list will be clipped by the stage edge, showListAbove is toggled.


Implementation

public function get autoPositionList():Boolean
public function set autoPositionList(value:Boolean):void

dataProvider


dataProvider:IDataProvider

Gets or 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

listWidthOffset


listWidthOffset:Number

Gets or sets the drop down list width offset from the width of the button.

The drop down width (in pixels) offset from the width of the button. A positive value would make the drop-down list wider than the drop-down button. A negative value would make the drop-down list narrower than the drop-down button.


Implementation

public function get listWidthOffset():Number
public function set listWidthOffset(value:Number):void

listYOffset


listYOffset:Number

Gets or sets the drop down list y coordinate offset. The offset determines the position of the open list relative to the button.


Implementation

public function get listYOffset():Number
public function set listYOffset(value:Number):void

measureContents


measureContents:Boolean


Implementation

public function get measureContents():Boolean
public function set measureContents(value:Boolean):void

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 or 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.


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.

setAboveBackgroundSkin()


public function setAboveBackgroundSkin(skin:Object):void

Sets the skin for the List background.

This method takes a DisplayObject class.

            var myDDList:DropDown = new DropDown();
            myDDList.setPosition(100, 500);
            myDDList.width = 195;
            myDDList.showListAbove = true;
            myDDList.setAboveBackgroundSkin(DropDownBackgroundSkinBlack);
            myDDList.prompt = "Intramurals";
            

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.

Parameters

skin:Object — The List background skin.

setAboveButtonSkin()


public function setAboveButtonSkin(skin:Object):void

Sets the skin for the drop down button when list expands upward.

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.

setAboveListSkin()


public function setAboveListSkin(skin:Object):void

Sets the CellRenderer for the List when list expands upward.

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.width = 195;
         myDDList.prompt = "Intramurals";
         myDDList.showListAbove = true;
         myDDList.setAboveListSkin(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.

setBackgroundSkin()


public function setBackgroundSkin(skin:Object):void

Sets the skin for the List background.

This method takes a DisplayObject class.

            var myDDList:DropDown = new DropDown();
            myDDList.setPosition(100, 200);
            myDDList.width = 195;
            myDDList.setBackgroundSkin(DropDownBackgroundSkinBlack);
            myDDList.prompt = "Intramurals";
         

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

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.fuse.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.width = 195;
            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);


        }



    }
}