The ComboBox control is 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.

For complete reference information, see the Adobe Flex Language Reference.

About the ComboBox control

The following image shows a ComboBox control:

In its editable state, the user can type text directly into the top of the list, or select one of the preset values from the list. In its noneditable state, as the user types a letter, the drop-down list opens and scrolls to the value that most closely matches the one being entered; matching is only performed on the first letter that the user types.

If the drop-down list hits the lower boundary of the application, it opens upward. If a list item is too long to fit in the horizontal display area, it is truncated to fit. If there are too many items to display in the drop-down list, a vertical scroll bar appears.

Creating a ComboBox control

You use the <mx:ComboBox> tag to define a ComboBox control in MXML. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The ComboBox control uses a list-based data provider. For more information, see Using Data Providers and Collections.

You specify the data for the ComboBox control by using the dataProvider property of the <mx:ComboBox> tag. The data provider should be a collection; the standard collection implementations are the ArrayCollection and XMLListCollection classes, for working with Array-based and XML-based data, respectively. You can also use a raw data object, such as Array or XMLList object, as a data provider; however, it is always better to specify a collection explicitly for data that could change. For more information on data providers and collections see Using Data Providers and Collections.

In a simple case for creating a ComboBox control, you specify the property by using an <mx:dataProvider> child tag, and use an <mx:ArrayCollection> tag to define the entries as an ArrayCollection whose source is an Array of Strings, as the following example shows:

<?xml version="1.0"?>
<!-- dpcontrols/ComboBoxSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
   <mx:ComboBox> 
      <mx:ArrayCollection>
         <mx:String>AK</mx:String>
         <mx:String>AL</mx:String>
         <mx:String>AR</mx:String>
      </mx:ArrayCollection>
   </mx:ComboBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

This example shows how you can take advantages of MXML defaults. You do not have to use an <mx:dataProvider> tag, because dataProvider is the default property of the ComboBox control. Similarly, you do not have to use an <mx:source> tag inside the <mx:ArrayCollection> tag because source is the default property of the ArrayCollection class. Finally, you do not have to specify an <mx:Array> tag for the source array.

The data provider can also contain objects with multiple fields, as in the following example:

<?xml version="1.0"?>
<!-- dpcontrols/ComboBoxMultiple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
   <mx:ComboBox> 
      <mx:ArrayCollection>
         <mx:Object label="AL" data="Montgomery"/>
         <mx:Object label="AK" data="Juneau"/>
         <mx:Object label="AR" data="Little Rock"/>
      </mx:ArrayCollection>
   </mx:ComboBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

If the data source is an array of strings, as in the first example, the ComboBox displays strings as the items in the drop-down list. If the data source consists of objects, the ComboBox, by default, uses the contents of the label field. You can, however, override this behavior, as described in Specifying ComboBox labels.

The index of items in the ComboBox control is zero-based, which means that values are 0, 1, 2, ... , n - 1, where n is the total number of items. The value of the item is its label text.

Using events with ComboBox controls

You typically use events to handle user interaction with a ComboBox control.

The ComboBox control broadcasts a change event (flash.events.Event class with a type property value of flash.events.Event.CHANGE) when the value of the control's selectedIndex or selectedItem property changes due to the following user actions:

• If the user closes the drop-down list by using a mouse click, Enter key, or Control+Up key, and the selected item is different from the previously selected item.
• If the drop-down list is currently closed, and the user presses the Up, Down, Page Up, or Page Down key to select a new item.
• If the ComboBox control is editable, and the user types into the control, Flex broadcasts a change event each time the text field of the control changes.

The ComboBox control broadcasts an mx.events.DropdownEvent with a type mx.events.DropdownEvent.OPEN (open) and mx.events.DropdownEvent.CLOSE (close) when the ComboBox control opens and closes. For detailed information on these and other ComboBox events, see ComboBox in the Adobe Flex Language Reference.

The following example displays information from ComboBox events:

<?xml version="1.0"?>
<!-- dpcontrols/ComboBoxEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
   <mx:Script>
      <![CDATA[
         import flash.events.Event;
         import mx.events.DropdownEvent;

         // Display the type of event for open and close events.
         private function dropEvt(event:DropdownEvent):void {
            forChange.text+=event.type + "\n";
         }

         // Display a selected item's label field and index for change events.
         private function changeEvt(event:Event):void {
            forChange.text+=event.currentTarget.selectedItem.label + " " + 
               event.currentTarget.selectedIndex + "\n";
         }
      ]]>
   </mx:Script>

   <mx:ComboBox open="dropEvt(event)" close="dropEvt(event)"
         change="changeEvt(event)" > 
      <mx:ArrayCollection>
         <mx:Object label="AL" data="Montgomery"/>
         <mx:Object label="AK" data="Juneau"/>
         <mx:Object label="AR" data="Little Rock"/>
      </mx:ArrayCollection>
   </mx:ComboBox>
   <mx:TextArea id="forChange" width="150" height="100%"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

If you populate the ComboBox control with an Array of Strings, the currentTarget.selectedItem field contains a String. If you populate it with an Array of Objects, the currentTarget.selectedItem field contains the Object that corresponds to the selected item, so, in this case, currentTarget.selectedItem.label refers to the selected item object's label field.

