Reference Manual
Inti Logo
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:

Inti::Gtk::Window Inti::Gtk::Bin Inti::Gtk::Container Inti::Gtk::Widget Inti::Gtk::Object Inti::Atk::Implementor Inti::G::Object Inti::G::TypeInterface Inti::G::TypeInstance Inti::MemoryHandler Inti::G::TypeInstance Inti::ReferencedBase Inti::ReferencedBase Inti::Gtk::ColorSelectionDialog Inti::Gtk::FileSelection Inti::Gtk::FontSelectionDialog Inti::Gtk::MessageDialog List of all members.

Public Member Functions

Constructors
Accessors
Methods
Property Proxies
Signal Proxies

Protected Member Functions

Constructors
Signal Handlers

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: Main Page - Footer


Generated on Sun Sep 14 20:08:14 2003 for Inti by doxygen 1.3.2 written by Dimitri van Heesch, © 1997-2002