1Glib(3)               User Contributed Perl Documentation              Glib(3)
2
3
4

NAME

6       Glib - Perl wrappers for the GLib utility and Object libraries
7

SYNOPSIS

9         use Glib;
10

ABSTRACT

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

DESCRIPTION

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

PERL VERSUS C

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
34   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
46   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
54   This Is Now That
55       Other GLib concepts have been converted to an analogous Perl concept.
56
57       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
61        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
67       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
73        Glib::Scalar
74
75       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
80       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
91         # 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
99       Beware that Perl will always return to you the nickname form, with the
100       dash.
101
102       Flags have some additional magic abilities in the form of overloaded
103       operators:
104
105         + 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
112       In addition, flags in boolean context indicate whether they are empty
113       or not, which allows you to write common operations naturally:
114
115         $widget->set_events ($widget->get_events - "motion_notify_mask");
116         $widget->set_events ($widget->get_events - ["motion_notify_mask",
117                                                     "button_press_mask"]);
118
119         # shift pressed (both work, it's a matter of taste)
120         if ($event->state >= "shift-mask") { ...
121         if ($event->state * "shift-mask") { ...
122
123         # either shift OR control pressed?
124         if ($event->state * ["shift-mask", "control-mask"]) { ...
125
126         # both shift AND control pressed?
127         if ($event->state >= ["shift-mask", "control-mask"]) { ...
128
129       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
133       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
138   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

FILENAMES, URIS AND ENCODINGS

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
151       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
156       In short: Everything should be in unicode on the perl level.
157
158       The following functions expose the conversion algorithm that GLib uses.
159
160       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
165       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
169       $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
175           Example:
176
177              $gtkfilesel->set_filename (filename_to_unicode $ARGV[1]);
178
179           This function will croak() if the conversion cannot be made, e.g.,
180           because the utf-8 is invalid.
181
182       $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
187           Example:
188
189              open MY, "<", filename_from_unicode $gtkfilesel->get_filename;
190
191       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
196       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
199       $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
208           Since glib 2.6, Glib 1.12
209
210       The following convert filenames to and from URI encoding.  (See also
211       URI::file.)
212
213       $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
218           $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
222               filename_to_uri ('/my/x%y/<dir>/foo.html', undef);
223               # returns 'file:///my/x%25y/%3Cdir%3E/foo.html'
224
225           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
228           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
233       $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
239           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
243               ($f,$h) = filename_from_uri ('file://foo.com/r%26b/bar.html');
244               # returns '/r&b/bar.html' and 'foo.com' on Unix
245
246           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

EXCEPTIONS

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
259       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
264       You may register subroutines as exception handlers, to be called when
265       such an exception is trapped.  Another function removes them for you.
266
267         $tag = Glib->install_exception_handler (\&my_handler);
268         Glib->remove_exception_handler ($tag);
269
270       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
275         sub my_handler {
276             if ($_[0] =~ m/ftang quisinart/) {
277                  clean_up_after_ftang ();
278             }
279             1; # live to fight another day
280         }
281
282       You can register as many handlers as you like; they will all run
283       independently.
284
285       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

LOG MESSAGES

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

64 BIT INTEGERS

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
309       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
314       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
322       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
328       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

EXPORTS

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
340       Tag: constants
341             TRUE
342             FALSE
343             SOURCE_CONTINUE
344             SOURCE_REMOVE
345             G_PRIORITY_HIGH
346             G_PRIORITY_DEFAULT
347             G_PRIORITY_HIGH_IDLE
348             G_PRIORITY_DEFAULT_IDLE
349             G_PRIORITY_LOW
350             G_PARAM_READWRITE
351
352       Tag: functions
353             filename_from_unicode
354             filename_to_unicode
355             filename_from_uri
356             filename_to_uri
357             filename_display_basename
358             filename_display_name
359

SEE ALSO

361       Glib::Object::Subclass explains how to create your own gobject
362       subclasses in Perl.
363
364       Glib::index lists the automatically-generated API reference for the
365       various packages in Glib.
366
367       This module is the basis for the Gtk2 module, so most of the references
368       you'll be able to find about this one are tied to that one.  The perl
369       interface aims to be very simply related to the C API, so see the C API
370       reference documentation:
371
372         GLib - http://developer.gnome.org/doc/API/2.0/glib/
373         GObject - http://developer.gnome.org/doc/API/2.0/gobject/
374
375       This module serves as the foundation for any module which needs to bind
376       GLib-based C libraries to perl.
377
378         Glib::devel - Binding developer's overview of Glib's internals
379         Glib::xsapi - internal API reference for GPerl
380         Glib::ParseXSDoc - extract API docs from xs sources.
381         Glib::GenPod - turn the output of Glib::ParseXSDoc into POD
382         Glib::MakeHelper - Makefile.PL utilities for Glib-based extensions
383
384         Yet another document, available separately, ties it all together:
385           http://gtk2-perl.sourceforge.net/doc/binding_howto.pod.html
386
387       For gtk2-perl itself, see its website at
388
389         gtk2-perl - http://gtk2-perl.sourceforge.net/
390
391       A mailing list exists for discussion of using gtk2-perl and related
392       modules.  Archives and subscription information are available at
393       http://lists.gnome.org/.
394

AUTHORS

396       muppet, <scott at asofyet dot org>, who borrowed heavily from the work
397       of Göran Thyni, <gthyni at kirra dot net> and Guillaume Cottenceau <gc
398       at mandrakesoft dot com> on the first gtk2-perl module, and from the
399       sourcecode of the original gtk-perl and pygtk projects.  Marc Lehmann
400       <pcg at goof dot com> did lots of great work on the magic of making
401       Glib::Object wrapper and subclassing work like they should.  Ross
402       McFarland <rwmcfa1 at neces dot com> wrote quite a bit of the
403       documentation generation tools.  Torsten Schoenfeld <kaffeetisch at web
404       dot de> contributed little patches and tests here and there.
405
407       Copyright 2003-2011 by muppet and the gtk2-perl team
408
409       This library is free software; you can redistribute it and/or modify it
410       under the terms of the Lesser General Public License (LGPL).  For more
411       information, see http://www.fsf.org/licenses/lgpl.txt
412
413
414
415perl v5.32.0                      2020-07-28                           Glib(3)
Impressum