Constructor Detail

• Dialog

  public Dialog()

  Creates a new Dialog box with both main area and an empty action area, separated by an HSeparator. You'll need to do the rest of the Dialog setup manually yourself, including calling setTransientFor() and setTitle().

  Since:

  4.0.5

• Dialog

  public Dialog(String title,
        Window parent,
        boolean modal)

  Create a new Dialog. This is a convenience constructor with the same effect as:

   d = new Dialog();
   d.setTitle(title);
   d.setModal(modal);
   d.setTransientFor(parent);
   

  Parameters:

  title - Title of the new Dialog.

  parent - Transient parent of the dialog, or null. If a parent is provided, the window manager will keep the Dialog on top of it. If the Dialog is modal, it is highly recommended that you provide a parent Window, otherwise the user could be trying to interact with the main Window while the Dialog is blocking it, but hidden under other Window. In that case, the user experience is really bad, as it is not easy to figure out the real case of the blocking.

  modal - Whether the dialog is to be modal or not. A modal Dialog blocks interaction with the other parts of the application. Note that you can also get a similar behaviour using the run() method.

  Since:

  4.0.5

Method Detail

• add

  public void add(Widget widget)

  Add a Widget to the main area of the Dialog.

  Overrides:

  add in class Container

  Since:

  4.0.5

• addButton

  public Button addButton(Stock stock,
                 ResponseType response)

  Add a Button whose icon and label are taken from a given Stock. It is, as ever, recommended to use a Stock Button for common actions. See addButton().

  Since:

  4.0.5

• addButton

  public Button addButton(String text,
                 ResponseType response)

  Adds an action Button with the given text as its label to the end of the Dialog's action area. The given ResponseType will be returned back in the Dialog's Dialog.Response signal when the Button added as a result of this call is clicked.

  Returns:

  the added Button. This is a convenience allowing you to hook up further handlers to the Button if necessary.

  Since:

  4.0.5

• addButton

  public Button addButton(Widget widget,
                 ResponseType response)

  Add a Button Widget you've already constructed to the action area of this Dialog.

  It is, as ever, recommended to use a Stock Button for common actions. See addButton().

  You can pass any Activatable as the widget parameter.

  Since:

  4.0.14

• connect

  public void connect(Dialog.Response handler)

  Hook up a Dialog.Response handler.

• emitResponse

  public void emitResponse(ResponseType response)

  Cause a Dialog.Response signal with the specified ResponseType to be emitted by this Dialog.

  Since:

  4.0.9

• run

  public ResponseType run()

  Block the rest of the application by running in a recursive main loop until a Dialog.Response signal arises on the Dialog as a result of the user activating one of the action area Buttons. This is known as a 'modal' Dialog. While this loop is running the user is prevented from interacting with the rest of the application.

   response = dialog.run();
   
   dialog.hide();
   if (response == ResponseType.CANCEL) {
       return;
   }
   // take action!
   

  If you don't care about the response, just go ahead and hide() right away as soon as run() returns.

   dialog = new AboutDialog();
   dialog.run();
   dialog.hide();
   

  While there are legitimate uses of modal Dialogs, it is a feature that tends to be badly abused. Therefore, before you call this method, please consider carefully if it is wise to prevent the rest of the user interface from being used.

  A common bug is for people to neglect to hide() the Dialog after this method returns. If you don't, then the Dialog will remain on screen despite repeated clicking of (for example) the "Close" Button [the Window is not hidden automatically because of cases like "Apply" in preferences Dialogs and "Open" in FileChoosers when a folder is selected and activation will change directory rather than finishing the Dialog].

  While run() can be very useful in callbacks when popping up a quick question, you may find hooking up to the Dialog.Response signal more flexible.

  Warning
  Using this method will prevent other threads that use GTK from running. That's a bug as far as we're concerned, but if the goal is to display a dialog without blocking other threads that use GTK, it is better (for now) to call Window's present() and the connect() to the Dialog.Response signal.

   dialog.connect(new Dialog.Response() {
       public void onResponse(Dialog source, ResponseType response) {
           dialog.hide();
           if (response == ResponseType.CLOSE) {
               return;
           }
           // take action!
       }
   });
   
   dialog.present();
   

  Returns:

  the emitted response constant. If asking a question, you should check this against the various constants in the ResponseType class. Don't forget to hide() afterwards.

  Since:

  4.0.5

  See Also:

  the bug report

• setDefaultResponse

  public void setDefaultResponse(ResponseType response)

  Tell the Dialog which Button (which ResponseType) is to be activated when the user presses Enter.

  If you're calling this because you've created a custom Button with addButton(), you'll probably need to call Widget's setCanDefault() on that Button first, before using this.

  Note that calling Widget's grabDefault() is insufficient; Dialogs have some fairly tricky internal wiring, and you need to use this method instead.

  Since:

  4.0.17