3.5.5. Dialogs

The Dialogs interface is designed to display standard dialogs windows. Its createMessageDialog() and createOptionDialog() methods are the entry points to the fluent API that allows you to construct and show dialogs.

In the following example, a message dialog is shown when the user clicks a button:

@Inject
private Dialogs dialogs;

@Subscribe("showDialogBtn")
protected void onShowDialogBtnClick(Button.ClickEvent event) {
    dialogs.createMessageDialog().withCaption("Information").withMessage("Message").show();
}

You can use \n characters for line breaks in messages. In order to show HTML, use the withContentMode() method with ContentMode.HTML parameter. When using HTML, don’t forget to escape data to prevent code injection.

The following methods allow you to customize the look and behavior of the message dialog:

  • withModal() - if false is passed, the dialog is shown as non-modal, which allows a user to interact with the other parts of the application.

  • withCloseOnClickOutside() - when true is passed and the dialog is modal, allows a user to close the dialog by clicking on the application window outside of the dialog.

  • withWidth(), withHeight() allow you to specify the desired dialog geometry.

For example:

@Inject
private Dialogs dialogs;

@Subscribe("showDialogBtn")
protected void onShowDialogBtnClick(Button.ClickEvent event) {
    dialogs.createMessageDialog()
            .withCaption("Information")
            .withMessage("<i>Message<i/>")
            .withContentMode(ContentMode.HTML)
            .withCloseOnClickOutside(true)
            .withWidth("100px")
            .withHeight("300px")
            .show();
}

The option dialog displays a message and a set of buttons for user reaction. Use withActions() method to provide actions, each of which is represented by a button in the dialog. For example:

@Inject
private Dialogs dialogs;

@Subscribe("showDialogBtn")
protected void onShowDialogBtnClick(Button.ClickEvent event) {
    dialogs.createOptionDialog()
            .withCaption("Confirm")
            .withMessage("Are you sure?")
            .withActions(
                new DialogAction(DialogAction.Type.YES, Action.Status.PRIMARY).withHandler(e -> {
                    doSomething();
                }),
                new DialogAction(DialogAction.Type.NO)
            )
            .show();
}

When a button is clicked, the dialog closes and invokes actionPerform() method of the corresponding action.

The DialogAction base class is designed to create actions with standard names and icons. Five types of actions defined by the DialogAction.Type enum are supported: OK, CANCEL, YES, NO, CLOSE. Names of corresponding buttons are extracted from the main message pack.

The second parameter of the DialogAction constructor is used to assign a special visual style for a button representing the action. Status.PRIMARY highlights the corresponding button and makes it selected, which is provided by the c-primary-action style. If multiple actions with Status.PRIMARY are defined for the dialog, only the first action’s button will get the style and focus.