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:

Xfc::Gtk::Window Xfc::Gtk::Bin Xfc::Gtk::Container Xfc::Gtk::Widget Xfc::Gtk::Object Xfc::Atk::Implementor Xfc::G::Object Xfc::G::TypeInterface Xfc::G::TypeInstance Xfc::G::TypeInstance Xfc::Trackable Xfc::Trackable Xfc::Gtk::AboutDialog Xfc::Gtk::ColorSelectionDialog Xfc::Gtk::FileChooserDialog Xfc::Gtk::FontSelectionDialog Xfc::Gtk::MessageDialog Xfc::Gtk::FileChooserOpenDialog Xfc::Gtk::FileChooserSaveAsDialog List of all members.

Signal Prototypes

Public Member Functions

Constructors
Accessors
Methods
Signal Proxies

Static Public Member Functions

Accessors

Protected Member Functions

Constructors
Methods

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: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3