APIdia Launch Partner
Top Description Inners Fields Constructors Methods
javafx.scene.control

public Class ChoiceBox<T>

extends Control
Class Inheritance
Annotations
@DefaultProperty:items
Type Parameters
<T>
the type of the item contained within the ChoiceBox
Imports
javafx.beans.DefaultProperty, javafx.beans.property.ObjectProperty, .ObjectPropertyBase, .ReadOnlyBooleanProperty, .ReadOnlyBooleanWrapper, .SimpleObjectProperty, javafx.beans.value.ChangeListener, .WeakChangeListener, javafx.collections.FXCollections, .ListChangeListener, .ObservableList, .WeakListChangeListener, javafx.css.PseudoClass, javafx.event.ActionEvent, .Event, .EventHandler, .EventType, javafx.scene.AccessibleAction, .AccessibleAttribute, .AccessibleRole, javafx.scene.control.skin.ChoiceBoxSkin, javafx.util.StringConverter, com.sun.javafx.tk.Toolkit
The ChoiceBox is used for presenting the user with a relatively small set of predefined choices from which they may choose. The ChoiceBox, when "showing", will display to the user these choices and allow them to pick exactly one choice. When not showing, the current choice is displayed.

By default, the ChoiceBox has no item selected unless otherwise specified. Although the ChoiceBox will only allow a user to select from the predefined list, it is possible for the developer to specify the selected item to be something other than what is available in the predefined list. This is required for several important use cases. Configuration of the ChoiceBox is order independent. You may either specify the items and then the selected item, or you may specify the selected item and then the items. Either way will function correctly.

ChoiceBox item selection is handled by SelectionModel. As with ListView and ComboBox, it is possible to modify the SelectionModel that is used, although this is likely to be rarely changed. ChoiceBox supports only a single selection model, hence the default used is a SingleSelectionModel.

Example: 

 ChoiceBox cb = new ChoiceBox();
cb.getItems().addAll("item1", "item2", "item3");
Image of the ChoiceBox control
Since
JavaFX 2.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
ChoiceBox.ChoiceBoxSelectionModel<T>

Field Summary

Modifier and TypeField and Description
private final ObjectProperty<StringConverter<T>>
converter

private ObjectProperty<ObservableList<T>>
items

The items to display in the choice box.

private final ListChangeListener<T>
itemsListener

public static final EventType<Event>
ON_HIDDEN

Called when the ChoiceBox popup has been hidden.

public static final EventType<Event>
ON_HIDING

Called when the ChoiceBox popup will be hidden.

public static final EventType<Event>
ON_SHOWING

Called prior to the ChoiceBox showing its popup after the user has clicked or otherwise interacted with the ChoiceBox.

public static final EventType<Event>
ON_SHOWN

Called after the ChoiceBox has shown its popup.

private ObjectProperty<EventHandler<ActionEvent>>
onAction

private ObjectProperty<EventHandler<Event>>
onHidden

private ObjectProperty<EventHandler<Event>>
onHiding

private ObjectProperty<EventHandler<Event>>
onShowing

private ObjectProperty<EventHandler<Event>>
onShown

private ChangeListener<T>
selectedItemListener

private ObjectProperty<SingleSelectionModel<T>>
selectionModel

The selection model for the ChoiceBox.

private ReadOnlyBooleanWrapper
showing

Indicates whether the drop down is displaying the list of choices to the user.

private static final PseudoClass
SHOWING_PSEUDOCLASS_STATE

private final ObjectProperty<T>
value

Constructor Summary

AccessConstructor and Description
public
ChoiceBox()

Create a new ChoiceBox which has an empty list of items.

public
ChoiceBox(ObservableList<T>
the set of items
items)

Create a new ChoiceBox with the given set of items.

Method Summary

Modifier and TypeMethod and Description
public final ObjectProperty<StringConverter<T>>

Returns:

the string converter property
converterProperty()

Allows a way to specify how to represent objects in the items list.

protected Skin<?>
createDefaultSkin()

