### Tutorial

« Progress Bars | MessageDialog »

## Dialogs

The Dialog widget is very simple, and is actually just a window with a few things pre-packed into it for you. Simply, it creates a window, and then packs a vertical box called the "client_area" into the top, which contains a separator and then a horizontal box called the "action_area".
The Dialog widget can be used for pop-up messages to the user, and other similar tasks. There are three constructors to create a new Dialog.

`Dialog(); Dialog(const String& title, Gtk::Window *parent = 0, Gtk::DialogFlagsField flags = Gtk::DIALOG_DESTROY_WITH_PARENT); Dialog(const String& title, Gtk::Window *parent, Gtk::DialogFlagsField flags, const char*first_button_text, ...);`

The first constructor will create an empty dialog, leaving it up to you to use it. You could pack a button in the action_area by doing something like this:

`Gtk::Button *button = new Gtk::Button("OK"); dialog->action_area()->pack_start(*button); button->show();`

And you could add to the client_area by packing, for instance, a label in it, try something like this:

`Gtk::Label *label = new Gtk::Dialog("Dialogs are groovy"); dialog->client_area()->pack_start (*label); label->show();`

As an example in using the dialog box, you could put two buttons in the action_area, a Cancel button and an Ok button, and a label in the client_area, asking the user a question or giving an error etc. Then you could attach a different signal to each of the buttons and perform the operation the user selects.
If the simple functionality provided by the default vertical and horizontal boxes in the two areas doesn't give you enough control for your application, then you can simply pack another layout widget into the boxes provided. For example, you could pack a table into the client_area.
The last two constructors are for convenience and let you set the title for the dialog box, the parent if the dialog box is modal, and one or more dialog flags:

- DIALOG_MODAL - make the dialog modal
- DIALOG_DESTROY_WITH_PARENT - ensures that the dialog window is destroyed together with the specified parent.
- DIALOG_NO_SEPARATOR - omits the separator between the client_area and the action_area.

After the flags argument the last constructor takes a variable argument list of button text/response ID pairs, with a null pointer ending the list. Button text can be either a stock ID such as GTK_STOCK_OK, or some arbitrary text but must be a C-style character string, not a String object. A response ID can be any positive number, or one of the values in the Gtk::ResponseType enumeration.

- RESPONSE_NONE
- RESPONSE_REJECT
- RESPONSE_ACCEPT
- RESPONSE_DELETE_EVENT
- RESPONSE_OK
- RESPONSE_CANCEL
- RESPONSE_CLOSE
- RESPONSE_YES
- RESPONSE_NO
- RESPONSE_APPLY
- RESPONSE_HELP

If the user clicks one of these dialog buttons, Gtk::Dialog will emit the response signal with the corresponding response ID. If a Gtk::Dialog receives the delete_event signal, it will emit`` response with a response ID of Gtk::RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the response signal; so be careful relying on response when using the Gtk::DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the left most button in the dialog.
You can use one the following methods to either add a single button or several buttons at once using a variable argument list of button text/response ID pairs, as in the last constructor.

`Gtk::Button* add_button(const char *button_text, int response_id); void add_buttons(const char *first_button_text, ...);`

The easiest way to display a modal dialog is to let Gtk::Dialog do it for you by calling its run() method:

`int run();`

This blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed. If the dialog is destroyed, Gtk::Dialog::run() returns Gtk::RESPONSE_NONE. Otherwise, it returns the response ID from the response signal emission. Before entering the recursive main loop, Gtk::Dialog::run() calls Gtk::Widget::show() on the dialog for you. Note that you still need to show any children of the dialog yourself.
During Gtk::Dialog::run(), the default behavior of delete_event is disabled; if the dialog receives delete_event, it will not be destroyed as windows usually are, and Gtk::Dialog::run() will return Gtk::RESPONSE_DELETE_EVENT. Also, during Gtk::Dialog::run() the dialog will be modal. You can force Gtk::Dialog::run() to return at any time by calling Gtk::Dialog::response() to emit the response signal. Destroying the dialog during Gtk::Dialog::run() is a very bad idea, because your post-run code won't know whether the dialog was destroyed or not.
After Gtk::Dialog::run() returns, you are responsible for hiding or destroying the dialog if you wish to do so.
Typical usage of this method might be:

`int result = dialog->run(); switch (result) { case RESPONSE_ACCEPT: do_application_specific_something(); break; default: do_nothing_since_dialog_was_canceled(); break; } dialog->dispose();`

You can emit the response signal with a specified response ID by calling:

`void response(int response_id);`

This method is used to indicate that the user has responded to the dialog in some way; typically either you or Gtk::Dialog::run() will be monitoring the response signal and take appropriate action.

`void set_default_response(int response_id);`

Sets the last widget in the dialog's action area with the given response_id as the default widget for the dialog. Pressing "Enter" normally activates the default widget.

`void set_response_sensitive(int response_id, bool setting);`

Calls Gtk::Widget::set_sensitive(setting) for each widget in the dialog's action area with the given response_id. A convenient way to sensitize/desensitize dialog buttons.

« Progress Bars | Index Miscellaneous Widgets Top | MessageDialog »