JavaFX 27 · javafx.scene.control.ComboBoxBase · APIdia, the JavaDoc alternative

Abstract base class for ComboBox-like controls. A ComboBox typically has a button that, when clicked, will pop up some means of allowing a user to select one or more values (depending on the implementation). This base class makes no assumptions about what happens when the show() and hide() methods are called, however commonly this results in either a popup or dialog appearing that allows for the user to provide the required information.

A ComboBox has a value property that represents the current user input. This may be based on a selection from a drop-down list, or it may be from user input when the ComboBox is editable.

An editable ComboBox is one which provides some means for an end-user to provide input for values that are not otherwise options available to them. For example, in the ComboBox implementation, an editable ComboBox provides a TextField that may be typed into. As mentioned above, when the user commits textual input into the textfield (commonly by pressing the Enter keyboard key), the value property will be updated.

The purpose of the separation between this class and, say, ComboBox is to allow for ComboBox-like controls that do not necessarily pop up a list of items. Examples of other implementations include color pickers, calendar pickers, etc. The ComboBox class provides the default, and most commonly expected implementation. Refer to that classes javadoc for more information.

Field Summary

Modifier and Type	Field and Description
private final BooleanProperty	armed
private static final String	DEFAULT_STYLE_CLASS
private final BooleanProperty	editable
public static final EventType<Event>	ON_HIDDEN Called when the ComboBox popup/display has been hidden.
public static final EventType<Event>	ON_HIDING Called when the ComboBox popup/display will be hidden.
public static final EventType<Event>	ON_SHOWING Called prior to the ComboBox showing its popup/display after the user has clicked or otherwise interacted with the ComboBox.
public static final EventType<Event>	ON_SHOWN Called after the ComboBox has shown its popup/display.
private ObjectProperty<EventHandler<ActionEvent>>	onAction
private ObjectProperty<EventHandler<Event>>	onHidden Called just after the `ComboBoxBase` popup/display has been hidden.
private ObjectProperty<EventHandler<Event>>	onHiding Called just prior to the `ComboBox` popup/display being hidden.
private ObjectProperty<EventHandler<Event>>	onShowing Called just prior to the `ComboBoxBase` popup/display being shown.
private ObjectProperty<EventHandler<Event>>	onShown Called just after the `ComboBoxBase` popup/display is shown.
private StringProperty	promptText The `ComboBox` prompt text to display, or `null` if no prompt text is displayed.
private static final PseudoClass	PSEUDO_CLASS_ARMED
private static final PseudoClass	PSEUDO_CLASS_EDITABLE
private static final PseudoClass	PSEUDO_CLASS_SHOWING
private ReadOnlyBooleanWrapper	showing Represents the current state of the ComboBox popup, and whether it is currently visible on screen (although it may be hidden behind other windows).
private final ObjectProperty<T>	value

Constructor Summary

Access	Constructor and Description
public	ComboBoxBase() Creates a default ComboBoxBase instance.

Method Summary

