1Gtk2::Dialog(3) User Contributed Perl Documentation Gtk2::Dialog(3)
2
6 Gtk2::Dialog - wrapper for GtkDialog
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 for
136 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 the
142 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 the
175 created widgets back. The buttons go from left to right, so the first
176 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 button
195 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 during
212 the call to "$dialog->run", the function returns 'GTK_RESPONSE_NONE'
213 ('none'). Otherwise, it returns the response ID from the "response"
214 signal emission. Before entering the recursive main loop,
215 "$dialog->run" calls "$widget->show" on $dialog for you. Note that you
216 still need to show any children of the dialog yourself.
217 During "run", the default behavior of "delete_event" is disabled; if
219 the dialog receives "delete_event", it will not be destroyed as windows
220 usually are, and "run" will return 'delete-event'. Also, during "run"
221 the dialog will be modal. You can force "run" to return at any time by
222 calling "$dialog->response" to emit the "response" signal. Destroying
223 the dialog during "run" is a very bad idea, because your post-run code
224 won't know whether the dialog was destroyed or not.
225 After "run" returns, you are responsible for hiding or destroying the
227 dialog if you wish to do so.
228 Typical usage of this function might be:
230 if ('accept' eq $dialog->run) {
232 do_application_specific_something ();
233 } else {
234 do_nothing_since_dialog_was_cancelled ();
235 }
236 $dialog->destroy;
237 widget = $dialog->get_widget_for_response ($response_id)
239 • $response_id (Gtk2::ResponseType)
240 Since: gtk+ 2.20
242
244 'has-separator' (boolean : default false : readable / writable /
245 private / static-nick / static-blurb / deprecated)
246 The dialog has a separator bar above its buttons
247
249 'action-area-border' (integer : default 5 : readable / private /
250 static-nick / static-blurb)
251 Width of border around the button area at the bottom of the dialog
252 'button-spacing' (integer : default 6 : readable / private / static-
254 nick / static-blurb)
255 Spacing between buttons
256 'content-area-border' (integer : default 2 : readable / private /
258 static-nick / static-blurb)
259 Width of border around the main dialog area
260 'content-area-spacing' (integer : default 0 : readable / private /
262 static-nick / static-blurb)
263 Spacing between elements of the main dialog area
264
266 close (Gtk2::Dialog)
267 response (Gtk2::Dialog, integer)
268 Note that currently in a Perl subclass of "Gtk2::Dialog" a class
270 closure, ie. class default signal handler, for the "response" signal
271 will be called with the response ID just as an integer, it's not turned
272 into an enum string like "ok" the way a handler setup with
273 "signal_connect" receives.
274 Hopefully this will change in the future, so don't count on it. In the
276 interim the easiest thing to do is install your default handler in
277 "INIT_INSTANCE" with a "signal_connect". (The subtleties of what order
278 handlers are called in will differ, but often that doesn't matter.)
279
281 flags Gtk2::DialogFlags
282 • 'modal' / 'GTK_DIALOG_MODAL'
283 • 'destroy-with-parent' / 'GTK_DIALOG_DESTROY_WITH_PARENT'
285 • 'no-separator' / 'GTK_DIALOG_NO_SEPARATOR'
287 enum Gtk2::ResponseType
289 The response type is somewhat abnormal as far as gtk2-perl enums go.
290 In C, this enum lists named, predefined integer values for a field that
291 is other composed of whatever integer values you like. In Perl, we
292 allow this to be either one of the string constants listed here or any
293 positive integer value. For example, 'ok', 'cancel', 4, and 42 are all
294 valid response ids. You cannot use arbitrary string values, they must
295 be integers. Be careful, because unknown string values tend to be
296 mapped to 0.
297 • 'none' / 'GTK_RESPONSE_NONE'
299 • 'reject' / 'GTK_RESPONSE_REJECT'
301 • 'accept' / 'GTK_RESPONSE_ACCEPT'
303 • 'delete-event' / 'GTK_RESPONSE_DELETE_EVENT'
305 • 'ok' / 'GTK_RESPONSE_OK'
307 • 'cancel' / 'GTK_RESPONSE_CANCEL'
309 • 'close' / 'GTK_RESPONSE_CLOSE'
311 • 'yes' / 'GTK_RESPONSE_YES'
313 • 'no' / 'GTK_RESPONSE_NO'
315 • 'apply' / 'GTK_RESPONSE_APPLY'
317 • 'help' / 'GTK_RESPONSE_HELP'
319
321 Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object, Gtk2::Widget,
322 Gtk2::Container, Gtk2::Bin, Gtk2::Window
323
325 Copyright (C) 2003-2011 by the gtk2-perl team.
326 This software is licensed under the LGPL. See Gtk2 for a full notice.
328perl v5.32.1 2021-01-27 Gtk2::Dialog(3)