A dialog is a window used to communicate information to the user and/or prompt the user for a response. Use the class WDialog to show a dialog. A specialized dialog is also available to alert the user with a message then use the simple WMessageBox dialog.
By default, a WDialog
is modal. A modal window blocks
the user interface, and does not allow the user to interact with
any other part of the user interface until the dialog is
closed. With a modeless dialog the window can be left open while
the user continues in another window of the application. Use
setModal(false)
to create a non-modal dialog. In the
Message box section below you can
find an example of a modeless window.
Unlike other widgets, a dialog does not need to be added to a parent
widget, and it is hidden by default. You must use the method
show()
or setHidden(false)
to show the dialog. The
dialog may be closed by calling accept()
, reject()
or
done()
(or connecting a signal to one of these methods). This
will hide the dialog and emit the finished()
signal, which you
then can listen for to process the dialog result.
Typically, an OK button will be connected to accept()
, and in
some cases a Cancel button to reject()
.
You can add content to the dialog by adding the content to its container.
You can get the container with the contents()
method.
A modal dialog can be instantiated in two ways —
synchronously or asynchronously — while a non-modal dialog
can only be instantiated asynchronously. By preference
instantiate a dialog asynchronously. The synchronous use of a
dialog is what is commonly done in desktop applications to show
a modal dialog, and involves a call to exec()
that
starts a local event loop, and returns only when the dialog is
closed. The draw-back of synchronous use is that the application
is not scalable to many concurrent sessions, since it blocks a
thread. This means it is only suitable for applications with
restricted access or applications that are deployed on an
intranet or extranet. When using a dialog asynchronously, there
is no API call that waits for the dialog to be closed. In this
case, the usage is similar to instantiating any other
widget.
A message box is a simple dialog to alert the user with a message. It may require an acknowledgment that the message has been read (usually by clicking an "OK" button), or a decision whether an action should proceed (by clicking an "OK" or "Cancel" button).
The usage is similar to instantiating a WDialog
(or any other
widget). You need to connect to the buttonClicked
signal with a
method that interprets the result.
You can get the resulting standard button with buttonResult()
.
The buttons of a WMessageBox may be standard or customized
type of buttons. Customized buttons should be dealt with using
the result()
method from the parent WDialog
.
The strings used in standard buttons can be translated by overriding the
default values of localization keys.
void MessageBox() {
WContainerWidget container = new WContainerWidget();
WPushButton button = new WPushButton("Status", (WContainerWidget) container);
final WText out = new WText((WContainerWidget) container);
out.setMargin(new WLength(10), EnumSet.of(Side.Left));
WContainerWidget c = container;
button
.clicked()
.addListener(
this,
() -> {
out.setText("The status button is clicked.");
final WMessageBox messageBox =
new WMessageBox(
"Status",
"<p>Ready to launch the rocket...</p><p>Launch the rocket immediately?</p>",
Icon.Information,
EnumUtils.or(EnumSet.of(StandardButton.Yes), StandardButton.No));
messageBox.setModal(false);
messageBox
.buttonClicked()
.addListener(
this,
() -> {
if (messageBox.getButtonResult() == StandardButton.Yes) {
out.setText("The rocket is launched!");
} else {
out.setText("The rocket is ready for launch...");
}
if (messageBox != null) messageBox.remove();
});
messageBox.show();
});
}
The following example is much more compact, but it has a big disadvantage
because the messagebox is instantiated synchronously. The show()
method is used statically; this involves the static use of the
exec()
method which blocks the current thread until the user has
clicked a button and the result of the messagebox is processed.
It is highly recommended to use a messagebox asynchronously because there
is no API call that waits for the messagebox to be processed in that
case.
void MessageBoxSync() {
WContainerWidget container = new WContainerWidget();
WPushButton button = new WPushButton("Start", (WContainerWidget) container);
final WText out = new WText((WContainerWidget) container);
out.setMargin(new WLength(10), EnumSet.of(Side.Left));
button
.clicked()
.addListener(
this,
() -> {
StandardButton answer =
WMessageBox.show(
"Launch phase",
"<p>Launch the rocket?</p>",
EnumSet.of(StandardButton.Ok, StandardButton.Cancel));
if (answer == StandardButton.Ok) {
out.setText("The rocket is launched!");
} else {
out.setText("Waiting on your decision...");
}
});
}
A WMessageBox
can be styled using the JWt-dialog
and
JWt-outset
style classes from it's superclass WDialog
.
Its buttons can be styled using the JWt-msgbox-buttons
style
class.