Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Glib::Object::IntrospeUsernContributed Perl DocuGlib::Object::Introspection(3)

       Glib::Object::Introspection - Dynamically create	Perl language bindings

	 use Glib::Object::Introspection;
	   basename => 'Gtk',
	   version => '3.0',
	   package => 'Gtk3');
	 # now GtkWindow, to mention just one example, is available as
	 # Gtk3::Window, and you can call gtk_window_new as Gtk3::Window->new

       Glib::Object::Introspection uses	the gobject-introspection and libffi
       projects	to dynamically create Perl bindings for	a wide variety of
       libraries.  Examples include gtk+, webkit, libsoup and many more.

       To allow	Glib::Object::Introspection to create bindings for a library,
       the library must	have installed a typelib file, for example
       "$prefix/lib/girepository-1.0/Gtk-3.0.typelib".	In your	code you then
       simply call "Glib::Object::Introspection->setup"	with the following
       key-value pairs to set everything up:

       basename	=> $basename
	   The basename	of the library that should be wrapped.	If your
	   typelib is called "Gtk-3.0.typelib",	then the basename is 'Gtk'.

       version => $version
	   The particular version of the library that should be	wrapped, in
	   string form.	 For "Gtk-3.0.typelib",	it is '3.0'.

       package => $package
	   The name of the Perl	package	where every class and method of	the
	   library should be rooted.  If a library with	basename 'Gtk'
	   contains an class 'GtkWindow', and you pick as the package 'Gtk3',
	   then	that class will	be available as	'Gtk3::Window'.

       The Perl	wrappers created by "Glib::Object::Introspection" follow the
       conventions of the Glib module and old hand-written bindings like Gtk2.
       You can use the included	tool "perli11ndoc" to view the documentation
       of all installed	libraries organized and	displayed in accordance	with
       these conventions.  The guiding principles underlying the conventions
       are described in	the following.

   Namespaces and Objects
       The namespaces of the C libraries are mapped to Perl packages according
       to the "package"	option specified, for example:

	 gtk_ => Gtk3
	 gdk_ => Gtk3::Gdk
	 gdk_pixbuf_ =>	Gtk3::Gdk::Pixbuf
	 pango_	=> Pango

       Classes,	interfaces and boxed and fundamental types get their own
       namespaces, in a	way, as	the concept of the GType is completely
       replaced	in the Perl bindings by	the Perl package name.

	 GtkButton => Gtk3::Button
	 GdkPixbuf => Gtk3::Gdk::Pixbuf
	 GtkScrolledWindow => Gtk3::ScrolledWindow
	 PangoFontDescription => Pango::FontDescription

       With this package mapping and Perl's built-in method lookup, the
       bindings	can do object casting for you.	This gives us a	rather
       comfortably object-oriented syntax, using normal	Perl object semantics:

	 in C:
	   GtkWidget * b;
	   b = gtk_check_button_new_with_mnemonic ("_Something");
	   gtk_toggle_button_set_active	(GTK_TOGGLE_BUTTON (b),	TRUE);
	   gtk_widget_show (b);

	 in Perl:
	   my $b = Gtk3::CheckButton->new_with_mnemonic	('_Something');
	   $b->set_active (1);

       You see from this that cast macros are not necessary and	that you don't
       need to type namespace prefixes quite so	often, so your code is a lot

   Flags and Enums
       Flags and enum values are handled as strings, because it's much more
       readable	than numbers, and because it's automagical thanks to the GType
       system.	Values are referred to by their	nicknames; basically, strip
       the common prefix, lower-case it, and optionally	convert	'_' to '-':

	 GTK_WINDOW_TOPLEVEL =>	'toplevel'
	 GTK_BUTTONS_OK_CANCEL => 'ok-cancel' (or 'ok_cancel')

       Flags are a special case.  You can't (sensibly) bitwise-or these
       string-constants, so you	provide	a reference to an array	of them
       instead.	 Anonymous arrays are useful here, and an empty	anonymous
       array is	a simple way to	say 'no	flags'.

	 FOO_BAR_BAZ | FOO_BAR_QUU | FOO_BAR_QUUX => [qw/baz quu qux/]
	 0 => []

       In some cases you need to see if	a bit is set in	a bitfield; methods
       returning flags therefore return	an overloaded object.  See Glib	for
       more details on which operations	are allowed on these flag objects, but
       here is a quick example:

	 in C:
	   /* event->state is a	bitfield */
	   if (event->state & GDK_CONTROL_MASK)	g_printerr ("control was down\n");

	 in Perl:
	   # $event->state is a	special	object
	   warn	"control was down\n" if	$event->state &	"control-mask";

       But this	also works:

	 warn "control was down\n" if $event->state * "control-mask";
	 warn "control was down\n" if $event->state >= "control-mask";
	 warn "control and shift were down\n"
				   if $event->state >= ["control-mask",	"shift-mask"];

   Memory Handling
       The functions for ref'ing and unref'ing objects and free'ing boxed
       structures are not even mapped to Perl, because it's all	handled
       automagically by	the bindings.  Objects will be kept alive so long as
       you have	a Perl scalar pointing to it or	the object is referenced in
       another way, e.g. from a	container.

       The only	thing you have to be careful about is the lifespan of non
       reference counted structures, which means most things derived from
       "Glib::Boxed".  If it comes from	a signal callback it might be good
       only until you return, or if it's the insides of	another	object then it
       might be	good only while	that object lives.  If in doubt	you can
       "copy".	Structs	from "copy" or "new" are yours and live	as long	as
       referred	to from	Perl.

       Use normal Perl callback/closure	tricks with callbacks.	The most
       common use you'll have for callbacks is with the	Glib "signal_connect"

	 $widget->signal_connect (event	=> \&event_handler, $user_data);
	 $button->signal_connect (clicked => sub { warn	"hi!\n"	});

       $user_data is optional, and with	Perl closures you don't	often need it
       (see "Persistent	variables with closures" in perlsub).

       The userdata is held in a scalar, initialized from what you give	in
       "signal_connect"	etc.  It's passed to the callback in usual Perl	"call
       by reference" style which means the callback can	modify its last
       argument, ie. $_[-1], to	modify the held	userdata.  This	is a little
       subtle, but you can use it for some "state" associated with the

	 $widget->signal_connect (activate => \&my_func, 1);
	 sub my_func {
	   print "activation count: $_[-1]\n";
	   $_[-1] ++;

       Because the held	userdata is a new scalar there's no change to the
       variable	(etc.) you originally passed to	"signal_connect".

       If you have a parent object in the userdata (or closure)	you have to be
       careful about circular references preventing parent and child being
       destroyed.  See "Two-Phased Garbage Collection" in perlobj about	this
       generally.  Toplevel widgets like "Gtk3::Window"	always need an
       explicit	"$widget->destroy" so their "destroy" signal is	a good place
       to break	circular references.  But for other widgets it's usually
       friendliest to avoid circularities in the first place, either by	using
       weak references in the userdata,	or possibly locating a parent
       dynamically with	"$widget->get_ancestor".

   Exception handling
       Anything	that uses GError in C will "croak" on failure, setting $@ to a
       magical exception object, which is overloaded to	print as the returned
       error message.  The ideology here is that GError	is to be used for
       runtime exceptions, and "croak" is how you do that in Perl.  You	can
       catch a croak very easily by wrapping the function in an	eval:

	 eval {
	   my $pixbuf =	Gtk3::Gdk::Pixbuf->new_from_file ($filename);
	   $image->set_from_pixbuf ($pixbuf);
	 if ($@) {
	   print "$@\n"; # prints the possibly-localized error message
	   if (Glib::Error::matches ($@, 'Gtk3::Gdk::Pixbuf::Error',
					 'unknown-format')) {
	     change_format_and_try_again ();
	   } elsif (Glib::Error::matches ($@, 'Glib::File::Error', 'noent')) {
	     change_source_dir_and_try_again ();
	   } else {
	     # don't know how to handle	this
	     die $@;

       This has	the added advantage of letting you bunch things	together as
       you would with a	try/throw/catch	block in C++ --	you get	cleaner	code.
       By using	Glib::Error exception objects, you don't have to rely on
       string matching on a possibly localized error message; you can match
       errors by explicit and predictable conditions.  See Glib::Error for
       more information.

   Output arguments, lists, hashes
       In C you	can only return	one value from a function, and it is a common
       practice	to modify pointers passed in to	simulate returning multiple
       values.	In Perl, you can return	lists; any functions which modify
       arguments are changed to	return them instead.

       Arguments and return values that	have the types GList or	GSList or
       which are C arrays of values will be converted to and from references
       to normal Perl arrays.  The same	holds for GHashTable and references to
       normal Perl hashes.

   Object class	functions
       Object class functions like "Gtk3::WidgetClass::find_style_propery" can
       be called either	with a package name or with an instance	of the
       package.	 For example:

	 Gtk3::WidgetClass::find_style_property	('Gtk3::Button', 'image-spacing')

	 my $button = Gtk3::Button->new;
	 Gtk3::WidgetClass::find_style_property	($button, 'image-spacing')

       "Glib::Object::Introspection->setup" takes a few	optional arguments
       that augment the	generated API:

       search_path => $search_path
	   A path that should be used when looking for typelibs.  If you use
	   typelibs from system	directories, or	if your	environment contains a
	   properly set	"GI_TYPELIB_PATH" variable, then this should not be

       name_corrections	=> { auto_name => new_name, ...	}
	   A hash ref that is used to rename functions and methods.  Use this
	   if you don't	like the automatically generated mapping for a
	   function or method.	For example, if	"g_file_hash" is automatically
	   represented as "Glib::IO::file_hash"	but you	want
	   "Glib::IO::File::hash" then pass

	     name_corrections => {
	       'Glib::IO::file_hash' =>	'Glib::IO::File::hash'

       class_static_methods => [ function1, ...	]
	   An array ref	of function names that you want	to be treated as
	   class-static	methods.  That is, if you want be able to call
	   "Gtk3::Window::list_toplevels" as "Gtk3::Window->list_toplevels",
	   then	pass

	     class_static_methods => [

	   The function	names refer to those after name	corrections.

       flatten_array_ref_return_for => [ function1, ...	]
	   An array ref	of function names that return an array ref that	you
	   want	to be flattened	so that	they return plain lists.  For example

	     flatten_array_ref_return_for => [

	   The function	names refer to those after name	corrections.
	   Functions occurring in "flatten_array_ref_return_for" may also
	   occur in "class_static_methods".

       handle_sentinel_boolean_for => [	function1, ... ]
	   An array ref	of function names that return multiple values, the
	   first of which is to	be interpreted as indicating whether the rest
	   of the returned values are valid.  This frequently occurs with
	   functions that have out arguments; the boolean then indicates
	   whether the out arguments have been written.	 With
	   "handle_sentinel_boolean_for", the first return value is taken to
	   be the sentinel boolean.  If	it is true, the	rest of	the original
	   return values will be returned, and otherwise an empty list will be

	     handle_sentinel_boolean_for => [

	   The function	names refer to those after name	corrections.
	   Functions occurring in "handle_sentinel_boolean_for"	may also occur
	   in "class_static_methods".

       use_generic_signal_marshaller_for => [ [package1, signal1,
       [arg_converter1]], ... ]
	   Use an introspection-based generic signal marshaller	for the	signal
	   "signal1" of	type "package1".  If given, use	the code reference
	   "arg_converter1" to convert the arguments that are passed to	the
	   signal handler.  In contrast	to Glib's normal signal	marshaller,
	   the generic signal marshaller supports, among other things, pointer
	   arrays and out arguments.

       reblessers => { package => \&reblesser, ... }
	   Tells G:O:I to invoke reblesser whenever a Perl object is created
	   for an object of type package.  Currently, this only	applies	to
	   boxed unions.  The reblesser	gets passed the	pre-created Perl
	   object and needs to return the modified Perl	object.	 For example:

	     sub Gtk3::Gdk::Event::_rebless {
	       my ($event) = @_;
	       return bless $event, lookup_real_package_for ($event);

       To invoke specific functions manually, you can use the low-level

	   $basename, $namespace, $function, @args)

       o   $basename is	the basename of	a library, like	'Gtk'.

       o   $namespace refers to	a namespace inside that	library, like
	   'Window'.  Use undef	here if	you want to call a library-global

       o   $function is	the name of the	function you want to invoke.  It can
	   also	refer to the name of a constant.

       o   @args are the arguments that	should be passed to the	function.  For
	   a method, this should include the invocant.	For a constructor,
	   this	should include the package name.

       "Glib::Object::Introspection->invoke" returns whatever the function
       being invoked returns.

       To override the behavior	of a specific function or method, create an
       appropriately named sub in the correct package and have it call
       "Glib::Object::Introspection->invoke".  Say you want to override
       "Gtk3::Window::list_toplevels", then do this:

	 sub Gtk3::Window::list_toplevels {
	   # something...
	   my $ref = Glib::Object::Introspection->invoke (
		       'Gtk', 'Window',	'list_toplevels',
	   # something...
	   return wantarray ? @$ref : $ref->[$#$ref];

       The sub's name and package must be those	after name corrections.

   Converting a	Perl variable to a GValue
       If you need to marshal into a GValue, then Glib::Object::Introspection
       cannot do this automatically because the	type information is missing.
       If you do have this information in your module, however,	you can	use
       Glib::Object::Introspection::GValueWrapper to do	the conversion.	 In
       the wrapper for a function that expects a GValue, do this:

	 my $type = ...; # somehow get the package name	that
			 # corresponds to the correct GType
	 my $wrapper =
	   Glib::Object::Introspection::GValueWrapper->new ($type, $value);
	 # now use Glib::Object::Introspection->invoke and
	 # substitute $wrapper where you'd use $value

       If you need to call a function that expects an already set-up GValue
       and modifies it,	use "get_value"	on the wrapper afterwards to obtain
       the value.  For example:

	 my $wrapper =
	   Glib::Object::Introspection::GValueWrapper->new ('Glib::Boolean', 0);
	 $box->child_get_property ($label, 'expand', $gvalue);
	 my $value = $gvalue->get_value

   Handling raw	enumerations and flags
       If you need to handle raw enumerations/flags or extendable enumerations
       for which more than the pre-defined values might	be valid, then use
       "Glib::Object::Introspection->convert_flags_to_sv" and
       "Glib::Object::Introspection->convert_sv_to_flags".  They will raise an
       exception on unknown values; catching it	then allows you	to implement
       fallback	behavior.

	 Glib::Object::Introspection->convert_enum_to_sv (package, enum_value)
	 Glib::Object::Introspection->convert_sv_to_enum (package, sv)

	 Glib::Object::Introspection->convert_flags_to_sv (package, flags_value)
	 Glib::Object::Introspection->convert_sv_to_flags (package, sv)

       perl-Glib: Glib
       gobject-introspection: <>
       libffi: <>

       Emmanuele Bassi <ebassi at linux	intel com>
       muppet <scott asofyet org>
       Torsten SchA<paragraph>nfeld <kaffeetisch at gmx	de>

       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

perl v5.24.1			  2017-05-31	Glib::Object::Introspection(3)


Want to link to this manual page? Use this URL:

home | help