logo top
Main Page   Widgets   Namespaces   Book  

Gtk::Dialog Class Reference
[Dialogs]

Inheritance diagram for Gtk::Dialog:

List of all members.


Detailed Description

Create popup windows.

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.

gtkmm treats a dialog as a window split vertically. The top section is a Gtk::VBox, and is where widgets such as a Gtk::Label or a Gtk::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 Gtk::HSeparator.

The dialog can be 'modal' (that is, one which freezes the rest of the application from user input) - this can be specified in the Gtk::Dialog constructor.

When adding buttons using add_button(), clicking the button will emit signal_response() with a "response id" you specified. You are encouraged to use the Gtk::ResponseType enum. If a dialog receives a delete event, the "response" signal will be emitted with a response id of Gtk::RESPONSE_NONE.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call run(). This function 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.

Public Member Functions

void add_action_widget (Widget& child, int response_id)
 Adds an activatable widget to the action area of a Gtk::Dialog, connecting a signal handler that will emit the Gtk::Dialog::response signal on the dialog when the widget is activated.
Buttonadd_button (const Gtk::StockID& stock_id, 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 Gtk::Dialog::response signal with the given response_id.
Buttonadd_button (const Glib::ustring& 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 Gtk::Dialog::response signal with the given response_id.
 Dialog (const Glib::ustring& title, Gtk::Window& parent, bool modal=false, bool use_separator=false)
 Dialog (const Glib::ustring& title, bool modal=false, bool use_separator=false)
 Dialog ()
const HButtonBoxget_action_area () const
 Returns: the action area.
HButtonBoxget_action_area ()
 Returns: the action area.
bool get_has_separator () const
 Accessor for whether the dialog has a separator.
int get_response_for_widget (const Gtk::Widget& widget) const
 Gets the response id of a widget in the action area of a dialog.
const VBoxget_vbox () const
 Returns: the content area Gtk::VBox.
VBoxget_vbox ()
 Returns: the content area Gtk::VBox.
const GtkDialog* gobj () const
 Provides access to the underlying C GtkObject.
GtkDialog* gobj ()
 Provides access to the underlying C GtkObject.
Glib::PropertyProxy_ReadOnly
<bool> 
property_has_separator () const
 The dialog has a separator bar above its buttons.
Glib::PropertyProxy<bool> property_has_separator ()
 The dialog has a separator bar above its buttons.
void response (int response_id)
 Emits the Gtk::Dialog::response signal with the given response ID.
int run ()
 Blocks in a recursive main loop until the dialog emits the response signal.
void set_alternative_button_order_from_array (const Glib::ArrayHandle<int>& new_order)
 Sets an alternative button order.
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 set_has_separator (bool setting=true)
 Sets whether the dialog has a separator above the buttons.
void set_response_sensitive (int response_id, bool setting=true)
 Calls <literal>gtk_widget_set_sensitive (widget, setting)</literal> for each widget in the dialog's action area with the given response_id.
Glib::SignalProxy1<void, int> signal_response ()
virtual ~Dialog ()

Static Public Member Functions

static bool alternative_button_order (const Glib::RefPtr<const Gdk::Screen>& screen)
 Returns: Whether the alternative button order should be used.

Protected Member Functions

void construct_ (bool modal, bool use_separator)
virtual void on_response (int response_id)

Related Functions

(Note that these are not member functions.)

Gtk::Dialogwrap (GtkDialog* object, bool take_copy=false)
 A Glib::wrap() method for this object.


Constructor & Destructor Documentation

virtual Gtk::Dialog::~Dialog (  )  [virtual]

Gtk::Dialog::Dialog (  ) 

Gtk::Dialog::Dialog ( const Glib::ustring title,
bool  modal = false,
bool  use_separator = false 
) [explicit]

Gtk::Dialog::Dialog ( const Glib::ustring title,
Gtk::Window parent,
bool  modal = false,
bool  use_separator = false 
)


Member Function Documentation

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

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

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 field of the Gtk::Dialog struct.

Parameters:
child An activatable widget.
response_id Response ID for child.

Button* Gtk::Dialog::add_button ( const Gtk::StockID stock_id,
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 Gtk::Dialog::response signal with the given response_id.

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.

Parameters:
button_text Text of button, or stock ID.
response_id Response ID for the button.
Returns:
The button widget that was added.

Button* Gtk::Dialog::add_button ( const Glib::ustring 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 Gtk::Dialog::response signal with the given response_id.

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.

Parameters:
button_text Text of button, or stock ID.
response_id Response ID for the button.
Returns:
The button widget that was added.

static bool Gtk::Dialog::alternative_button_order ( const Glib::RefPtr<const Gdk::Screen>&  screen  )  [static]

Returns: Whether the alternative button order should be used.

Parameters:
screen A Gdk::Screen, or 0 to use the default screen.
Returns:
Whether the alternative button order should be used
Since gtkmm 2.6:

void Gtk::Dialog::construct_ ( bool  modal,
bool  use_separator 
) [protected]

const HButtonBox* Gtk::Dialog::get_action_area (  )  const

Returns: the action area.

Returns:
The action area.
Since gtkmm 2.14:

Reimplemented in Gtk::FileSelection.

HButtonBox* Gtk::Dialog::get_action_area (  ) 

Returns: the action area.

Returns:
The action area.
Since gtkmm 2.14:

Reimplemented in Gtk::FileSelection.

bool Gtk::Dialog::get_has_separator (  )  const

Accessor for whether the dialog has a separator.

Returns:
true if the dialog has a separator.

int Gtk::Dialog::get_response_for_widget ( const Gtk::Widget widget  )  const

Gets the response id of a widget in the action area of a dialog.

Parameters:
widget A widget in the action area of dialog.
Returns:
The response id of widget, or Gtk::RESPONSE_NONE if widget doesn't have a response id set.
Since gtkmm 2.8:

const VBox* Gtk::Dialog::get_vbox (  )  const

Returns: the content area Gtk::VBox.

Returns:
The content area Gtk::VBox.
Since gtkmm 2.14:

VBox* Gtk::Dialog::get_vbox (  ) 

Returns: the content area Gtk::VBox.

Returns:
The content area Gtk::VBox.
Since gtkmm 2.14:

const GtkDialog* Gtk::Dialog::gobj (  )  const [inline]

GtkDialog* Gtk::Dialog::gobj (  )  [inline]

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

Glib::PropertyProxy_ReadOnly<bool> Gtk::Dialog::property_has_separator (  )  const

The dialog has a separator bar above its buttons.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Gtk::Dialog::property_has_separator (  ) 

The dialog has a separator bar above its buttons.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

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

Emits the Gtk::Dialog::response signal with the given 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.

Parameters:
response_id Response ID.

int Gtk::Dialog::run (  ) 

Blocks in a recursive main loop until the dialog emits the response signal.

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.

If the dialog receives "delete_event", Gtk::Dialog::run() will return Gtk::RESPONSE_DELETE_EVENT. Also, during Gtk::Dialog::run() the dialog will be modal. You can force Gtk::Dialog::run() to return at any time by calling Gtk::Dialog::response() to emit the "response" signal.

After Gtk::Dialog::run() returns, you are responsible for hiding or destroying the dialog if you wish to do so.

Typical usage of this function might be:

 int result = dialog.run();
 switch (result)
 {
 case Gtk::RESPONSE_ACCEPT:
   do_application_specific_something();
   break;
 default:
   do_nothing_since_dialog_was_cancelled();
   break;
 }
Returns:
Response ID.

void Gtk::Dialog::set_alternative_button_order_from_array ( const Glib::ArrayHandle< int > &  new_order  ) 

Sets an alternative button order.

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.

By default, GTK+ dialogs use the button order advocated by the Gnome <ulink url="http://developer.gnome.org/projects/gup/hig/2.0/">Human Interface Guidelines</ulink> with the affirmative button at the far right, and the cancel button left of it. But the builtin GTK+ dialogs and GtkMessageDialogs do provide an alternative button order, which is more suitable on some platforms, e.g. Windows.

Use this function after adding all the buttons to your dialog

Parameters:
new_order an array of response ids of the dialog's buttons.

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

Pressing "Enter" normally activates the default widget.

Parameters:
response_id A response ID.

void Gtk::Dialog::set_has_separator ( bool  setting = true  ) 

Sets whether the dialog has a separator above the buttons.

true by default.

Parameters:
setting true to have a separator.

void Gtk::Dialog::set_response_sensitive ( int  response_id,
bool  setting = true 
)

Calls <literal>gtk_widget_set_sensitive (widget, setting)</literal> for each widget in the dialog's action area with the given response_id.

A convenient way to sensitize/desensitize dialog buttons.

Parameters:
response_id A response ID.
setting true for sensitive.

Glib::SignalProxy1< void,int > Gtk::Dialog::signal_response (  ) 

Prototype:
void on_my_response(int response_id)


Friends And Related Function Documentation

Gtk::Dialog* wrap ( GtkDialog *  object,
bool  take_copy = false 
) [related]

A Glib::wrap() method for this object.

Parameters:
object The C instance.
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.


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

Generated for gtkmm 2.4 by Doxygen 1.5.6 © 1997-2001