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)
246 The dialog has a separator bar above its buttons
247
249 'action-area-border' (integer : default 5 : readable / private)
250 Width of border around the button area at the bottom of the dialog
251 'button-spacing' (integer : default 6 : readable / private)
253 Spacing between buttons
254 'content-area-border' (integer : default 2 : readable / private)
256 Width of border around the main dialog area
257 'content-area-spacing' (integer : default 0 : readable / private)
259 Spacing between elements of the main dialog area
260
262 close (Gtk2::Dialog)
263 response (Gtk2::Dialog, integer)
264 Note that currently in a Perl subclass of "Gtk2::Dialog" a class
266 closure, ie. class default signal handler, for the "response" signal
267 will be called with the response ID just as an integer, it's not turned
268 into an enum string like "ok" the way a handler setup with
269 "signal_connect" receives.
270 Hopefully this will change in the future, so don't count on it. In the
272 interim the easiest thing to do is install your default handler in
273 "INIT_INSTANCE" with a "signal_connect". (The subtleties of what order
274 handlers are called in will differ, but often that doesn't matter.)
275
277 flags Gtk2::DialogFlags
278 · 'modal' / 'GTK_DIALOG_MODAL'
279 · 'destroy-with-parent' / 'GTK_DIALOG_DESTROY_WITH_PARENT'
281 · 'no-separator' / 'GTK_DIALOG_NO_SEPARATOR'
283 enum Gtk2::ResponseType
285 The response type is somewhat abnormal as far as gtk2-perl enums go.
286 In C, this enum lists named, predefined integer values for a field that
287 is other composed of whatever integer values you like. In Perl, we
288 allow this to be either one of the string constants listed here or any
289 positive integer value. For example, 'ok', 'cancel', 4, and 42 are all
290 valid response ids. You cannot use arbitrary string values, they must
291 be integers. Be careful, because unknown string values tend to be
292 mapped to 0.
293 · 'none' / 'GTK_RESPONSE_NONE'
295 · 'reject' / 'GTK_RESPONSE_REJECT'
297 · 'accept' / 'GTK_RESPONSE_ACCEPT'
299 · 'delete-event' / 'GTK_RESPONSE_DELETE_EVENT'
301 · 'ok' / 'GTK_RESPONSE_OK'
303 · 'cancel' / 'GTK_RESPONSE_CANCEL'
305 · 'close' / 'GTK_RESPONSE_CLOSE'
307 · 'yes' / 'GTK_RESPONSE_YES'
309 · 'no' / 'GTK_RESPONSE_NO'
311 · 'apply' / 'GTK_RESPONSE_APPLY'
313 · 'help' / 'GTK_RESPONSE_HELP'
315
317 Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object, Gtk2::Widget,
318 Gtk2::Container, Gtk2::Bin, Gtk2::Window
319
321 Copyright (C) 2003-2011 by the gtk2-perl team.
322 This software is licensed under the LGPL. See Gtk2 for a full notice.
324perl v5.28.0 2018-07-18 Gtk2::Dialog(3)