org.gnome.gtk
Class Dialog

Object
  org.freedesktop.bindings.Pointer
      org.freedesktop.bindings.Proxy
          org.gnome.glib.Object
              org.gnome.gtk.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

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

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

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD