|$filename = filename_to_unicode $filename_in_local_encoding|
|$filename = Glib->filename_to_unicode ($filename_in_local_encoding)||
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.
This function will croak() if the conversion cannot be made, e.g., because the utf-8 is invalid.
|$filename_in_local_encoding = filename_from_unicode $filename|
|$filename_in_local_encoding = Glib->filename_from_unicode ($filename)||
Converts a perl string containing a filename into a filename in the local
encoding in the same way GLib does it.
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:
|$uft8_string = filename_display_name ($filename)|
|$uft8_string = filename_display_basename ($filename)||
Given a $filename in filename encoding, return the filename, or just
the files 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.
Since glib 2.6, Glib 1.12
|$string = filename_to_uri ($filename, $hostname)|
|$string = Glib->filename_to_uri ($filename, $hostname)||
Return a file:// schema URI for a filename. Unsafe and non-ascii chars in
$filename are escaped with URI % forms.
$filename must be an absolute path as a byte string in local filesystem encoding. $hostname is a utf-8 string, or empty or undef for no host specified. For example,
When using the class style Glib->filename_to_uri remember that the $hostname argument is mandatory. If you forget then it looks like a 2-argument call with filename of Glib and hostname of what you meant to be the filename.
|$filename = filename_from_uri ($uri)|
|($filename, $hostname) = filename_from_uri ($uri)||
Extract the filename and hostname from a file:// schema URI. In scalar
context just the filename is returned, in array context both filename and
hostname are returned.
If $uri is not a file:, or is mal-formed, or the hostname part doesnt look like a host name then filename_from_uri croaks with a Glib::Error.
The C language doesnt support exceptions; GLib is a C library, and of course doesnt support exceptions either. In Perl, we use die and eval to raise and trap exceptions as a rather common practice. So, the bindings have to work a little black magic behind the scenes to keep GLib from exploding when the Perl program uses exceptions. Unfortunately, a little of this magic has to leak out to where you can see it at the Perl level.
Signal and event handlers are run in an eval context; if an exception occurs in such a handler and you dont catch it, Perl will report that an error occurred, and then go on about its business like nothing happened.
You may register subroutines as exception handlers, to be called when such an exception is trapped. Another function removes them for you.
$tag = Glib->install_exception_handler (\&my_handler); Glib->remove_exception_handler ($tag);
The exception handler will get a fresh copy of the $@ of the offending exception on the argument stack, and is expected to return non-zero if the handler is to remain installed. If it returns false, the handler will be removed.
You can register as many handlers as you like; they will all run independently.
An important thing to remember is that exceptions do not cross main loops. In fact, exceptions are completely distinct from main loops. If you need to quit a main loop when an exception occurs, install a handler that quits the main loop, but also ask yourself if you are using exceptions for flow control or exception handling.
GLibs g_log function provides a flexible mechanism for reporting messages, and most GLib-based C libraries use this mechanism for warnings, assertions, critical messages, etc. The Perl bindings offer a mechanism for routing these messages through Perls native system, warn() and die(). Extensions should register the log domains they wrap for this to happen fluidly. [FIXME say more here]
Since perls integer data type can only hold 32 bit values on all 32 bit machines and even on some 64 bit machines, Glib converts 64 bit integers to and from strings if necessary. These strings can then be used to feed one of the various big integer modules. Make sure you dont let your strings get into numerical context before passing them into a Glib function because in this case, perl will convert the number to scientific notation which at this point is not understood by Glibs converters.
Here is an overview of what big integer modules are available. First of all, theres Math::BigInt. It has everything you will ever need, but its pure-Perl implementation is also rather slow. There are multiple ways around this, though.
Math::BigInt::FastCalc Math::BigInt::FastCalc can help avoid the glacial speed of vanilla Math::BigInt::Calc. Recent versions of Math::BigInt will automatically use Math::BigInt::FastCalc in place of Math::BigInt::Calc when available. Other options include Math::BigInt::GMP or Math::BigInt::Pari, which however have much larger dependencies. Math::BigInt::Lite Then theres Math::BigInt::Lite, which uses native Perl integer operations as long as Perl integers have sufficient range, and upgrades itself to Math::BigInt when Perl integers would overflow. This must be used in place of Math::BigInt. bigint / bignum / bigfloat Finally, theres the bigint/bignum/bigfloat pragmata, which automatically load the corresponding Math:: modules and which will autobox constants. bignum/bigint will automatically use Math::BigInt::Lite if its available.
For the most part, gtk2-perl avoids exporting things. Nothing is exported by default, but some functions and constants in Glib are available by request; you can also get all of them with the export tag all.
Tag: constants TRUE FALSE SOURCE_CONTINUE SOURCE_REMOVE G_PRIORITY_HIGH G_PRIORITY_DEFAULT G_PRIORITY_HIGH_IDLE G_PRIORITY_DEFAULT_IDLE G_PRIORITY_LOW G_PARAM_READWRITE Tag: functions filename_from_unicode filename_to_unicode filename_from_uri filename_to_uri filename_display_basename filename_display_name
Glib::Object::Subclass explains how to create your own gobject subclasses in Perl.
Glib::index lists the automatically-generated API reference for the various packages in Glib.
This module is the basis for the Gtk2 module, so most of the references youll be able to find about this one are tied to that one. The perl interface aims to be very simply related to the C API, so see the C API reference documentation:
This module serves as the foundation for any module which needs to bind GLib-based C libraries to perl.
Glib::devel - Binding developers overview of Glibs internals Glib::xsapi - internal API reference for GPerl Glib::ParseXSDoc - extract API docs from xs sources. Glib::GenPod - turn the output of Glib::ParseXSDoc into POD Glib::MakeHelper - Makefile.PL utilities for Glib-based extensions Yet another document, available separately, ties it all together: http://gtk2-perl.sourceforge.net/doc/binding_howto.pod.html
For gtk2-perl itself, see its website at
gtk2-perl - http://gtk2-perl.sourceforge.net/
A mailing list exists for discussion of using gtk2-perl and related modules. Archives and subscription information are available at http://lists.gnome.org/.
muppet, <scott at asofyet dot org>, who borrowed heavily from the work of Goeran Thyni, <gthyni at kirra dot net> and Guillaume Cottenceau <gc at mandrakesoft dot com> on the first gtk2-perl module, and from the sourcecode of the original gtk-perl and pygtk projects. Marc Lehmann <pcg at goof dot com> did lots of great work on the magic of making Glib::Object wrapper and subclassing work like they should. Ross McFarland <rwmcfa1 at neces dot com> wrote quite a bit of the documentation generation tools. Torsten Schoenfeld <kaffeetisch at web dot de> contributed little patches and tests here and there.
Copyright 2003-2011 by muppet and the gtk2-perl team
This library is free software; you can redistribute it and/or modify it under the terms of the Lesser General Public License (LGPL). For more information, see http://www.fsf.org/licenses/lgpl.txt
|perl v5.20.3||GLIB (3)||2015-07-12|