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
22 materials you can find on using GLib may still apply to using the
23 libraries from perl. This module also provides facilities for creating
24 wrappers for other GObject-based libraries. The "SEE ALSO" section
25 contains 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
36 list), GHashTable, GArray, etc have all been replaced by native Perl
37 datatypes. In fact, many functions which take GLists or arrays simply
38 accept lists on the Perl stack. For the most part, GIOChannels are no
39 more functional than Perl file handles, so you won't see any
40 GIOChannels. GClosures are not visible at the Perl level, because Perl
41 code references do the same thing. Just about any function taking
42 either a C function pointer or a GClosure will accept a code reference
43 in Perl. (In fact, you can probably get away with just a subroutine
44 name in many spots, provided you aren't using strict subs.)
45 Don't Worry About That
47 Some concepts have been eliminated; you need never worry about
48 reference-counting on GObjects or having to free GBoxed structures.
49 Perl is a garbage-collected language, and we've put a lot of work into
50 making the bindings take care of memory for you in a way that feels
51 natural to a Perl developer. You won't see GValues in Perl (that's
52 just a C structure with Perl scalar envy, anyway).
53 This Is Now That
55 Other GLib concepts have been converted to an analogous Perl concept.
56 The GType id will never be seen in Perl, as the package name serves
58 that purpose. Several packages corresponding to the GTypes of the
59 fundamental types have been registered for you:
60 G_TYPE_STRING Glib::String
62 G_TYPE_INT Glib::Int
63 G_TYPE_UINT Glib::UInt
64 G_TYPE_DOUBLE Glib::Double
65 G_TYPE_BOOLEAN Glib::Boolean
66 The remaining fundamentals (char/uchar, short, float, etc) are also
68 registered so that we can properly interact with properties of C
69 objects, but perl really only uses ints, uints, and doubles. Oh, and
70 we created a GBoxed type for Perl scalars so you can use scalars where
71 any boxed type would be allowed (e.g. GtkTreeModel columns):
72 Glib::Scalar
74 Functions that can return false and set a GError in C raise an
76 exception in Perl, using an exception object based on the GError for
77 $@; see Glib::Error. Trapping exceptions in signals is a sticky issue,
78 so they get their own section; see EXCEPTIONS.
79 Enumerations and flags are treated as strings and arrays of strings,
81 respectively. GLib provides a way to register nicknames for
82 enumeration values, and the Perl bindings use these nicknames for the
83 real values, so that we never have to deal with numbers in Perl. This
84 can get a little cumbersome for bitfields, but it's very nice when you
85 forget a flag value, as the bindings will tell you what values are
86 accepted when you pass something invalid. Also, the bindings consider
87 the - and _ characters to be equivalent, so that signal and property
88 names can be properly stringified by the => operator. For example, the
89 following are equivalent:
90 # property foo-matic of type FooType, using the
92 # value FOO_SOMETHING_COOL. its nickname would be
93 # 'something-cool'. you may use either the full
94 # name or the nickname when supplying values to perl.
95 $object->set ('foo-matic', 'FOO_SOMETHING_COOL');
96 $object->set ('foo_matic', 'something_cool');
97 $object->set (foo_matic => 'something-cool');
98 Beware that Perl will always return to you the nickname form, with the
100 dash.
101 Flags have some additional magic abilities in the form of overloaded
103 operators:
104 + or | union of two flagsets ("add")
106 - difference of two flagsets ("sub", "remove")
107 * or & intersection of two bitsets ("and")
108 / or ^ symmetric difference ("xor", you will rarely need this)
109 >= contains-operator ("is the left set a superset of the right set?")
110 == equality
111 In addition, flags in boolean context indicate whether they are empty
113 or not, which allows you to write common operations naturally:
114 $widget->set_events ($widget->get_events - "motion_notify_mask");
116 $widget->set_events ($widget->get_events - ["motion_notify_mask",
117 "button_press_mask"]);
118 # shift pressed (both work, it's a matter of taste)
120 if ($event->state >= "shift-mask") { ...
121 if ($event->state * "shift-mask") { ...
122 # either shift OR control pressed?
124 if ($event->state * ["shift-mask", "control-mask"]) { ...
125 # both shift AND control pressed?
127 if ($event->state >= ["shift-mask", "control-mask"]) { ...
128 In general, "+" and "-" work as expected to add or remove flags. To
130 test whether any bits are set in a mask, you use "$mask * ...", and to
131 test whether all bits are set in a mask, you use "$mask >= ...".
132 When dereferenced as an array @$flags or "$flags->[...]", you can
134 access the flag values directly as strings (but you are not allowed to
135 modify the array), and when stringified "$flags" a flags value will
136 output a human-readable version of its contents.
137 It's All the Same
139 For the most part, the remaining bits of GLib are unchanged. GMainLoop
140 is now Glib::MainLoop, GObject is now Glib::Object, GBoxed is now
141 Glib::Boxed, etc.
142
144 Perl knows two datatypes, unicode text and binary bytes. Filenames on a
145 system that doesn't use a utf-8 locale are often stored in a local
146 encoding ("binary bytes"). Gtk+ and descendants, however, internally
147 work in unicode most of the time, so when feeding a filename into a
148 GLib/Gtk+ function that expects a filename, you first need to convert
149 it from the local encoding to unicode.
150 This involves some elaborate guessing, which perl currently avoids, but
152 GLib and Gtk+ do. As an exception, some Gtk+ functions want a filename
153 in local encoding, but the perl interface usually works around this by
154 automatically converting it for you.
155 In short: Everything should be in unicode on the perl level.
157 The following functions expose the conversion algorithm that GLib uses.
159 These functions are only necessary when you want to use perl functions
161 to manage filenames returned by a GLib/Gtk+ function, or when you feed
162 filenames into GLib/Gtk+ functions that have their source outside your
163 program (e.g. commandline arguments, readdir results etc.).
164 These functions are available as exports by request (see "Exports"),
166 and also support method invocation syntax for pathological consistency
167 with the OO syntax of the rest of the bindings.
168 $filename = filename_to_unicode $filename_in_local_encoding
170 $filename = Glib->filename_to_unicode ($filename_in_local_encoding)
171 Convert a perl string that supposedly contains a filename in local
172 encoding into a filename represented as unicode, the same way that
173 GLib does it internally.
174 Example:
176 $gtkfilesel->set_filename (filename_to_unicode $ARGV[1]);
178 This function will croak() if the conversion cannot be made, e.g.,
180 because the utf-8 is invalid.
181 $filename_in_local_encoding = filename_from_unicode $filename
183 $filename_in_local_encoding = Glib->filename_from_unicode ($filename)
184 Converts a perl string containing a filename into a filename in the
185 local encoding in the same way GLib does it.
186 Example:
188 open MY, "<", filename_from_unicode $gtkfilesel->get_filename;
190 It might be useful to know that perl currently has no policy at all
192 regarding filename issues, if your scalar happens to be in utf-8
193 internally it will use utf-8, if it happens to be stored as bytes, it
194 will use it as-is.
195 When dealing with filenames that you need to display, there is a much
197 easier way, as of Glib 1.120 and glib 2.6.0:
198 $uft8_string = filename_display_name ($filename)
200 $uft8_string = filename_display_basename ($filename)
201 Given a $filename in filename encoding, return the filename, or
202 just the file's basename, in utf-8. Unlike the other functions
203 described above, this one is guaranteed to return valid utf-8, but
204 the conversion is not necessarily reversible. These functions are
205 intended to be used for failsafe display of filenames, for example
206 in gtk+ labels.
207 Since glib 2.6, Glib 1.12
209 The following convert filenames to and from URI encoding. (See also
211 URI::file.)
212 $string = filename_to_uri ($filename, $hostname)
214 $string = Glib->filename_to_uri ($filename, $hostname)
215 Return a "file://" schema URI for a filename. Unsafe and non-ascii
216 chars in $filename are escaped with URI "%" forms.
217 $filename must be an absolute path as a byte string in local
219 filesystem encoding. $hostname is a utf-8 string, or empty or
220 "undef" for no host specified. For example,
221 filename_to_uri ('/my/x%y/<dir>/foo.html', undef);
223 # returns 'file:///my/x%25y/%3Cdir%3E/foo.html'
224 If $filename is a relative path or $hostname doesn't look like a
226 hostname then "filename_to_uri" croaks with a "Glib::Error".
227 When using the class style "Glib->filename_to_uri" remember that
229 the $hostname argument is mandatory. If you forget then it looks
230 like a 2-argument call with filename of "Glib" and hostname of what
231 you meant to be the filename.
232 $filename = filename_from_uri ($uri)
234 ($filename, $hostname) = filename_from_uri ($uri)
235 Extract the filename and hostname from a "file://" schema URI. In
236 scalar context just the filename is returned, in array context both
237 filename and hostname are returned.
238 The filename returned is bytes in the local filesystem encoding and
240 with the OS path separator character. The hostname returned is
241 utf-8. For example,
242 ($f,$h) = filename_from_uri ('file://foo.com/r%26b/bar.html');
244 # returns '/r&b/bar.html' and 'foo.com' on Unix
245 If $uri is not a "file:", or is mal-formed, or the hostname part
247 doesn't look like a host name then "filename_from_uri" croaks with
248 a "Glib::Error".
249
251 The C language doesn't support exceptions; GLib is a C library, and of
252 course doesn't support exceptions either. In Perl, we use die and eval
253 to raise and trap exceptions as a rather common practice. So, the
254 bindings have to work a little black magic behind the scenes to keep
255 GLib from exploding when the Perl program uses exceptions.
256 Unfortunately, a little of this magic has to leak out to where you can
257 see it at the Perl level.
258 Signal and event handlers are run in an eval context; if an exception
260 occurs in such a handler and you don't catch it, Perl will report that
261 an error occurred, and then go on about its business like nothing
262 happened.
263 You may register subroutines as exception handlers, to be called when
265 such an exception is trapped. Another function removes them for you.
266 $tag = Glib->install_exception_handler (\&my_handler);
268 Glib->remove_exception_handler ($tag);
269 The exception handler will get a fresh copy of the $@ of the offending
271 exception on the argument stack, and is expected to return non-zero if
272 the handler is to remain installed. If it returns false, the handler
273 will be removed.
274 sub my_handler {
276 if ($_[0] =~ m/ftang quisinart/) {
277 clean_up_after_ftang ();
278 }
279 1; # live to fight another day
280 }
281 You can register as many handlers as you like; they will all run
283 independently.
284 An important thing to remember is that exceptions do not cross main
286 loops. In fact, exceptions are completely distinct from main loops.
287 If you need to quit a main loop when an exception occurs, install a
288 handler that quits the main loop, but also ask yourself if you are
289 using exceptions for flow control or exception handling.
290
292 GLib's g_log function provides a flexible mechanism for reporting
293 messages, and most GLib-based C libraries use this mechanism for
294 warnings, assertions, critical messages, etc. The Perl bindings offer
295 a mechanism for routing these messages through Perl's native system,
296 warn() and die(). Extensions should register the log domains they wrap
297 for this to happen fluidly. [FIXME say more here]
298
300 Since perl's integer data type can only hold 32 bit values on all 32
301 bit machines and even on some 64 bit machines, Glib converts 64 bit
302 integers to and from strings if necessary. These strings can then be
303 used to feed one of the various big integer modules. Make sure you
304 don't let your strings get into numerical context before passing them
305 into a Glib function because in this case, perl will convert the number
306 to scientific notation which at this point is not understood by Glib's
307 converters.
308 Here is an overview of what big integer modules are available. First
310 of all, there's Math::BigInt. It has everything you will ever need,
311 but its pure-Perl implementation is also rather slow. There are
312 multiple ways around this, though.
313 Math::BigInt::FastCalc
315 Math::BigInt::FastCalc can help avoid the glacial speed of vanilla
316 Math::BigInt::Calc. Recent versions of Math::BigInt will
317 automatically use Math::BigInt::FastCalc in place of
318 Math::BigInt::Calc when available. Other options include
319 Math::BigInt::GMP or Math::BigInt::Pari, which however have much
320 larger dependencies.
321 Math::BigInt::Lite
323 Then there's Math::BigInt::Lite, which uses native Perl integer
324 operations as long as Perl integers have sufficient range, and
325 upgrades itself to Math::BigInt when Perl integers would overflow.
326 This must be used in place of Math::BigInt.
327 bigint / bignum / bigfloat
329 Finally, there's the bigint/bignum/bigfloat pragmata, which
330 automatically load the corresponding Math:: modules and which will
331 autobox constants. bignum/bigint will automatically use
332 Math::BigInt::Lite if it's available.
333
335 For the most part, gtk2-perl avoids exporting things. Nothing is
336 exported by default, but some functions and constants in Glib are
337 available by request; you can also get all of them with the export tag
338 "all".
339 Tag: constants
341 TRUE
342 FALSE
343 G_PRIORITY_HIGH
344 G_PRIORITY_DEFAULT
345 G_PRIORITY_HIGH_IDLE
346 G_PRIORITY_DEFAULT_IDLE
347 G_PRIORITY_LOW
348 G_PARAM_READWRITE
349 Tag: functions
351 filename_from_unicode
352 filename_to_unicode
353 filename_from_uri
354 filename_to_uri
355 filename_display_basename
356 filename_display_name
357
359 Glib::Object::Subclass explains how to create your own gobject
360 subclasses in Perl.
361 Glib::index lists the automatically-generated API reference for the
363 various packages in Glib.
364 This module is the basis for the Gtk2 module, so most of the references
366 you'll be able to find about this one are tied to that one. The perl
367 interface aims to be very simply related to the C API, so see the C API
368 reference documentation:
369 GLib - http://developer.gnome.org/doc/API/2.0/glib/
371 GObject - http://developer.gnome.org/doc/API/2.0/gobject/
372 This module serves as the foundation for any module which needs to bind
374 GLib-based C libraries to perl.
375 Glib::devel - Binding developer's overview of Glib's internals
377 Glib::xsapi - internal API reference for GPerl
378 Glib::ParseXSDoc - extract API docs from xs sources.
379 Glib::GenPod - turn the output of Glib::ParseXSDoc into POD
380 Glib::MakeHelper - Makefile.PL utilities for Glib-based extensions
381 Yet another document, available separately, ties it all together:
383 http://gtk2-perl.sourceforge.net/doc/binding_howto.pod.html
384 For gtk2-perl itself, see its website at
386 gtk2-perl - http://gtk2-perl.sourceforge.net/
388 A mailing list exists for discussion of using gtk2-perl and related
390 modules. Archives and subscription information are available at
391 http://lists.gnome.org/.
392
394 muppet, <scott at asofyet dot org>, who borrowed heavily from the work
395 of Goeran Thyni, <gthyni at kirra dot net> and Guillaume Cottenceau <gc
396 at mandrakesoft dot com> on the first gtk2-perl module, and from the
397 sourcecode of the original gtk-perl and pygtk projects. Marc Lehmann
398 <pcg at goof dot com> did lots of great work on the magic of making
399 Glib::Object wrapper and subclassing work like they should. Ross
400 McFarland <rwmcfa1 at neces dot com> wrote quite a bit of the
401 documentation generation tools. Torsten Schoenfeld <kaffeetisch at web
402 dot de> contributed little patches and tests here and there.
403
405 Copyright 2003-2009 by muppet and the gtk2-perl team
406 This library is free software; you can redistribute it and/or modify it
408 under the terms of the Lesser General Public License (LGPL). For more
409 information, see http://www.fsf.org/licenses/lgpl.txt
410perl v5.12.1 2010-05-30 Glib(3)