ComboBox class -- Version 8

The ComboBox component combines three separate subcomponents: Button, TextInput, and List. Most of the methods, properties, and events of each subcomponent are available directly from the ComboBox component and are listed in the summary tables for the ComboBox class.

The drop-down list in a combo box is provided either as an array or as a data provider. If you use a data provider, the list changes at runtime. You can change the source of the ComboBox data dynamically by switching to a new array or data provider.

Items in a combo box list are indexed by position, starting with the number 0. An item can be one of the following:

If the item is a primitive data type other than String, it is converted to a string. If an item is an object, the label property must be a string and the data property can be any ActionScript value.

ComboBox methods to which you supply items have two parameters, label and data, that refer to the properties above. Methods that return an item return it as an object.

A combo box defers the instantiation of its drop-down list until a user interacts with it. Therefore, a combo box may appear to respond slowly on first use.

Use the following code to programmatically access the ComboBox component's drop-down list and override the delay:

Accessing the pop-up list may cause a pause in the application. This may occur when the user first interacts with the combo box, or when the above code runs.

Method summary for the ComboBox class

Method	Description
ComboBox.addItem()	Adds an item to the end of the list.
ComboBox.addItemAt()	Adds an item to the end of the list at the specified index.
ComboBox.close()	Closes the drop-down list.
ComboBox.getItemAt()	Returns the item at the specified index.
ComboBox.open()	Opens the drop-down list.
ComboBox.removeAll()	Removes all items in the list.
ComboBox.removeItemAt()	Removes an item from the list at the specified location.
ComboBox.replaceItemAt()	Replaces the content of the item at the specified index.
ComboBox.sortItems()	Sorts the list using a compare function.
ComboBox.sortItemsBy()	Sorts the list using a field of each item.

Methods inherited from the UIObject class

The following table lists the methods the ComboBox class inherits from the UIObject class. When calling these methods from the ComboBox object, use the form comboBoxInstance.methodName.

Method	Description
UIObject.createClassObject()	Creates an object on the specified class.
UIObject.createObject()	Creates a subobject on an object.
UIObject.destroyObject()	Destroys a component instance.
UIObject.doLater()	Calls a function when parameters have been set in the Property and Component inspectors.
UIObject.getStyle()	Gets the style property from the style declaration or object.
UIObject.invalidate()	Marks the object so it is redrawn on the next frame interval.
UIObject.move()	Moves the object to the requested position.
UIObject.redraw()	Forces validation of the object so it is drawn in the current frame.
UIObject.setSize()	Resizes the object to the requested size.
UIObject.setSkin()	Sets a skin in the object.
UIObject.setStyle()	Sets the style property on the style declaration or object.

Methods inherited from the UIComponent class

The following table lists the methods the ComboBox class inherits from the UIComponent class. When calling these methods from the ComboBox object, use the form comboBoxInstance.methodName.

Method	Description
UIComponent.getFocus()	Returns a reference to the object that has focus.
UIComponent.setFocus()	Sets focus to the component instance.

Property summary for the ComboBox class

Property	Description
ComboBox.dataProvider	The data model for the items in the list.
ComboBox.dropdown	Returns a reference to the List component contained by the combo box.
ComboBox.dropdownWidth	The width of the drop-down list, in pixels.
ComboBox.editable	Indicates whether a combo box is editable.
ComboBox.labelField	Indicates which data field to use as the label for the drop-down list.
ComboBox.labelFunction	Specifies a function to compute the label field for the drop-down list.
ComboBox.length	Read-only; the length of the drop-down list.
ComboBox.restrict	The set of characters that a user can enter in the text field of a combo box.
ComboBox.rowCount	The maximum number of list items to display at one time.
ComboBox.selectedIndex	The index of the selected item in the drop-down list.
ComboBox.selectedItem	The value of the selected item in the drop-down list.
ComboBox.text	The string of text in the text box.
ComboBox.textField	A reference to the TextInput component in the combo box.
ComboBox.value	The value of the text box (editable) or drop-down list (static).

Properties inherited from the UIObject class

The following table lists the properties the ComboBox class inherits from the UIObject class. When accessing these properties from the ComboBox object, use the form comboBoxInstance.propertyName.

Property	Description
UIObject.bottom	Read-only; the position of the bottom edge of the object, relative to the bottom edge of its parent.
UIObject.height	Read-only; the height of the object, in pixels.
UIObject.left	Read-only; the left edge of the object, in pixels.
UIObject.right	Read-only.The position of the right edge of the object, relative to the right edge of its parent.
UIObject.scaleX	A number indicating the scaling factor in the x direction of the object, relative to its parent.
UIObject.scaleY	A number indicating the scaling factor in the y direction of the object, relative to its parent.
UIObject.top	Read-only; the position of the top edge of the object, relative to its parent.
UIObject.visible	A Boolean value indicating whether the object is visible (`true`) or not (`false`).
UIObject.width	Read-only; the width of the object, in pixels.
UIObject.x	Read-only; the left edge of the object, in pixels.
UIObject.y	Read-only; the top edge of the object, in pixels.

