Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::Gtk::Dialog Class Reference

A GtkDialog C++ wrapper class. More...

`#include <inti/gtk/dialog.h>`

Inheritance diagram for Inti::Gtk::Dialog:

List of all members.

## Public Member Functions

Constructors

- Dialog ()
    Construct a new Dialog.
- Dialog (const String &title, Window *parent=0, DialogFlagsField flags=DIALOG_DESTROY_WITH_PARENT)
    Construct a new Dialog with the specified title, parent and creation flags.
- Dialog (const String &title, Window *parent, DialogFlagsField flags, const char *first_button_text,...)
    Construct a new Dialog with the specified title, parent, creation flags and buttons.
- virtual ~Dialog ()
    Destructor.

Accessors

- GtkDialog * gtk_dialog () const
    Get a pointer to the GtkDialog structure.
- GtkDialogClass * gtk_dialog_class () const
    Get a pointer to the GtkDialogClass structure.
- operator GtkDialog * () const
    Conversion operator; safely converts a Dialog to a GtkDialog pointer.
- VBox * client_area () const
    Returns the VBox which is the client area of the dialog box.
- HButtonBox * action_area () const
    Returns the HButtonBox which is the action area packed below the dividing HSeparator in the dialog.
- bool get_has_separator () const
    Returns true if the dialog has a separator.

Methods

- void add_action_widget (Widget &child, int response_id)
    Adds an activatable widget to the action area of a Dialog, connecting a signal handler that will emit the "response" signal on the dialog when the widget is activated.
- Button * add_button (const char *button_text, int response_id)
    Adds a button with the given text (or a stock button, if button_text is a stock ID) and sets things up so that clicking the button will emit the "response" signal with the given response_id.
- void add_buttons (const char *first_button_text,...)
    Adds more buttons, as specified in the null-terminated variable list of button text/response ID pairs.
- 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.
- 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.
- void response (int response_id)
    Emits the "response" signal with the given response ID.
- int run ()
    Blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed.
- void set_has_separator (bool setting)
    Sets whether the dialog has a separator above the buttons; true by default.

Property Proxies

- const HasSeparatorPropertyProxy prop_has_separator ()
    The dialog has a separator bar above its buttons (bool : Read / Write).

Signal Proxies

- const ResponseSignalProxy sig_response ()
    Connect to the response_signal; emmitted when an action widget is activated, the dialog receives a delete event, or the application programmer calls response().
- const CloseSignalProxy sig_close ()
    Connect to the close_signel; emitted when the user closes the dialog box by pressing the escape key (GDK_Escape).

## Protected Member Functions

Constructors

- Dialog (GtkDialog *dialog, bool reference=false)
    Construct a new Dialog from an existing GtkDialog.

Signal Handlers

- virtual void on_response (int response_id)
    Called when an action widget is activated, the dialog receives a delete event, or the application programmer calls response().
- virtual void on_close ()
    Called when the user closes the dialog box by pressing the escape key (GDK_Escape).

## Detailed Description

A GtkDialog C++ wrapper class.

Dialog boxes are a convenient way to prompt the user for a small amount of input, eg. to display a message, ask a question, or anything else that does not require extensive effort on the user's part. GTK+ treats a dialog as a window split vertically. The top section is the client area (a VBox), and is where widgets such as a Label or an Entry should be packed. The bottom area is known as the action area. This is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply. The two areas are separated by a HSeparator. They can be accessed with client_area() and action_area(), as can be seen from the example below.

A 'modal' dialog (that is, one which freezes the rest of the application from user input), can be created by calling Gtk::Window::set_modal() on the dialog. When constructing a dialog you can also pass the DIALOG_MODAL flag to make a dialog modal. If you add buttons to the dialog, clicking the button will emit a signal called "response" with a response ID that you specified. GTK+ will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the ResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the "response" signal will be emitted with a response ID of RESPONSE_NONE.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call Gtk::Dialog::run(). This method enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked. For the simple dialog in the following example, in reality, you'd probably use MessageDialog to save yourself some effort. But you'd need to create the dialog contents manually if you had more than a simple message in the dialog.

Example: A function to open a simple dialog box displaying the message provided.

        void MyWindow::quick_message(const String& message)
        {
            using namespace Gtk;

            // Creating the dialog on the stack is OK because it's only temporary. When finished, we dispose of it.
            Dialog dialog("Message", this, DIALOG_DESTROY_WITH_PARENT, GTK_STOCK_OK, RESPONSE_NONE, 0);

            // Add a label to the dialog to display the message.
            Label *label = new Label(message);
            dialog.client_area()->add(*label);
            label->show();

            // Run the dialog. You must call dispose(), not unref(), because the dialog is in a modal loop.
            if (dialog.run())
                    dialog.dispose();
        }

## Constructor & Destructor Documentation

Inti::Gtk::Dialog::Dialog | ( | GtkDialog * | dialog,
|  | bool | reference = false
| ) | `[explicit, protected]`

Construct a new Dialog from an existing GtkDialog.

Parameters:

  dialog | A pointer to a GtkDialog.
  reference | Set false if the initial reference count is floating, set true if it's not.

The dialog can be a newly created GtkDialog or an existing GtkDialog. (see G::Object::Object).

Inti::Gtk::Dialog::Dialog | ( |  | ) |

| Construct a new Dialog. Widgets should not be packed into this window directly, but into the client area and action area, as described above. You can add one or more buttons with add_button() or add_buttons().

Inti::Gtk::Dialog::Dialog | ( | const String & | title,
|  | Window * | parent = 0,
|  | DialogFlagsField | flags = DIALOG_DESTROY_WITH_PARENT
| ) |

