JavaFX 24 · javafx.scene.control.Dialog · APIdia, the JavaDoc alternative

A Dialog in JavaFX wraps a DialogPane and provides the necessary API to present it to end users. In JavaFX 8u40, this essentially means that the DialogPane is shown to users inside a Stage, but future releases may offer alternative options (such as 'lightweight' or 'internal' dialogs). This API therefore is intentionally ignorant of the underlying implementation, and attempts to present a common API for all possible implementations.

The Dialog class has a single generic type, R, which is used to represent the type of the result property (and also, how to convert from ButtonType to R, through the use of the result converter Callback).

Critical note: It is critical that all developers who choose to create their own dialogs by extending the Dialog class understand the importance of the result converter property. A result converter must always be set, whenever the R type is not Void or ButtonType. If this is not heeded, developers will find that they get ClassCastExceptions in their code, for failure to convert from ButtonType via the result converter.

It is likely that most developers would be better served using either the Alert class (for pre-defined, notification-style alerts), or either of the two pre-built dialogs (TextInputDialog and ChoiceDialog), depending on their needs.

Once a Dialog is instantiated, the next step is to configure it. Almost all properties on Dialog are not related to the content of the Dialog, the only exceptions are contentTextProperty(), headerTextProperty(), and graphicProperty(), and these properties are simply forwarding API onto the respective properties on the DialogPane stored in the dialog pane property. These three properties are forwarded from DialogPane for developer convenience. For developers wanting to configure their dialog, they will in many cases be required to use code along the lines of dialog.getDialogPane().setExpandableContent(node).

