|« Main Page | Index|
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 two constructors to create a new Dialog:
The first constructor creates 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:
And you could add to the client_area by packing, for instance, a label in it, try something like this:
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 message. 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 constructor is for convenience and lets you set the 'title' for the dialog box, the 'parent' if the dialog box is modal, and one or more dialog 'flags':
All three methods return a pointer to the newly created button that was added, but normally you wont use it. The first method takes two arguments, the button text and the response id. The second method takes one of the stock id's list in <xfc/gtk/stockid.hh> and the response id.
A response id can be any positive number, or one of the values in the Gtk::ResponseType enum:
If the user clicks one of the 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 a response signal 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.The easiest way to display a modal dialog is to let Gtk::Dialog do it for you by calling its run() method:
The last add_button() method takes a stock button type which corresponds the a predefined stock id and response id pair. It can be one of the values from the Gtk::StockButtonType enum:
This blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed. If the dialog is destroyed, run() returns RESPONSE_NONE. Otherwise, it returns the response id from the response signal emission. Before entering the recursive main loop, run() calls Gtk::Widget::show() on the dialog for you. Note that you still need to show any children of the dialog yourself.
During run(), the default behavior of 'delete_event' is disabled; if the dialog receives a delete_event, it will not be destroyed as windows usually are, and run() will return RESPONSE_DELETE_EVENT. Also, during run() the dialog will be modal. You can force run() to return at any time by calling response() to emit a response signal.
This method is used to indicate that the user has responded to the dialog in some way; typically either you or run() will be monitoring the response signal and take appropriate action.
You can set 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.
The following method is a convenient way to sensitize/desensitize dialog buttons:
Destroying the dialog during run() is a very bad idea, because your post-run code won't know whether the dialog was destroyed or not. After run() returns, you are responsible for hiding or destroying the dialog if you wish to do so.
Typical usage of the run() method might be: