Module javafx.controls
Package javafx.scene.control

Class ChoiceBox<T>

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
javafx.scene.control.ChoiceBox<T>
All Implemented Interfaces:
Styleable, EventTarget, Skinnable
@DefaultProperty("items") public class ChoiceBox<T> extends Control
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

  • Property Details

  • Field Details

    • ON_SHOWING

      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_SHOWN

      public static final EventType<Event> ON_SHOWN
      Called after the ChoiceBox has shown its popup.
      Since:
      JavaFX 8u60

    • ON_HIDING

      public static final EventType<Event> ON_HIDING
      Called when the ChoiceBox popup will be hidden.
      Since:
      JavaFX 8u60

    • ON_HIDDEN

      public static final EventType<Event> ON_HIDDEN
      Called when the ChoiceBox popup has been hidden.
      Since:
      JavaFX 8u60

  • Constructor Details

    • ChoiceBox

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

    • ChoiceBox

      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 - the set of items

  • Method Details

    • setSelectionModel

      public final void setSelectionModel(SingleSelectionModel<T> value)
      Sets the value of the selectionModel property.
      Property description:
      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.
      Parameters:
      value - the value for the selectionModel property
      See Also:

    • getSelectionModel

      public final SingleSelectionModel<T> getSelectionModel()
      Gets the value of the selectionModel property.
      Property description:
      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.
      Returns:
      the value of the selectionModel property
      See Also:

    • selectionModelProperty

      public final ObjectProperty<SingleSelectionModel<T>> selectionModelProperty()
      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.
      Returns:
      the selectionModel property
      See Also:

    • isShowing

      public final boolean isShowing()
      Gets the value of the showing property.
      Property description:
      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.
      Returns:
      the value of the showing property
      See Also:

    • showingProperty

      public final ReadOnlyBooleanProperty showingProperty()
      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.
      Returns:
      the showing property
      See Also:

    • setItems

      public final void setItems(ObservableList<T> value)
      Sets the value of the items property.
      Property description:
      The items to display in the choice box. The selected item (as indicated in the selection model) must always be one of these items.
      Parameters:
      value - the value for the items property
      See Also:

    • getItems

      public final ObservableList<T> getItems()
      Gets the value of the items property.
      Property description:
      The items to display in the choice box. The selected item (as indicated in the selection model) must always be one of these items.
      Returns:
      the value of the items property
      See Also:

    • itemsProperty

      public final ObjectProperty<ObservableList<T>> itemsProperty()
      The items to display in the choice box. The selected item (as indicated in the selection model) must always be one of these items.
      Returns:
      the items property
      See Also:

    • converterProperty

      public 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:
      the string converter property
      Since:
      JavaFX 2.1
      See Also:

    • setConverter

      public final void setConverter(StringConverter<T> value)
      Sets the value of the converter property.
      Property description:
      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.
      Parameters:
      value - the value for the converter property
      Since:
      JavaFX 2.1
      See Also:

    • getConverter

      public final StringConverter<T> getConverter()
      Gets the value of the converter property.
      Property description:
      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:
      the value of the converter property
      Since:
      JavaFX 2.1
      See Also:

    • valueProperty

      public 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:
      the value property
      Since:
      JavaFX 2.1
      See Also:

    • setValue

      public final void setValue(T value)
      Sets the value of the value property.
      Property description:
      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.
      Parameters:
      value - the value for the value property
      Since:
      JavaFX 2.1
      See Also:

    • getValue

      public final T getValue()
      Gets the value of the value property.
      Property description:
      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:
      the value of the value property
      Since:
      JavaFX 2.1
      See Also:

    • onActionProperty

      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:
      the on action property
      Since:
      JavaFX 8u60
      See Also:

    • setOnAction

      public final void setOnAction(EventHandler<ActionEvent> value)
      Sets the value of the onAction property.
      Property description:
      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.
      Parameters:
      value - the value for the onAction property
      Since:
      JavaFX 8u60
      See Also:

    • getOnAction

      public final EventHandler<ActionEvent> getOnAction()
      Gets the value of the onAction property.
      Property description:
      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:
      the value of the onAction property
      Since:
      JavaFX 8u60
      See Also:

    • onShowingProperty

      public final ObjectProperty<EventHandler<Event>> onShowingProperty()
      Called just prior to the ChoiceBox popup being shown.
      Returns:
      the on showing property
      Since:
      JavaFX 8u60
      See Also:

    • setOnShowing

      public final void setOnShowing(EventHandler<Event> value)
      Sets the value of the onShowing property.
      Property description:
      Called just prior to the ChoiceBox popup being shown.
      Parameters:
      value - the value for the onShowing property
      Since:
      JavaFX 8u60
      See Also:

    • getOnShowing

      public final EventHandler<Event> getOnShowing()
      Gets the value of the onShowing property.
      Property description:
      Called just prior to the ChoiceBox popup being shown.
      Returns:
      the value of the onShowing property
      Since:
      JavaFX 8u60
      See Also:

    • onShownProperty

      public final ObjectProperty<EventHandler<Event>> onShownProperty()
      Called just after the ChoiceBox popup is shown.
      Returns:
      the on shown property
      Since:
      JavaFX 8u60
      See Also:

    • setOnShown

      public final void setOnShown(EventHandler<Event> value)
      Sets the value of the onShown property.
      Property description:
      Called just after the ChoiceBox popup is shown.
      Parameters:
      value - the value for the onShown property
      Since:
      JavaFX 8u60
      See Also:

    • getOnShown

      public final EventHandler<Event> getOnShown()
      Gets the value of the onShown property.
      Property description:
      Called just after the ChoiceBox popup is shown.
      Returns:
      the value of the onShown property
      Since:
      JavaFX 8u60
      See Also:

    • onHidingProperty

      public final ObjectProperty<EventHandler<Event>> onHidingProperty()
      Called just prior to the ChoiceBox popup being hidden.
      Returns:
      the on hiding property
      Since:
      JavaFX 8u60
      See Also:

    • setOnHiding

      public final void setOnHiding(EventHandler<Event> value)
      Sets the value of the onHiding property.
      Property description:
      Called just prior to the ChoiceBox popup being hidden.
      Parameters:
      value - the value for the onHiding property
      Since:
      JavaFX 8u60
      See Also:

    • getOnHiding

      public final EventHandler<Event> getOnHiding()
      Gets the value of the onHiding property.
      Property description:
      Called just prior to the ChoiceBox popup being hidden.
      Returns:
      the value of the onHiding property
      Since:
      JavaFX 8u60
      See Also:

    • onHiddenProperty

      public final ObjectProperty<EventHandler<Event>> onHiddenProperty()
      Called just after the ChoiceBox popup has been hidden.
      Returns:
      the on hidden property
      Since:
      JavaFX 8u60
      See Also:

    • setOnHidden

      public final void setOnHidden(EventHandler<Event> value)
      Sets the value of the onHidden property.
      Property description:
      Called just after the ChoiceBox popup has been hidden.
      Parameters:
      value - the value for the onHidden property
      Since:
      JavaFX 8u60
      See Also:

    • getOnHidden

      public final EventHandler<Event> getOnHidden()
      Gets the value of the onHidden property.
      Property description:
      Called just after the ChoiceBox popup has been hidden.
      Returns:
      the value of the onHidden property
      Since:
      JavaFX 8u60
      See Also:

    • show

      public void show()
      Opens the list of choices.

    • hide

      public void hide()
      Closes the list of choices.