After configuring these properties, all that remains is to consider whether the buttons (created using ButtonType and the DialogPane#createButton(ButtonType) method) are fully configured. Developers will quickly find that the amount of configurability offered via the ButtonType class is minimal. This is intentional, but does not mean that developers can not modify the buttons created by the ButtonType that have been specified. To do this, developers simply call the DialogPane#lookupButton(ButtonType) method with the ButtonType (assuming it has already been set in the DialogPane#getButtonTypes() list. The returned Node is typically of type Button, but this depends on if the DialogPane#createButton(ButtonType) method has been overridden. A typical approach is therefore along the following lines:

 ButtonType loginButtonType = new ButtonType("Login", ButtonData.OK_DONE);
Dialog<String> dialog = new Dialog<>();
dialog.setTitle("Login Dialog");
dialog.setContentText("Would you like to log in?");
dialog.getDialogPane().getButtonTypes().add(loginButtonType);
boolean disabled = false; // computed based on content of text fields, for example
dialog.getDialogPane().lookupButton(loginButtonType).setDisable(disabled);
dialog.showAndWait();

Once a Dialog is instantiated and fully configured, the next step is to show it. More often than not, dialogs are shown in a modal and blocking fashion. 'Modal' means that the dialog prevents user interaction with the owning application whilst it is showing, and 'blocking' means that code execution stops at the point in which the dialog is shown. This means that you can show a dialog, await the user response, and then continue running the code that directly follows the show call, giving developers the ability to immediately deal with the user input from the dialog (if relevant).

JavaFX dialogs are modal by default (you can change this via the initModality(javafx.stage.Modality) API). To specify whether you want blocking or non-blocking dialogs, developers simply choose to call showAndWait() or show() (respectively). By default most developers should choose to use showAndWait(), given the ease of coding in these situations. Shown below is three code snippets, showing three equally valid ways of showing a dialog:

Option 1: The 'traditional' approach

 Optional<ButtonType> result = dialog.showAndWait();
if (result.isPresent() && result.get() == ButtonType.OK) {
    formatSystem();
}

Option 2: The traditional + Optional approach

 dialog.showAndWait().ifPresent(response -> {
    if (response == ButtonType.OK) {
        formatSystem();
    }
});

Option 3: The fully lambda approach

 dialog.showAndWait()
      .filter(response -> response == ButtonType.OK)
      .ifPresent(response -> formatSystem());

There is no better or worse option of the three listed above, so developers are encouraged to work to their own style preferences. The purpose of showing the above is to help introduce developers to the Optional API, which is new in Java 8 and may be foreign to many developers.

Dialog Validation / Intercepting Button Actions

In some circumstances it is desirable to prevent a dialog from closing until some aspect of the dialog becomes internally consistent (e.g. a form inside the dialog has all fields in a valid state). To do this, users of the dialogs API should become familiar with the DialogPane#lookupButton(ButtonType) method. By passing in a ButtonType (that has already been set in the button types list), users will be returned a Node that is typically of type Button (but this depends on if the DialogPane#createButton(ButtonType) method has been overridden). With this button, users may add an event filter that is called before the button does its usual event handling, and as such users may prevent the event handling by consuming the event. Here's a simplified example:

 final Button btOk = (Button) dlg.getDialogPane().lookupButton(ButtonType.OK);
btOk.addEventFilter(ActionEvent.ACTION, event -> {
    if (!validateAndStore()) {
        event.consume();
    }
});

Dialog Closing Rules

It is important to understand what happens when a Dialog is closed, and also how a Dialog can be closed, especially in abnormal closing situations (such as when the 'X' button is clicked in a dialogs title bar, or when operating system specific keyboard shortcuts (such as alt-F4 on Windows) are entered). Fortunately, the outcome is well-defined in these situations, and can be best summarised in the following bullet points:

JavaFX dialogs can only be closed 'abnormally' (as defined above) in two situations:
1. When the dialog only has one button, or
2. When the dialog has multiple buttons, as long as one of them meets one of the following requirements:
  1. The button has a ButtonType whose ButtonData is of type ButtonData#CANCEL_CLOSE.
  2. The button has a ButtonType whose ButtonData returns true when ButtonData#isCancelButton() is called.
In all other situations, the dialog will refuse to respond to all close requests, remaining open until the user clicks on one of the available buttons in the DialogPane area of the dialog.
If a dialog is closed abnormally, and if the dialog contains a button which meets one of the two criteria above, the dialog will attempt to set the result property to whatever value is returned from calling the result converter with the first matching ButtonType.
If for any reason the result converter returns null, or if the dialog is closed when only one non-cancel button is present, the result property will be null, and the showAndWait() method will return Optional#empty(). This later point means that, if you use either of option 2 or option 3 (as presented earlier in this class documentation), the Optional#ifPresent(java.util.function.Consumer) lambda will never be called, and code will continue executing as if the dialog had not returned any value at all.

Field Summary

Modifier and Type	Field and Description
pack-priv final FXDialog	dialog
private ObjectProperty<DialogPane>	dialogPane The root node of the dialog, the `DialogPane` contains all visual elements shown in the dialog.
private final EventHandlerManager	eventHandlerManager
private static final PseudoClass	HEADER_PSEUDO_CLASS
private boolean	isClosing
private static final PseudoClass	NO_HEADER_PSEUDO_CLASS
private ObjectProperty<EventHandler<DialogEvent>>	onCloseRequest Called when there is an external request to close this `Dialog`.
private ObjectProperty<EventHandler<DialogEvent>>	onHidden Called just after the Dialog has been hidden.
private ObjectProperty<EventHandler<DialogEvent>>	onHiding Called just prior to the Dialog being hidden.
private ObjectProperty<EventHandler<DialogEvent>>	onShowing Called just prior to the Dialog being shown.
private ObjectProperty<EventHandler<DialogEvent>>	onShown Called just after the Dialog is shown.
private final ObjectProperty<Callback<ButtonType, R>>	resultConverterProperty
private final ObjectProperty<R>	resultProperty

Constructor Summary

Access	Constructor and Description
public	Dialog() Creates a dialog without a specified owner.

Method Summary

Modifier and Type	Method and Description
public final <E extends Event> void	addEventFilter(EventType<E> the type of the events received by the filter eventType, EventHandler<? super E> the event filter eventFilter) Overrides default javafx.event.EventTarget.addEventFilter. Registers an event filter for this target.
public final <E extends Event> void	addEventHandler(EventType<E> the type of the events received by the handler eventType, EventHandler<? super E> the event handler eventHandler) Overrides default javafx.event.EventTarget.addEventHandler. Registers an event handler for this target.
public EventDispatchChain	buildEventDispatchChain(EventDispatchChain the initial chain to build from tail) Implements javafx.event.EventTarget.buildEventDispatchChain. Construct an event dispatch chain for this target.
public final void	close() Closes this `Dialog`.
public final StringProperty	Returns: the property representing the content text for the dialog pane contentTextProperty() A property representing the content text for the dialog pane.
public final ObjectProperty<DialogPane>	dialogPaneProperty()
public final String	Returns: the currently-set content text for this DialogPane getContentText() Returns the currently-set content text for this DialogPane.
public final DialogPane	getDialogPane()
public final Node	getGraphic()
public final String	Returns: the currently-set header text for this DialogPane getHeaderText() Returns the currently-set header text for this DialogPane.
public final double	Returns: the height of the dialog getHeight() Returns the height of the dialog.
public final Modality	Returns: the modality. getModality() Retrieves the modality attribute for this dialog.
public final EventHandler<DialogEvent>	getOnCloseRequest()
public final EventHandler<DialogEvent>	getOnHidden()
public final EventHandler<DialogEvent>	getOnHiding()
public final EventHandler<DialogEvent>	getOnShowing()
public final EventHandler<DialogEvent>	getOnShown()
public final Window	Returns: the owner Window. getOwner() Retrieves the owner Window for this dialog, or null for an unowned dialog.
public final R	getResult()
public final Callback<ButtonType, R>	getResultConverter()
public final String	Returns: the title of the dialog getTitle() Return the title of the dialog.
public final double	Returns: the width of the dialog getWidth() Returns the width of the dialog.
public final double	getX()
public final double	getY()
public final ObjectProperty<Node>	Returns: An ObjectProperty wrapping the current graphic. graphicProperty() The dialog graphic, presented either in the header, if one is showing, or to the left of the `content`.
public final StringProperty	Returns: a property representing the header text for the dialog pane headerTextProperty() A property representing the header text for the dialog pane.
public final ReadOnlyDoubleProperty	Returns: the property representing the height of the dialog heightProperty() Property representing the height of the dialog.
public final void	hide() Hides this `Dialog`.
public final void	initModality(Modality the modality for this dialog. modality) Specifies the modality for this dialog.
public final void	initOwner(Window the owner `Window` for this dialog. window) Specifies the owner `Window` for this dialog, or null for a top-level, unowned dialog.
public final void	initStyle(StageStyle the style for this dialog. style) Specifies the style for this dialog.
public final boolean	Returns: true if dialog is resizable. isResizable() Returns whether or not the dialog is resizable.
public final boolean	Returns: true if dialog is showing. isShowing() Returns whether or not the dialog is showing.
public final ObjectProperty<EventHandler<DialogEvent>>	onCloseRequestProperty()
public final ObjectProperty<EventHandler<DialogEvent>>	onHiddenProperty()
public final ObjectProperty<EventHandler<DialogEvent>>	onHidingProperty()
public final ObjectProperty<EventHandler<DialogEvent>>	onShowingProperty()
public final ObjectProperty<EventHandler<DialogEvent>>	onShownProperty()
public final <E extends Event> void	removeEventFilter(EventType<E> the event type from which to unregister eventType, EventHandler<? super E> the event filter eventFilter) Overrides default javafx.event.EventTarget.removeEventFilter. Unregisters a previously registered event filter from this target.
public final <E extends Event> void	removeEventHandler(EventType<E> the event type from which to unregister eventType, EventHandler<? super E> the event handler eventHandler) Overrides default javafx.event.EventTarget.removeEventHandler. Unregisters a previously registered event handler from this target.
public final BooleanProperty	Returns: the property representing whether the dialog is resizable resizableProperty() Represents whether the dialog is resizable.
public final ObjectProperty<Callback<ButtonType, R>>	Returns: the API to convert the `ButtonType` that the user clicked on resultConverterProperty() API to convert the `ButtonType` that the user clicked on into a result that can be returned via the `result` property.
public final ObjectProperty<R>	Returns: a property representing what has been returned from the dialog resultProperty() A property representing what has been returned from the dialog.
public final void	setContentText(String the string to show in the dialog content area contentText) Sets the string to show in the dialog content area.
public final void	setDialogPane(DialogPane value)
public final void	setGraphic(Node The new dialog graphic, or null if no graphic should be shown. graphic) Sets the dialog graphic, which will be displayed either in the header, if one is showing, or to the left of the `content`.
public final void	setHeaderText(String the string to show in the dialog header area headerText) Sets the string to show in the dialog header area.
public final void	setHeight(double the height of the dialog height) Sets the height of the dialog.
public final void	setOnCloseRequest(EventHandler<DialogEvent> value)
public final void	setOnHidden(EventHandler<DialogEvent> value)
public final void	setOnHiding(EventHandler<DialogEvent> value)
public final void	setOnShowing(EventHandler<DialogEvent> value)
public final void	setOnShown(EventHandler<DialogEvent> value)
public final void	setResizable(boolean true if dialog should be resizable. resizable) Sets whether the dialog can be resized by the user.
public final void	setResult(R value)
pack-priv void	setResultAndClose(ButtonType cmd, boolean close)
public final void	setResultConverter(Callback<ButtonType, R> value)
public final void	setTitle(String the Title of the dialog title) Change the Title of the dialog.
public final void	setWidth(double the width of the dialog width) Sets the width of the dialog.
public final void	setX(double x)
public final void	setY(double y)
public final void	show() Shows the dialog but does not wait for a user response (in other words, this brings up a non-blocking dialog).
public final Optional<R>	Returns: An `Optional` that contains the `result`. Refer to the `Dialog` class documentation for more detail. showAndWait() Shows the dialog and waits for the user response (in other words, brings up a blocking dialog, with the returned value the users input).
public final ReadOnlyBooleanProperty	Returns: the property representing whether the dialog is currently showing showingProperty() Represents whether the dialog is currently showing.
public final StringProperty	Returns: the titleProperty of the dialog titleProperty() Return the titleProperty of the dialog.
private void	updatePseudoClassState()
public final ReadOnlyDoubleProperty	Returns: the property representing the width of the dialog widthProperty() Property representing the width of the dialog.
public final ReadOnlyDoubleProperty	Returns: the horizontal location of this `Dialog` xProperty() The horizontal location of this `Dialog`.
public final ReadOnlyDoubleProperty	Returns: the vertical location of this `Dialog` yProperty() The vertical location of this `Dialog`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

dialog	back to summary
pack-priv final FXDialog dialog

dialogPane	back to summary
private ObjectProperty<DialogPane> dialogPane The root node of the dialog, the `DialogPane` contains all visual elements shown in the dialog. As such, it is possible to completely adjust the display of the dialog by modifying the existing dialog pane or creating a new one.

eventHandlerManager	back to summary
private final EventHandlerManager eventHandlerManager

HEADER_PSEUDO_CLASS	back to summary
private static final PseudoClass HEADER_PSEUDO_CLASS

isClosing	back to summary
private boolean isClosing

NO_HEADER_PSEUDO_CLASS	back to summary
private static final PseudoClass NO_HEADER_PSEUDO_CLASS

onCloseRequest	back to summary
private ObjectProperty<EventHandler<DialogEvent>> onCloseRequest Called when there is an external request to close this `Dialog`. The installed event handler can prevent dialog closing by consuming the received event.

onHidden	back to summary
private ObjectProperty<EventHandler<DialogEvent>> onHidden Called just after the Dialog has been hidden. When the `Dialog` is hidden, this event handler is invoked allowing the developer to clean up resources or perform other tasks when the `Alert` is closed.

onHiding	back to summary
private ObjectProperty<EventHandler<DialogEvent>> onHiding Called just prior to the Dialog being hidden.

onShowing	back to summary
private ObjectProperty<EventHandler<DialogEvent>> onShowing Called just prior to the Dialog being shown.

onShown	back to summary
private ObjectProperty<EventHandler<DialogEvent>> onShown Called just after the Dialog is shown.

resultConverterProperty	back to summary
private final ObjectProperty<Callback<ButtonType, R>> resultConverterProperty

resultProperty	back to summary
private final ObjectProperty<R> resultProperty

Constructor Detail

Dialog	back to summary
public Dialog() Creates a dialog without a specified owner.

Method Detail

addEventFilter back to summary

addEventFilter	back to summary
public final <E extends Event> void addEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter) Overrides default javafx.event.EventTarget.addEventFilter. Doc from javafx.event.EventTarget.addEventFilter. Registers an event filter for this target. The filter is called when the target receives an `Event` of the specified type during the capturing phase of event delivery. Parameters <E> the event class of the filter eventType:EventType<E> the type of the events received by the filter eventFilter:EventHandler<? super E> the event filter Annotations @Override

