1Gtk2::api(3) User Contributed Perl Documentation Gtk2::api(3)
2
6 Gtk2::api - Mapping the Gtk+ C API to perl
7
9 The Gtk2 module attempts to stick as close as is reasonable to the C
10 API, to minimize the need to maintain documentation which is nearly a
11 copy of the C API reference documentation. However, the world is not
12 perfect, and the mappings between C and perl are not as clean and
13 predictable as you might wish. Thus, this page described the basics of
14 how to map the C API to the perl API, and lists various points in the
15 API which follow neither the C API documentation nor the mapping
16 principles.
17
19 The canonical documentation is the C API reference at
20 http://developer.gnome.org/doc/API/gtk/ and
21 http://developer.gnome.org/doc/API/gdk/
22 There are two main sections: 'BINDING BASICS' describes the principles
24 on which the bindings work; understanding these can lead you to guess
25 the proper syntax to use for any given function described in the C API
26 reference. The second section lists various specific points of
27 difference which don't necessarily correspond with what you expect;
28 this section is in three main parts: missing methods, renamed methods,
29 and different call signatures.
30
32 We avoid deprecated APIs. Many functions refer to C concepts which are
33 alien to the bindings. Many things have replacements.
34 Deprecated Stuff Isn't Bound
36 Things that were marked as deprecated at gtk+ 2.0.0 do not appear in
37 the bindings. This means that gtk+-1.x's GtkCList, GtkTree, and
38 GtkText are not available. The notable exception is GtkList, which is
39 available solely in support of GtkCombo (which was itself replaced by
40 GtkComboBox in 2.4); it should not be used under any other
41 circumstances. If you really need access to these old widgets, search
42 the web for "Gtk2::Deprecated".
43 Some other things were deprecated during the gtk+ 2.x series, e.g.
45 GtkOptionMenu was deprecated in favor of GtkComboBox in 2.4. Things
46 that were marked as deprecated during the 2.x series will not be
47 removed, basically because older versions do not have the replacements,
48 and removing them would break backward compatibility.
49 Namespaces and Objects
51 The namespaces of the C libraries are mapped to perl packages according
52 to scope, although in some cases the distinction may seem rather
53 arbitrary:
54 g_ => Glib (the Glib module - distributed separately)
56 gtk_ => Gtk2
57 gdk_ => Gtk2::Gdk
58 gdk_pixbuf_ => Gtk2::Gdk::Pixbuf
59 pango_ => Gtk2::Pango
60 Objects get their own namespaces, in a way, as the concept of the GType
62 is completely replaced in the perl bindings by the perl package name.
63 This goes for GBoxed, GObject, and even things like Glib::String and
64 Glib::Int (which are needed for specifying column types in the
65 Gtk2::TreeModel). (Flags and enums are special -- see below.)
66 GtkButton => Gtk2::Button
68 GdkPixbuf => Gtk2::Gdk::Pixbuf
69 GtkScrolledWindow => Gtk2::ScrolledWindow
70 PangoFontDescription => Gtk2::Pango::FontDescription
71 With this package mapping and perl's built-in method lookup, the
73 bindings can do object casting for you. This gives us a rather
74 comfortably object-oriented syntax, using normal perl syntax semantics:
75 in C:
77 GtkWidget * b;
78 b = gtk_check_button_new_with_mnemonic ("_Something");
79 gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (b), TRUE);
80 gtk_widget_show (b);
81 in perl:
83 my $b = Gtk2::CheckButton->new ('_Something');
84 $b->set_active (1);
85 $b->show;
86 You see from this that constructors for most widgets which allow
88 mnemonics will use mnemonics by default in their "new" methods. For
89 those who don't guess this right off, Gtk2::Button->new_with_mnemonic
90 is also available. Cast macros are not necessary, and your code is a
91 lot shorter.
92 Flags and Enums
94 Constants are handled as strings, because it's much more readable than
95 numbers, and because it's automagical thanks to the GType system.
96 Constants are referred to by their nicknames; basically, strip the
97 common prefix, lower-case it, and optionally convert '_' to '-':
98 GTK_WINDOW_TOPLEVEL => 'toplevel'
100 GTK_BUTTONS_OK_CANCEL => 'ok-cancel' (or 'ok_cancel')
101 Flags are a special case. You can't (sensibly) bitwise-or these
103 string-constants, so you provide a reference to an array of them
104 instead. Anonymous arrays are useful here, and an empty anonymous
105 array is a simple way to say 'no flags'.
106 FOO_BAR_BAZ | FOO_BAR_QUU | FOO_BAR_QUUX => [qw/baz quu qux/]
108 0 => []
109 In some cases you need to see if a bit is set in a bitfield; methods
111 returning flags therefore return an overloaded object. See Glib for
112 more details on which operations are allowed on these flag objects, but
113 here is a quick example:
114 in C:
116 /* event->state is a bitfield */
117 if (event->state & GDK_CONTROL_MASK) g_printerr ("control was down\n");
118 in perl:
120 # $event->state is a special object
121 warn "control was down\n" if $event->state & "control-mask";
122 But this also works:
124 warn "control was down\n" if $event->state * "control-mask";
126 warn "control was down\n" if $event->state >= "control-mask";
127 warn "control and shift were down\n"
128 if $event->state >= ["control-mask", "shift-mask"];
129 And treating it as an array of strings (as in older versions) is still
131 supported:
132 warn "control was down\n" if grep /control-mask/, @{ $event->state };
134 The gtk stock item stuff is a little different -- the GTK_STOCK_*
136 constants are actually macros which evaluate to strings, so they aren't
137 handled by the mechanism described above; you just specify the string,
138 e.g., GTK_STOCK_OK => 'gtk-ok'. The full list of stock items can be
139 found at
140 http://developer.gnome.org/doc/API/2.0/gtk/gtk-Stock-Items.html
141 Memory Handling
143 The functions for ref'ing and unref'ing objects and free'ing boxed
144 structures are not even mapped to perl, because it's all handled
145 automagically by the bindings. I could write a treatise on how we're
146 handling reference counts and object lifetimes, but all you need to
147 know as perl developer is that it's handled for you, and the object
148 will be alive so long as you have a perl scalar pointing to it or the
149 object is referenced in another way, e.g. from a container.
150 The only thing you have to be careful about is the lifespan of non
152 reference counted structures, which means most things derived from
153 "Glib::Boxed". If it comes from a signal callback it might be good
154 only until you return, or if it's the insides of another object then it
155 might be good only while that object lives. If in doubt you can
156 "copy". Structs from "copy" or "new" are yours and live as long as
157 referred to from Perl.
158 Callbacks
160 Use normal perl callback/closure tricks with callbacks. The most
161 common use you'll have for callbacks is with the Glib "signal_connect"
162 method:
163 $widget->signal_connect (event => \&event_handler, $user_data);
165 $button->signal_connect (clicked => sub { warn "hi!\n" });
166 $user_data is optional, and with perl closures you don't often need it
168 (see "Persistent variables with closures" in perlsub).
169 The userdata is held in a scalar, initialized from what you give in
171 "signal_connect" etc. It's passed to the callback in usual Perl "call
172 by reference" style which means the callback can modify its last
173 argument, ie. $_[-1], to modify the held userdata. This is a little
174 subtle, but you can use it for some "state" associated with the
175 connection.
176 $widget->signal_connect (activate => \&my_func, 1);
178 sub my_func {
179 print "activation count: $_[-1]\n";
180 $_[-1] ++;
181 }
182 Because the held userdata is a new scalar there's no change to the
184 variable (etc) you originally passed to "signal_connect".
185 If you have a parent object in the userdata (or closure) you have to be
187 careful about circular references preventing parent and child being
188 destroyed. See "Two-Phased Garbage Collection" in perlobj about this
189 generally. In Gtk2-Perl toplevel widgets like "Gtk2::Window" always
190 need an explicit "$widget->destroy" so their "destroy" signal is a good
191 place to break circular references. But for other widgets it's usually
192 friendliest to avoid circularities in the first place, either by using
193 weak references in the userdata, or possibly locating a parent
194 dynamically with "$widget->get_ancestor".
195 A major change from gtk-perl (the bindings for Gtk+-1.x) is that
197 callbacks take their arguments in the order proscribed by the C
198 documentation, and only one value is available for user data. gtk-perl
199 allowed you to pass multiple values for user_data, and always brought
200 in the user_data immediately after the instance reference; this proved
201 to be rather confusing, and did not follow the C API reference, so we
202 decided not to do that for gtk2-perl.
203 Miscellaneous
205 In C you can only return one value from a function, and it is a common
206 practice to modify pointers passed in to simulate returning multiple
207 values. In perl, you can return lists; any functions which modify
208 arguments have been changed to return them instead. A common idiom in
209 gtk is returning gboolean, and modifying several arguments if the
210 function returns TRUE; for such functions, the perl wrapper just
211 returns an empty list on failure.
212 in C: foo_get_baz_and_quux (foo, &baz, &quux);
214 in perl: ($baz, $quux) = $foo->get_baz_and_quux;
215 Most things that take or return a GList, GSList, or array of values
217 will use native perl arrays (or the argument stack) instead.
218 You don't need to specify string lengths, although string length
220 parameters should still be available for functions dealing with binary
221 strings. You can always use "substr" to pass different parts of a
222 string.
223 Anything that uses GError in C will "croak" on failure, setting $@ to a
225 magical exception object, which is overloaded to print as the returned
226 error message. The ideology here is that GError is to be used for
227 runtime exceptions, and "croak" is how you do that in perl. You can
228 catch a croak very easily by wrapping the function in an eval:
229 eval {
231 my $pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename);
232 $image->set_from_pixbuf ($pixbuf);
233 };
234 if ($@) {
235 print "$@\n"; # prints the possibly-localized error message
236 if (Glib::Error::matches ($@, 'Gtk2::Gdk::Pixbuf::Error',
237 'unknown-format')) {
238 change_format_and_try_again ();
239 } elsif (Glib::Error::matches ($@, 'Glib::File::Error', 'noent')) {
240 change_source_dir_and_try_again ();
241 } else {
242 # don't know how to handle this
243 die $@;
244 }
245 }
246 This has the added advantage of letting you bunch things together as
248 you would with a try/throw/catch block in C++ -- you get cleaner code.
249 By using Glib::Error exception objects, you don't have to rely on
250 string matching on a possibly localized error message; you can match
251 errors by explicit and predictable conditions. See Glib::Error for
252 more information.
253
255 g_object_ref => no replacement
256 g_object_unref => no replacement
257 g_boxed_free => no replacement
258 The bindings do automatic memory management. You should never need
259 to use these.
260 gtk_timeout_add => Glib::Timeout->add
262 gtk_timeout_remove => Glib::Source->remove
263 gtk_idle_add => Glib::Idle->add
264 gtk_idle_remove => Glib::Source->remove
265 gtk_input_add => Glib::IO->add_watch
266 gtk_input_remove => Glib::Source->remove
267 The gtk_* functions are deprecated in favor of the g_* ones.
268 Gtk2::Helper has a wrapper for Glib::IO->add_watch which makes it
269 behave more like gtk_input_add.
270 gtk_accel_group_from_accel_closure => no replacement
272 Because of the use of Perl subroutine references in place of
273 GClosures, there is no way to preserve at the Perl level the one-
274 to-one mapping between GtkAccelGroups and GClosures. Without that
275 mapping, this function is useless.
276
278 gtk_aspect_frame_set => $aspect_frame->set_params
279 Avoid a clash with $gobject->set.
280
282 As a general rule function that take a pair of parameters, a list and
283 the number of elements in that list, will normally omit the number of
284 elements and just accept a variable number of arguments that will be
285 converted into the list and number of elements. In many instances
286 parameters have been reordered so that this will work. See below for
287 exceptions and specific cases that are not detailed in the generated
288 Perl API reference.
289 Gtk2::ScrollBar vs. GtkScrollbar
291 These classes were incorrectly written with a capital "B" in
292 version 1.00 and below. They have been renamed in version 1.01 and
293 the old way to write them is deprecated, but supported.
294 Gtk2::ItemFactory::create_items
296 The n_entries parameter has been omitted and callback_data is
297 accepted as the first parameter. All parameters after that are
298 considered to be entries.
299 Gtk2::List::insert_items
301 Position and items parameters flipped order so that an open ended
302 parameter list could be used. "$list->insert_items($position,
303 $item1, $item2, ...)" (Note that GtkList and GtkListItem are
304 deprecated and only included because GtkCombo still makes use of
305 them, they are subject to removal at any point so you should not
306 utilize them unless absolutely necessary.)
307 Gtk2::Notebook::append_page
309 Gtk2::Notebook::prepend_page
310 Gtk2::Notebook::insert_page
311 The C API for these functions requires a GtkWidget for the
312 tab_label, since you can set any widget you like to be the tab
313 label. However, the most common use is a plain Gtk2::Label; so
314 these three functions will stringify anything passed to tab_label
315 that's not a GtkWidget and wrap a Gtk2::Label around it for you.
316 Note that the "_menu" versions of these functions do not do this.
318 Gtk2::AccelGroup::connect
320 Gtk2::AccelGroup::disconnect
321 Where a GClosure is wanted by the C stuff, a perl subroutine
322 reference suffices. However, because of this, there are a few
323 subtle differences in semantics. a GClosure may be connected to
324 only one GtkAccelGroup; however, a perl subroutine may be connected
325 to many GtkAccelGroups (because at the binding level, a new
326 GClosure is created on each call to ->connect). Thus,
327 $accel_group->disconnect will disconnect the first group it finds
328 to be connected to the given perl subroutine. To disconnect all
329 groups attached to a subroutine, you can call disconnect with the
330 same subroutine reference (or name) until it stops returning true.
331 Gtk2::Clipboard::set_with_data
333 Gtk2::Clipboard::set_with_owner
334 In C, these functions take an array of GtkTargetEntries and the
335 number of elements in that array as the second and third
336 parameters. In Perl, the number of target entries is implied by
337 the number of items on the stack, and the target entries are
338 supplied as a list at the end of the parameter list:
339 $clipboard->set_with_data (\&get_func, \&clear_func, $user_data,
341 @target_entries);
342 $clipboard->set_with_owner (\&get_func, \&clear_func, $owner,
343 @target_entries);
344
346 The canonical documentation is the C API reference at
347 http://developer.gnome.org/doc/API/gtk/ and
348 http://developer.gnome.org/doc/API/gdk/
349 Gtk2 includes a full suite of automatically-generated API reference POD
351 for the Perl API -- see Gtk2::index for the starting point.
352 There should be a similar document for Glib --- link to it here when it
354 exists.
355
357 muppet <scott at asofyet dot org>
358
360 Copyright (C) 2003, 2009 by the gtk2-perl team (see the file AUTHORS
361 for the full list)
362 This library is free software; you can redistribute it and/or modify it
364 under the terms of the GNU Library General Public License as published
365 by the Free Software Foundation; either version 2.1 of the License, or
366 (at your option) any later version.
367 This library is distributed in the hope that it will be useful, but
369 WITHOUT ANY WARRANTY; without even the implied warranty of
370 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
371 Library General Public License for more details.
372 You should have received a copy of the GNU Library General Public
374 License along with this library; if not, write to the Free Software
375 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
376 02110-1301 USA.
377perl v5.32.0 2020-07-28 Gtk2::api(3)