1Glib(3) User Contributed Perl Documentation Glib(3)
2
6 Glib - Perl wrappers for the GLib utility and Object libraries
7
9 use Glib;
10
12 This module provides perl access to GLib and GLib's GObject libraries.
13 GLib is a portability and utility library; GObject provides a generic
14 type system with inheritance and a powerful signal system. Together
15 these libraries are used as the foundation for many of the libraries
16 that make up the Gnome environment, and are used in many unrelated
17 projects.
18
20 This wrapper attempts to provide a perlish interface while remaining as
21 true as possible to the underlying C API, so that any reference materi‐
22 als you can find on using GLib may still apply to using the libraries
23 from perl. This module also provides facilities for creating wrappers
24 for other GObject-based libraries. The "SEE ALSO" section contains
25 pointers to all sorts of good information.
26
28 GLib provides to C programs many of the same facilities Perl offers
29 natively. Where GLib's functionality overlaps Perl's, Perl's is
30 favored. Some concepts have been eliminated entirely, as Perl is a
31 higher-level language than C. In other instances we've had to add or
32 change APIs to make sense in Perl. Here's a quick run-down:
33 Perl Already Does That
35 The GLib types GList (a doubly-linked list), GSList (singly-linked
37 list), GHashTable, GArray, etc have all been replaced by native Perl
38 datatypes. In fact, many functions which take GLists or arrays simply
39 accept lists on the Perl stack. For the most part, GIOChannels are no
40 more functional than Perl file handles, so you won't see any GIOChan‐
41 nels. GClosures are not visible at the Perl level, because Perl code
42 references do the same thing. Just about any function taking either a
43 C function pointer or a GClosure will accept a code reference in Perl.
44 (In fact, you can probably get away with just a subroutine name in many
45 spots, provided you aren't using strict subs.)
46 Don't Worry About That
48 Some concepts have been eliminated; you need never worry about refer‐
50 ence-counting on GObjects or having to free GBoxed structures. Perl is
51 a garbage-collected language, and we've put a lot of work into making
52 the bindings take care of memory for you in a way that feels natural to
53 a Perl developer. You won't see GValues in Perl (that's just a C
54 structure with Perl scalar envy, anyway).
55 This Is Now That
57 Other GLib concepts have been converted to an analogous Perl concept.
59 The GType id will never be seen in Perl, as the package name serves
61 that purpose. Several packages corresponding to the GTypes of the fun‐
62 damental types have been registered for you:
63 G_TYPE_STRING Glib::String
65 G_TYPE_INT Glib::Int
66 G_TYPE_UINT Glib::UInt
67 G_TYPE_DOUBLE Glib::Double
68 G_TYPE_BOOLEAN Glib::Boolean
69 The remaining fundamentals (char/uchar, short, float, etc) are also
71 registered so that we can properly interact with properties of C
72 objects, but perl really only uses ints, uints, and doubles. Oh, and
73 we created a GBoxed type for Perl scalars so you can use scalars where
74 any boxed type would be allowed (e.g. GtkTreeModel columns):
75 Glib::Scalar
77 Functions that can return false and set a GError in C raise an excep‐
79 tion in Perl, using an exception object based on the GError for $@; see
80 Glib::Error. Trapping exceptions in signals is a sticky issue, so they
81 get their own section; see EXCEPTIONS.
82 Enumerations and flags are treated as strings and arrays of strings,
84 respectively. GLib provides a way to register nicknames for enumera‐
85 tion values, and the Perl bindings use these nicknames for the real
86 values, so that we never have to deal with numbers in Perl. This can
87 get a little cumbersome for bitfields, but it's very nice when you for‐
88 get a flag value, as the bindings will tell you what values are
89 accepted when you pass something invalid. Also, the bindings consider
90 the - and _ characters to be equivalent, so that signal and property
91 names can be properly stringified by the => operator. For example, the
92 following are equivalent:
93 # property foo-matic of type FooType, using the
95 # value FOO_SOMETHING_COOL. its nickname would be
96 # 'something-cool'. you may use either the full
97 # name or the nickname when supplying values to perl.
98 $object->set ('foo-matic', 'FOO_SOMETHING_COOL');
99 $object->set ('foo_matic', 'something_cool');
100 $object->set (foo_matic => 'something-cool');
101 Beware that Perl will always return to you the nickname form, with the
103 dash.
104 Flags have some additional magic abilities in the form of overloaded
106 operators:
107 + or ⎪ union of two flagsets ("add")
109 - difference of two flagsets ("sub", "remove")
110 * or & intersection of two bitsets ("and")
111 / or ^ symmetric difference ("xor", you will rarely need this)
112 >= contains-operator ("is the left set a superset of the right set?")
113 == equality
114 In addition, flags in boolean context indicate whether they are empty
116 or not, which allows you to write common operations naturally:
117 $widget->set_events ($widget->get_events - "motion_notify_mask");
119 $widget->set_events ($widget->get_events - ["motion_notify_mask",
120 "button_press_mask"]);
121 # shift pressed (both work, it's a matter of taste)
123 if ($event->state >= "shift-mask") { ...
124 if ($event->state * "shift-mask") { ...
125 # either shift OR control pressed?
127 if ($event->state * ["shift-mask", "control-mask"]) { ...
128 # both shift AND control pressed?
130 if ($event->state >= ["shift-mask", "control-mask"]) { ...
131 In general, "+" and "-" work as expected to add or remove flags. To
133 test whether any bits are set in a mask, you use "$mask * ...", and to
134 test whether all bits are set in a mask, you use "$mask >= ...".
135 When dereferenced as an array @$flags or "$flags->[...]", you can
137 access the flag values directly as strings (but you are not allowed to
138 modify the array), and when stringified "$flags" a flags value will
139 output a human-readable version of its contents.
140 It's All the Same
142 For the most part, the remaining bits of GLib are unchanged. GMainLoop
144 is now Glib::MainLoop, GObject is now Glib::Object, GBoxed is now
145 Glib::Boxed, etc.
146
148 Perl knows two datatypes, unicode text and binary bytes. Filenames on a
149 system that doesn't use a utf-8 locale are often stored in a local
150 encoding ("binary bytes"). Gtk+ and descendants, however, internally
151 work in unicode most of the time, so when feeding a filename into a
152 GLib/Gtk+ function that expects a filename, you first need to convert
153 it from the local encoding to unicode.
154 This involves some elaborate guessing, which perl currently avoids, but
156 GLib and Gtk+ do. As an exception, some Gtk+ functions want a filename
157 in local encoding, but the perl interface usually works around this by
158 automatically converting it for you.
159 In short: Everything should be in unicode on the perl level.
161 The following functions expose the conversion algorithm that GLib uses.
163 These functions are only necessary when you want to use perl functions
165 to manage filenames returned by a GLib/Gtk+ function, or when you feed
166 filenames into GLib/Gtk+ functions that have their source outside your
167 program (e.g. commandline arguments, readdir results etc.).
168 These functions are available as exports by request (see "Exports"),
170 and also support method invocation syntax for pathological consistency
171 with the OO syntax of the rest of the bindings.
172 $filename = filename_to_unicode $filename_in_local_encoding
174 $filename = Glib->filename_to_unicode ($filename_in_local_encoding)
175 Convert a perl string that supposedly contains a filename in local
176 encoding into a filename represented as unicode, the same way that
177 GLib does it internally.
178 Example:
180 $gtkfilesel->set_filename (filename_to_unicode $ARGV[1]);
182 This function will croak() if the conversion cannot be made, e.g.,
184 because the utf-8 is invalid.
185 $filename_in_local_encoding = filename_from_unicode $filename
187 $filename_in_local_encoding = Glib->filename_from_unicode ($filename)
188 Converts a perl string containing a filename into a filename in the
189 local encoding in the same way GLib does it.
190 Example:
192 open MY, "<", filename_from_unicode $gtkfilesel->get_filename;
194 Other functions for converting URIs are currently missing. Also, it
196 might be useful to know that perl currently has no policy at all
197 regarding filename issues, if your scalar happens to be in utf-8 inter‐
198 nally it will use utf-8, if it happens to be stored as bytes, it will
199 use it as-is.
200 When dealing with filenames that you need to display, there is a much
202 easier way, as of Glib 1.120 and glib 2.6.0:
203 $uft8_string = filename_display_name ($filename)
205 $uft8_string = filename_display_basename ($filename)
206 Given a $filename in filename encoding, return the filename, or
207 just the file's basename, in utf-8. Unlike the other functions
208 described above, this one is guaranteed to return valid utf-8, but
209 the conversion is not necessarily reversible. These functions are
210 intended to be used for failsafe display of filenames, for example
211 in gtk+ labels.
212 Since gtk+ 2.6, Glib 1.12
214
216 The C language doesn't support exceptions; GLib is a C library, and of
217 course doesn't support exceptions either. In Perl, we use die and eval
218 to raise and trap exceptions as a rather common practice. So, the
219 bindings have to work a little black magic behind the scenes to keep
220 GLib from exploding when the Perl program uses exceptions. Unfortu‐
221 nately, a little of this magic has to leak out to where you can see it
222 at the Perl level.
223 Signal and event handlers are run in an eval context; if an exception
225 occurs in such a handler and you don't catch it, Perl will report that
226 an error occurred, and then go on about its business like nothing hap‐
227 pened.
228 You may register subroutines as exception handlers, to be called when
230 such an exception is trapped. Another function removes them for you.
231 $tag = Glib->install_exception_handler (\&my_handler);
233 Glib->remove_exception_handler ($tag);
234 The exception handler will get a fresh copy of the $@ of the offending
236 exception on the argument stack, and is expected to return non-zero if
237 the handler is to remain installed. If it returns false, the handler
238 will be removed.
239 sub my_handler {
241 if ($_[0] =~ m/ftang quisinart/) {
242 clean_up_after_ftang ();
243 }
244 1; # live to fight another day
245 }
246 You can register as many handlers as you like; they will all run inde‐
248 pendently.
249 An important thing to remember is that exceptions do not cross main
251 loops. In fact, exceptions are completely distinct from main loops.
252 If you need to quit a main loop when an exception occurs, install a
253 handler that quits the main loop, but also ask yourself if you are
254 using exceptions for flow control or exception handling.
255
257 GLib's g_log function provides a flexible mechanism for reporting mes‐
258 sages, and most GLib-based C libraries use this mechanism for warnings,
259 assertions, critical messages, etc. The Perl bindings offer a mecha‐
260 nism for routing these messages through Perl's native system, warn()
261 and die(). Extensions should register the log domains they wrap for
262 this to happen fluidly. [FIXME say more here]
263
265 Since perl's integer data type can only hold 32 bit values on all 32
266 bit machines and even on some 64 bit machines, Glib converts 64 bit
267 integers to and from strings if necessary. These strings can then be
268 used to feed one of the various big integer modules. Make sure you
269 don't let your strings get into numerical context before passing them
270 into a Glib function because in this case, perl will convert the number
271 to scientific notation which at this point is not understood by Glib's
272 converters.
273 Here is an overview of what big integer modules are available. First
275 of all, there's Math::BigInt. It has everything you will ever need,
276 but its pure-Perl implementation is also rather slow. There are multi‐
277 ple ways around this, though.
278 Math::BigInt::FastCalc
280 Math::BigInt::FastCalc can help avoid the glacial speed of vanilla
281 Math::BigInt::Calc. Recent versions of Math::BigInt will automati‐
282 cally use Math::BigInt::FastCalc in place of Math::BigInt::Calc
283 when available. Other options include Math::BigInt::GMP or
284 Math::BigInt::Pari, which however have much larger dependencies.
285 Math::BigInt::Lite
287 Then there's Math::BigInt::Lite, which uses native Perl integer
288 operations as long as Perl integers have sufficient range, and
289 upgrades itself to Math::BigInt when Perl integers would overflow.
290 This must be used in place of Math::BigInt.
291 bigint / bignum / bigfloat
293 Finally, there's the bigint/bignum/bigfloat pragmata, which auto‐
294 matically load the corresponding Math:: modules and which will
295 autobox constants. bignum/bigint will automatically use Math::Big‐
296 Int::Lite if it's available.
297
299 For the most part, gtk2-perl avoids exporting things. Nothing is
300 exported by default, but some functions and constants in Glib are
301 available by request; you can also get all of them with the export tag
302 "all".
303 Tag: constants
305 TRUE
306 FALSE
307 G_PRIORITY_HIGH
308 G_PRIORITY_DEFAULT
309 G_PRIORITY_HIGH_IDLE
310 G_PRIORITY_DEFAULT_IDLE
311 G_PRIORITY_LOW
312 G_PARAM_READWRITE
313 Tag: functions
315 filename_from_unicode
316 filename_to_unicode
317 filename_from_uri
318 filename_to_uri
319 filename_display_basename
320 filename_display_name
321
323 Glib::Object::Subclass explains how to create your own gobject sub‐
324 classes in Perl.
325 Glib::index lists the automatically-generated API reference for the
327 various packages in Glib.
328 This module is the basis for the Gtk2 module, so most of the references
330 you'll be able to find about this one are tied to that one. The perl
331 interface aims to be very simply related to the C API, so see the C API
332 reference documentation:
333 GLib - http://developer.gnome.org/doc/API/2.0/glib/
335 GObject - http://developer.gnome.org/doc/API/2.0/gobject/
336 This module serves as the foundation for any module which needs to bind
338 GLib-based C libraries to perl.
339 Glib::devel - Binding developer's overview of Glib's internals
341 Glib::xsapi - internal API reference for GPerl
342 Glib::ParseXSDoc - extract API docs from xs sources.
343 Glib::GenPod - turn the output of Glib::ParseXSDoc into POD
344 Glib::MakeHelper - Makefile.PL utilities for Glib-based extensions
345 Yet another document, available separately, ties it all together:
347 http://gtk2-perl.sourceforge.net/doc/binding_howto.pod.html
348 For gtk2-perl itself, see its website at
350 gtk2-perl - http://gtk2-perl.sourceforge.net/
352 A mailing list exists for discussion of using gtk2-perl and related
354 modules. Archives and subscription information are available at
355 http://lists.gnome.org/.
356
358 muppet, <scott at asofyet dot org>, who borrowed heavily from the work
359 of Göran Thyni, <gthyni at kirra dot net> and Guillaume Cottenceau <gc
360 at mandrakesoft dot com> on the first gtk2-perl module, and from the
361 sourcecode of the original gtk-perl and pygtk projects. Marc Lehmann
362 <pcg at goof dot com> did lots of great work on the magic of making
363 Glib::Object wrapper and subclassing work like they should. Ross
364 McFarland <rwmcfa1 at neces dot com> wrote quite a bit of the documen‐
365 tation generation tools. Torsten Schoenfeld <kaffeetisch at web dot
366 de> contributed little patches and tests here and there.
367
369 Copyright 2003-2007 by muppet and the gtk2-perl team
370 This library is free software; you can redistribute it and/or modify it
372 under the terms of the Lesser General Public License (LGPL). For more
373 information, see http://www.fsf.org/licenses/lgpl.txt
374perl v5.8.8 2007-02-26 Glib(3)