View comments | RSS feed
Methods | Properties | Effects | Events | Styles | Examples Frames | No Frames

mx.controls
Class ComboBox

Inheritance ImageInheritance ImageInheritance Image

class ComboBox
extends mx.controls.ComboBase

The ComboBox control contains a drop-down List from which the user can select a single value. Its functionality is very similar to that of the SELECT form element in HTML. The ComboBox can be editable in which case the user can type entries into the TextInput portion of the ComboBox that are not in the List.

MXML Syntax

The <mx:ComboBox> tag inherits all the properties of its parent classes, and the following properties: 

 <mx:ComboBox
   dataProvider="No default."
   dropdownWidth="Size wide enough to hold text."
   editable="false|true"
   labelField="No default."
   labelFunction="No default."
   rowCount="5"
   selectedIndex="No default."
   selectedItem="No default."
   change="Event handler; no default."
   close="Event handler; no default."
   enter="Event handler; no default."
   itemRollOver="Event handler; no default."
   itemRollOut="Event handler; no default."
   open="Event handler; no default."
   scroll="Event handler; no default."
 />

Click here to view the Examples

See Also
    List
    mx.effects.Tween
    mx.managers.PopUpManager


Methods
       close( ) :  Void
Hides the dropdown list.
       layoutChildren( ) :  Void
 Make sure the dropdown width is the same as the rest of the ComboBox
       measure( ) :  Void
 Makes sure the control is at least 100 pixels wide, and tall enough to fit one line of text in the TextInput are of the control.
       open( ) :  Void
Displays the dropdown list.

Methods inherited from class mx.controls.ComboBase
addItem   addItemAt   getDataProvider   getItemAt   getLength   getSelectedIndex   getSelectedIndices   getSelectedItem   getSelectedItems   layoutChildren   measure   removeAll   removeItemAt   replaceItemAt   setDataProvider   sortItems   sortItemsBy  

Methods inherited from class mx.core.UIComponent
drawFocus   getFocus   getFocusManager   setEnabled   setFocus  

Methods inherited from class mx.core.UIObject
addEventListener   applyProperties   buildDepthTable   commitProperties   constructObject2   createAccessibilityImplementation   createChildAtDepth   createChildren   createClassChildAtDepth   createClassObject   createEmptyObject   destroyObject   dispatchEvent   doLater   draw   drawRect   executeBindings   fillRect   findNextAvailableDepth   getRepeaterItem   getStyle   handleEvent   init   invalidate   invalidateLayout   invalidateProperties   invalidateSize   invalidateStyle   layoutChildren   measure   move   redraw   removeEventListener   setDepthAbove   setDepthBelow   setMask   setSize   setSizeNoLayout   setStyle   swapDepths  



Properties
       dataProvider: Object
 The dataProvider for the ComboBox control.
       dropdown: Object    [Read-Only]
A reference to the List that acts as the dropdown in the ComboBox.
       dropdownWidth: Number
Width of the dropdown, in pixels.
       labelField: String
Name of the field in the objects of the dataProvider array to display as the label.
       labelFunction: Function
User-supplied function to run on each item to determine its label.
       prompt: Object
 The prompts for the ComboBox control.
       rowCount: Number
Maximum number of rows visible in the ComboBox control list.
       selectedIndex: Number
 Index of the selected item in the drop-down list.
       selectedItem: Object
 Contains a reference to the selected item in the dataProvider.
staticversion: String
Version string for this class.

Properties inherited from class mx.controls.ComboBase
dataProvider   editable   length   restrict   selectedIndex   selectedItem   text   textField   value   version  

Properties inherited from class mx.core.UIComponent
enabled   errorString   tabEnabled   tabIndex   version  

