org.gnome.gtk

## Class Dialog

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Widget
        - - org.gnome.gtk.Container
          - - org.gnome.gtk.Bin
            - - org.gnome.gtk.Window
              - - org.gnome.gtk.Dialog

- Direct Known Subclasses:
    AboutDialog, ColorSelectionDialog, FileChooserDialog, FontSelectionDialog, MessageDialog, PageSetupUnixDialog, PrintUnixDialog, RecentChooserDialog

      public class Dialog
      extends Window

  A Dialog is a special Window which is used to display information for the user or to get response from her. While a normal Window usually is used to represent the whole application and to offer sometimes many interactions for the user, a Dialog should only be opened if a special situation has occurred.

  A Dialog is a composite Window which contains a `VBox`. This box is split by an HSeparator into two areas:

  - The main area consists of the VBox itself above the separator. It is used to pack Widgets such as Labels or Icons which will display the descriptive part of your Dialog. The easiest way to add Widget(s) to the top area is to simply call the `add()` method. It is a good technique to first add your own Container such as an `HBox` to the top area and pack all other Widgets to it if you need more refined layout control, although this is not compulsory.

  - The bottom action area (actually an HButtonBox) is used to pack buttons to the Dialog which may perform actions such as "Ok" or "Cancel". You should only add Buttons to the action area using one of the `addButton()` methods allowing you to specify a ResponseType constant to be emitted if the Button is clicked.

  To open the Dialog as a normal non-blocking Window you use the `present()` method after you have packed the various child elements into it. On the other hand, for occasions where you are using a Dialog to get information required for the further progress of the main application, the `run()` method can be used to open the Dialog. This method blocks the application and waits for response from the user.

  Like any Window that you are finished with, you have to `hide()` when you receive a `Dialog.Response` callback, or after `run()` returns.

  GTK comes with a number of standard Dialogs which can be used for typical situations such as `MessageDialog` to present urgent information to the user, and `FileChooserDialog` which provides the familiar behaviour of popping up a Dialog to select a file.

  Since:
    4.0.5
  Author:
    Thomas Schmitz, Vreixo Formoso, Andrew Cowie

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Dialog.Response` This signal arises when a user activates one of the Widgets laid out in the action area of the Dialog.

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Window

      `Window.ConfigureEvent, Window.DeleteEvent`

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Widget

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.QueryTooltip, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Dialog()` Creates a new Dialog box with both main area and an empty action area, separated by an HSeparator.
    `Dialog(String title, Window parent, boolean modal)` Create a new Dialog.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(Widget widget)` Add a Widget to the main area of the Dialog.
    `Button` | `addButton(Stock stock, ResponseType response)` Add a Button whose icon and label are taken from a given Stock.
    `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.
    `Button` | `addButton(Widget widget, ResponseType response)` Add a Button Widget you've already constructed to the action area of this Dialog.
    `void` | `connect(Dialog.Response handler)` Hook up a `Dialog.Response` handler.
    `void` | `emitResponse(ResponseType response)` Cause a `Dialog.Response` signal with the specified ResponseType to be emitted by this Dialog.
    `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.
    `void` | `setDefaultResponse(ResponseType response)` Tell the Dialog which Button (which ResponseType) is to be activated when the user presses `Enter`.

    - ### Methods inherited from class org.gnome.gtk.Window

      `addAcceleratorGroup, connect, connect, getHeight, getMaximized, getPositionX, getPositionY, getScreen, getWidth, move, present, resize, setDecorated, setDefaultSize, setFullscreen, setGravity, setHasResizeGrip, setIcon, setIcon, setKeepAbove, setKeepBelow, setMaximize, setModal, setPosition, setResizable, setSkipPagerHint, setSkipTaskbarHint, setStick, setTitle, setTransientFor, setTypeHint`

    - ### Methods inherited from class org.gnome.gtk.Bin

      `getChild`

    - ### Methods inherited from class org.gnome.gtk.Container

      `getChildren, remove, setBorderWidth`

    - ### Methods inherited from class org.gnome.gtk.Widget

      `activate, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### 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