public final <E extends Event> void addEventFilter(EventType<E> eventType, EventHandler<? super E> eventFilter)

Overrides default javafx.event.EventTarget.addEventFilter.

Doc from javafx.event.EventTarget.addEventFilter.

Registers an event filter for this target.

The filter is called when the target receives an Event of the specified type during the capturing phase of event delivery.

Parameters

<E>: the event class of the filter
eventType:EventType<E>: the type of the events received by the filter
eventFilter:EventHandler<? super E>: the event filter

Annotations

@Override

addEventHandler back to summary

addEventHandler	back to summary
public final <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler) Overrides default javafx.event.EventTarget.addEventHandler. Doc from javafx.event.EventTarget.addEventHandler. Registers an event handler for this target. The handler is called when the target receives an `Event` of the specified type during the bubbling phase of event delivery. Parameters <E> the event class of the handler eventType:EventType<E> the type of the events received by the handler eventHandler:EventHandler<? super E> the event handler Annotations @Override

public final <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<? super E> eventHandler)

Overrides default javafx.event.EventTarget.addEventHandler.

Doc from javafx.event.EventTarget.addEventHandler.

Registers an event handler for this target.

The handler is called when the target receives an Event of the specified type during the bubbling phase of event delivery.

Parameters

<E>: the event class of the handler
eventType:EventType<E>: the type of the events received by the handler
eventHandler:EventHandler<? super E>: the event handler

Annotations

@Override

buildEventDispatchChain back to summary

buildEventDispatchChain	back to summary
public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) Implements javafx.event.EventTarget.buildEventDispatchChain. Doc from javafx.event.EventTarget.buildEventDispatchChain. Construct an event dispatch chain for this target. The event dispatch chain contains event dispatchers which might be interested in processing of events targeted at this `EventTarget`. This event target is not automatically added to the chain, so if it wants to process events, it needs to add an `EventDispatcher` for itself to the chain. In the case the event target is part of some hierarchy, the chain for it is usually built from event dispatchers collected from the root of the hierarchy to the event target. The event dispatch chain is constructed by modifications to the provided initial event dispatch chain. The returned chain should have the initial chain at its end so the dispatchers should be prepended to the initial chain. The caller shouldn't assume that the initial chain remains unchanged nor that the returned value will reference a different chain. Parameters tail:EventDispatchChain the initial chain to build from Returns:EventDispatchChain the resulting event dispatch chain for this target Annotations @Override

public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail)

Implements javafx.event.EventTarget.buildEventDispatchChain.

Doc from javafx.event.EventTarget.buildEventDispatchChain.

Construct an event dispatch chain for this target. The event dispatch chain contains event dispatchers which might be interested in processing of events targeted at this EventTarget. This event target is not automatically added to the chain, so if it wants to process events, it needs to add an EventDispatcher for itself to the chain.