In this example, you use two properties of the ComboBox control, selectedItem and selectedIndex, in the event handlers. Every change event updates the TextArea control with the label of the selected item and the item's index in the control, and every open or close event appends the event type.

Specifying ComboBox labels

If the ComboBox data source is an array of strings, the control displays the string for each item. If the data source is contains Objects, by default, the ComboBox control expects each object to contain a property named label that defines the text that appears in the ComboBox control for the item. If each Object does not contain a label property, you can use the labelField property of the ComboBox control to specify the property name, as the following example shows:

    <mx:ComboBox open="dropEvt(event)" close="dropEvt(event)"
            change="changeEvt(event)" labelField="state">
        <mx:ArrayCollection>
            <mx:Object state="AL" capital="Montgomery"/>
            <mx:Object state="AK" capital="Juneau"/>
            <mx:Object state="AR" capital="Little Rock"/>
        </mx:ArrayCollection>
    </mx:ComboBox>

To make the event handler in the section Using events with ComboBox controls display the state ID and capital, you would modify the change event handler to use a property named state, as the following example shows:

        private function changeEvt(event) {
            forChange.text=event.currentTarget.selectedItem.state + " " + 
            event.currentTarget.selectedItem.capital + " " +
            event.currenttarget.selectedIndex;
        }

You can also specify the ComboBox labels by using a label function, as described in Using a label function.

Populating a ComboBox control by using variables and models

Flex lets you populate the data provider of a ComboBox control from an ActionScript variable definition or from a Flex data model. Each element of the data provider must contain a string label, and can contain one or more fields with additional data. The following example populates two ComboBox controls; one from an ArrayCollection variable that it populates directly from an Array, the other from an ArrayCollection that it populates from an array of items in an <MX:Model> tag.

<?xml version="1.0"?>
<!-- dpcontrols/ComboBoxVariables.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
   initialize="initData();">

   <mx:Script>
      <![CDATA[
         import mx.collections.*
         private var COLOR_ARRAY:Array= 
            [{label:"Red", data:"#FF0000"},
            {label:"Green", data:"#00FF00"},
            {label:"Blue", data:"#0000FF"}];
         // Declare an ArrayCollection variable for the colors.
         // Make it Bindable so it can be used in bind 
         // expressions ({colorAC}).
         [Bindable]
         public var colorAC:ArrayCollection;

         // Initialize colorAC ArrayCollection variable from the Array.
         // Use an initialize event handler to initialize data variables
         // that do not rely on components, so that the initial values are
         // available when the controls that use them are constructed.
         //See the mx:ArrayCollection tag, below, for a second way to
         //initialize an ArrayCollection.
         private function initData():void {
            colorAC=new ArrayCollection(COLOR_ARRAY);
         }
      ]]>
   </mx:Script>
   <!-- This example shows two different ways to 
        structure a Model. -->
   <mx:Model id="myDP">
      <obj>
         <item label="AL" data="Montgomery"/>
         <item>
            <label>AK</label>
            <data>Juneau</data>
         </item>
         <item>
            <label>AR</label>
            <data>Little Rock</data>
         </item>
      </obj>
   </mx:Model>
      
   <!-- Create a stateAC ArrayCollection that uses as its source an Array of
         the item elements from the myDP model. 
         This technique and the declaration and initialization code used for
         the colorAC variable are alternative methods of creating and
         initializing the ArrayCollection. -->
   <mx:ArrayCollection id="stateAC" source="{myDP.item}"/>

   <mx:ComboBox dataProvider="{colorAC}"/>
   <mx:ComboBox dataProvider="{stateAC}"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

This example uses a simple model. However, you can populate the model from an external data source or define a custom data model class in ActionScript. For more information on using data models, see Storing Data.

You can use remote data providers to supply data to your ComboBox control. For example, when a web service operation returns an Array of strings, you can use the following format to display each string as a row of a ComboBox control:

<mx:ArrayCollection id="resultAC"
    source="mx.utils.ArrayUtil.toArray(service.operation.lastResult);"
<mx:ComboBox dataProvider="{resultAC}" />

For more information on using remote data providers, see Remote data in data provider components.

ComboBox control user interaction

An ArrayCollection control can be noneditable or editable, as specified by the Boolean editable property. In a noneditable ComboBox control, a user can make a single selection from a drop-down list. In an editable ComboBox control, the portion button of the control is a text field that the user can enter text directly into or can populate by selecting an item from the drop-down list. When the user makes a selection in the ComboBox control list, the label of the selection is copied to the text field at the top of the ComboBox control.

When a ComboBox control (and not the drop-down box) has focus and is editable, all keystrokes go to the text field and are handled according to the rules of the TextInput control (see TextInput control), with the exception of the Control+Down key combination, which opens the drop-down list. When the drop-down list is open, you can use the Up and Down keys to navigate in the list and the Enter key to select an item from the list.

When a ComboBox control has focus and is noneditable, alphanumeric keystrokes move the selection up and down the data provider to the next item with the same first character and display the label in the text field. If the drop-down list is open, the visible selection moves to the selected item.

You can also use the following keys to control a noneditable ComboBox control when the drop-down list is not open:

When the drop-down list of a noneditable ComboBox control has focus, alphanumeric keystrokes move the selection up and down the drop-down list to the next item with the same first character. You can also use the following keys to control a drop-down list when it is open: