org.controlsfx.dialog

Class Dialogs

java.lang.Object

org.controlsfx.dialog.Dialogs

public final class Dialogs
extends Object

A simple (yet flexible) API for showing the most common forms of (modal) UI dialogs. This class contains a fluent API to make building and customizing the pre-built dialogs really easy, but for those developers who want complete control, you may be interested in instead using the Dialog class (which is what all of these pre-built dialogs use as well).

A dialog consists of a number of sections, and the pre-built dialogs in this class modify these sections as required. Refer to the Dialog class documentation for more detail, but a brief overview is provided in the following section.

Anatomy of a Dialog

A dialog consists of the following sections:

• Title,
• System buttons (min, max, close),
• Masthead,
• Content,
• Expandable content,
• Button bar

This is more easily demonstrated in the diagram shown below:

The system buttons are hidden, only "close" button is visible by default. "Maximize" button is only available when dialog becomes resizable. This happens for example with the Exception dialog when details are expanded.

Screenshots

To better explain the dialogs, here is a table showing the default look of all available pre-built dialogs when run on Windows (the button placement in dialogs uses the ButtonBar control, so the buttons vary in order based on the operating system in which the dialog is shown):

	Without Masthead	With Masthead
Information
Confirmation
Warning
Error
Exception
Exception (Expanded)
Exception (new window)
Text Input
Choice Input (ChoiceBox/ComboBox)
Command Link
Font Selector
Progress

Native and Cross-Platform Dialogs

The ControlsFX dialogs API supports displaying dialogs with either a consistent cross-platform titlebar area, or by using the titlebar of the users operating system. All of the screenshots above are taken using the cross-platform style, whereas the screenshots below are the same dialog code being rendered using the users native platform titlebar. To enable this in the Dialogs fluent API, simply call nativeTitleBar() when creating the dialog. If you're using the Dialog class, you can specify that you want to use the native titlebar as part of the Dialog.Dialog(Object, String, boolean, boolean) constructor (where the fourth parameter is used to represent whether to use the native titlebar or not).

Here are the screenshots of dialogs with their native title bars:

Platform	Screenshot
Cross-Platform (default)
Mac OS X
Windows 8
Linux (Ubuntu)

Heavyweight vs Lightweight Dialogs

The ControlsFX dialogs API supports a distinction between heavyweight and lightweight dialogs. In short, a heavyweight dialog is rendered in its own JavaFX window, allowing for it to appear outside the bounds of the application. This is the most common style of dialog, and is therefore the default behavior when creating dialogs in ControlsFX. However, in some case, lightweight dialogs make more sense, so the following paragraphs will detail when you might want to use lightweight dialogs.

Lightweight dialogs are rendered within the scenegraph (and can't leave the window). Other than this limitation, lightweight dialogs otherwise render exactly the same as heavyweight dialogs (except a lightweight dialog normally inserts an opaque overlay into the scene so that the dialog sticks out visually). Lightweight dialogs are commonly useful in environments where a windowing system is unavailable (e.g. tablet devices), and also when you only want to block execution (and access to) a portion of your user interface. For example, you could create a lightweight dialog with an owner of a single Tab in a TabPane, and this will only block on that one tab - all other tabs will continue to be interactive and execute as per usual.

One limitation of lightweight dialogs is that it is not possible to use the native titlebar feature. If you call both lightweight() and nativeTitleBar(), the call to enable lightweight takes precedence over the use of the native titlebar, so you will end up seeing what is shown in the screenshot below (that is, a cross-platform-looking dialog that is lightweight).

To make a dialog lightweight, you simply call lightweight() when constructing the dialog using this Dialogs API. If you are using the Dialog class instead, then the decision between heavyweight and lightweight dialogs must be made in the Dialog.Dialog(Object, String, boolean) constructor.

Shown below is a screenshot of a lightweight dialog whose owner is the Tab. This means that whilst the first tab is blocked for input until the dialog is dismissed by the user, the rest of the UI (including going to other tabs) remains interactive):

Code Examples