Overrides javafx.scene.control.Control.createDefaultSkin.

Create a new instance of the default skin for this control.

public void
executeAccessibleAction(AccessibleAction action, Object... parameters)

Overrides javafx.scene.control.Control.executeAccessibleAction.

This method is called by the assistive technology to request the action indicated by the argument should be executed.

public final StringConverter<T>
getConverter()

public final ObservableList<T>
getItems()

public final EventHandler<ActionEvent>
getOnAction()

public final EventHandler<Event>
getOnHidden()

public final EventHandler<Event>
getOnHiding()

public final EventHandler<Event>
getOnShowing()

public final EventHandler<Event>
getOnShown()

public final SingleSelectionModel<T>
getSelectionModel()

public final T
getValue()

public void
hide()

Closes the list of choices.

public final boolean
isShowing()

public final ObjectProperty<ObservableList<T>>
itemsProperty()

public final ObjectProperty<EventHandler<ActionEvent>>

Returns:

the on action property
onActionProperty()

The ChoiceBox action, which is invoked whenever the ChoiceBox value property is changed.

public final ObjectProperty<EventHandler<Event>>

Returns:

the on hidden property
onHiddenProperty()

Called just after the ChoiceBox popup has been hidden.

public final ObjectProperty<EventHandler<Event>>

Returns:

the on hiding property
onHidingProperty()

Called just prior to the ChoiceBox popup being hidden.

public final ObjectProperty<EventHandler<Event>>

Returns:

the on showing property
onShowingProperty()

Called just prior to the ChoiceBox popup being shown.

public final ObjectProperty<EventHandler<Event>>

Returns:

the on shown property
onShownProperty()

Called just after the ChoiceBox popup is shown.

public Object
queryAccessibleAttribute(AccessibleAttribute attribute, Object... parameters)

Overrides javafx.scene.control.Control.queryAccessibleAttribute.

This method is called by the assistive technology to request the value for an attribute.

public final ObjectProperty<SingleSelectionModel<T>>
selectionModelProperty()

public final void
setConverter(StringConverter<T> value)

public final void
setItems(ObservableList<T> value)

public final void
setOnAction(EventHandler<ActionEvent> value)

public final void
setOnHidden(EventHandler<Event> value)

public final void
setOnHiding(EventHandler<Event> value)

public final void
setOnShowing(EventHandler<Event> value)

public final void
setOnShown(EventHandler<Event> value)

public final void
setSelectionModel(SingleSelectionModel<T> value)

private void
setShowing(boolean value)

public final void
setValue(T value)

public void
show()

Opens the list of choices.

public final ReadOnlyBooleanProperty
showingProperty()

public final ObjectProperty<T>

Returns:

the value property
valueProperty()

The value of this ChoiceBox is defined as the selected item in the ChoiceBox selection model.

Inherited from javafx.scene.control.Control:
computeMaxHeightcomputeMaxWidthcomputeMinHeightcomputeMinWidthcomputePrefHeightcomputePrefWidthcontextMenuPropertygetBaselineOffsetgetClassCssMetaDatagetContextMenugetControlChildrengetControlCssMetaDatagetCssMetaDatagetInitialFocusTraversablegetSkingetTooltipisResizablelayoutChildrenloadSkinClasssetContextMenusetSkinsetTooltipskinClassNamePropertyskinPropertytooltipProperty

Field Detail

converterback to summary
private final ObjectProperty<StringConverter<T>> converter
itemsback to summary
private ObjectProperty<ObservableList<T>> items

The items to display in the choice box. The selected item (as indicated in the selection model) must always be one of these items.

itemsListenerback to summary
private final ListChangeListener<T> itemsListener
ON_HIDDENback to summary
public static final EventType<Event> ON_HIDDEN

Called when the ChoiceBox popup has been hidden.

Since
JavaFX 8u60
ON_HIDINGback to summary
public static final EventType<Event> ON_HIDING

Called when the ChoiceBox popup will be hidden.

Since
JavaFX 8u60
ON_SHOWINGback to summary
public static final EventType<Event> ON_SHOWING

