class ComboBox
package feathers.controls
extends FeathersControl › MeasureSprite › ValidatingSprite
implements IStageFocusDelegate, IDataSelector<Dynamic>, IIndexSelector
Displays a control consisting of a TextInput and Button that allows an
item from a collection to be selected. When the button is triggered, a list
box of items is displayed as a pop-up. The text input allows filtering, or
(optionally) choosing custom items.
The following example creates a ComboBox, gives it a data provider, tells
the item renderer how to interpret the data, and listens for when the
selection changes:
var comboBox = new ComboBox();
comboBox.dataProvider = new ArrayCollection([
{ text: "Milk" },
{ text: "Eggs" },
{ text: "Bread" },
{ text: "Steak" },
]);
comboBox.itemToText = (item:Dynamic) -> {
return item.text;
};
comboBox.addEventListener(Event.CHANGE, (event:Event) -> {
var comboBox = cast(event.currentTarget, ComboBox);
trace("ComboBox changed: " + comboBox.selectedIndex + " " + comboBox.selectedItem.text);
});
this.addChild(comboBox);Events:
openfl.events.Event.CHANGE | Dispatched when either
|
|---|---|
openfl.events.Event.OPEN | Dispatched when the pop-up list view is opened. |
openfl.events.Event.CLOSE | Dispatched when the pop-up list view is closed. |
feathers.events.ListViewEvent.ITEM_TRIGGER | Dispatched when the user taps or clicks an item renderer in the pop-up list view. The pointer must remain within the bounds of the item renderer on release, and the list view cannot scroll before release, or the gesture will be ignored. |
1.0.0
.See also:
Static variables
staticfinalread onlyCHILD_VARIANT_BUTTON:String = "comboBox_button"
The variant used to style the Button child component in a theme.
To override this default variant, set the
ComboBox.customButtonVariant property.
1.0.0
.See also:
staticfinalread onlyCHILD_VARIANT_LIST_VIEW:String = "comboBox_listView"
The variant used to style the ListView child component in a theme.
To override this default variant, set the
ComboBox.customListViewVariant property.
1.0.0
.See also:
staticfinalread onlyCHILD_VARIANT_TEXT_INPUT:String = "comboBox_textInput"
The variant used to style the TextInput child component in a theme.
To override this default variant, set the
ComboBox.customTextInputVariant property.
1.0.0
.See also:
Constructor
new(?dataProvider:IFlatCollection<Dynamic>, ?changeListener:Event ‑> Void)
Creates a new ComboBox object.
1.0.0
.Variables
allowCustomUserValue:Bool
Allows the user to type a custom value into the text input. If a custom
value is selected, the selectedIndex property will be -1, but the
selectedItem property will contain the custom value.
1.0.0
.buttonFactory:AbstractDisplayObjectFactory<Dynamic, Button>
Creates the button, which must be of type feathers.controls.Button.
In the following example, a custom button factory is provided:
comboBox.buttonFactory = () ->
{
return new Button();
};1.0.0
.See also:
customButtonVariant:String
A custom variant to set on the button, instead of
ComboBox.CHILD_VARIANT_BUTTON.
The customButtonVariant will be not be used if the result of
buttonFactory already has a variant set.
1.0.0
.See also:
customListViewVariant:String
A custom variant to set on the pop-up list view, instead of
ComboBox.CHILD_VARIANT_LIST_VIEW.
The customListViewVariant will be not be used if the result of
listViewFactory already has a variant set.
1.0.0
.See also:
customTextInputVariant:String
A custom variant to set on the text input, instead of
ComboBox.CHILD_VARIANT_TEXT_INPUT.
The customTextInputVariant will be not be used if the result of
textInputFactory already has a variant set.
1.0.0
.See also:
dataProvider:IFlatCollection<Dynamic>
The collection of data displayed by the list.
Items in the collection must be class instances or anonymous structures. Do not add primitive values (such as strings, booleans, or numeric values) directly to the collection.
Additionally, all items in the collection must be unique object instances. Do not add the same instance to the collection more than once because a runtime exception will be thrown.
The following example passes in a data provider and tells the item renderer how to interpret the data:
comboBox.dataProvider = new ArrayCollection([
{ text: "Milk" },
{ text: "Eggs" },
{ text: "Bread" },
{ text: "Chicken" },
]);
comboBox.itemToText = (item:Dynamic) -> {
return item.text;
};1.0.0
.See also:
itemRendererRecycler:AbstractDisplayObjectRecycler<Dynamic, ListViewItemState, DisplayObject>
Manages item renderers used by the list view.
In the following example, the pop-up list view uses a custom item renderer class:
comboBox.itemRendererRecycler = DisplayObjectRecycler.withClass(CustomItemRenderer);1.0.0
.listViewFactory:AbstractDisplayObjectFactory<Dynamic, ListView>
Creates the list view that is displayed as a pop-up. The list view must
be of type feathers.controls.ListView.
In the following example, a custom list view factory is provided:
comboBox.listViewFactory = () ->
{
return new ListView();
};1.0.0
.See also:
openListViewOnFocus:Bool = false
Determines if the pop-up list should automatically open when the combo box receives focus, or if the user is required to click the open button.
1.0.0
.popUpAdapter:IPopUpAdapter
Manages how the pop-up list is displayed when it is opened and closed.
In the following example, a custom pop-up adapter is provided:
comboBox.popUpAdapter = new DropDownPopUpAdapter();1.0.0
.prompt:String
The text displayed by the text input when no item is selected.
The following example sets the combo box's prompt:
comboBox.prompt = "Select an item";1.0.0
.selectedIndex:Int
See also:
feathers.core.IIndexSelector.selectedIndexNote: If theselectedIndexis-1, it's still possible for theselectedItemto not benull. This can happen when a custom value is entered into the text input by the user.
selectedItem:Dynamic
See also:
feathers.core.IDataSelector.selectedItemNote: If theselectedItemis notnull, and theselectedIndexis-1, the value ofselectedItemis a custom value entered into the text input by the user.
textInputFactory:AbstractDisplayObjectFactory<Dynamic, TextInput>
Creates the text input, which must be of type feathers.controls.TextInput.
In the following example, a custom text input factory is provided:
comboBox.textInputFactory = () ->
{
return new TextInput();
};1.0.0
.See also:
Methods
closeListView():Void
Closes the pop-up list, if it is open.
The following example closes the pop-up list:
if(comboBox.open)
{
comboBox.closeListView();
}When the pop-up list closes, the component will dispatch an event of
type Event.CLOSE.
1.0.0
.See also:
dynamicitemToText(data:Dynamic):String
Converts an item to text to display within the pop-up ListView, or
within the Button, if the item is selected. By default, the
toString() method is called to convert an item to text. This method
may be replaced to provide custom text.
This function is not called if the item is already a string.
For example, consider the following item:
{ text: "Example Item" }If the ListView should display the text "Example Item", a custom
implementation of itemToText() might look like this:
comboBox.itemToText = (item:Dynamic) -> {
return item.text;
};1.0.0
.openListView():Void
Opens the pop-up list, if it is not already open.
The following example opens the pop-up list:
if(!comboBox.open)
{
comboBox.openListView();
}When the pop-up list opens, the component will dispatch an event of type
Event.OPEN.
1.0.0
.See also:
dynamictextToItem(text:String):Dynamic
Called when none of the items in the data provider match the custom text typed by the user. By default, returns the original string, without any changes.
For example, consider the following item type:
{ text: "Example Item" }A custom implementation of textToItem() might look like this:
comboBox.textToItem = (customText:String) -> {
return { text: customText };
};1.0.0
.See also: