.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Glib 3pm" .TH Glib 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Glib \- Perl wrappers for the GLib utility and Object libraries .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Glib; .Ve .SH ABSTRACT .IX Header "ABSTRACT" This module provides perl access to GLib and GLib's GObject libraries. GLib is a portability and utility library; GObject provides a generic type system with inheritance and a powerful signal system. Together these libraries are used as the foundation for many of the libraries that make up the Gnome environment, and are used in many unrelated projects. .SH DESCRIPTION .IX Header "DESCRIPTION" This wrapper attempts to provide a perlish interface while remaining as true as possible to the underlying C API, so that any reference materials you can find on using GLib may still apply to using the libraries from perl. This module also provides facilities for creating wrappers for other GObject-based libraries. The "SEE ALSO" section contains pointers to all sorts of good information. .SH "PERL VERSUS C" .IX Header "PERL VERSUS C" GLib provides to C programs many of the same facilities Perl offers natively. Where GLib's functionality overlaps Perl's, Perl's is favored. Some concepts have been eliminated entirely, as Perl is a higher-level language than C. In other instances we've had to add or change APIs to make sense in Perl. Here's a quick run-down: .SS "Perl Already Does That" .IX Subsection "Perl Already Does That" The GLib types GList (a doubly-linked list), GSList (singly-linked list), GHashTable, GArray, etc have all been replaced by native Perl datatypes. In fact, many functions which take GLists or arrays simply accept lists on the Perl stack. For the most part, GIOChannels are no more functional than Perl file handles, so you won't see any GIOChannels. GClosures are not visible at the Perl level, because Perl code references do the same thing. Just about any function taking either a C function pointer or a GClosure will accept a code reference in Perl. (In fact, you can probably get away with just a subroutine name in many spots, provided you aren't using strict subs.) .SS "Don't Worry About That" .IX Subsection "Don't Worry About That" Some concepts have been eliminated; you need never worry about reference-counting on GObjects or having to free GBoxed structures. Perl is a garbage-collected language, and we've put a lot of work into making the bindings take care of memory for you in a way that feels natural to a Perl developer. You won't see GValues in Perl (that's just a C structure with Perl scalar envy, anyway). .SS "This Is Now That" .IX Subsection "This Is Now That" Other GLib concepts have been converted to an analogous Perl concept. .PP The GType id will never be seen in Perl, as the package name serves that purpose. Several packages corresponding to the GTypes of the fundamental types have been registered for you: .PP .Vb 5 \& G_TYPE_STRING Glib::String \& G_TYPE_INT Glib::Int \& G_TYPE_UINT Glib::UInt \& G_TYPE_DOUBLE Glib::Double \& G_TYPE_BOOLEAN Glib::Boolean .Ve .PP The remaining fundamentals (char/uchar, short, float, etc) are also registered so that we can properly interact with properties of C objects, but perl really only uses ints, uints, and doubles. Oh, and we created a GBoxed type for Perl scalars so you can use scalars where any boxed type would be allowed (e.g. GtkTreeModel columns): .PP .Vb 1 \& Glib::Scalar .Ve .PP Functions that can return false and set a GError in C raise an exception in Perl, using an exception object based on the GError for $@; see Glib::Error. Trapping exceptions in signals is a sticky issue, so they get their own section; see EXCEPTIONS. .PP Enumerations and flags are treated as strings and arrays of strings, respectively. GLib provides a way to register nicknames for enumeration values, and the Perl bindings use these nicknames for the real values, so that we never have to deal with numbers in Perl. This can get a little cumbersome for bitfields, but it's very nice when you forget a flag value, as the bindings will tell you what values are accepted when you pass something invalid. Also, the bindings consider the \- and _ characters to be equivalent, so that signal and property names can be properly stringified by the => operator. For example, the following are equivalent: .PP .Vb 7 \& # property foo\-matic of type FooType, using the \& # value FOO_SOMETHING_COOL. its nickname would be \& # \*(Aqsomething\-cool\*(Aq. you may use either the full \& # name or the nickname when supplying values to perl. \& $object\->set (\*(Aqfoo\-matic\*(Aq, \*(AqFOO_SOMETHING_COOL\*(Aq); \& $object\->set (\*(Aqfoo_matic\*(Aq, \*(Aqsomething_cool\*(Aq); \& $object\->set (foo_matic => \*(Aqsomething\-cool\*(Aq); .Ve .PP Beware that Perl will always return to you the nickname form, with the dash. .PP Flags have some additional magic abilities in the form of overloaded operators: .PP .Vb 6 \& + or | union of two flagsets ("add") \& \- difference of two flagsets ("sub", "remove") \& * or & intersection of two bitsets ("and") \& / or ^ symmetric difference ("xor", you will rarely need this) \& >= contains\-operator ("is the left set a superset of the right set?") \& == equality .Ve .PP In addition, flags in boolean context indicate whether they are empty or not, which allows you to write common operations naturally: .PP .Vb 3 \& $widget\->set_events ($widget\->get_events \- "motion_notify_mask"); \& $widget\->set_events ($widget\->get_events \- ["motion_notify_mask", \& "button_press_mask"]); \& \& # shift pressed (both work, it\*(Aqs a matter of taste) \& if ($event\->state >= "shift\-mask") { ... \& if ($event\->state * "shift\-mask") { ... \& \& # either shift OR control pressed? \& if ($event\->state * ["shift\-mask", "control\-mask"]) { ... \& \& # both shift AND control pressed? \& if ($event\->state >= ["shift\-mask", "control\-mask"]) { ... .Ve .PP In general, \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR work as expected to add or remove flags. To test whether \fIany\fR bits are set in a mask, you use \f(CW\*(C`$mask * ...\*(C'\fR, and to test whether \fIall\fR bits are set in a mask, you use \f(CW\*(C`$mask >= ...\*(C'\fR. .PP When dereferenced as an array \f(CW@$flags\fR or \f(CW\*(C`$flags\->[...]\*(C'\fR, you can access the flag values directly as strings (but you are not allowed to modify the array), and when stringified \f(CW"$flags"\fR a flags value will output a human-readable version of its contents. .SS "It's All the Same" .IX Subsection "It's All the Same" For the most part, the remaining bits of GLib are unchanged. GMainLoop is now Glib::MainLoop, GObject is now Glib::Object, GBoxed is now Glib::Boxed, etc. .SH "FILENAMES, URIS AND ENCODINGS" .IX Header "FILENAMES, URIS AND ENCODINGS" Perl knows two datatypes, unicode text and binary bytes. Filenames on a system that doesn't use a utf\-8 locale are often stored in a local encoding ("binary bytes"). Gtk+ and descendants, however, internally work in unicode most of the time, so when feeding a filename into a GLib/Gtk+ function that expects a filename, you first need to convert it from the local encoding to unicode. .PP This involves some elaborate guessing, which perl currently avoids, but GLib and Gtk+ do. As an exception, some Gtk+ functions want a filename in local encoding, but the perl interface usually works around this by automatically converting it for you. .PP In short: Everything should be in unicode on the perl level. .PP The following functions expose the conversion algorithm that GLib uses. .PP These functions are only necessary when you want to use perl functions to manage filenames returned by a GLib/Gtk+ function, or when you feed filenames into GLib/Gtk+ functions that have their source outside your program (e.g. commandline arguments, readdir results etc.). .PP These functions are available as exports by request (see "Exports"), and also support method invocation syntax for pathological consistency with the OO syntax of the rest of the bindings. .ie n .IP "$filename = filename_to_unicode $filename_in_local_encoding" 4 .el .IP "\f(CW$filename\fR = filename_to_unicode \f(CW$filename_in_local_encoding\fR" 4 .IX Item "$filename = filename_to_unicode $filename_in_local_encoding" .PD 0 .ie n .IP "$filename = Glib\->filename_to_unicode ($filename_in_local_encoding)" 4 .el .IP "\f(CW$filename\fR = Glib\->filename_to_unicode ($filename_in_local_encoding)" 4 .IX Item "$filename = Glib->filename_to_unicode ($filename_in_local_encoding)" .PD Convert a perl string that supposedly contains a filename in local encoding into a filename represented as unicode, the same way that GLib does it internally. .Sp Example: .Sp .Vb 1 \& $gtkfilesel\->set_filename (filename_to_unicode $ARGV[1]); .Ve .Sp This function will \fBcroak()\fR if the conversion cannot be made, e.g., because the utf\-8 is invalid. .ie n .IP "$filename_in_local_encoding = filename_from_unicode $filename" 4 .el .IP "\f(CW$filename_in_local_encoding\fR = filename_from_unicode \f(CW$filename\fR" 4 .IX Item "$filename_in_local_encoding = filename_from_unicode $filename" .PD 0 .ie n .IP "$filename_in_local_encoding = Glib\->filename_from_unicode ($filename)" 4 .el .IP "\f(CW$filename_in_local_encoding\fR = Glib\->filename_from_unicode ($filename)" 4 .IX Item "$filename_in_local_encoding = Glib->filename_from_unicode ($filename)" .PD Converts a perl string containing a filename into a filename in the local encoding in the same way GLib does it. .Sp Example: .Sp .Vb 1 \& open MY, "<", filename_from_unicode $gtkfilesel\->get_filename; .Ve .PP It might be useful to know that perl currently has no policy at all regarding filename issues, if your scalar happens to be in utf\-8 internally it will use utf\-8, if it happens to be stored as bytes, it will use it as-is. .PP When dealing with filenames that you need to display, there is a much easier way, as of Glib 1.120 and glib 2.6.0: .ie n .IP "$uft8_string = filename_display_name ($filename)" 4 .el .IP "\f(CW$uft8_string\fR = filename_display_name ($filename)" 4 .IX Item "$uft8_string = filename_display_name ($filename)" .PD 0 .ie n .IP "$uft8_string = filename_display_basename ($filename)" 4 .el .IP "\f(CW$uft8_string\fR = filename_display_basename ($filename)" 4 .IX Item "$uft8_string = filename_display_basename ($filename)" .PD Given a \fR\f(CI$filename\fR\fI\fR in filename encoding, return the filename, or just the file's basename, in utf\-8. Unlike the other functions described above, this one is guaranteed to return valid utf\-8, but the conversion is not necessarily reversible. These functions are intended to be used for failsafe display of filenames, for example in gtk+ labels. .Sp Since glib 2.6, Glib 1.12 .PP The following convert filenames to and from URI encoding. (See also URI::file.) .ie n .IP "$string = filename_to_uri ($filename, $hostname)" 4 .el .IP "\f(CW$string\fR = filename_to_uri ($filename, \f(CW$hostname\fR)" 4 .IX Item "$string = filename_to_uri ($filename, $hostname)" .PD 0 .ie n .IP "$string = Glib\->filename_to_uri ($filename, $hostname)" 4 .el .IP "\f(CW$string\fR = Glib\->filename_to_uri ($filename, \f(CW$hostname\fR)" 4 .IX Item "$string = Glib->filename_to_uri ($filename, $hostname)" .PD Return a "file://" schema URI for a filename. Unsafe and non-ascii chars in \&\f(CW$filename\fR are escaped with URI "%" forms. .Sp \&\f(CW$filename\fR must be an absolute path as a byte string in local filesystem encoding. \f(CW$hostname\fR is a utf\-8 string, or empty or \f(CW\*(C`undef\*(C'\fR for no host specified. For example, .Sp .Vb 2 \& filename_to_uri (\*(Aq/my/x%y/