gtkmm: Gtk::Dialog Class Reference

Create popup windows. More...

Inheritance diagram for Gtk::Dialog:

Collaboration diagram for Gtk::Dialog:

Public Member Functions
virtual	~Dialog ()
GtkDialog*	gobj ()
	Provides access to the underlying C GtkObject.
const GtkDialog*	gobj () const
	Provides access to the underlying C GtkObject.
	Dialog ()
	Dialog (const Glib::ustring& title, bool modal=false)
	Dialog (const Glib::ustring& title, Gtk::Window& parent, bool modal=false)
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.
Button*	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.
Button*	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.
void	set_response_sensitive (int response_id, bool setting=true)
	Calls `gtk_widget_set_sensitive (widget, 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.
Widget*	get_widget_for_response (int response_id)
	Gets the widget button that uses the given response ID in the action area of a dialog.
const Widget*	get_widget_for_response (int response_id) const
	Gets the widget button that uses the given response ID in the action area of a dialog.
int	get_response_for_widget (const Gtk::Widget& widget) const
	Gets the response id of a widget in the action area of a dialog.
void	set_alternative_button_order_from_array (const std::vector< int >& new_order)
	Sets an alternative button order.
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.
ButtonBox*	get_action_area ()
	Returns the action area of dialog.
const ButtonBox*	get_action_area () const
	Returns the action area of dialog.
Box*	get_vbox ()
	Returns the content area of dialog.
const Box*	get_vbox () const
	Returns the content area of dialog.
Glib::SignalProxy1< void, int >	signal_response ()
Static Public Member Functions
static bool	alternative_button_order (const Glib::RefPtr< const Gdk::Screen >& screen)
	Returns `true` if dialogs are expected to use an alternative button order on the screen screen.
Protected Member Functions
virtual void	on_response (int response_id)
Related Functions
(Note that these are not member functions.)
Gtk::Dialog*	wrap (GtkDialog* object, bool take_copy=false)
	A Glib::wrap() method for this object.

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.

Constructor & Destructor Documentation

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

Gtk::Dialog::Dialog ( )

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

Gtk::Dialog::Dialog	(	const Glib::ustring &	title,
		Gtk::Window&	parent,
		bool	modal = `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 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.

Button* Gtk::Dialog::add_button	(	const Gtk::StockID&	stock_id,
		int	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 true if dialogs are expected to use an alternative button order on the screen screen.

See Gtk::Dialog::set_alternative_button_order() for more details about alternative button order.

If you need to use this function, you should probably connect to the ::notify:gtk-alternative-button-order signal on the Gtk::Settings object associated to screen, in order to be notified if the button order setting changes.

Since gtkmm 2.6:

Parameters:

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

Returns:: Whether the alternative button order should be used.

ButtonBox* Gtk::Dialog::get_action_area ( )

Returns the action area of dialog.

Since gtkmm 2.14:

Returns:: The action area.

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

Returns the action area of dialog.

Since gtkmm 2.14:

Returns:: The action area.

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.

Since gtkmm 2.8:

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.

Box* Gtk::Dialog::get_vbox ( )

Returns the content area of dialog.

Since gtkmm 2.14:

Returns:: The content area Gtk::VBox.

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

Returns the content area of dialog.

Since gtkmm 2.14:

Returns:: The content area Gtk::VBox.

Widget* Gtk::Dialog::get_widget_for_response ( int response_id )

Gets the widget button that uses the given response ID in the action area of a dialog.

Since gtkmm 2.20:

Parameters:

response_id The response ID used by the dialog widget.

Returns:: The widget button that uses the given response_id, or 0.

const Widget* Gtk::Dialog::get_widget_for_response ( int response_id ) const

Gets the widget button that uses the given response ID in the action area of a dialog.

Since gtkmm 2.20:

Parameters:

response_id The response ID used by the dialog widget.

Returns:: The widget button that uses the given response_id, or 0.

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

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Window.

Reimplemented in Gtk::AboutDialog, Gtk::AppChooserDialog, Gtk::ColorSelectionDialog, Gtk::FileChooserDialog, Gtk::FontSelectionDialog, Gtk::MessageDialog, Gtk::RecentChooserDialog, Gtk::PageSetupUnixDialog, and Gtk::PrintUnixDialog.

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

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Window.

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

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: <informalexample><programlisting> int result = dialog.run(); switch (result) { case Gtk::RESPONSE_ACCEPT: do_application_specific_something(); break; default: do_nothing_since_dialog_was_cancelled(); break; } </programlisting></informalexample>

Returns:: Response ID.

void Gtk::Dialog::set_alternative_button_order_from_array ( const std::vector< 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_response_sensitive	(	int	response_id,
		bool	setting = `true`
	)

Calls gtk_widget_set_sensitive (widget, setting) 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:

gtkmm/dialog.h

gtkmm: Gtk::Dialog Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation