Module com.gluonhq.charm.glisten
Package com.gluonhq.charm.glisten.control

Class Dialog<T>

  • Type Parameters:
    T - The return type of the showAndWait() method.
    All Implemented Interfaces:
    EventTarget
    Direct Known Subclasses:
    Alert, DatePicker, ExceptionDialog, TimePicker
    public class Dialog<T>
extends Object
implements EventTarget

    A Dialog is composed of a graphic, a title, a content node and a collection of buttons. The Dialog class is the Glisten API for showing dialogs that are modal and blocking. "Modal" means that the user is prevented from interacting with the rest of the application while the Dialog is showing and "blocking" means the call to showAndWait() blocks code execution until the Dialog is closed, this means the developer can show the Dialog and interact with the result right after the method showAndWait() returns, which typically simplifies the code.

    The Dialog class is a powerful class. It is the base class for any Dialog based control, but it can also be used to create simple Dialogs with a text title, a text content and one or two buttons for the user to interact with. The example below creates and shows such a Dialog: 

     
 Dialog dialog = new Dialog();
 dialog.setTitle(new Label("This is a regular dialog"));
 dialog.setContent(new Label("Just a regular dialog, plain and simple");
 Button okButton = new Button("OK");
 okButton.setOnAction(e -> {
   dialog.hide();
 });
 dialog.getButtons().add(okButton);
 dialog.showAndWait();

    Screenshot of Dialog

    You can also create fullscreen dialogs by passing in true to the Dialog constructor. Fullscreen dialogs are essentially Views and are used for example when the dialog includes components (like pickers or form fields) that require a keyboard.

    Fullscreen dialog's controls are inside the AppBar including a close button (Nav Icon), the title and the buttons list (Action Icons). The content is inserted in the center of the View.

    The following example shows a fullscreen dialog. When the dialog closes a confirmation dialog is displayed, to ask the user whether he wants to 'discard' changes or keep them. If the user presses 'keep editing' the close request event is consumed and so the dialog doesn't close, otherwise we let the event go through (this is a common workflow in Material Design: https://www.google.com/design/spec/components/dialogs.html#dialogs-full-screen-dialogs). 

     
 Dialog dialog = new Dialog(true);
 dialog.setTitleText("");
 dialog.setContent(new Label("Some dialog content..."));
 Button saveButton = new Button("SAVE");
 dialog.getButtons().addAll(saveButton);

 dialog.setOnCloseRequest(closeRequestEvent -> {
   Dialog areYouSureDialog = new Dialog(false);
   areYouSureDialog.setContent(new Label("Are you sure you want to discard all changes?"));
   Button yesButton = new Button("DISCARD");
   Button noButton = new Button("KEEP EDITING");
   yesButton.setOnAction(event2 -> {
     areYouSureDialog.hide();
   });
   noButton.setOnAction(event2 -> {
     closeRequestEvent.consume();
     areYouSureDialog.hide();
   });
   areYouSureDialog.getButtons().addAll(yesButton, noButton);
   areYouSureDialog.showAndWait();
 });

 dialog.showAndWait();

    Screenshot of Fullscreen Dialog

    Since:
    1.0.0
    See Also:
    Alert, TimePicker, DatePicker

    • Field Detail

      • rootNode

        protected BorderPane rootNode
        The root node of regular sized dialogs

    • Constructor Detail

      • Dialog

        public Dialog()
        Creates an empty Dialog instance.

      • Dialog

        public Dialog​(String contentText)
        Creates an empty Dialog instance. The given string is used as the text of the Label that is set as its content.
        Parameters:
        contentText - The text to show as the Dialog's content.

      • Dialog

        public Dialog​(String title,
              String contentText)
        Creates a Dialog instance with the given title and content text.
        Parameters:
        title - The title to show at the top of the dialog.
        contentText - The content text below the title.

      • Dialog

        public Dialog​(boolean fullscreen)
        Creates an empty fullscreen Dialog if the flag passed in is true, creates an empty regular Dialog otherwise.
        Parameters:
        fullscreen - Whether the Dialog should be fullscreen

    • Method Detail

      • isShowing

        public final boolean isShowing()
        Gets the value of the property showing.
        Property description:
        Represents whether the Dialog instance is currently showing or not.

      • getTitle

        public final Node getTitle()
        Gets the value of the property title.
        Property description:
        The title of the Dialog. Typically it can be set it with a Label but it can be any type extending from Node

      • setTitle

        public final void setTitle​(Node title)
        Sets the value of the property title.
        Property description:
        The title of the Dialog. Typically it can be set it with a Label but it can be any type extending from Node

      • titleTextProperty

        public final StringProperty titleTextProperty()
        The String title of the dialog, setting this property with a non null value will result in the title being a Label with the value of this property as the text. This property might not reflect the actual title since no synchronization between titleProperty() and titleTextProperty exists when the title property is set
        See Also:
        getTitleText(), setTitleText(String)

      • setTitleText

        public final void setTitleText​(String text)
        Sets the value of the property titleText.
        Property description:
        The String title of the dialog, setting this property with a non null value will result in the title being a Label with the value of this property as the text. This property might not reflect the actual title since no synchronization between titleProperty() and titleTextProperty exists when the title property is set

      • getTitleText

        public final String getTitleText()
        Gets the value of the property titleText.
        Property description:
        The String title of the dialog, setting this property with a non null value will result in the title being a Label with the value of this property as the text. This property might not reflect the actual title since no synchronization between titleProperty() and titleTextProperty exists when the title property is set

      • setContentText

        public final void setContentText​(String text)
        Sets the value of the property contentText.
        Property description:
        The String content of the dialog, setting this property with a non null value will result in the content being a Label with the value of this property as the text. This property might not reflect the actual content since no synchronization between contentProperty() and contentTextProperty() exists when the content property is set

      • getContentText

        public final String getContentText()
        Gets the value of the property contentText.
        Property description:
        The String content of the dialog, setting this property with a non null value will result in the content being a Label with the value of this property as the text. This property might not reflect the actual content since no synchronization between contentProperty() and contentTextProperty() exists when the content property is set

      • getContent

        public final Node getContent()
        Gets the value of the property content.
        Property description:
        The content of the Dialog. For a regular Dialog this is typically set as a Label but can be set with any type extending from Node

      • setContent

        public final void setContent​(Node content)
        Sets the value of the property content.
        Property description:
        The content of the Dialog. For a regular Dialog this is typically set as a Label but can be set with any type extending from Node

      • graphicProperty

        public final ObjectProperty<Node> graphicProperty()
        The graphic to be displayed in this Dialog. If set to null then no graphic will be displayed. The graphic is only used in non fullscreen dialogs. By default no graphic is shown.
        See Also:
        getGraphic(), setGraphic(Node)

      • setGraphic

        public final void setGraphic​(Node graphic)
        Sets the value of the property graphic.
        Property description:
        The graphic to be displayed in this Dialog. If set to null then no graphic will be displayed. The graphic is only used in non fullscreen dialogs. By default no graphic is shown.

      • getGraphic

        public final Node getGraphic()
        Gets the value of the property graphic.
        Property description:
        The graphic to be displayed in this Dialog. If set to null then no graphic will be displayed. The graphic is only used in non fullscreen dialogs. By default no graphic is shown.

      • autoHideProperty

        public final BooleanProperty autoHideProperty()
        This property indicates whether the Dialog should close if a mouse/finger is pressed/tapped outside of the Dialog. By default this property is true.
        See Also:
        isAutoHide(), setAutoHide(boolean)

      • setAutoHide

        public final void setAutoHide​(boolean value)
        Sets the value of the property autoHide.
        Property description:
        This property indicates whether the Dialog should close if a mouse/finger is pressed/tapped outside of the Dialog. By default this property is true.

      • isAutoHide

        public final boolean isAutoHide()
        Gets the value of the property autoHide.
        Property description:
        This property indicates whether the Dialog should close if a mouse/finger is pressed/tapped outside of the Dialog. By default this property is true.

      • idProperty

        public final StringProperty idProperty()
        The id of this Dialog. This simple string identifier is useful for finding a specific Dialog within the scene graph. While the id of a Dialog should be unique within the scene graph, this uniqueness is not enforced. This is analogous to the "id" attribute on an HTML element (CSS ID Specification).

        For example, if a Dialog is given the id of "myId", then the lookup method can be used to find this dialog as follows: scene.lookup("#myId");.

        Default value:
        null
        Since:
        4.2.0
        See Also:
        getId(), setId(String)

      • setId

        public final void setId​(String id)
        Sets the value of the property id.
        Property description:
        The id of this Dialog. This simple string identifier is useful for finding a specific Dialog within the scene graph. While the id of a Dialog should be unique within the scene graph, this uniqueness is not enforced. This is analogous to the "id" attribute on an HTML element (CSS ID Specification).

        For example, if a Dialog is given the id of "myId", then the lookup method can be used to find this dialog as follows: scene.lookup("#myId");.

        Default value:
        null
        Since:
        4.2.0

      • getId

        public final String getId()
        Gets the value of the property id.
        Property description:
        The id of this Dialog. This simple string identifier is useful for finding a specific Dialog within the scene graph. While the id of a Dialog should be unique within the scene graph, this uniqueness is not enforced. This is analogous to the "id" attribute on an HTML element (CSS ID Specification).

        For example, if a Dialog is given the id of "myId", then the lookup method can be used to find this dialog as follows: scene.lookup("#myId");.

        Default value:
        null
        Since:
        4.2.0

      • setOnShowing

        public final void setOnShowing​(EventHandler<LifecycleEvent> value)
        Sets the value of the property onShowing.
        Property description:
        Called just prior to the Dialog being shown.

      • getOnShowing

        public final EventHandler<LifecycleEvent> getOnShowing()
        Gets the value of the property onShowing.
        Property description:
        Called just prior to the Dialog being shown.

      • setOnShown

        public final void setOnShown​(EventHandler<LifecycleEvent> value)
        Sets the value of the property onShown.
        Property description:
        Called just after the Dialog is shown.

      • getOnShown

        public final EventHandler<LifecycleEvent> getOnShown()
        Gets the value of the property onShown.
        Property description:
        Called just after the Dialog is shown.

      • setOnHiding

        public final void setOnHiding​(EventHandler<LifecycleEvent> value)
        Sets the value of the property onHiding.
        Property description:
        Called just prior to the Dialog being hidden.

      • getOnHiding

        public final EventHandler<LifecycleEvent> getOnHiding()
        Gets the value of the property onHiding.
        Property description:
        Called just prior to the Dialog being hidden.

      • setOnHidden

        public final void setOnHidden​(EventHandler<LifecycleEvent> value)
        Sets the value of the property onHidden.
        Property description:
        Called just after the Dialog has been hidden. This allows the developer to clean up resources or perform other tasks when the Dialog is closed.

      • getOnHidden

        public final EventHandler<LifecycleEvent> getOnHidden()
        Gets the value of the property onHidden.
        Property description:
        Called just after the Dialog has been hidden. This allows the developer to clean up resources or perform other tasks when the Dialog is closed.

      • setOnCloseRequest

        public final void setOnCloseRequest​(EventHandler<LifecycleEvent> value)
        Sets the value of the property onCloseRequest.
        Property description:
        Called when there is an external request to close this Dialog. If in the event handler the received event is consumed the dialog will no longer close.

      • getOnCloseRequest

        public final EventHandler<LifecycleEvent> getOnCloseRequest()
        Gets the value of the property onCloseRequest.
        Property description:
        Called when there is an external request to close this Dialog. If in the event handler the received event is consumed the dialog will no longer close.

      • getButtons

        public final ObservableList<ButtonBase> getButtons()
        A list of buttons to show within the dialog.
        Returns:
        A modifiable list of buttons that will appear in the dialog.

      • isFullscreen

        public final boolean isFullscreen()
        Indicates whether this dialog is a fullscreen dialog.
        Returns:
        a boolean value indicating if the dialog is in fullscreen mode

      • showAndWait

        public final Optional<T> showAndWait()
        Requests that the dialog be shown. This method will not return until the Dialog is closed.
        Returns:
        An Optional instance that contains the result from the user dismissing the dialog.

      • setResult

        public final void setResult​(T result)
        Sets the result to return once the dialog is hidden.
        Parameters:
        result - The result from the users interaction.

      • hide

        public final void hide()
        Hides/closes the dialog.