Dialog (ControlsFX Project 8.0.2-developer-preview-1)

java.lang.Object
- org.controlsfx.dialog.Dialog

public class Dialog
extends Object

A lower-level API for creating standardized dialogs consisting of the following subsections:

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

This is more easily demonstrated in the diagram shown below:

For developers wanting a simpler API, consider using the high-level Dialogs class, which provides a simpler, fluent API for displaying the most common types of dialog.

Code Examples

Getting The User Response
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, you might do the following:

  
 Action response = Dialogs.create()
      .title("You do want dialogs right?")
      .masthead("Just Checkin'")
      .message( "I was a bit worried that you might not want them, so I wanted to double check.")
      .showConfirm();
      
 if (response == Dialog.Actions.OK) {
     // ... submit user input
 } else {
     // ... user cancelled, reset form to default
 }

Custom Dialogs
It is not always the case that one of the pre-built Dialogs suits the requirements of your application. In that case, you can build a custom dialog. Shown below is a screenshot of one such custom dialog, and below that the source code used to create the code. I hope you'll agree that the code is logical and simple!

 
 // This dialog will consist of two input fields (username and password),
 // and have two buttons: Login and Cancel.
 
 final TextField txUserName = new TextField();
 final PasswordField txPassword = new PasswordField();
 final Action actionLogin = new AbstractAction("Login") {
     {  
         ButtonBar.setType(this, ButtonType.OK_DONE); 
     }
       
     // This method is called when the login button is clicked...
     public void execute(ActionEvent ae) {
          Dialog dlg = (Dialog) ae.getSource();
          // real login code here
          dlg.hide();
      }
 };
   
 // This method is called when the user types into the username / password fields  
 private void validate() {
     actionLogin.disabledProperty().set( 
           txUserName.getText().trim().isEmpty() || txPassword.getText().trim().isEmpty());
 }
   
 // Imagine that this method is called somewhere in your codebase
 private void showLoginDialog() {
     Dialog dlg = new Dialog(null, "Login Dialog");
       
     // listen to user input on dialog (to enable / disable the login button)
     ChangeListener<String> changeListener = new ChangeListener<String>() {
         public void changed(ObservableValue<? extends String> observable, String oldValue, String newValue) {
             validate();
         }
     };
     txUserName.textProperty().addListener(changeListener);
     txPassword.textProperty().addListener(changeListener);
       
     // layout a custom GridPane containing the input fields and labels
     final GridPane content = new GridPane();
     content.setHgap(10);
     content.setVgap(10);
       
     content.add(new Label("User name"), 0, 0);
     content.add(txUserName, 1, 0);
     GridPane.setHgrow(txUserName, Priority.ALWAYS);
     content.add(new Label("Password"), 0, 1);
     content.add(txPassword, 1, 1);
     GridPane.setHgrow(txPassword, Priority.ALWAYS);
       
     // create the dialog with a custom graphic and the gridpane above as the
     // main content region
     dlg.setResizable(false);
     dlg.setIconifiable(false);
     dlg.setGraphic(new ImageView(HelloDialog.class.getResource("login.png").toString()));
     dlg.setContent(content);
     dlg.getActions().addAll(actionLogin, Dialog.Actions.CANCEL);
     validate();
       
     // request focus on the username field by default (so the user can
     // type immediately without having to click first)
     Platform.runLater(new Runnable() {
         public void run() {
             txUserName.requestFocus();
         }
     });

     dlg.show();
 }

See Also:: Dialogs, Action, Dialog.Actions

Property Summary