In the case the event target is part of some hierarchy, the chain for it is usually built from event dispatchers collected from the root of the hierarchy to the event target.

The event dispatch chain is constructed by modifications to the provided initial event dispatch chain. The returned chain should have the initial chain at its end so the dispatchers should be prepended to the initial chain.

The caller shouldn't assume that the initial chain remains unchanged nor that the returned value will reference a different chain.

Parameters

tail:EventDispatchChain: the initial chain to build from

Returns:EventDispatchChain

the resulting event dispatch chain for this target

Annotations

@Override

close	back to summary
public final void close() Closes this `Dialog`. This call is equivalent to `hide`.

contentTextProperty back to summary

contentTextProperty	back to summary
public final StringProperty contentTextProperty() A property representing the content text for the dialog pane. The content text is lower precedence than the `content node`, meaning that if both the content node and the contentText properties are set, the content text will not be displayed in a default DialogPane instance. Returns:StringProperty the property representing the content text for the dialog pane

public final StringProperty contentTextProperty()

A property representing the content text for the dialog pane. The content text is lower precedence than the content node, meaning that if both the content node and the contentText properties are set, the content text will not be displayed in a default DialogPane instance.

Returns:StringProperty: the property representing the content text for the dialog pane

dialogPaneProperty	back to summary
public final ObjectProperty<DialogPane> dialogPaneProperty()

getContentText	back to summary
public final String getContentText() Returns the currently-set content text for this DialogPane. Returns:String the currently-set content text for this DialogPane

getContentText

public Class Dialog<R>

Dialog Validation / Intercepting Button Actions

Dialog Closing Rules

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail