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, it 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 is set up correctly, 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