All Methods Instance Methods Concrete Methods
Type	Property and Description
`ObjectProperty<Node>`	`content` Property representing the content area of the dialog.
`ObjectProperty<Node>`	`expandableContent` A property that represents the dialog expandable content area.
`ObjectProperty<Node>`	`graphic` The dialog graphic, presented either in the masthead, if one is showing, or to the left of the `content`.
`ObjectProperty<Node>`	`masthead` Property representing the masthead area of the dialog.
`BooleanProperty`	`resizable` Represents whether the dialog is resizable.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Dialog.Actions` An enumeration of common dialog actions, ideal for use in dialogs if the common behavior of presenting options to a user and listening to their response is all that is necessary.

Constructor Summary

Constructors
Constructor and Description
`Dialog(Object owner, String title)` Creates a heavyweight dialog using specified owner and title.
`Dialog(Object owner, String title, boolean lightweight)` Creates a dialog using specified owner and title, which may be rendered in either a heavyweight or lightweight fashion.
`Dialog(Object owner, String title, boolean lightweight, boolean nativeTitleBar)` Creates a dialog using specified owner and title, which may be rendered in either a heavyweight or lightweight fashion.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ObjectProperty<Node>`	`contentProperty()` Property representing the content area of the dialog.
`ObjectProperty<Node>`	`expandableContentProperty()` A property that represents the dialog expandable content area.
`ObservableList<Action>`	`getActions()` Observable list of actions used for the dialog `ButtonBar`.
`Node`	`getContent()` Returns the dialog content as a Node (even if it was set as a String using `setContent(String)` - this was simply transformed into a `Node` (most probably a `Label`).
`Node`	`getExpandableContent()` Returns the dialog expandable content node, if one is set, or null otherwise.
`Node`	`getGraphic()` Gets the value of the property graphic.
`double`	`getHeight()` Returns the height of the dialog.
`Node`	`getMasthead()` Node which acts as dialog's masthead
`double`	`getWidth()` Returns the width of the dialog.
`ObjectProperty<Node>`	`graphicProperty()` The dialog graphic, presented either in the masthead, if one is showing, or to the left of the `content`.
`void`	`hide()` Hides the dialog.
`boolean`	`isResizable()` Returns whether or not the dialog is resizable.
`ObjectProperty<Node>`	`mastheadProperty()` Property representing the masthead area of the dialog.
`BooleanProperty`	`resizableProperty()` Represents whether the dialog is resizable.
`void`	`setClosable(boolean closable)` Sets whether the dialog can be closed
`void`	`setContent(Node content)` Assign dialog content.
`void`	`setContent(String contentText)` Assign text as the dialog's content (this will be transformed into a `Node` and then set via `setContent(Node)`).
`void`	`setExpandableContent(Node content)` Sets the dialog expandable content node, or null if no expandable content needs to be shown.
`void`	`setGraphic(Node graphic)` Sets the dialog graphic, which will be displayed either in the masthead, if one is showing, or to the left of the `content`.
`void`	`setIconifiable(boolean iconifiable)` Sets whether the dialog can be iconified (minimized)
`void`	`setMasthead(Node masthead)` Assigns dialog's masthead.
`void`	`setMasthead(String mastheadText)` Sets the string to show in the dialog masthead area.
`void`	`setResizable(boolean resizable)` Sets whether the dialog can be resized by the user.
`Action`	`show()` Shows the dialog and waits for the user response (in other words, brings up a modal dialog, with the returned value the users input).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Property Detail
  - resizable
```
public BooleanProperty resizableProperty
```
    Represents whether the dialog is resizable.
    
    See Also:
    
    isResizable(), setResizable(boolean)
  - graphic
```
public ObjectProperty<Node> graphicProperty
```
    The dialog graphic, presented either in the masthead, if one is showing, or to the left of the content.
    
    See Also:
    
    getGraphic(), setGraphic(Node)
  - masthead
```
public ObjectProperty<Node> mastheadProperty
```
    Property representing the masthead area of the dialog.
    
    See Also:
    
    getMasthead(), setMasthead(Node)
  - content
```
public ObjectProperty<Node> contentProperty
```
    Property representing the content area of the dialog.
    
    See Also:
    
    getContent(), setContent(Node)
  - expandableContent
```
public ObjectProperty<Node> expandableContentProperty
```
    A property that represents the dialog expandable content area. Any Node can be placed in this area, but it will only be shown when the user clicks the 'Show Details' expandable button. This button will be added automatically when the expandable content property is non-null.
    
    See Also:
    
    getExpandableContent(), setExpandableContent(Node)
- Constructor Detail
  - Dialog
```
public Dialog(Object owner,
              String title)
```
    Creates a heavyweight dialog using specified owner and title.
    
    Parameters:
    
    owner - The dialog window owner - if specified the dialog will be centered over the owner, otherwise the dialog will be shown in the middle of the screen.
    
    title - The dialog title to be shown at the top of the dialog.
  - Dialog
```
public Dialog(Object owner,
              String title,
              boolean lightweight)
```
    Creates a dialog using specified owner and title, which may be rendered in either a heavyweight or lightweight fashion.
    
    Parameters:
    
    owner - The dialog window owner - if specified the dialog will be centered over the owner, otherwise the dialog will be shown in the middle of the screen.
    
    title - The dialog title to be shown at the top of the dialog.
    
    lightweight - If true this dialog will be rendered inside the given owner, rather than in a separate window (as heavyweight dialogs are). Refer to the Dialogs class documentation for more details on the difference between heavyweight and lightweight dialogs.
  - Dialog
```
public Dialog(Object owner,
              String title,
              boolean lightweight,
              boolean nativeTitleBar)
```
    Creates a dialog using specified owner and title, which may be rendered in either a heavyweight or lightweight fashion.
    
    Parameters:
    
    owner - The dialog window owner - if specified the dialog will be centered over the owner, otherwise the dialog will be shown in the middle of the screen.
    
    title - The dialog title to be shown at the top of the dialog.
    
    lightweight - If true this dialog will be rendered inside the given owner, rather than in a separate window (as heavyweight dialogs are). Refer to the Dialogs class documentation for more details on the difference between heavyweight and lightweight dialogs.
    
    nativeTitleBar - Specifies that the dialog should use the native titlebar of the users operating system rather than the custom cross-platform rendering used by default. Refer to the Dialogs class javadoc for more information.
- Method Detail
  - show
```
public Action show()
```
    Shows the dialog and waits for the user response (in other words, brings up a modal dialog, with the returned value the users input).
    
    Returns:
    
    The Action used to close the dialog.
  - hide
```
public void hide()
```
    Hides the dialog.
  - resizableProperty
```
public BooleanProperty resizableProperty()
```
    Represents whether the dialog is resizable.
    
    See Also:
    
    isResizable(), setResizable(boolean)
  - isResizable
```
public final boolean isResizable()
```
    Returns whether or not the dialog is resizable.
    
    Returns:
    
    true if dialog is resizable
  - setResizable
```
public final void setResizable(boolean resizable)
```
    Sets whether the dialog can be resized by the user. Resizable dialogs can also be maximized ( maximize button becomes visible)
    
    Parameters:
    
    resizable - true if dialog should be resizable.
  - setIconifiable
```
public void setIconifiable(boolean iconifiable)
```
    Sets whether the dialog can be iconified (minimized)
    
    Parameters:
    
    iconifiable - if dialog should be iconifiable
  - setClosable
```
public void setClosable(boolean closable)
```
    Sets whether the dialog can be closed
    
    Parameters:
    
    closable - if dialog should be closable
  - graphicProperty
```
public ObjectProperty<Node> graphicProperty()
```
    The dialog graphic, presented either in the masthead, if one is showing, or to the left of the content.
    
    See Also:
    
    getGraphic(), setGraphic(Node)
  - getGraphic
```
public final Node getGraphic()
```
    Gets the value of the property graphic.
  - setGraphic
```
public final void setGraphic(Node graphic)
```
    Sets the dialog graphic, which will be displayed either in the masthead, if one is showing, or to the left of the content.
    
    Parameters:
    
    graphic - The new dialog graphic, or null if no graphic should be shown.
  - getMasthead
```
public final Node getMasthead()
```
    Node which acts as dialog's masthead
    
    Returns:
    
    dialog's masthead
  - setMasthead
```
public final void setMasthead(Node masthead)
```
    Assigns dialog's masthead. Any Node can be used
    
    Parameters:
    
    masthead - future masthead
  - setMasthead
```
public final void setMasthead(String mastheadText)
```
    Sets the string to show in the dialog masthead area.
    
    Parameters:
    
    mastheadText - The masthead text to show in the masthead area.
  - mastheadProperty
```
public ObjectProperty<Node> mastheadProperty()
```
    Property representing the masthead area of the dialog.
    
    See Also:
    
    getMasthead(), setMasthead(Node)
  - getContent
```
public final Node getContent()
```
    Returns the dialog content as a Node (even if it was set as a String using setContent(String) - this was simply transformed into a Node (most probably a Label).
    
    Returns:
    
    dialog's content
  - setContent
```
public final void setContent(Node content)
```
    Assign dialog content. Any Node can be used
    
    Parameters:
    
    content - dialog's content
  - setContent
```
public final void setContent(String contentText)
```
    Assign text as the dialog's content (this will be transformed into a Node and then set via setContent(Node)).
    
    Parameters:
    
    contentText - The text to show in the main section of the dialog.
  - contentProperty
```
public ObjectProperty<Node> contentProperty()
```
    Property representing the content area of the dialog.
    
    See Also:
    
    getContent(), setContent(Node)
  - expandableContentProperty
```
public ObjectProperty<Node> expandableContentProperty()
```
    A property that represents the dialog expandable content area. Any Node can be placed in this area, but it will only be shown when the user clicks the 'Show Details' expandable button. This button will be added automatically when the expandable content property is non-null.
    
    See Also:
    
    getExpandableContent(), setExpandableContent(Node)
  - getExpandableContent
```
public final Node getExpandableContent()
```
    Returns the dialog expandable content node, if one is set, or null otherwise.
  - setExpandableContent
```
public final void setExpandableContent(Node content)
```
    Sets the dialog expandable content node, or null if no expandable content needs to be shown.
  - getWidth
```
public final double getWidth()
```
    Returns the width of the dialog.
  - getHeight
```
public final double getHeight()
```
    Returns the height of the dialog.
  - getActions
```
public final ObservableList<Action> getActions()
```
    Observable list of actions used for the dialog ButtonBar. Modifying the contents of this list will change the actions available to the user.
    
    Returns:
    
    The ObservableList of actions available to the user.

Class Dialog

Code Examples

Property Summary

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Property Detail

resizable

graphic

masthead

content

expandableContent

Constructor Detail

Dialog

Dialog

Dialog

Method Detail

show

hide

resizableProperty

isResizable

setResizable

setIconifiable

setClosable

graphicProperty

getGraphic

setGraphic

getMasthead

setMasthead

setMasthead

mastheadProperty

getContent

setContent

setContent

contentProperty

expandableContentProperty

getExpandableContent

setExpandableContent

getWidth

getHeight

getActions