1Gtk2::Dialog(3) User Contributed Perl Documentation Gtk2::Dialog(3)
2
6 Gtk2::Dialog
7
9 # create a new dialog with some buttons - one stock, one not.
10 $dialog = Gtk2::Dialog->new ($title, $parent_window, $flags,
11 'gtk-cancel' => 'cancel',
12 'Do it' => 'ok');
13 # create window contents for yourself.
14 $dialog->get_content_area ()->add ($some_widget);
15 $dialog->set_default_response ('ok');
17 # show and interact modally -- blocks until the user
19 # activates a response.
20 $response = $dialog->run;
21 if ($response eq 'ok') {
22 do_the_stuff ();
23 }
24 # activating a response does not destroy the window,
26 # that's up to you.
27 $dialog->destroy;
28
30 Dialog boxes are a convenient way to prompt the user for a small amount
31 of input, eg. to display a message, ask a question, or anything else
32 that does not require extensive effort on the user's part.
33 GTK+ treats a dialog as a window split vertically. The top section is a
35 Gtk2::VBox, and is where widgets such as a Gtk2::Label or a Gtk2::Entry
36 should be packed. The bottom area is known as the "action_area". This
37 is generally used for packing buttons into the dialog which may perform
38 functions such as cancel, ok, or apply. The two areas are separated by
39 a Gtk2::HSeparator.
40 GtkDialog boxes are created with a call to "Gtk2::Dialog->new". The
42 multi-argument form (and its alias, "new_with_buttons" is recommended;
43 it allows you to set the dialog title, some convenient flags, and add
44 simple buttons all in one go.
45 If $dialog is a newly created dialog, the two primary areas of the
47 window can be accessed as "$dialog->get_content_area ()" and
48 "$dialog->get_action_area ()", as can be seen from the example, below.
49 A 'modal' dialog (that is, one which freezes the rest of the
51 application from user input), can be created by calling the
52 Gtk2::Window method "set_modal" on the dialog. You can also pass the
53 'modal' flag to "new".
54 If you add buttons to GtkDialog using "new", "new_with_buttons",
56 "add_button", "add_buttons", or "add_action_widget", clicking the
57 button will emit a signal called "response" with a response ID that you
58 specified. GTK+ will never assign a meaning to positive response IDs;
59 these are entirely user-defined. But for convenience, you can use the
60 response IDs in the Gtk2::ResponseType enumeration. If a dialog
61 receives a delete event, the "response" signal will be emitted with a
62 response ID of 'delete-event'.
63 If you want to block waiting for a dialog to return before returning
65 control flow to your code, you can call "$dialog->run". This function
66 enters a recursive main loop and waits for the user to respond to the
67 dialog, returning the response ID corresponding to the button the user
68 clicked.
69 For the simple dialog in the following example, in reality you'd
71 probably use Gtk2::MessageDialog to save yourself some effort. But
72 you'd need to create the dialog contents manually if you had more than
73 a simple message in the dialog.
74 # Function to open a dialog box displaying the message provided.
76 sub quick_message {
78 my $message = shift;
79 my $dialog = Gtk2::Dialog->new ('Message', $main_app_window,
80 'destroy-with-parent',
81 'gtk-ok' => 'none');
82 my $label = Gtk2::Label->new (message);
83 $dialog->get_content_area ()->add ($label);
84 # Ensure that the dialog box is destroyed when the user responds.
86 $dialog->signal_connect (response => sub { $_[0]->destroy });
87 $dialog->show_all;
89 }
90 Delete, Close and Destroy
92 In the default keybindings the "Esc" key calls the "close" action
93 signal. The default in that signal is to synthesise a "delete-event"
94 like a window manager close would do.
95 A delete-event first runs the "response" signal with ID "delete-event",
97 but the handler there can't influence the default destroy behaviour of
98 the "delete-event" signal. See Gtk2::Window for notes on destroy vs
99 hide.
100 If you add your own "Close" button to the dialog, perhaps using the
102 builtin "close" response ID, you must make your "response" signal
103 handler do whatever's needed for closing. Often a good thing is just
104 to run the "close" action signal the same as the Esc key.
105 sub my_response_handler {
107 my ($dialog, $response) = @_;
108 if ($response eq 'close') {
109 $self->signal_emit ('close');
110 } elsif ...
112 }
113
115 Glib::Object
116 +----Glib::InitiallyUnowned
117 +----Gtk2::Object
118 +----Gtk2::Widget
119 +----Gtk2::Container
120 +----Gtk2::Bin
121 +----Gtk2::Window
122 +----Gtk2::Dialog
123
125 Glib::Object::_Unregistered::AtkImplementorIface
126 Gtk2::Buildable
127
129 $widget = Gtk2::Dialog->new;
130 $widget = Gtk2::Dialog->new ($title, $parent, $flags, ...)
131 · ... (list) of button-text => response-id pairs.
132 · $flags (Gtk2::DialogFlags) interesting properties
134 · $parent (Gtk2::Window or undef) make the new dialog transient
136 for this window
137 · $title (string) window title
139 The multi-argument form takes the same list of text => response-id
141 pairs as "$dialog->add_buttons". Do not pack widgets directly into
142 the window; add them to "$dialog->get_content_area ()".
143 Here's a simple example:
145 $dialog = Gtk2::Dialog->new ('A cool dialog',
147 $main_app_window,
148 [qw/modal destroy-with-parent/],
149 'gtk-ok' => 'accept',
150 'gtk-cancel' => 'reject');
151 $widget = Gtk2::Dialog->new_with_buttons ($title, $parent, $flags, ...)
153 · ... (list) of button-text => response-id pairs.
154 Alias for the multi-argument version of "Gtk2::Dialog->new".
156 widget = $dialog->get_action_area
158 $dialog->add_action_widget ($child, $response_id)
159 · $child (Gtk2::Widget)
160 · $response_id (Gtk2::ResponseType)
162 widget = $dialog->add_button ($button_text, $response_id)
164 · $button_text (string) may be arbitrary text with mnenonics, or
165 stock ids
166 · $response_id (Gtk2::ResponseType)
168 Returns the created button.
170 $dialog->add_buttons (...)
172 · ... (list) of button-text => response-id pairs
173 Like calling "$dialog->add_button" repeatedly, except you don't get
175 the created widgets back. The buttons go from left to right, so
176 the first button added will be the left-most one.
177 $dialog->set_alternative_button_order (...)
179 · ... (list)
180 Since: gtk+ 2.6
182 widget = $dialog->get_content_area
184 $dialog->set_default_response ($response_id)
185 · $response_id (Gtk2::ResponseType)
186 boolean = $dialog->get_has_separator
188 $dialog->set_has_separator ($setting)
189 · $setting (boolean)
190 $dialog->response ($response_id)
192 · $response_id (Gtk2::ResponseType)
193 Emit the response signal, as though the user had clicked on the
195 button with $response_id.
196 scalar = $dialog->get_response_for_widget ($widget)
198 · $widget (Gtk2::Widget)
199 Since: gtk+ 2.8
201 $dialog->set_response_sensitive ($response_id, $setting)
203 · $response_id (Gtk2::ResponseType)
204 · $setting (boolean)
206 Enable or disable an action button by its $response_id.
208 $responsetype = $dialog->run
210 Blocks in a recursive main loop until the dialog either emits the
211 response signal, or is destroyed. If the dialog is destroyed
212 during the call to "$dialog->run", the function returns
213 'GTK_RESPONSE_NONE' ('none'). Otherwise, it returns the response
214 ID from the "response" signal emission. Before entering the
215 recursive main loop, "$dialog->run" calls "$widget->show" on
216 $dialog for you. Note that you still need to show any children of
217 the dialog yourself.
218 During "run", the default behavior of "delete_event" is disabled;
220 if the dialog receives "delete_event", it will not be destroyed as
221 windows usually are, and "run" will return 'delete-event'. Also,
222 during "run" the dialog will be modal. You can force "run" to
223 return at any time by calling "$dialog->response" to emit the
224 "response" signal. Destroying the dialog during "run" is a very
225 bad idea, because your post-run code won't know whether the dialog
226 was destroyed or not.
227 After "run" returns, you are responsible for hiding or destroying
229 the dialog if you wish to do so.
230 Typical usage of this function might be:
232 if ('accept' eq $dialog->run) {
234 do_application_specific_something ();
235 } else {
236 do_nothing_since_dialog_was_cancelled ();
237 }
238 $dialog->destroy;
239
241 'has-separator' (boolean : readable / writable / private)
242 The dialog has a separator bar above its buttons
243
245 response (Gtk2::Dialog, integer)
246 close (Gtk2::Dialog)
247 Note that currently in a Perl subclass of "Gtk2::Dialog" a class
249 closure, ie. class default signal handler, for the "response" signal
250 will be called with the response ID just as an integer, it's not turned
251 into an enum string like "ok" the way a handler setup with
252 "signal_connect" receives.
253 Hopefully this will change in the future, so don't count on it. In the
255 interim the easiest thing to do is install your default handler in
256 "INIT_INSTANCE" with a "signal_connect". (The subtleties of what order
257 handlers are called in will differ, but often that doesn't matter.)
258
260 flags Gtk2::DialogFlags
261 · 'modal' / 'GTK_DIALOG_MODAL'
262 · 'destroy-with-parent' / 'GTK_DIALOG_DESTROY_WITH_PARENT'
264 · 'no-separator' / 'GTK_DIALOG_NO_SEPARATOR'
266 enum Gtk2::ResponseType
268 The response type is somewhat abnormal as far as gtk2-perl enums go.
269 In C, this enum lists named, predefined integer values for a field that
270 is other composed of whatever integer values you like. In Perl, we
271 allow this to be either one of the string constants listed here or any
272 positive integer value. For example, 'ok', 'cancel', 4, and 42 are all
273 valid response ids. You cannot use arbitrary string values, they must
274 be integers. Be careful, because unknown string values tend to be
275 mapped to 0.
276 · 'none' / 'GTK_RESPONSE_NONE'
278 · 'reject' / 'GTK_RESPONSE_REJECT'
280 · 'accept' / 'GTK_RESPONSE_ACCEPT'
282 · 'delete-event' / 'GTK_RESPONSE_DELETE_EVENT'
284 · 'ok' / 'GTK_RESPONSE_OK'
286 · 'cancel' / 'GTK_RESPONSE_CANCEL'
288 · 'close' / 'GTK_RESPONSE_CLOSE'
290 · 'yes' / 'GTK_RESPONSE_YES'
292 · 'no' / 'GTK_RESPONSE_NO'
294 · 'apply' / 'GTK_RESPONSE_APPLY'
296 · 'help' / 'GTK_RESPONSE_HELP'
298
300 Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object, Gtk2::Widget,
301 Gtk2::Container, Gtk2::Bin, Gtk2::Window
302
304 Copyright (C) 2003-2008 by the gtk2-perl team.
305 This software is licensed under the LGPL. See Gtk2 for a full notice.
307perl v5.12.0 2010-05-02 Gtk2::Dialog(3)