javafx.scene.control

Class ChoiceBox<T>

java.lang.Object

javafx.scene.Node

javafx.scene.Parent

javafx.scene.control.Control

javafx.scene.control.ChoiceBox<T>

All Implemented Interfaces:

EventTarget, Skinnable

@DefaultProperty(value="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.

The ChoiceBox can be configured either to support null as a valid choice, or to prohibit it. In the case that it is prohibited, there will always be some item that is selected, as long as there is at least one item defined. By default, no item is selected unless otherwise specified. In the case that null is acceptable, a default entry may be inserted into the list of choices at the top, with a name similar to "None" and localized for different Locales.

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.

It means 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.

 import javafx.scene.control.ChoiceBox;

 ChoiceBox cb = new ChoiceBox();
 cb.getItems().addAll("item1", "item2", "item3");
 

Property Summary

Properties

Type	Property and Description
ObjectProperty<StringConverter<T>>	converter Allows a way to specify how to represent objects in the items list.
ObjectProperty<ObservableList<T>>	items The items to display in the choice box.
ObjectProperty<SingleSelectionModel<T>>	selectionModel The selection model for the ChoiceBox.
ReadOnlyBooleanProperty	showing Indicates whether the drop down is displaying the list of choices to the user.
ObjectProperty<T>	value The value of this ChoiceBox is defined as the selected item in the ChoiceBox selection model.

Properties inherited from class javafx.scene.control.Control

contextMenu, height, maxHeight, maxWidth, minHeight, minWidth, prefHeight, prefWidth, skinClassName, skin, tooltip, width

Properties inherited from class javafx.scene.Parent

needsLayout

Properties inherited from class javafx.scene.Node

blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effect, eventDispatcher, focused, focusTraversable, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, onContextMenuRequested, onDragDetected, onDragDone, onDragDropped, onDragEntered, onDragExited, onDragOver, onInputMethodTextChanged, onKeyPressed, onKeyReleased, onKeyTyped, onMouseClicked, onMouseDragEntered, onMouseDragExited, onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, onMouseReleased, onRotate, onRotationFinished, onRotationStarted, onScrollFinished, onScroll, onScrollStarted, onSwipeDown, onSwipeLeft, onSwipeRight, onSwipeUp, onTouchMoved, onTouchPressed, onTouchReleased, onTouchStationary, onZoomFinished, onZoom, onZoomStarted, opacity, parent, pickOnBounds, pressed, rotate, rotationAxis, scaleX, scaleY, scaleZ, scene, style, translateX, translateY, translateZ, visible

Field Summary

Fields inherited from class javafx.scene.control.Control

USE_COMPUTED_SIZE, USE_PREF_SIZE

Constructor Summary

Constructors

Constructor and Description
ChoiceBox() Create a new ChoiceBox which has an empty list of items.
ChoiceBox(ObservableList<T> items) Create a new ChoiceBox with the given set of items.

Method Summary

Methods

Modifier and Type	Method and Description
ObjectProperty<StringConverter<T>>	converterProperty() Allows a way to specify how to represent objects in the items list.
StringConverter<T>	getConverter() Gets the value of the property converter.
ObservableList<T>	getItems() Gets the value of the property items.
SingleSelectionModel<T>	getSelectionModel() Gets the value of the property selectionModel.
T	getValue() Gets the value of the property value.
void	hide() Closes the list of choices.
boolean	isShowing() Gets the value of the property showing.
ObjectProperty<ObservableList<T>>	itemsProperty() The items to display in the choice box.
ObjectProperty<SingleSelectionModel<T>>	selectionModelProperty() The selection model for the ChoiceBox.
void	setConverter(StringConverter<T> value) Sets the value of the property converter.
void	setItems(ObservableList<T> value) Sets the value of the property items.
void	setSelectionModel(SingleSelectionModel<T> value) Sets the value of the property selectionModel.
void	setValue(T value) Sets the value of the property value.
void	show() Opens the list of choices.
ReadOnlyBooleanProperty	showingProperty() Indicates whether the drop down is displaying the list of choices to the user.
ObjectProperty<T>	valueProperty() The value of this ChoiceBox is defined as the selected item in the ChoiceBox selection model.

Methods inherited from class javafx.scene.control.Control

computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, getBaselineOffset, getContextMenu, getHeight, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getPrefHeight, getPrefWidth, getSkin, getTooltip, getUserAgentStylesheet, getWidth, heightProperty, intersects, isResizable, layoutChildren, maxHeight, maxHeightProperty, maxWidth, maxWidthProperty, minHeight, minHeightProperty, minWidth, minWidthProperty, prefHeight, prefHeightProperty, prefWidth, prefWidthProperty, resize, setContextMenu, setHeight, setMaxHeight, setMaxSize, setMaxWidth, setMinHeight, setMinSize, setMinWidth, setPrefHeight, setPrefSize, setPrefWidth, setSkin, setSkinClassName, setTooltip, setWidth, skinClassNameProperty, skinProperty, tooltipProperty, widthProperty

Methods inherited from class javafx.scene.Parent

getChildren, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, lookup, needsLayoutProperty, requestLayout, setNeedsLayout

Methods inherited from class javafx.scene.Node

addEventFilter, addEventHandler, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectProperty, eventDispatcherProperty, fireEvent, focusedProperty, focusTraversableProperty, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClip, getContentBias, getCursor, getDepthTest, getEffect, getEventDispatcher, getId, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getOnContextMenuRequested, getOnDragDetected, getOnDragDone, getOnDragDropped, getOnDragEntered, getOnDragExited, getOnDragOver, getOnInputMethodTextChanged, getOnKeyPressed, getOnKeyReleased, getOnKeyTyped, getOnMouseClicked, getOnMouseDragEntered, getOnMouseDragExited, getOnMouseDragged, getOnMouseDragOver, getOnMouseDragReleased, getOnMouseEntered, getOnMouseExited, getOnMouseMoved, getOnMousePressed, getOnMouseReleased, getOnRotate, getOnRotationFinished, getOnRotationStarted, getOnScroll, getOnScrollFinished, getOnScrollStarted, getOnSwipeDown, getOnSwipeLeft, getOnSwipeRight, getOnSwipeUp, getOnTouchMoved, getOnTouchPressed, getOnTouchReleased, getOnTouchStationary, getOnZoom, getOnZoomFinished, getOnZoomStarted, getOpacity, getParent, getProperties, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleClass, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getUserData, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToSceneTransformProperty, lookupAll, managedProperty, mouseTransparentProperty, onContextMenuRequestedProperty, onDragDetectedProperty, onDragDoneProperty, onDragDroppedProperty, onDragEnteredProperty, onDragExitedProperty, onDragOverProperty, onInputMethodTextChangedProperty, onKeyPressedProperty, onKeyReleasedProperty, onKeyTypedProperty, onMouseClickedProperty, onMouseDragEnteredProperty, onMouseDragExitedProperty, onMouseDraggedProperty, onMouseDragOverProperty, onMouseDragReleasedProperty, onMouseEnteredProperty, onMouseExitedProperty, onMouseMovedProperty, onMousePressedProperty, onMouseReleasedProperty, onRotateProperty, onRotationFinishedProperty, onRotationStartedProperty, onScrollFinishedProperty, onScrollProperty, onScrollStartedProperty, onSwipeDownProperty, onSwipeLeftProperty, onSwipeRightProperty, onSwipeUpProperty, onTouchMovedProperty, onTouchPressedProperty, onTouchReleasedProperty, onTouchStationaryProperty, onZoomFinishedProperty, onZoomProperty, onZoomStartedProperty, opacityProperty, parentProperty, parentToLocal, parentToLocal, parentToLocal, pickOnBoundsProperty, pressedProperty, relocate, removeEventFilter, removeEventHandler, requestFocus, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setOnContextMenuRequested, setOnDragDetected, setOnDragDone, setOnDragDropped, setOnDragEntered, setOnDragExited, setOnDragOver, setOnInputMethodTextChanged, setOnKeyPressed, setOnKeyReleased, setOnKeyTyped, setOnMouseClicked, setOnMouseDragEntered, setOnMouseDragExited, setOnMouseDragged, setOnMouseDragOver, setOnMouseDragReleased, setOnMouseEntered, setOnMouseExited, setOnMouseMoved, setOnMousePressed, setOnMouseReleased, setOnRotate, setOnRotationFinished, setOnRotationStarted, setOnScroll, setOnScrollFinished, setOnScrollStarted, setOnSwipeDown, setOnSwipeLeft, setOnSwipeRight, setOnSwipeUp, setOnTouchMoved, setOnTouchPressed, setOnTouchReleased, setOnTouchStationary, setOnZoom, setOnZoomFinished, setOnZoomStarted, setOpacity, setPickOnBounds, setPressed, setRotate, setRotationAxis, setScaleX, setScaleY, setScaleZ, setStyle, setTranslateX, setTranslateY, setTranslateZ, setUserData, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, visibleProperty

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Property Detail

selectionModel

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.

See Also:

getSelectionModel(), setSelectionModel(SingleSelectionModel)

showing

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.

See Also:

isShowing()

items

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.

See Also:

getItems(), setItems(ObservableList)

converter

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.

See Also:

getConverter(), setConverter(StringConverter)

value

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.

See Also:

getValue(), setValue(T)

Constructor Detail

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 -

Method Detail

setSelectionModel

public final void setSelectionModel(SingleSelectionModel<T> value)

Sets the value of the property selectionModel.

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.

getSelectionModel

public final SingleSelectionModel<T> getSelectionModel()

Gets the value of the property selectionModel.

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.

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.

See Also:

getSelectionModel(), setSelectionModel(SingleSelectionModel)

isShowing

public final boolean isShowing()

Gets the value of the property showing.

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.

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.

See Also:

isShowing()

setItems

public final void setItems(ObservableList<T> value)

Sets the value of the property items.

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.

getItems

public final ObservableList<T> getItems()

Gets the value of the property items.

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.

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.

See Also:

getItems(), setItems(ObservableList)

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.

See Also:

getConverter(), setConverter(StringConverter)

setConverter

public final void setConverter(StringConverter<T> value)

Sets the value of the property converter.

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.

getConverter

public final StringConverter<T> getConverter()

Gets the value of the property converter.

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.

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.

See Also:

getValue(), setValue(T)

setValue

public final void setValue(T value)

Sets the value of the property value.

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.

getValue

public final T getValue()

Gets the value of the property value.

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.

show

public void show()

Opens the list of choices.

hide

public void hide()

Closes the list of choices.