public class ComboBox<T> extends ComboBoxBase<T>
ComboBoxBase abstract class for the most common
form of ComboBox, where a popup list is shown to users providing them with
a choice that they may select from. For more information around the general
concepts and API of ComboBox, refer to the ComboBoxBase class
documentation.
On top of ComboBoxBase, the ComboBox class introduces additional API. Most
importantly, it adds an items property that works in
much the same way as the ListView items
property. In other words, it is the content of the items list that is displayed
to users when they click on the ComboBox button.
The ComboBox exposes the ComboBoxBase.valueProperty() from
ComboBoxBase, but there are some important points
of the value property that need to be understood in relation to ComboBox.
These include:
selection in the selection model does not null the value
property - it remains the same as before.SelectionModel.selectedItemProperty() and
value property will be updated to have this value. This is inconsistent with
other controls that use a selection model, but done intentionally for ComboBox.By default, when the popup list is showing, the maximum number of rows
visible is 10, but this can be changed by modifying the
visibleRowCount property. If the number of
items in the ComboBox is less than the value of visibleRowCount,
then the items size will be used instead so that the popup list is not
exceedingly long.
As with ListView, it is possible to modify the
selection model that is used,
although this is likely to be rarely changed. This is because the ComboBox
enforces the need for a SingleSelectionModel
instance, and it is not likely that there is much need for alternate
implementations. Nonetheless, the option is there should use cases be found
for switching the selection model.
As the ComboBox internally renders content with a ListView, API exists in
the ComboBox class to allow for a custom cell factory to be set. For more
information on cell factories, refer to the Cell and ListCell
classes. It is important to note that if a cell factory is set on a ComboBox,
cells will only be used in the ListView that shows when the ComboBox is
clicked. If you also want to customize the rendering of the 'button' area
of the ComboBox, you can set a custom ListCell instance in the
button cell property. One way of doing this
is with the following code (note the use of setButtonCell:
Callback<ListView<String>, ListCell<String>> cellFactory = ...;
ComboBox comboBox = new ComboBox();
comboBox.setItems(items);
comboBox.setButtonCell(cellFactory.call(null));
comboBox.setCellFactory(cellFactory);
Because a ComboBox can be editable, and the
default means of allowing user input is via a TextField, a
string converter property is provided to allow
for developers to specify how to translate a users string into an object of
type T, such that the value property may contain it.
By default the converter simply returns the String input as the user typed it,
which therefore assumes that the type of the editable ComboBox is String. If
a different type is specified and the ComboBox is to be editable, it is
necessary to specify a custom StringConverter.
Node instances. Putting nodes into
the items list is strongly not recommended. This is because
the default cell factory simply inserts Node
items directly into the cell, including in the ComboBox 'button' area too.
Because the scenegraph only allows for Nodes to be in one place at a time,
this means that when an item is selected it becomes removed from the ComboBox
list, and becomes visible in the button area. When selection changes the
previously selected item returns to the list and the new selection is removed.
The recommended approach, rather than inserting Node instances into the
items list, is to put the relevant information into the ComboBox, and then
provide a custom cell factory. For example,
rather than use the following code:
ComboBox<Rectangle> cmb = new ComboBox<Rectangle>();
cmb.getItems().addAll(
new Rectangle(10, 10, Color.RED),
new Rectangle(10, 10, Color.GREEN),
new Rectangle(10, 10, Color.BLUE));
You should do the following:
ComboBox<Color> cmb = new ComboBox<Color>();
cmb.getItems().addAll(
Color.RED,
Color.GREEN,
Color.BLUE);
cmb.setCellFactory(new Callback<ListView<Color>, ListCell<Color>>() {
@Override public ListCell<Color> call(ListView<Color> p) {
return new ListCell<Color>() {
private final Rectangle rectangle;
{
setContentDisplay(ContentDisplay.GRAPHIC_ONLY);
rectangle = new Rectangle(10, 10);
}
@Override protected void updateItem(Color item, boolean empty) {
super.updateItem(item, empty);
if (item == null || empty) {
setGraphic(null);
} else {
rectangle.setFill(item);
setGraphic(rectangle);
}
}
};
}
});Admittedly the above approach is far more verbose, but it offers the required functionality without encountering the scenegraph constraints.
ComboBoxBase,
Cell,
ListCell,
StringConverter| Type | Property and Description |
|---|---|
ObjectProperty<ListCell<T>> |
buttonCell
The button cell is used to render what is shown in the ComboBox 'button'
area.
|
ObjectProperty<Callback<ListView<T>,ListCell<T>>> |
cellFactory
Providing a custom cell factory allows for complete customization of the
rendering of items in the ComboBox.
|
ObjectProperty<StringConverter<T>> |
converter
|
ReadOnlyObjectProperty<TextField> |
editor
The editor for the ComboBox.
|
ObjectProperty<ObservableList<T>> |
items
The list of items to show within the ComboBox popup.
|
ObjectProperty<Node> |
placeholder
This Node is shown to the user when the ComboBox has no content to show.
|
ObjectProperty<SingleSelectionModel<T>> |
selectionModel
The selection model for the ComboBox.
|
IntegerProperty |
visibleRowCount
The maximum number of rows to be visible in the ComboBox popup when it is
showing.
|
armed, editable, onAction, onHidden, onHiding, onShowing, onShown, promptText, showing, valuecontextMenu, skin, tooltipbackground, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, widthneedsLayoutaccessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, nodeOrientation, 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, visibleON_HIDDEN, ON_HIDING, ON_SHOWING, ON_SHOWNUSE_COMPUTED_SIZE, USE_PREF_SIZEBASELINE_OFFSET_SAME_AS_HEIGHT| Constructor and Description |
|---|
ComboBox()
Creates a default ComboBox instance with an empty
items list and default
selection model. |
ComboBox(ObservableList<T> items)
Creates a default ComboBox instance with the provided items list and
a default
selection model. |
| Modifier and Type | Method and Description |
|---|---|
ObjectProperty<ListCell<T>> |
buttonCellProperty()
The button cell is used to render what is shown in the ComboBox 'button'
area.
|
ObjectProperty<Callback<ListView<T>,ListCell<T>>> |
cellFactoryProperty()
Providing a custom cell factory allows for complete customization of the
rendering of items in the ComboBox.
|
ObjectProperty<StringConverter<T>> |
converterProperty()
|
protected Skin<?> |
createDefaultSkin()
Create a new instance of the default skin for this control.
|
ReadOnlyObjectProperty<TextField> |
editorProperty()
The editor for the ComboBox.
|
ListCell<T> |
getButtonCell()
Gets the value of the property buttonCell.
|
Callback<ListView<T>,ListCell<T>> |
getCellFactory()
Gets the value of the property cellFactory.
|
StringConverter<T> |
getConverter()
Gets the value of the property converter.
|
TextField |
getEditor()
Gets the value of the property editor.
|
ObservableList<T> |
getItems()
Gets the value of the property items.
|
Node |
getPlaceholder()
Gets the value of the property placeholder.
|
SingleSelectionModel<T> |
getSelectionModel()
Gets the value of the property selectionModel.
|
int |
getVisibleRowCount()
Gets the value of the property visibleRowCount.
|
ObjectProperty<ObservableList<T>> |
itemsProperty()
The list of items to show within the ComboBox popup.
|
ObjectProperty<Node> |
placeholderProperty()
This Node is shown to the user when the ComboBox has no content to show.
|
Object |
queryAccessibleAttribute(AccessibleAttribute attribute,
Object... parameters)
*
Accessibility handling *
*
|
ObjectProperty<SingleSelectionModel<T>> |
selectionModelProperty()
The selection model for the ComboBox.
|
void |
setButtonCell(ListCell<T> value)
Sets the value of the property buttonCell.
|
void |
setCellFactory(Callback<ListView<T>,ListCell<T>> value)
Sets the value of the property cellFactory.
|
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 |
setPlaceholder(Node value)
Sets the value of the property placeholder.
|
void |
setSelectionModel(SingleSelectionModel<T> value)
Sets the value of the property selectionModel.
|
void |
setVisibleRowCount(int value)
Sets the value of the property visibleRowCount.
|
IntegerProperty |
visibleRowCountProperty()
The maximum number of rows to be visible in the ComboBox popup when it is
showing.
|
arm, armedProperty, disarm, editableProperty, executeAccessibleAction, getOnAction, getOnHidden, getOnHiding, getOnShowing, getOnShown, getPromptText, getValue, hide, isArmed, isEditable, isShowing, onActionProperty, onHiddenProperty, onHidingProperty, onShowingProperty, onShownProperty, promptTextProperty, setEditable, setOnAction, setOnHidden, setOnHiding, setOnShowing, setOnShown, setPromptText, setValue, show, showingProperty, valuePropertycomputeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, getBaselineOffset, getClassCssMetaData, getContextMenu, getControlCssMetaData, getCssMetaData, getSkin, getTooltip, isResizable, layoutChildren, setContextMenu, setSkin, setTooltip, skinProperty, tooltipPropertybackgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, getBackground, getBorder, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, getUserAgentStylesheet, getWidth, heightProperty, insetsProperty, isCacheShape, isCenterShape, isScaleShape, isSnapToPixel, layoutInArea, layoutInArea, layoutInArea, layoutInArea, maxHeight, maxHeightProperty, maxWidth, maxWidthProperty, minHeight, minHeightProperty, minWidth, minWidthProperty, opaqueInsetsProperty, paddingProperty, positionInArea, positionInArea, prefHeight, prefHeightProperty, prefWidth, prefWidthProperty, resize, scaleShapeProperty, setBackground, setBorder, setCacheShape, setCenterShape, setHeight, setMaxHeight, setMaxSize, setMaxWidth, setMinHeight, setMinSize, setMinWidth, setOpaqueInsets, setPadding, setPrefHeight, setPrefSize, setPrefWidth, setScaleShape, setShape, setSnapToPixel, setWidth, shapeProperty, snappedBottomInset, snappedLeftInset, snappedRightInset, snappedTopInset, snapPosition, snapSize, snapSpace, snapToPixelProperty, widthPropertygetChildren, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, lookup, needsLayoutProperty, requestLayout, requestParentLayout, setNeedsLayout, updateBoundsaccessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectiveNodeOrientationProperty, effectProperty, eventDispatcherProperty, fireEvent, focusedProperty, focusTraversableProperty, getAccessibleHelp, getAccessibleRole, getAccessibleRoleDescription, getAccessibleText, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClip, getContentBias, getCursor, getDepthTest, getEffect, getEffectiveNodeOrientation, getEventDispatcher, getId, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getNodeOrientation, 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, getPseudoClassStates, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleableParent, getStyleClass, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getTypeSelector, getUserData, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToSceneTransformProperty, localToScreen, localToScreen, localToScreen, localToScreen, localToScreen, lookupAll, managedProperty, mouseTransparentProperty, nodeOrientationProperty, notifyAccessibleAttributeChanged, 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, parentToLocal, parentToLocal, pickOnBoundsProperty, pressedProperty, pseudoClassStateChanged, relocate, removeEventFilter, removeEventHandler, requestFocus, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, screenToLocal, screenToLocal, screenToLocal, setAccessibleHelp, setAccessibleRole, setAccessibleRoleDescription, setAccessibleText, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setNodeOrientation, 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, usesMirroring, visiblePropertypublic ObjectProperty<ObservableList<T>> itemsProperty
getItems(),
setItems(ObservableList)public ObjectProperty<StringConverter<T>> converterProperty
editable) to an object of type T, such that
the input may be retrieved via the value property.getConverter(),
setConverter(StringConverter)public ObjectProperty<Callback<ListView<T>,ListCell<T>>> cellFactoryProperty
Cell javadoc
for more information on cell factories.getCellFactory(),
setCellFactory(Callback)public ObjectProperty<ListCell<T>> buttonCellProperty
cell factory API.getButtonCell(),
setButtonCell(ListCell)public final ObjectProperty<SingleSelectionModel<T>> selectionModelProperty
public final IntegerProperty visibleRowCountProperty
getVisibleRowCount(),
setVisibleRowCount(int)public final ReadOnlyObjectProperty<TextField> editorProperty
editable.getEditor()public final ObjectProperty<Node> placeholderProperty
getPlaceholder(),
setPlaceholder(Node)public ComboBox()
items list and default
selection model.public ComboBox(ObservableList<T> items)
selection model.public final void setItems(ObservableList<T> value)
public final ObservableList<T> getItems()
public ObjectProperty<ObservableList<T>> itemsProperty()
getItems(),
setItems(ObservableList)public ObjectProperty<StringConverter<T>> converterProperty()
editable) to an object of type T, such that
the input may be retrieved via the value property.getConverter(),
setConverter(StringConverter)public final void setConverter(StringConverter<T> value)
public final StringConverter<T> getConverter()
public final void setCellFactory(Callback<ListView<T>,ListCell<T>> value)
Cell javadoc
for more information on cell factories.public final Callback<ListView<T>,ListCell<T>> getCellFactory()
Cell javadoc
for more information on cell factories.public ObjectProperty<Callback<ListView<T>,ListCell<T>>> cellFactoryProperty()
Cell javadoc
for more information on cell factories.getCellFactory(),
setCellFactory(Callback)public ObjectProperty<ListCell<T>> buttonCellProperty()
cell factory API.getButtonCell(),
setButtonCell(ListCell)public final void setButtonCell(ListCell<T> value)
cell factory API.public final ListCell<T> getButtonCell()
cell factory API.public final void setSelectionModel(SingleSelectionModel<T> value)
public final SingleSelectionModel<T> getSelectionModel()
public final ObjectProperty<SingleSelectionModel<T>> selectionModelProperty()
public final void setVisibleRowCount(int value)
public final int getVisibleRowCount()
public final IntegerProperty visibleRowCountProperty()
getVisibleRowCount(),
setVisibleRowCount(int)public final TextField getEditor()
editable.public final ReadOnlyObjectProperty<TextField> editorProperty()
editable.getEditor()public final ObjectProperty<Node> placeholderProperty()
getPlaceholder(),
setPlaceholder(Node)public final void setPlaceholder(Node value)
public final Node getPlaceholder()
protected Skin<?> createDefaultSkin()
-fx-skin or set explicitly in a sub-class with setSkin(...).createDefaultSkin in class Controlpublic Object queryAccessibleAttribute(AccessibleAttribute attribute, Object... parameters)
queryAccessibleAttribute in class ComboBoxBase<T>attribute - the requested attributeparameters - optional list of parametersAccessibleAttributeCopyright (c) 2008, 2015, Oracle and/or its affiliates. All rights reserved.