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->vbox->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 win‐
47 dow can be accessed as "$dialog->vbox" and "$dialog->action_area", as
48 can be seen from the example, below.
49 A 'modal' dialog (that is, one which freezes the rest of the applica‐
51 tion from user input), can be created by calling the Gtk2::Window
52 method "set_modal" on the dialog. You can also pass the 'modal' flag
53 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 but‐
57 ton 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 'GTK_RESPONSE_NONE' (except within "run" -- see below).
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 proba‐
71 bly use Gtk2::MessageDialog to save yourself some effort. But you'd
72 need to create the dialog contents manually if you had more than a sim‐
73 ple 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->vbox->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
92 Glib::Object
93 +----Glib::InitiallyUnowned
94 +----Gtk2::Object
95 +----Gtk2::Widget
96 +----Gtk2::Container
97 +----Gtk2::Bin
98 +----Gtk2::Window
99 +----Gtk2::Dialog
100
102 Glib::Object::_Unregistered::AtkImplementorIface
103
105 $widget = Gtk2::Dialog->new;
106 $widget = Gtk2::Dialog->new ($title, $parent, $flags, ...)
108 * ... (list) of button-text => response-id pairs.
110 * $flags (Gtk2::DialogFlags) interesting properties
111 * $parent (Gtk2::Window or undef) make the new dialog transient for
112 this window
113 * $title (string) window title
114 The multi-argument form takes the same list of text => response-id
116 pairs as "$dialog->add_buttons". Do not pack widgets directly into
117 the window; add them to "$dialog->vbox".
118 Here's a simple example:
120 $dialog = Gtk2::Dialog->new ('A cool dialog',
122 $main_app_window,
123 [qw/modal destroy-with-parent/],
124 'gtk-ok' => 'accept',
125 'gtk-cancel' => 'reject');
126 $widget = Gtk2::Dialog->new_with_buttons ($title, $parent, $flags, ...)
128 * ... (list) of button-text => response-id pairs.
130 Alias for the multi-argument version of "Gtk2::Dialog->new".
132 widget = $dialog->action_area
134 $dialog->add_action_widget ($child, $response_id)
136 * $child (Gtk2::Widget)
138 * $response_id (Gtk2::ResponseType)
139 widget = $dialog->add_button ($button_text, $response_id)
141 * $button_text (string) may be arbitrary text with mnenonics, or
143 stock ids
144 * $response_id (Gtk2::ResponseType)
145 Returns the created button.
147 $dialog->add_buttons (...)
149 * ... (list) of button-text => response-id pairs
151 Like calling "$dialog->add_button" repeatedly, except you don't get
153 the created widgets back. The buttons go from left to right, so
154 the first button added will be the left-most one.
155 $dialog->set_alternative_button_order (...)
157 * ... (list)
159 $dialog->set_default_response ($response_id)
161 * $response_id (Gtk2::ResponseType)
163 boolean = $dialog->get_has_separator
165 $dialog->set_has_separator ($setting)
167 * $setting (boolean)
169 $dialog->response ($response_id)
171 * $response_id (Gtk2::ResponseType)
173 Emit the response signal, as though the user had clicked on the
175 button with $response_id.
176 scalar = $dialog->get_response_for_widget ($widget)
178 * $widget (Gtk2::Widget)
180 $dialog->set_response_sensitive ($response_id, $setting)
182 * $response_id (Gtk2::ResponseType)
184 * $setting (boolean)
185 Enable or disable an action button by its $response_id.
187 $responsetype = $dialog->run
189 Blocks in a recursive main loop until the dialog either emits the
191 response signal, or is destroyed. If the dialog is destroyed dur‐
192 ing the call to "$dialog->run", the function returns
193 'GTK_RESPONSE_NONE' ('none'). Otherwise, it returns the response
194 ID from the "response" signal emission. Before entering the recur‐
195 sive main loop, "$dialog->run" calls "$widget->show" on $dialog for
196 you. Note that you still need to show any children of the dialog
197 yourself.
198 During "run", the default behavior of "delete_event" is disabled;
200 if the dialog receives "delete_event", it will not be destroyed as
201 windows usually are, and "run" will return
202 'GTK_RESPONSE_DELETE_EVENT' ('delete-event'). Also, during "run"
203 the dialog will be modal. You can force "run" to return at any
204 time by calling "$dialog->response" to emit the "response" signal.
205 Destroying the dialog during "run" is a very bad idea, because your
206 post-run code won't know whether the dialog was destroyed or not.
207 After "run" returns, you are responsible for hiding or destroying
209 the dialog if you wish to do so.
210 Typical usage of this function might be:
212 if ('accept' eq $dialog->run) {
214 do_application_specific_something ();
215 } else {
216 do_nothing_since_dialog_was_cancelled ();
217 }
218 $dialog->destroy;
219 widget = $dialog->vbox
221
223 'has-separator' (boolean : readable / writable / private)
224 The dialog has a separator bar above its buttons
225
227 response (Gtk2::Dialog, integer)
228 close (Gtk2::Dialog)
229
231 flags Gtk2::DialogFlags
232 * 'modal' / 'GTK_DIALOG_MODAL'
234 * 'destroy-with-parent' / 'GTK_DIALOG_DESTROY_WITH_PARENT'
235 * 'no-separator' / 'GTK_DIALOG_NO_SEPARATOR'
236 enum Gtk2::ResponseType
238 The response type is somewhat abnormal as far as gtk2-perl enums go.
240 In C, this enum lists named, predefined integer values for a field that
241 is other composed of whatever integer values you like. In Perl, we
242 allow this to be either one of the string constants listed here or any
243 positive integer value. For example, 'ok', 'cancel', 4, and 42 are all
244 valid response ids. You cannot use arbitrary string values, they must
245 be integers. Be careful, because unknown string values tend to be
246 mapped to 0.
247 * 'none' / 'GTK_RESPONSE_NONE'
249 * 'reject' / 'GTK_RESPONSE_REJECT'
250 * 'accept' / 'GTK_RESPONSE_ACCEPT'
251 * 'delete-event' / 'GTK_RESPONSE_DELETE_EVENT'
252 * 'ok' / 'GTK_RESPONSE_OK'
253 * 'cancel' / 'GTK_RESPONSE_CANCEL'
254 * 'close' / 'GTK_RESPONSE_CLOSE'
255 * 'yes' / 'GTK_RESPONSE_YES'
256 * 'no' / 'GTK_RESPONSE_NO'
257 * 'apply' / 'GTK_RESPONSE_APPLY'
258 * 'help' / 'GTK_RESPONSE_HELP'
259
261 Gtk2, Glib::Object, Glib::InitiallyUnowned, Gtk2::Object, Gtk2::Widget,
262 Gtk2::Container, Gtk2::Bin, Gtk2::Window
263
265 Copyright (C) 2003-2007 by the gtk2-perl team.
266 This software is licensed under the LGPL. See Gtk2 for a full notice.
268perl v5.8.8 2007-03-18 Gtk2::Dialog(3)