The code below will setup and show a confirmation dialog:

  Action response = Dialogs.create()
      .owner( isOwnerSelected ? stage : null)
      .title("You do want dialogs right?")
      .masthead(isMastheadVisible() ? "Just Checkin'" : null)
      .message( "I was a bit worried that you might not want them, so I wanted to double check.")
      .showConfirm();

The most important point to note about the dialogs is that they are modal, which means that they stop the application code from progressing until the dialog is closed. Because of this, it is very easy to retrieve the users input: when the user closes the dialog (e.g. by clicking on one of the buttons), the dialog will be hidden, and their response will be returned from the show method that was called to bring the dialog up in the first place. In other words, following on from the code sample above, you might do the following:

  
 if (response == Dialog.Actions.OK) {
     // ... submit user input
 } else {
     // ... user cancelled, reset form to default
 }

The following code is an example of setting up a CommandLink dialog:

 
   List<CommandLink> links = Arrays.asList(
        new CommandLink("Add a network that is in the range of this computer", 
                        "This shows you a list of networks that are currently available and lets you connect to one."),
        new CommandLink("Manually create a network profile", 
                        "This creates a new network profile or locates an existing one and saves it on your computer"),
        new CommandLink("Create an ad hoc network", 
                "This creates a temporary network for sharing files or and Internet connection"));
   
   Action response = Dialogs.create()
           .owner(cbSetOwner.isSelected() ? stage : null)
           .title("Manually connect to wireless network")
           .masthead(isMastheadVisible() ? "Manually connect to wireless network": null)
           .message("How do you want to add a network?")
           .showCommandLinks( links.get(1), links );

See Also:

Dialog, Action, Dialog.Actions, AbstractAction

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Dialogs.CommandLink Command Link class.

Field Summary

Fields

Modifier and Type	Field and Description
static String	USE_DEFAULT USE_DEFAULT can be passed in to title(String) and masthead(String) methods to specify that the default text for the dialog should be used, where the default text is specific to the type of dialog being shown.

Method Summary

Modifier and Type	Method and Description
Dialogs	actions(Action... actions) Completely replaces standard actions with provided ones.
Dialogs	actions(Collection<? extends Action> actions) Completely replaces standard actions with provided ones.
static Dialogs	create() Creates the initial dialog
Dialogs	lightweight() Specifies that the dialog should become lightweight, which means it is rendered within the scene graph (and can't leave the window).
Dialogs	masthead(String masthead) Assigns dialog's masthead
Dialogs	message(String message) Assigns dialog's instructions
Dialogs	nativeTitleBar() Specifies that the dialog should use the native title bar of the users operating system rather than the custom cross-platform rendering used by default.
Dialogs	owner(Object owner) Assigns the owner of the dialog.
<T> T	showChoices(Collection<T> choices) Show a dialog with one combobox filled with provided choices
<T> T	showChoices(T... choices) Show a dialog with one combobox filled with provided choices
<T> T	showChoices(T defaultChoice, Collection<T> choices) Show a dialog with one combobox filled with provided choices.
Action	showCommandLinks(Dialogs.CommandLink defaultCommandLink, Dialogs.CommandLink... links) Show a dialog filled with provided command links.
Action	showCommandLinks(Dialogs.CommandLink defaultCommandLink, List<Dialogs.CommandLink> links) Show a dialog filled with provided command links.
Action	showCommandLinks(List<Dialogs.CommandLink> links) Show a dialog filled with provided command links.
Action	showConfirm() Shows confirmation dialog.
Action	showError() Show error dialog
Action	showException(Throwable exception) Shows exception dialog with expandable stack trace.
Action	showExceptionInNewWindow(Throwable exception) Shows exception dialog with a button to open the exception text in a new window.
Font	showFontSelector(Font font) Show font selection dialog, allowing to manipulate font name, style and size.
void	showInformation() Shows information dialog.
String	showTextInput() Shows dialog with one text field
String	showTextInput(String defaultValue) Shows dialog with one text field
Action	showWarning() Shows warning dialog
void	showWorkerProgress(Worker<?> worker) Creates a progress bar Dialog which is attached to the given Worker instance.
Dialogs	title(String title) Assigns dialog's title

Methods inherited from class java.lang.Object

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

Field Detail

USE_DEFAULT

public static final String USE_DEFAULT

USE_DEFAULT can be passed in to title(String) and masthead(String) methods to specify that the default text for the dialog should be used, where the default text is specific to the type of dialog being shown.

See Also:

Constant Field Values

Method Detail

create

public static Dialogs create()

Creates the initial dialog

Returns:

dialog instance

owner

public Dialogs owner(Object owner)

Assigns the owner of the dialog. If an owner is specified, the dialog will block input to the owner and all parent owners. If no owner is specified, or if owner is null, the dialog will block input to the entire application.

Parameters:

owner - The dialog owner.

Returns:

dialog instance.

title

public Dialogs title(String title)

Assigns dialog's title

Parameters:

title - dialog title

Returns:

dialog instance.

message

public Dialogs message(String message)

Assigns dialog's instructions

Parameters:

message - dialog message

Returns:

dialog instance.

masthead

public Dialogs masthead(String masthead)

Assigns dialog's masthead

Parameters:

masthead - dialog masthead

Returns:

dialog instance.

actions

public Dialogs actions(Collection<? extends Action> actions)

Completely replaces standard actions with provided ones.

Parameters:

actions - new dialog actions

Returns:

dialog instance.

actions

public Dialogs actions(Action... actions)

Completely replaces standard actions with provided ones.

Parameters:

actions - new dialog actions

Returns:

dialog instance.

lightweight

public Dialogs lightweight()

Specifies that the dialog should become lightweight, which means it is rendered within the scene graph (and can't leave the window). Lightweight dialogs are commonly useful in environments where a windowing system is unavailable (e.g. tablet devices), and also when you only want to block execution (and access to) a portion of your user interface. For example, you could create a lightweight dialog with an owner of a single Tab in a TabPane, and this will only block on that one tab - all other tabs will continue to be interactive and execute as per usual.

Returns:

dialog instance.

nativeTitleBar

public Dialogs nativeTitleBar()

Specifies that the dialog should use the native title bar of the users operating system rather than the custom cross-platform rendering used by default. Refer to the Dialogs class JavaDoc for more information.

Returns:

dialog instance.

showInformation

public void showInformation()

Shows information dialog.

showConfirm

public Action showConfirm()

Shows confirmation dialog.

Returns:

action used to close dialog.

showWarning

public Action showWarning()

Shows warning dialog

Returns:

action used to close dialog

showError

public Action showError()

Show error dialog

Returns:

action used to close dialog

showException

public Action showException(Throwable exception)

Shows exception dialog with expandable stack trace.

Parameters:

exception - exception to present

Returns:

action used to close dialog

showExceptionInNewWindow

public Action showExceptionInNewWindow(Throwable exception)

Shows exception dialog with a button to open the exception text in a new window.

Parameters:

exception - exception to present

Returns:

action used to close dialog

showTextInput

public String showTextInput(String defaultValue)

Shows dialog with one text field

Parameters:

defaultValue - text field default value

Returns:

text from input field if OK action is used otherwise null

showTextInput

public String showTextInput()

Shows dialog with one text field

Returns:

text from input field or null if dialog is cancelled

showChoices

public <T> T showChoices(T defaultChoice,
                         Collection<T> choices)

Show a dialog with one combobox filled with provided choices. The combobox selection will be set to a default value if one is provided.

Parameters:

defaultChoice - default combobox selection

choices - dialog choices

Returns:

selected choice or null if dialog is cancelled.

showChoices

public <T> T showChoices(Collection<T> choices)

Show a dialog with one combobox filled with provided choices

Parameters:

choices - dialog choices

Returns:

selected choice or null if dialog is cancelled

showChoices

public <T> T showChoices(T... choices)

Show a dialog with one combobox filled with provided choices

Parameters:

choices - dialog choices

Returns:

selected choice or null if dialog is cancelled

showCommandLinks

public Action showCommandLinks(Dialogs.CommandLink defaultCommandLink,
                               List<Dialogs.CommandLink> links)

Show a dialog filled with provided command links. Command links are used instead of button bar and represent a set of available 'radio' buttons

Parameters:

defaultCommandLink - command is set to be default. Null means no default

links - list of command links presented in specified sequence

Returns:

action used to close dialog (it is either one of command links or CANCEL)

showCommandLinks

public Action showCommandLinks(List<Dialogs.CommandLink> links)

Show a dialog filled with provided command links. Command links are used instead of button bar and represent a set of available 'radio' buttons

Parameters:

links - list of command links presented in specified sequence

Returns:

action used to close dialog (it is either one of command links or CANCEL)

showCommandLinks

public Action showCommandLinks(Dialogs.CommandLink defaultCommandLink,
                               Dialogs.CommandLink... links)

Show a dialog filled with provided command links. Command links are used instead of button bar and represent a set of available 'radio' buttons

Parameters:

defaultCommandLink - command is set to be default. Null means no default

links - command links presented in specified sequence

Returns:

action used to close dialog (it is either one of command links or CANCEL)

showFontSelector

public Font showFontSelector(Font font)

Show font selection dialog, allowing to manipulate font name, style and size.

Parameters:

font - default font value

Returns:

selected font or null if the dialog is canceled.

showWorkerProgress

public void showWorkerProgress(Worker<?> worker)

Creates a progress bar Dialog which is attached to the given Worker instance. The worker will be observed permanently and the attached dialog will be shown and hidden as the worker starts and completes. If the worker's state is Worker.State.SCHEDULED or Worker.State.RUNNING the dialog will be visible.

Expected Behavior

If the worker has a state of Worker.State.READY, Worker.State.SUCCEEDED, Worker.State.FAILED, or Worker.State.CANCELLED, the dialog will be shown when the worker's state changes to SUCCEDED or RUNNING. If the worker has a state of SCHEDULED or RUNNING, the dialog will be hidden when the worker's state changes to SUCCEEDED, FAILED, or CANCELLED. All other changes in worker state will not cause the visibility of the attached dialog to change. Note that if a worker is submitted with a state of SCHEDULED or RUNNING the dialog will be shown immediately.

Multiple Workers

It's important to make sure that only one progress dialog is shown at a time, especially when using LightweightDialogs. If an attempt is made to show more than one lightweight dialog at a time, an IllegalArgumentException will be thrown. If several workers have dialogs attached, care should be taken to ensure only one of those workers is SCHEDULED or RUNNING at any given time.

Worker Completion Handling

It's important to remember, especially when using lightweight dialogs, that when a worker completes the attached dialog may still be visible. If a worker's completion handler attempts to show another dialog, the result may be undesirable. For heavyweight dialogs it's possible to end up with two dialogs on the screen at once. For lightweight dialogs it's possible for an IllegalArgumentException to be thrown. If a worker's completion handler is going to cause another dialog to be shown, or is going to restart a failed worker, Platform.runLater(Runnable) should be used to ensure notification about the worker's completion is finished first. Doing so makes sure the worker's attached dialog has been hidden before any new dialogs are shown during completion handling.

    Service<Void> service = getService();

    service.setOnFailed(new EventHandler<WorkerStateEvent>() {
        public void handle(WorkerStateEvent event) {
            Platform.runLater(new Runnable() {
                public void run() {
                    // Make sure the service state is still failed.  If so, the
                    // call to shouldRetry() will show the user a dialog asking
                    // if they'd like to retry and will return true or false
                    // depending on the user's answer.
                    if(isFailed(service) && shouldRetry()) {
                        service.restart();
                    }
                }
            });
        }
    });
 

The above code is much cleaner with Java 8 syntax:

    Service<Void> service = getService();

    service.setOnFailed(event -> Platform.runLater(() -> {
        if(isFailed(service) && shouldRetry()) {
            service.restart();
        }
    }));