Modifier and Type	Method and Description
public void	arm() Arms the ComboBox.
public final BooleanProperty	Returns: the armed property armedProperty() Indicates that the ComboBox has been "armed" such that a mouse release will cause the ComboBox `show()` method to be invoked.
public void	disarm() Disarms the ComboBox.
public final BooleanProperty	Returns: the editable property editableProperty() Specifies whether the ComboBox allows for user input.
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 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 String	getPromptText()
public final T	getValue()
public void	hide() Closes the popup / dialog that was shown when `show()` was called.
public final boolean	isArmed()
public final boolean	isEditable()
public final boolean	isShowing()
public final ObjectProperty<EventHandler<ActionEvent>>	Returns: the on action property onActionProperty() The ComboBox action, which is invoked whenever the ComboBox `value` property is changed.
public final ObjectProperty<EventHandler<Event>>	onHiddenProperty()
public final ObjectProperty<EventHandler<Event>>	onHidingProperty()
public final ObjectProperty<EventHandler<Event>>	onShowingProperty()
public final ObjectProperty<EventHandler<Event>>	onShownProperty()
public final StringProperty	promptTextProperty()
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.
private final void	setArmed(boolean value)
public final void	setEditable(boolean 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	setPromptText(String value)
private void	setShowing(boolean value)
public final void	setValue(T value)
public void	show() Requests that the ComboBox display the popup associated with this control.
public final ReadOnlyBooleanProperty	showingProperty()
private ReadOnlyBooleanWrapper	showingPropertyImpl()
public final ObjectProperty<T>	Returns: the value property valueProperty() The value of this ComboBox is defined as the selected item if the input is not editable, or if it is editable, the most recent user action: either the value input by the user, or the last selected item.

Field Detail

armed	back to summary
private final BooleanProperty armed

DEFAULT_STYLE_CLASS	back to summary
private static final String DEFAULT_STYLE_CLASS

editable	back to summary
private final BooleanProperty editable

ON_HIDDEN	back to summary
public static final EventType<Event> ON_HIDDEN Called when the ComboBox popup/display has been hidden. Since JavaFX 2.2

ON_HIDDEN

back to summary

public static final EventType<Event> ON_HIDDEN

Called when the ComboBox popup/display has been hidden.

Since: JavaFX 2.2

ON_HIDING	back to summary
public static final EventType<Event> ON_HIDING Called when the ComboBox popup/display will be hidden. Since JavaFX 2.2

ON_HIDING

back to summary

public static final EventType<Event> ON_HIDING

Called when the ComboBox popup/display will be hidden.

Since: JavaFX 2.2

ON_SHOWING	back to summary
public static final EventType<Event> ON_SHOWING Called prior to the ComboBox showing its popup/display after the user has clicked or otherwise interacted with the ComboBox. Since JavaFX 2.2

ON_SHOWING

back to summary

public static final EventType<Event> ON_SHOWING

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

Since: JavaFX 2.2

ON_SHOWN	back to summary
public static final EventType<Event> ON_SHOWN Called after the ComboBox has shown its popup/display. Since JavaFX 2.2

ON_SHOWN

back to summary

public static final EventType<Event> ON_SHOWN

Called after the ComboBox has shown its popup/display.

Since: JavaFX 2.2

onAction	back to summary
private ObjectProperty<EventHandler<ActionEvent>> onAction

onHidden back to summary

onHidden	back to summary
private ObjectProperty<EventHandler<Event>> onHidden Called just after the `ComboBoxBase` popup/display has been hidden. Since JavaFX 2.2

private ObjectProperty<EventHandler<Event>> onHidden

Called just after the ComboBoxBase popup/display has been hidden.

Since: JavaFX 2.2

onHiding back to summary

onHiding	back to summary
private ObjectProperty<EventHandler<Event>> onHiding Called just prior to the `ComboBox` popup/display being hidden. Since JavaFX 2.2

private ObjectProperty<EventHandler<Event>> onHiding

Called just prior to the ComboBox popup/display being hidden.

Since: JavaFX 2.2

onShowing back to summary

onShowing	back to summary
private ObjectProperty<EventHandler<Event>> onShowing Called just prior to the `ComboBoxBase` popup/display being shown. Since JavaFX 2.2

private ObjectProperty<EventHandler<Event>> onShowing

Called just prior to the ComboBoxBase popup/display being shown.

Since: JavaFX 2.2

onShown back to summary

onShown	back to summary
private ObjectProperty<EventHandler<Event>> onShown Called just after the `ComboBoxBase` popup/display is shown. Since JavaFX 2.2

private ObjectProperty<EventHandler<Event>> onShown

Called just after the ComboBoxBase popup/display is shown.

Since: JavaFX 2.2

promptText back to summary

promptText	back to summary
private StringProperty promptText The `ComboBox` prompt text to display, or `null` if no prompt text is displayed. Prompt text is not displayed in all circumstances, it is dependent upon the subclasses of ComboBoxBase to clarify when promptText will be shown. For example, in most cases prompt text will never be shown when a combo box is non-editable (that is, prompt text is only shown when user input is allowed via text input).

private StringProperty promptText

The ComboBox prompt text to display, or null if no prompt text is displayed. Prompt text is not displayed in all circumstances, it is dependent upon the subclasses of ComboBoxBase to clarify when promptText will be shown. For example, in most cases prompt text will never be shown when a combo box is non-editable (that is, prompt text is only shown when user input is allowed via text input).

PSEUDO_CLASS_ARMED	back to summary
private static final PseudoClass PSEUDO_CLASS_ARMED

PSEUDO_CLASS_EDITABLE	back to summary
private static final PseudoClass PSEUDO_CLASS_EDITABLE

PSEUDO_CLASS_SHOWING	back to summary
private static final PseudoClass PSEUDO_CLASS_SHOWING

showing	back to summary
private ReadOnlyBooleanWrapper showing Represents the current state of the ComboBox popup, and whether it is currently visible on screen (although it may be hidden behind other windows).

value	back to summary
private final ObjectProperty<T> value

Constructor Detail

ComboBoxBase	back to summary
public ComboBoxBase() Creates a default ComboBoxBase instance.

Method Detail

arm	back to summary
public void arm() Arms the ComboBox. An armed ComboBox will show a popup list on the next expected UI gesture. Note This function is intended to be used by experts, primarily by those implementing new Skins or Behaviors. It is not common for developers or designers to access this function directly.

armedProperty back to summary

armedProperty	back to summary
public final BooleanProperty armedProperty() Indicates that the ComboBox has been "armed" such that a mouse release will cause the ComboBox `show()` method to be invoked. This is subtly different from pressed. Pressed indicates that the mouse has been pressed on a Node and has not yet been released. `arm` however also takes into account whether the mouse is actually over the ComboBox and pressed. Returns:BooleanProperty the armed property

public final BooleanProperty armedProperty()

Indicates that the ComboBox has been "armed" such that a mouse release will cause the ComboBox show() method to be invoked. This is subtly different from pressed. Pressed indicates that the mouse has been pressed on a Node and has not yet been released. arm however also takes into account whether the mouse is actually over the ComboBox and pressed.

Returns:BooleanProperty: the armed property

disarm	back to summary
public void disarm() Disarms the ComboBox. See `arm()`. Note This function is intended to be used by experts, primarily by those implementing new Skins or Behaviors. It is not common for developers or designers to access this function directly.

editableProperty back to summary

editableProperty	back to summary
public final BooleanProperty editableProperty() Specifies whether the ComboBox allows for user input. When editable is true, the ComboBox has a text input area that a user may type in to. This input is then available via the `value` property. Note that when the editable property changes, the value property is reset, along with any other relevant state. Returns:BooleanProperty the editable property

public final BooleanProperty editableProperty()

Specifies whether the ComboBox allows for user input. When editable is true, the ComboBox has a text input area that a user may type in to. This input is then available via the value property.

Note that when the editable property changes, the value property is reset, along with any other relevant state.

Returns:BooleanProperty: the editable property

executeAccessibleAction	back 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

executeAccessibleAction

back 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

getOnAction	back to summary
public final EventHandler<ActionEvent> getOnAction()

getOnHidden	back to summary
public final EventHandler<Event> getOnHidden()

getOnHiding	back to summary
public final EventHandler<Event> getOnHiding()

getOnShowing	back to summary
public final EventHandler<Event> getOnShowing()

getOnShown	back to summary
public final EventHandler<Event> getOnShown()

getPromptText	back to summary
public final String getPromptText()

getValue	back to summary
public final T getValue()

hide back to summary

hide	back to summary
public void hide() Closes the popup / dialog that was shown when `show()` was called. Exceptions IllegalStateException: if this method is called on a thread other than the JavaFX Application Thread.

public void hide()

Closes the popup / dialog that was shown when show() was called.

Exceptions

IllegalStateException:: if this method is called on a thread other than the JavaFX Application Thread.

isArmed	back to summary
public final boolean isArmed()

isEditable	back to summary
public final boolean isEditable()

isShowing	back to summary
public final boolean isShowing()

onActionProperty back to summary

onActionProperty	back to summary
public final ObjectProperty<EventHandler<ActionEvent>> onActionProperty() The ComboBox action, which is invoked whenever the ComboBox `value` property is changed. This may be due to the value property being programmatically changed, when the user selects an item in a popup list or dialog, or, in the case of `editable` ComboBoxes, it may be when the user provides their own input (be that via a `TextField` or some other input mechanism. Returns:ObjectProperty<EventHandler<ActionEvent>> the on action property

public final ObjectProperty<EventHandler<ActionEvent>> onActionProperty()

The ComboBox action, which is invoked whenever the ComboBox value property is changed. This may be due to the value property being programmatically changed, when the user selects an item in a popup list or dialog, or, in the case of editable ComboBoxes, it may be when the user provides their own input (be that via a TextField or some other input mechanism.

Returns:ObjectProperty<EventHandler<ActionEvent>>: the on action property

onHiddenProperty	back to summary
public final ObjectProperty<EventHandler<Event>> onHiddenProperty()

onHidingProperty	back to summary
public final ObjectProperty<EventHandler<Event>> onHidingProperty()

onShowingProperty	back to summary
public final ObjectProperty<EventHandler<Event>> onShowingProperty()

onShownProperty	back to summary
public final ObjectProperty<EventHandler<Event>> onShownProperty()

promptTextProperty	back to summary
public final StringProperty promptTextProperty()

queryAccessibleAttribute	back 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

queryAccessibleAttribute

back 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

setArmed	back to summary
private final void setArmed(boolean value)

setEditable	back to summary
public final void setEditable(boolean value)

setOnAction	back to summary
public final void setOnAction(EventHandler<ActionEvent> value)

setOnHidden	back to summary
public final void setOnHidden(EventHandler<Event> value)

setOnHiding	back to summary
public final void setOnHiding(EventHandler<Event> value)

setOnShowing	back to summary
public final void setOnShowing(EventHandler<Event> value)

setOnShown	back to summary
public final void setOnShown(EventHandler<Event> value)

setPromptText	back to summary
public final void setPromptText(String value)

setShowing	back to summary
private void setShowing(boolean value)

setValue	back to summary
public final void setValue(T value)

show back to summary

public void show()

Requests that the ComboBox display the popup associated with this control. As mentioned in the ComboBoxBase class javadoc, what is actually shown when this method is called is undefined, but commonly it is some form of popup or dialog window.

Exceptions

IllegalStateException:: if this method is called on a thread other than the JavaFX Application Thread.

showingProperty	back to summary
public final ReadOnlyBooleanProperty showingProperty()

showingPropertyImpl	back to summary
private ReadOnlyBooleanWrapper showingPropertyImpl()

valueProperty

back to summary

public final ObjectProperty<T> valueProperty()

The value of this ComboBox is defined as the selected item if the input is not editable, or if it is editable, the most recent user action: either the value input by the user, or the last selected item.

Returns:ObjectProperty<T>: the value property

public abstract Class ComboBoxBase<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail