.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Glib::Object::Introspection 3pm" .TH Glib::Object::Introspection 3pm "2012-05-21" "perl v5.14.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::Object::Introspection \- Dynamically create Perl language bindings .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 7 \& use Glib::Object::Introspection; \& Glib::Object::Introspection\->setup( \& basename => \*(AqGtk\*(Aq, \& version => \*(Aq3.0\*(Aq, \& package => \*(AqGtk3\*(Aq); \& # now GtkWindow, to mention just one example, is available as \& # Gtk3::Window, and you can call gtk_window_new as Gtk3::Window\->new .Ve .SH "ABSTRACT" .IX Header "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. .SH "DESCRIPTION" .IX Header "DESCRIPTION" .ie n .SS """Glib::Object::Introspection\->setup""" .el .SS "\f(CWGlib::Object::Introspection\->setup\fP" .IX Subsection "Glib::Object::Introspection->setup" To allow Glib::Object::Introspection to create bindings for a library, it must have installed a typelib file, for example \&\f(CW\*(C`$prefix/lib/girepository\-1.0/Gtk\-3.0.typelib\*(C'\fR. In your code you then simply call \f(CW\*(C`Glib::Object::Introspection\->setup\*(C'\fR to set everything up. This method takes a couple of key-value pairs as arguments. These three are mandatory: .ie n .IP "basename => $basename" 4 .el .IP "basename => \f(CW$basename\fR" 4 .IX Item "basename => $basename" The basename of the library that should be wrapped. If your typelib is called \&\f(CW\*(C`Gtk\-3.0.typelib\*(C'\fR, then the basename is 'Gtk'. .ie n .IP "version => $version" 4 .el .IP "version => \f(CW$version\fR" 4 .IX Item "version => $version" The particular version of the library that should be wrapped, in string form. For \f(CW\*(C`Gtk\-3.0.typelib\*(C'\fR, it is '3.0'. .ie n .IP "package => $package" 4 .el .IP "package => \f(CW$package\fR" 4 .IX Item "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'. .PP The rest are optional: .ie n .IP "search_path => $search_path" 4 .el .IP "search_path => \f(CW$search_path\fR" 4 .IX Item "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. .IP "name_corrections => { auto_name => new_name, ... }" 4 .IX Item "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 \f(CW\*(C`g_file_hash\*(C'\fR is automatically represented as \&\f(CW\*(C`Glib::IO::file_hash\*(C'\fR but you want \f(CW\*(C`Glib::IO::File::hash\*(C'\fR then pass .Sp .Vb 3 \& name_corrections => { \& \*(AqGlib::IO::file_hash\*(Aq => \*(AqGlib::IO::File::hash\*(Aq \& } .Ve .IP "class_static_methods => [ function1, ... ]" 4 .IX Item "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 \&\f(CW\*(C`Gtk3::Window::list_toplevels\*(C'\fR as \f(CW\*(C`Gtk3::Window\->list_toplevels\*(C'\fR, then pass .Sp .Vb 3 \& class_static_methods => [ \& \*(AqGtk3::Window::list_toplevels\*(Aq \& ] .Ve .Sp The function names refer to those after name corrections. .IP "flatten_array_ref_return_for => [ function1, ... ]" 4 .IX Item "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 .Sp .Vb 3 \& flatten_array_ref_return_for => [ \& \*(AqGtk3::Window::list_toplevels\*(Aq \& ] .Ve .Sp The function names refer to those after name corrections. Functions occuring in \f(CW\*(C`flatten_array_ref_return_for\*(C'\fR may also occur in \f(CW\*(C`class_static_methods\*(C'\fR. .IP "handle_sentinel_boolean_for => [ function1, ... ]" 4 .IX Item "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 \&\f(CW\*(C`handle_sentinel_boolean_for\*(C'\fR, 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. .Sp .Vb 3 \& handle_sentinel_boolean_for => [ \& \*(AqGtk3::TreeSelection::get_selected\*(Aq \& ] .Ve .Sp The function names refer to those after name corrections. Functions occuring in \f(CW\*(C`handle_sentinel_boolean_for\*(C'\fR may also occur in \f(CW\*(C`class_static_methods\*(C'\fR. .ie n .SS """Glib::Object::Introspection\->invoke""" .el .SS "\f(CWGlib::Object::Introspection\->invoke\fP" .IX Subsection "Glib::Object::Introspection->invoke" To invoke specific functions manually, you can use the low-level \f(CW\*(C`Glib::Object::Introspection\->invoke\*(C'\fR. .PP .Vb 2 \& Glib::Object::Introspection\->invoke( \& $basename, $namespace, $function, @args) .Ve .IP "\(bu" 4 \&\f(CW$basename\fR is the basename of a library, like 'Gtk'. .IP "\(bu" 4 \&\f(CW$namespace\fR refers to a namespace inside that library, like 'Window'. Use undef here if you want to call a library-global function. .IP "\(bu" 4 \&\f(CW$function\fR is the name of the function you want to invoke. It can also refer to the name of a constant. .IP "\(bu" 4 \&\f(CW@args\fR 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. .PP \&\f(CW\*(C`Glib::Object::Introspection\->invoke\*(C'\fR returns whatever the function being invoked returns. .SS "Overrides" .IX Subsection "Overrides" To override the behavior of a specific function or method, create an appropriately named sub in the correct package and have it call \f(CW\*(C`Glib::Object::Introspection\->invoke\*(C'\fR. Say you want to override \&\f(CW\*(C`Gtk3::Window::list_toplevels\*(C'\fR, then do this: .PP .Vb 8 \& sub Gtk3::Window::list_toplevels { \& # ...do something... \& my $ref = Glib::Object::Introspection\->invoke ( \& \*(AqGtk\*(Aq, \*(AqWindow\*(Aq, \*(Aqlist_toplevels\*(Aq, \& @_); \& # ...do something... \& return wantarray ? @$ref : $ref\->[$#$ref]; \& } .Ve .PP The sub's name and package must be those after name corrections. .SS "Converting a Perl variable to a GValue" .IX Subsection "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: .PP .Vb 8 \& ... \& 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\*(Aqd use $value \& ... .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "gobject-introspection: " 4 .IX Item "gobject-introspection: " .PD 0 .IP "libffi: " 4 .IX Item "libffi: " .PD .SH "AUTHORS" .IX Header "AUTHORS" .IP "Emmanuele Bassi " 4 .IX Item "Emmanuele Bassi " .PD 0 .IP "muppet " 4 .IX Item "muppet " .IP "Torsten Scho\*:nfeld " 4 .IX Item "Torsten Scho:nfeld " .PD .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the terms of the Lesser General Public License (\s-1LGPL\s0). For more information, see http://www.fsf.org/licenses/lgpl.txt