Xfce Foundation Classes

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:

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 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':

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.

There are three methods you can call to add a button to the action area of the dialog:

 Button* add_button(const String&
button_text, int response_id);

      

Button* add_button(const
StockId& stock_id, int
response_id);

    

Button* add_button(StockButtonType button_type);

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:

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

STOCK_BUTTON_OK - a stock OK button that returns the id Gtk::RESPONSE_OK.
STOCK_BUTTON_CANCEL - a stock CANCEL button that returns the id Gtk::RESPONSE_CANCEL.
STOCK_BUTTON_CLOSE - a stock CLOSE button that returns the id Gtk::RESPONSE_CLOSE.
STOCK_BUTTON_YES - a stock YES button that returns the id Gtk::RESPONSE_YES.
STOCK_BUTTON_NO - a stock NO button that returns the id Gtk::RESPONSE_NO.
STOCK_BUTTON_APPLY - stock APPLY button that returns the id Gtk::RESPONSE_APPLY.
STOCK_BUTTON_HELP - stock HELP button that returns the id Gtk::RESPONSE_HELP.

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, 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.

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

void
set_default_response(int response_id);

Pressing 'Enter' normally activates the default widget.

The following method is a convenient way to sensitize/desensitize dialog buttons:

void
set_response_sensitive(int response_id, bool setting)

This calls Gtk::Widget::set_sensitive(setting) for each widget in the dialog's action area with the given 'response_id'.

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:

int
result = dialog->run();

switch (result)

{

case RESPONSE_ACCEPT:

    do_application_specific_something();

    break;

      

default:

    do_nothing_since_dialog_was_canceled();

    break;

}

dialog->dispose();