NAME¶
Glib::Object::Introspection - Dynamically create Perl language bindings
SYNOPSIS¶
use Glib::Object::Introspection;
Glib::Object::Introspection->setup(
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
ABSTRACT¶
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.
DESCRIPTION¶
"Glib::Object::Introspection->setup"¶
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" to set
everything up. This method takes a couple of key-value pairs as arguments.
These three are mandatory:
- 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 object
'GtkWindow', and you pick as the package 'Gtk3', then that object will be
available as 'Gtk3::Window'.
The rest are optional:
- 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
necessary.
- 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 => [
'Gtk3::Window::list_toplevels'
]
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 => [
'Gtk3::Window::list_toplevels'
]
The function names refer to those after name corrections. Functions occuring
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 returned.
handle_sentinel_boolean_for => [
'Gtk3::TreeSelection::get_selected'
]
The function names refer to those after name corrections. Functions occuring
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);
}
"Glib::Object::Introspection->invoke"¶
To invoke specific functions manually, you can use the low-level
"Glib::Object::Introspection->invoke".
Glib::Object::Introspection->invoke(
$basename, $namespace, $function, @args)
- •
- $basename is the basename of a library, like 'Gtk'.
- •
- $namespace refers to a namespace inside that library, like 'Window'. Use
undef here if you want to call a library-global function.
- •
- $function is the name of the function you want to invoke. It can also
refer to the name of a constant.
- •
- @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.
Overrides¶
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 {
# ...do something...
my $ref = Glib::Object::Introspection->invoke (
'Gtk', 'Window', 'list_toplevels',
@_);
# ...do 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 $real_value =
Glib::Object::Introspection::GValueWrapper->new ($type, $value);
# now use Glib::Object::Introspection->invoke and
# substitute $real_value where you'd use $value
...
Handling extendable enumerations¶
If you need to handle extendable enumerations for which more than the
pre-defined values might be valid, then use
"Glib::Object::Introspection->convert_enum_to_sv" and
"Glib::Object::Introspection->convert_sv_to_enum". 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)
SEE ALSO¶
- gobject-introspection:
<http://live.gnome.org/GObjectIntrospection>
- libffi: <http://sourceware.org/libffi/>
AUTHORS¶
- Emmanuele Bassi <ebassi at linux intel com>
- muppet <scott asofyet org>
- Torsten Schoenfeld <kaffeetisch at gmx de>
LICENSE¶
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