1Gtk2::Dialog(3)       User Contributed Perl Documentation      Gtk2::Dialog(3)
2
3
4

NAME

6       Gtk2::Dialog - wrapper for GtkDialog
7

SYNOPSIS

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
16         $dialog->set_default_response ('ok');
17
18         # 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
25         # activating a response does not destroy the window,
26         # that's up to you.
27         $dialog->destroy;
28

DESCRIPTION

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
34       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
41       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
46       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
50       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
55       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
64       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
70       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
75        # Function to open a dialog box displaying the message provided.
76
77        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
85           # Ensure that the dialog box is destroyed when the user responds.
86           $dialog->signal_connect (response => sub { $_[0]->destroy });
87
88           $dialog->show_all;
89        }
90
91   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
96       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
101       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
106           sub my_response_handler {
107             my ($dialog, $response) = @_;
108             if ($response eq 'close') {
109               $self->signal_emit ('close');
110
111             } elsif ...
112           }
113

HIERARCHY

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

INTERFACES

125         Glib::Object::_Unregistered::AtkImplementorIface
126         Gtk2::Buildable
127

METHODS

129   $widget = Gtk2::Dialog->new;
130   $widget = Gtk2::Dialog->new ($title, $parent, $flags, ...)
131       •   ... (list) of button-text => response-id pairs.
132
133       •   $flags (Gtk2::DialogFlags) interesting properties
134
135       •   $parent (Gtk2::Window or undef) make the new dialog transient for
136           this window
137
138       •   $title (string) window title
139
140       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
144       Here's a simple example:
145
146        $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
152   $widget = Gtk2::Dialog->new_with_buttons ($title, $parent, $flags, ...)
153       •   ... (list) of button-text => response-id pairs.
154
155       Alias for the multi-argument version of "Gtk2::Dialog->new".
156
157   widget = $dialog->get_action_area
158   $dialog->add_action_widget ($child, $response_id)
159       •   $child (Gtk2::Widget)
160
161       •   $response_id (Gtk2::ResponseType)
162
163   widget = $dialog->add_button ($button_text, $response_id)
164       •   $button_text (string) may be arbitrary text with mnenonics, or
165           stock ids
166
167       •   $response_id (Gtk2::ResponseType)
168
169       Returns the created button.
170
171   $dialog->add_buttons (...)
172       •   ... (list) of button-text => response-id pairs
173
174       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
178   $dialog->set_alternative_button_order (...)
179       •   ... (list)
180
181       Since: gtk+ 2.6
182
183   widget = $dialog->get_content_area
184   $dialog->set_default_response ($response_id)
185       •   $response_id (Gtk2::ResponseType)
186
187   boolean = $dialog->get_has_separator
188   $dialog->set_has_separator ($setting)
189       •   $setting (boolean)
190
191   $dialog->response ($response_id)
192       •   $response_id (Gtk2::ResponseType)
193
194       Emit the response signal, as though the user had clicked on the button
195       with $response_id.
196
197   scalar = $dialog->get_response_for_widget ($widget)
198       •   $widget (Gtk2::Widget)
199
200       Since: gtk+ 2.8
201
202   $dialog->set_response_sensitive ($response_id, $setting)
203       •   $response_id (Gtk2::ResponseType)
204
205       •   $setting (boolean)
206
207       Enable or disable an action button by its $response_id.
208
209   $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
218       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
226       After "run" returns, you are responsible for hiding or destroying the
227       dialog if you wish to do so.
228
229       Typical usage of this function might be:
230
231         if ('accept' eq $dialog->run) {
232                do_application_specific_something ();
233         } else {
234                do_nothing_since_dialog_was_cancelled ();
235         }
236         $dialog->destroy;
237
238   widget = $dialog->get_widget_for_response ($response_id)
239       •   $response_id (Gtk2::ResponseType)
240
241       Since: gtk+ 2.20
242

PROPERTIES

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

STYLE PROPERTIES

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
253       'button-spacing' (integer : default 6 : readable / private / static-
254       nick / static-blurb)
255           Spacing between buttons
256
257       'content-area-border' (integer : default 2 : readable / private /
258       static-nick / static-blurb)
259           Width of border around the main dialog area
260
261       'content-area-spacing' (integer : default 0 : readable / private /
262       static-nick / static-blurb)
263           Spacing between elements of the main dialog area
264

SIGNALS

266       close (Gtk2::Dialog)
267       response (Gtk2::Dialog, integer)
268
269       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
275       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

ENUMS AND FLAGS

281   flags Gtk2::DialogFlags
282       •   'modal' / 'GTK_DIALOG_MODAL'
283
284       •   'destroy-with-parent' / 'GTK_DIALOG_DESTROY_WITH_PARENT'
285
286       •   'no-separator' / 'GTK_DIALOG_NO_SEPARATOR'
287
288   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
298       •   'none' / 'GTK_RESPONSE_NONE'
299
300       •   'reject' / 'GTK_RESPONSE_REJECT'
301
302       •   'accept' / 'GTK_RESPONSE_ACCEPT'
303
304       •   'delete-event' / 'GTK_RESPONSE_DELETE_EVENT'
305
306       •   'ok' / 'GTK_RESPONSE_OK'
307
308       •   'cancel' / 'GTK_RESPONSE_CANCEL'
309
310       •   'close' / 'GTK_RESPONSE_CLOSE'
311
312       •   'yes' / 'GTK_RESPONSE_YES'
313
314       •   'no' / 'GTK_RESPONSE_NO'
315
316       •   'apply' / 'GTK_RESPONSE_APPLY'
317
318       •   'help' / 'GTK_RESPONSE_HELP'
319

SEE ALSO

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
327       This software is licensed under the LGPL.  See Gtk2 for a full notice.
328
329
330
331perl v5.32.1                      2021-01-27                   Gtk2::Dialog(3)
Impressum