Called prior to the ChoiceBox showing its popup after the user has clicked or otherwise interacted with the ChoiceBox.

Since
JavaFX 8u60
ON_SHOWNback to summary
public static final EventType<Event> ON_SHOWN

Called after the ChoiceBox has shown its popup.

Since
JavaFX 8u60
onActionback to summary
private ObjectProperty<EventHandler<ActionEvent>> onAction
onHiddenback to summary
private ObjectProperty<EventHandler<Event>> onHidden
onHidingback to summary
private ObjectProperty<EventHandler<Event>> onHiding
onShowingback to summary
private ObjectProperty<EventHandler<Event>> onShowing
onShownback to summary
private ObjectProperty<EventHandler<Event>> onShown
selectedItemListenerback to summary
private ChangeListener<T> selectedItemListener
selectionModelback to summary
private ObjectProperty<SingleSelectionModel<T>> selectionModel

The selection model for the ChoiceBox. Only a single choice can be made, hence, the ChoiceBox supports only a SingleSelectionModel. Generally, the main interaction with the selection model is to explicitly set which item in the items list should be selected, or to listen to changes in the selection to know which item has been chosen.

showingback to summary
private ReadOnlyBooleanWrapper showing

Indicates whether the drop down is displaying the list of choices to the user. This is a readonly property which should be manipulated by means of the #show and #hide methods.

SHOWING_PSEUDOCLASS_STATEback to summary
private static final PseudoClass SHOWING_PSEUDOCLASS_STATE
valueback to summary
private final ObjectProperty<T> value

Constructor Detail

ChoiceBoxback to summary
public ChoiceBox()

Create a new ChoiceBox which has an empty list of items.

ChoiceBoxback to summary
public ChoiceBox(ObservableList<T> items)

Create a new ChoiceBox with the given set of items. Since it is observable, the content of this list may change over time and the ChoiceBox will be updated accordingly.

Parameters
items:ObservableList<T>

the set of items

Method Detail

converterPropertyback to summary
public final ObjectProperty<StringConverter<T>> converterProperty()

Allows a way to specify how to represent objects in the items list. When a StringConverter is set, the object toString method is not called and instead its toString(object T) is called, passing the objects in the items list. This is useful when using domain objects in a ChoiceBox as this property allows for customization of the representation. Also, any of the pre-built Converters available in the javafx.util.converter package can be set.

Returns:ObjectProperty<StringConverter<T>>

the string converter property

Since
JavaFX 2.1
createDefaultSkinback to summary
protected Skin<?> createDefaultSkin()

Overrides javafx.scene.control.Control.createDefaultSkin.

Doc from javafx.scene.control.Control.createDefaultSkin.

Create a new instance of the default skin for this control. This is called to create a skin for the control if no skin is provided via CSS -fx-skin or set explicitly in a sub-class with setSkin(...).

Annotations
@Override
executeAccessibleActionback to summary
public void executeAccessibleAction(AccessibleAction action, Object... parameters)

Overrides javafx.scene.control.Control.executeAccessibleAction.

Doc from javafx.scene.control.Control.executeAccessibleAction.

This method is called by the assistive technology to request the action indicated by the argument should be executed.

This method is commonly overridden by subclasses to implement action that are required for a specific role.
If a particular action is not handled, the superclass implementation must be called.

Annotations
@Override
getConverterback to summary
public final StringConverter<T> getConverter()
getItemsback to summary
public final ObservableList<T> getItems()
getOnActionback to summary
public final EventHandler<ActionEvent> getOnAction()
getOnHiddenback to summary
public final EventHandler<Event> getOnHidden()
getOnHidingback to summary
public final EventHandler<Event> getOnHiding()
getOnShowingback to summary
public final EventHandler<Event> getOnShowing()
getOnShownback to summary
public final EventHandler<Event> getOnShown()
getSelectionModelback to summary
public final SingleSelectionModel<T> getSelectionModel()
getValueback to summary
public final T getValue()
hideback to summary
public void hide()

Closes the list of choices.

Exceptions
IllegalStateException:
if this method is called on a thread other than the JavaFX Application Thread.
isShowingback to summary
public final boolean isShowing()
itemsPropertyback to summary
public final ObjectProperty<ObservableList<T>> itemsProperty()
onActionPropertyback to summary
public final ObjectProperty<EventHandler<ActionEvent>> onActionProperty()

The ChoiceBox action, which is invoked whenever the ChoiceBox value property is changed. This may be due to the value property being programmatically changed or when the user selects an item in a popup menu.

Returns:ObjectProperty<EventHandler<ActionEvent>>

the on action property

Since
JavaFX 8u60
onHiddenPropertyback to summary
public final ObjectProperty<EventHandler<Event>> onHiddenProperty()

Called just after the ChoiceBox popup has been hidden.

Returns:ObjectProperty<EventHandler<Event>>

the on hidden property

Since
JavaFX 8u60
onHidingPropertyback to summary
public final ObjectProperty<EventHandler<Event>> onHidingProperty()

Called just prior to the ChoiceBox popup being hidden.

Returns:ObjectProperty<EventHandler<Event>>

the on hiding property

Since
JavaFX 8u60
onShowingPropertyback to summary
public final ObjectProperty<EventHandler<Event>> onShowingProperty()

Called just prior to the ChoiceBox popup being shown.

Returns:ObjectProperty<EventHandler<Event>>

the on showing property

Since
JavaFX 8u60
onShownPropertyback to summary
public final ObjectProperty<EventHandler<Event>> onShownProperty()

Called just after the ChoiceBox popup is shown.

Returns:ObjectProperty<EventHandler<Event>>

the on shown property

Since
JavaFX 8u60
queryAccessibleAttributeback to summary
public Object queryAccessibleAttribute(AccessibleAttribute attribute, Object... parameters)

Overrides javafx.scene.control.Control.queryAccessibleAttribute.

Doc from javafx.scene.control.Control.queryAccessibleAttribute.

This method is called by the assistive technology to request the value for an attribute.

This method is commonly overridden by subclasses to implement attributes that are required for a specific role.
If a particular attribute is not handled, the superclass implementation must be called.

Annotations
@Override
selectionModelPropertyback to summary
public final ObjectProperty<SingleSelectionModel<T>> selectionModelProperty()
setConverterback to summary
public final void setConverter(StringConverter<T> value)
setItemsback to summary
public final void setItems(ObservableList<T> value)
setOnActionback to summary
public final void setOnAction(EventHandler<ActionEvent> value)
setOnHiddenback to summary
public final void setOnHidden(EventHandler<Event> value)
setOnHidingback to summary
public final void setOnHiding(EventHandler<Event> value)
setOnShowingback to summary
public final void setOnShowing(EventHandler<Event> value)
setOnShownback to summary
public final void setOnShown(EventHandler<Event> value)
setSelectionModelback to summary
public final void setSelectionModel(SingleSelectionModel<T> value)
setShowingback to summary
private void setShowing(boolean value)
setValueback to summary
public final void setValue(T value)
showback to summary
public void show()

Opens the list of choices.

Exceptions
IllegalStateException:
if this method is called on a thread other than the JavaFX Application Thread.
showingPropertyback to summary
public final ReadOnlyBooleanProperty showingProperty()
valuePropertyback to summary
public final ObjectProperty<T> valueProperty()

The value of this ChoiceBox is defined as the selected item in the ChoiceBox selection model. The valueProperty is synchronized with the selectedItem. This property allows for bi-directional binding of external properties to the ChoiceBox and updates the selection model accordingly.

Returns:ObjectProperty<T>

the value property

Since
JavaFX 2.1
javafx.scene.control back to summary

pack-priv Class ChoiceBox.ChoiceBoxSelectionModel<T>

extends SingleSelectionModel<T>
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final ChoiceBox<T>
choiceBox

private ListChangeListener<T>
itemsContentObserver

private ChangeListener<ObservableList<T>>
itemsObserver

private WeakListChangeListener<T>
weakItemsContentObserver

Constructor Summary

AccessConstructor and Description
public
ChoiceBoxSelectionModel(final ChoiceBox<T> cb)

Method Summary

Modifier and TypeMethod and Description
protected int
getItemCount()

Implements abstract javafx.scene.control.SingleSelectionModel.getItemCount.

Gets the number of items available for the selection model.

protected T
getModelItem(int index)

Implements abstract javafx.scene.control.SingleSelectionModel.getModelItem.

Gets the data model item associated with a specific index.

public void
select(int index)

Overrides javafx.scene.control.SingleSelectionModel.select, javafx.scene.control.SingleSelectionModel.select.

Selects the given row.

public void
select(T obj)

Overrides javafx.scene.control.SingleSelectionModel.select.

Selects the index for the first instance of given object in the underlying data model.

public void
selectNext()

Overrides javafx.scene.control.SingleSelectionModel.selectNext.

Selects the next index.

public void
selectPrevious()

Overrides javafx.scene.control.SingleSelectionModel.selectPrevious.

Selects the previous index.

Inherited from javafx.scene.control.SingleSelectionModel:
clearAndSelectclearSelectionclearSelectionisEmptyisSelectedselectFirstselectLast

Field Detail

choiceBoxback to summary
private final ChoiceBox<T> choiceBox
itemsContentObserverback to summary
private ListChangeListener<T> itemsContentObserver
itemsObserverback to summary
private ChangeListener<ObservableList<T>> itemsObserver
weakItemsContentObserverback to summary
private WeakListChangeListener<T> weakItemsContentObserver

Constructor Detail

ChoiceBoxSelectionModelback to summary
public ChoiceBoxSelectionModel(final ChoiceBox<T> cb)

Method Detail

getItemCountback to summary
protected int getItemCount()

Implements abstract javafx.scene.control.SingleSelectionModel.getItemCount.

Doc from javafx.scene.control.SingleSelectionModel.getItemCount.

Gets the number of items available for the selection model. If the number of items can change dynamically, it is the responsibility of the concrete SingleSelectionModel implementation to ensure that items are selected or unselected as appropriate as the items change.

Annotations
@Override
getModelItemback to summary
protected T getModelItem(int index)

Implements abstract javafx.scene.control.SingleSelectionModel.getModelItem.

Doc from javafx.scene.control.SingleSelectionModel.getModelItem.

Gets the data model item associated with a specific index.

Annotations
@Override
selectback to summary
public void select(int index)

Overrides javafx.scene.control.SingleSelectionModel.select, javafx.scene.control.SingleSelectionModel.select.

Selects the given row. Since the SingleSelectionModel can only support having a single row selected at a time, this also causes any previously selected row to be unselected. This method is overridden here so that we can move past a Separator in a ChoiceBox and select the next valid menuitem.

Annotations
@Override
selectback to summary
public void select(T obj)

Overrides javafx.scene.control.SingleSelectionModel.select.

Doc from javafx.scene.control.SingleSelectionModel.select.

Selects the index for the first instance of given object in the underlying data model. Since the SingleSelectionModel can only support having a single index selected at a time, this also causes any previously selected index to be unselected.

Overridden to clear selectedIndex if selectedItem is not contained in the items.

Annotations
@Override
selectNextback to summary
public void selectNext()

Overrides javafx.scene.control.SingleSelectionModel.selectNext.

Doc from javafx.scene.control.SingleSelectionModel.selectNext.

Selects the next index. Since the SingleSelectionModel can only support having a single index selected at a time, this also causes any previously selected index to be unselected.

Annotations
@Override
selectPreviousback to summary
public void selectPrevious()

Overrides javafx.scene.control.SingleSelectionModel.selectPrevious.

Doc from javafx.scene.control.SingleSelectionModel.selectPrevious.

Selects the previous index. Since the SingleSelectionModel can only support having a single index selected at a time, this also causes any previously selected index to be unselected.

Annotations
@Override