Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::Gtk::Dialog Class Reference

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

`#include <xfc/gtk/dialog.hh>`

Inheritance diagram for Xfc::Gtk::Dialog:

List of all members.

## Signal Prototypes

- const ResponseSignalType response_signal
    Response signal (see signal_response()).
- const CloseSignalType close_signal
    Close signal (see signal_close()).

## 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.
- virtual ~Dialog ()
    Destructor.

Accessors

- GtkDialog * gtk_dialog () const
    Get a pointer to the GtkDialog 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 String &button_text, int response_id)
    Adds a button with the given text and sets things up so that clicking the button will emit a "response" signal with the given response_id.
- Button * add_button (const StockId &stock_id, int response_id)
    Adds a stock button and sets things up so that clicking the button will emit a "response" signal with the given response_id.
- Button * add_button (StockButtonType button_type)
    Adds the stock button button_type and sets things up so that clicking the button will emit a "response" signal with the associated response_id.
- 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.
- void set_alternative_button_order (int n_params, int *new_order)
    Sets an alternative button order.

Signal Proxies

- const ResponseSignalProxy signal_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 signal_close ()
    Connect to the close_signel; emitted when the user closes the dialog box by pressing the escape key (GDK_Escape).

## Static Public Member Functions

Accessors

- bool alternative_button_order (const Gdk::Screen *screen=0)
    Determines whether dialogs are expected to use an alternative button order on screen.

## Protected Member Functions

Constructors

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

Methods

- void construct (const char *title, Gtk::Window *parent, Gtk::DialogFlagsField flags)
    Construction method that sets the title, parent and dialog flags.

## 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, StockId::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();
        }

See also: the Dialog HOWTO.

## Constructor & Destructor Documentation

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

Construct a new Dialog from an existing GtkDialog.

Parameters:

  | dialog | A pointer to a GtkDialog.
  | owns_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).

Xfc::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().

Xfc::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 Gdk::DialogFlags 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).

## Member Function Documentation

HButtonBox* Xfc::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 Xfc::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* Xfc::Gtk::Dialog::add_button | ( | StockButtonType | button_type | ) |

Adds the stock button button_type and sets things up so that clicking the button will emit a "response" signal with the associated response_id.

Parameters:

  | button_type | The Gtk::StockButtonType.

The button_type specifies the stock button to add and the repsonse id to return when the stock button is clicked. This is a convenience method that is eqivalent to calling add_button(const StockId&, int).

Button* Xfc::Gtk::Dialog::add_button | ( | const StockId & | stock_id,
|  | int | response_id
| ) |

Adds a stock button and sets things up so that clicking the button will emit a "response" signal with the given response_id.

Parameters:

  | stock_id | The ID of the stock item.
  | 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.

Button* Xfc::Gtk::Dialog::add_button | ( | const String & | button_text,
|  | int | response_id
| ) |

Adds a button with the given text and sets things up so that clicking the button will emit a "response" signal with the given response_id.

Parameters:

  | button_text | The text of the button.
  | 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.

bool Xfc::Gtk::Dialog::alternative_button_order | ( | const Gdk::Screen * | screen = `0` | ) | `[static]`

Determines whether dialogs are expected to use an alternative button order on screen.

Parameters:

  | screen | A Gdk::Screen, or null to use the default screen.

Returns:
  true if the dialogs are expected to use an alternative button order.

If you need to use this function, you should probably connect to the G::Object "notify_signal::gtk-alternative-button-order" signal on the GtkSettings object associated to screen, in order to be notified if the button order setting changes. See set_alternative_button_order() for more details about alternative button order.

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

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

void Xfc::Gtk::Dialog::construct | ( | const char * | title,
|  | Gtk::Window * | parent,
|  | Gtk::DialogFlagsField | flags
| ) | `[protected]`

Construction method that sets the title, parent and dialog flags.

Parameters:

  | title | The dialiog box title.
  | parent | A pointer to the parent for the dialog box, or null for no parent.
  | flags | The Gdk::DialogFlags to set.

This is a convenience method that can be called from dialog box constructors to set the dialog box title, parent and flags in one call. It is used internally by Gtk::Dialog. If parent is set, the dialog is set transient for that parent.

void Xfc::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 Xfc::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 Xfc::Gtk::Dialog::set_alternative_button_order | ( | int | n_params,
|  | int * | new_order
| ) |

Sets an alternative button order.

Parameters:

  | n_params | The number of response ids in new_order.
  | new_order | An array of response ids of the dialog's buttons.

If the "gtk-alternative-button-order" setting is set to true, the dialog buttons are reordered according to the order of the response ids in new_order. Call this method after adding all the buttons to your dialog.

void Xfc::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 Xfc::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 Xfc::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.

## Member Data Documentation

const CloseSignalType Xfc::Gtk::Dialog::close_signal `[static, protected]`

Close signal (see signal_close()).

Calls a slot with the signature:

                 void function();

const ResponseSignalType Xfc::Gtk::Dialog::response_signal `[static, protected]`

Response signal (see signal_response()).

Calls a slot with the signature:

                 void function(int response_id);
                 // response_id: The response ID of the action widget.

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

- dialog.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3