Properties inherited from class mx.core.UIObject
alpha   baselinePosition   className   depth   documentDescriptor   height   heightFlex   id   instanceIndices   isDocument   kStretch   layoutHeight   layoutWidth   maxHeight   maxWidth   minHeight   minWidth   mouseX   mouseY   nestLevel   oldHeight   oldWidth   oldX   oldY   parent   parentApplication   parentDocument   percentHeight   percentWidth   preferredHeight   preferredWidth   repeaterIndices   scaleX   scaleY   styleName   tabEnabled   toolTip   version   visible   width   widthFlex   x   y  



Effects

Effects inherited from class mx.core.UIComponent
focusInEffect   focusOutEffect  

Effects inherited from class mx.core.UIObject
creationCompleteEffect   hideEffect   mouseDownEffect   mouseOutEffect   mouseOverEffect   mouseUpEffect   moveEffect   resizeEffect   showEffect  



Events
changeBroadcast when the selectedIndex/selectedItem property changes as a result of user interaction. The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, change. You can access the attributes of the selected item as:
evt.target.selectedItem.label
evt.target.selectedItem.data
closeBroadcast when dropdown is dismissed because the user selected an item in the dropdown, clicked outside of the dropdown, or clicked the dropdown button while the dropdown was displayed. The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, close.
enterBroadcast if the ComboBox editable property is set to true and the user presses the Enter key while typing in the TextInput. The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, enter.
itemRollOutBroadcast when list items are rolled out. The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, itemRollOut. The event object's index property contains the index of the item that was rolled out.
itemRollOverBroadcast when items are rolled over. The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, itemRollOver. The event object's index property contains the index of the item that was rolled over.
modelChangedBroadcast when the dataprovider is changed. Commonly used to add an initial prompt to the dataProvider so that the first selection is something like "Select a name...". The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, modelChanged.
openBroadcast when the user clicks on the dropdown button to display the dropdown. The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, open.
scrollBroadcast when the user scrolls the ComboBox's dropdown list. The event object's target property contains a reference to the component that triggered the event. The event object's type property contains the name of the event, scroll.

Events inherited from class: mx.core.UIComponent
focusIn  focusOut  invalid  keyDown  keyUp  valid  valueCommitted 

Events inherited from class: mx.core.UIObject
creationComplete  dragComplete  dragDrop  dragEnter  dragExit  dragOver  draw  effectEnd  effectStart  hide  hideToolTip  initialize  load  mouseChangeSomewhere  mouseDown  mouseDownSomewhere  mouseMove  mouseMoveSomewhere  mouseOut  mouseOver  mouseUp  mouseUpSomewhere  move  resize  show  showToolTip  unload 



Styles
alternatingRowColors Type: Array   CSS Inheritance: yes
Colors for rows in an alternating pattern. Value can be an Array of two of more colors. Only used if backgroundColor is not specified
closeDuration Type: Number   Format: Time   CSS Inheritance: no
Length of a close transition, in milliseconds. The default value is 250.
closeEasing Type: String   Format: Time   CSS Inheritance: no
Easing function to control component tweening.
openDuration Type: Number   Format: Time   CSS Inheritance: no
Length of an open transition, in milliseconds. The default value is 250.
openEasing Type: String   Format: Time   CSS Inheritance: no
Easing function to control component tweening.
rollOverColor Type: Number   Format: Color   CSS Inheritance: yes
Color of the background when the user rolls over an item. The default value is 0x0EFFD6.
selectionColor Type: Number   Format: Color   CSS Inheritance: yes
Color of the background when the user selects an item. The default value is 0x0DFFC1.
selectionEasing Type: String   CSS Inheritance: no
Reference to an easing equation (function) used for controlling programmatic tweening.

Styles inherited from class mx.core.UIComponent
backgroundAlpha   backgroundColor   backgroundDisabledColor   backgroundImage   backgroundSize   barColor   borderCapColor   borderColor   borderSides   borderStyle   borderThickness   cornerRadius   disabledColor   dropShadow   errorColor   fillColors   highlightColor   modalTransparency   scrollTrackColor   selectedFillColors   shadowCapColor   shadowColor   shadowDirection   shadowDistance   symbolBackgroundColor   symbolBackgroundDisabledColor   symbolBackgroundPressedColor   symbolColor   symbolDisabledColor   themeColor  

Styles inherited from class mx.core.UIObject
color   fontFamily   fontSize   fontStyle   fontWeight   horizontalGap   leading   marginLeft   marginRight   textAlign   textDecoration   textIndent   verticalGap  



Method Detail

close

close( ) :  Void

Hides the dropdown list.

layoutChildren

layoutChildren( ) :  Void

Make sure the dropdown width is the same as the rest of the ComboBox

measure

measure( ) :  Void

Makes sure the control is at least 100 pixels wide, and tall enough to fit one line of text in the TextInput are of the control.

open

open( ) :  Void

Displays the dropdown list.



Property Detail

dataProvider

dataProvider: Object  

The dataProvider for the ComboBox control.

dropdown

dropdown: Object   [Read-Only]

A reference to the List that acts as the dropdown in the ComboBox.

dropdownWidth

dropdownWidth: Number  

Width of the dropdown, in pixels. The default value is 100 or the width of the longest text in the dataProvider, whichever is greater.

labelField

labelField: String  

Name of the field in the objects of the dataProvider array to display as the label. By default, the control uses a property named label on each array object and display it. However, if the dataProvider objects do not contain a label property, you can set the labelField property to use a different property.

labelFunction

labelFunction: Function  

User-supplied function to run on each item to determine its label. By default the control uses a property named label on each array object to determine its label. However, some data sets do not have a label property, or do not have another property that can be used for displaying as a label. An example is a data set that has lastName and firstName fields but you want to display full names. You use labelFunction to specify a callback function that uses the appropriate fields and return a displayable string.

prompt

prompt: Object  

The prompts for the ComboBox control. These get added to the beginning of the data provider so you can add options like "select one.." or "Western Region/EasternRegion" to the results of a webservice query. Note that it actually modifies the dataprovider so your selection indexes change.

rowCount

rowCount: Number  

Maximum number of rows visible in the ComboBox control list. The default value is 5.

selectedIndex

selectedIndex: Number  

Index of the selected item in the drop-down list. Setting this property sets the current index, and displays the associated label in the text field. The default value is undefined. If the control is editable, and the user types in the text field the selectedIndex becomes undefined. If the selected index is out of range, the assignment is ignored.

selectedItem

selectedItem: Object  

Contains a reference to the selected item in the dataProvider. Modifying this data modifies the dataProvider and thus its views. If the ComboBox control is editable, the selectedItem property is undefined if the user types any text into the text field. It has a value only if the user selects an item from the drop-down list, or if it is set programmatically.

version

static  version: String  

Version string for this class.


Examples
SimpleComboBox.mxml 
<?xml version="1.0"?>
<!-- Simple example to demonstrate the ComboBox control -->
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" backgroundColor="#FFFFFF">

    <mx:Panel title="ComboBox Panel" marginTop="10">

        <mx:ComboBox id="SoftwareSelection">

            <mx:dataProvider>
                <mx:Array>
                    <mx:String>Macromedia Flex</mx:String>
                    <mx:String>Macromedia Dreamweaver</mx:String>
                    <mx:String>Macromedia ColdFusion</mx:String>
                    <mx:String>Macromedia Flash</mx:String>
                </mx:Array>
            </mx:dataProvider>

        </mx:ComboBox>

    </mx:Panel>

</mx:Application>



Comments


Teseo2005 said on Oct 20, 2005 at 8:18 PM :
The examples are too tribial, how do i fire a function on the change event?
smgilson said on Oct 21, 2005 at 5:47 AM :
You can see examples for handling events in the 'Customizing Data Provider Controls' chapter of the 'Developing Flex Applications' book at:

http://livedocs.macromedia.com/flex/15/flex_docs_en/00000527.htm

Stephen

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flex/15/asdocs_en/mx/controls/ComboBox.html