Properties inherited from the UIComponent class

The following table lists the properties the ComboBox class inherits from the UIComponent class. When accessing these properties from the ComboBox object, use the form comboBoxInstance.propertyName.

Property	Description
UIComponent.enabled	Indicates whether the component can receive focus and input.
UIComponent.tabIndex	A number indicating the tab order for a component in a document.

Event summary for the ComboBox class

Event	Description
ComboBox.change	Broadcast when the value of the combo box changes as a result of user interaction.
ComboBox.close	Broadcast when the list of the combo box begins to retract.
ComboBox.enter	Broadcast when the Enter key is pressed.
ComboBox.itemRollOut	Broadcast when the pointer rolls off a pop-up list item.
ComboBox.itemRollOver	Broadcast when a drop-down list item is rolled over.
ComboBox.open	Broadcast when the drop-down list begins to open.
ComboBox.scroll	Broadcast when the drop-down list is scrolled.

Events inherited from the UIObject class

The following table lists the events the ComboBox class inherits from the UIObject class.

Event	Description
UIObject.draw	Broadcast when an object is about to draw its graphics.
UIObject.hide	Broadcast when an object's state changes from visible to invisible.
UIObject.load	Broadcast when subobjects are being created.
UIObject.move	Broadcast when the object has moved.
UIObject.resize	Broadcast when an object has been resized.
UIObject.reveal	Broadcast when an object's state changes from invisible to visible.
UIObject.unload	Broadcast when the subobjects are being unloaded.

Events inherited from the UIComponent class

The following table lists the events the ComboBox class inherits from the UIComponent class.

Event	Description
UIComponent.focusIn	Broadcast when an object receives focus.
UIComponent.focusOut	Broadcast when an object loses focus.
UIComponent.keyDown	Broadcast when a key is pressed.
UIComponent.keyUp	Broadcast when a key is released.

Comments

diskofish said on Dec 2, 2005 at 2:30 PM :

If you are creating ComboBoxes dynamically, I have found when you avoid the _visible and .visible properties the typical problems with masks do not surface.

No screen name said on Mar 14, 2006 at 1:55 PM :

ComboBox.close is actually called when it fully retracted, not when it begins to retract as stated above.

JohnKirk said on Nov 17, 2006 at 12:01 PM :

The ComboBox will not work under certain known conditions (see below).
Adobe neither documents this nor provides a workaround.
EXAMPLE:
-- Create a Flash file named "Combo.fla", with a populated combobox on the stage, and publish the file to create "Combo.swf".
-- Create a Flash file named "Main.fla", which loads "Combo.swf"
Case #1: Won't Open:
-- Put the following code into "Main", and run.
-- The combobox will NOT open.
this.createEmptyMovieClip("mc_content", 5);
var MCL:MovieClipLoader = new MovieClipLoader();
MCL.loadClip("Combo.swf", mc_content);
Case #2: Will Open:
-- Put the following code into "Main", and run.
-- The combobox will open.
-- Note: Adobe does NOT document this usage for "loadClip".
var MCL:MovieClipLoader = new MovieClipLoader();
MCL.loadClip("Combo.swf", 5);
-- I would say that I hope this helps members of the Flash community, but I know from previous experience that Adobe will not add this note to live docs.

Atlahua said on Feb 8, 2007 at 12:26 PM :

What happened with the ->setSelectedIndex<- Property?
How can I do the same in Flash 8?

spor1 said on Feb 15, 2007 at 6:36 PM :

I have an application that loads a scrollbar into _level2 of the app. The content (including combo boxes) is on _level0. The scrollbar moves the _y of _level0.

The problem is, when the _y of the comboBoxes on _level0 changes, the comboBoxes no longer work. The options do not reveal.

I attempted to attach a listener that would redraw(); the component after the scrolling was done, but this did not help. Does anyone know how to avoid this?

-Spor1

Unkulunkulu said on Mar 7, 2007 at 3:33 AM :

How can I access the button instance of a ComboBox component?

The dropdown and textField-properties would indicate that it is possible somehow.

mcarey said on May 10, 2007 at 1:23 PM :

I have come across a bug where, other than for an initial instantiation, a combobox component instance whose enabled property is set to false will display a square graphic artifact over the triangular drop-down button that appears similar to the checkbox component background square. This artifact disappears as soon as the combobox is enabled, but reappears for any occurance of disabling applied to ANY combobox instance in the app, even if loaded in as an external swf for the first time OR created/attached dynamically. A couple other developers on actionscript have also experienced this bug. ( thread id: 132496 ). Can someone at MM/Adobe please weigh in on this issue and suggest a workaround?

bcraigie said on May 13, 2007 at 4:37 AM :

Please can Adobe document how to put the scrollbar at the left side of the box instead of the right side?

badchoosed said on May 25, 2007 at 6:30 AM :

How can I force the ComboBox open to upside?