Construct a new Dialog with the specified title, parent and creation flags.

Parameters:

  title | The title of the dialog.
  parent | Transient parent of the dialog, or null.
  flags | One or more flags from the DialogFlags enumeration OR'd together.

Widgets should not be packed into this window directly, but into the client area and action area, as described above. You can add one or more buttons with add_button() or add_buttons(). The flags argument can be used to make the dialog modal (DIALOG_MODAL) and/or to have it destroyed along with its transient parent (DIALOG_DESTROY_WITH_PARENT).

Inti::Gtk::Dialog::Dialog | ( | const String & | title,
|  | Window * | parent,
|  | DialogFlagsField | flags,
|  | const char * | first_button_text,
|  | ... |
| ) |

Construct a new Dialog with the specified title, parent, creation flags and buttons.

Parameters:

  title | The title of the dialog.
  parent | Transient parent of the dialog, or null.
  flags | One or more flags from the DialogFlags enumeration OR'd together.
  first_button_text | The stock ID or text to go in first button, or null.
  ... | The response ID for first button, then additional button text/response ID pairs, ending with null.

Widgets should not be packed into this window directly, but into the client area and action area, as described above. You can add one or more buttons with add_button() or add_buttons(). The flags argument can be used to make the dialog modal (DIALOG_MODAL) and/or to have it destroyed along with its transient parent (DIALOG_DESTROY_WITH_PARENT). After flags, button text/response ID pairs should be listed, with a NULL pointer ending the list. Button text can be either a stock ID such as GTK_STOCK_OK, or some arbitrary text. A response ID can be any positive number, or one of the values in the ResponseType enumeration. If the user clicks one of these dialog buttons, Dialog will emit the "response" signal with the corresponding response ID. If a Dialog receives the "delete_event" signal, it will emit "response" with a response ID of RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the "response" signal; so be careful relying on "response" when using the DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog.

## Member Function Documentation

HButtonBox* Inti::Gtk::Dialog::action_area | ( |  | ) | const

| Returns the HButtonBox which is the action area packed below the dividing HSeparator in the dialog. It is treated exactly the same as any other HButtonBox. You add your action widgets, usually buttons, to this area.

void Inti::Gtk::Dialog::add_action_widget | ( | Widget & | child,
|  | int | response_id
| ) |

Adds an activatable widget to the action area of a Dialog, connecting a signal handler that will emit the "response" signal on the dialog when the widget is activated.

Parameters:

  child | An activatable widget.
  response_id | The response ID for child.

The widget is appended to the end of the dialog's action area. If you want to add a non-activatable widget, simply pack it into the action_area of the Dialog.

Button* Inti::Gtk::Dialog::add_button | ( | const char * | button_text,
|  | int | response_id
| ) |

Adds a button with the given text (or a stock button, if button_text is a stock ID) and sets things up so that clicking the button will emit the "response" signal with the given response_id.

Parameters:

  button_text | The text of button, or stock ID.
  response_id | The response ID for the button.

Returns:
  The button widget that was added.

The button is appended to the end of the dialog's action area. The button widget is returned, but usually you don't need it.

void Inti::Gtk::Dialog::add_buttons | ( | const char * | first_button_text,
|  | ... |
| ) |

Adds more buttons, as specified in the null-terminated variable list of button text/response ID pairs.

Parameters:

  first_button_text | The stock ID or text to go in first button, or null.
  ... | The response ID for first button, then additional button text/response ID pairs, ending with null.

Widgets should not be packed into this window directly, but into the client_area and action_area, as described above. After first_button_text, button text/response ID pairs should be listed, with a null pointer ending the list. Button text can be either a stock ID such as GTK_STOCK_OK, or some arbitrary text. A response ID can be any positive number, or one of the values in the ResponseType enumeration. If the user clicks one of these dialog buttons, Dialog will emit the "response" signal with the corresponding response ID. If a Dialog receives the "delete_event" signal, it will emit "response" with a response ID of RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the "response" signal; so be careful relying on "response" when using the DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog.

This method is the same as calling add_button repeatedly.

VBox* Inti::Gtk::Dialog::client_area | ( |  | ) | const

| Returns the VBox which is the client area of the dialog box. You pack your widgets into this box.

virtual void Inti::Gtk::Dialog::on_response | ( | int | response_id | ) | `[protected, virtual]`

Called when an action widget is activated, the dialog receives a delete event, or the application programmer calls response().

Parameters:

  response_id | The response ID of the action widget.

On a delete event, the response ID is RESPONSE_NONE. Otherwise, it depends on which action widget was activated.

void Inti::Gtk::Dialog::response | ( | int | response_id | ) |

Emits the "response" signal with the given response ID.

Parameters:

  response_id | A response ID.

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.

int Inti::Gtk::Dialog::run | ( |  | ) |

Blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed.

Returns:
  Response ID

If the dialog is destroyed during the call to run(), 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 the "response" signal. 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.

Example: 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_cancelled();
                    break;
                 }
                 dialog->dispose();

void Inti::Gtk::Dialog::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.

Parameters:

  response_id | A response ID.

Pressing "Enter" normally activates the default widget.

void Inti::Gtk::Dialog::set_has_separator | ( | bool | setting | ) |

Sets whether the dialog has a separator above the buttons; true by default.

Parameters:

  setting | true to have a separator.

void Inti::Gtk::Dialog::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.

Parameters:

  response_id | A response ID.
  setting | true for sensitive.

A convenient way to sensitize/desensitize dialog buttons.

The documentation for this class was generated from the following file:

- dialog.h

Main Page - Footer