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
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.
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);
$b->show;
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 shorter.
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"];
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.
$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 connection.
$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".
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.
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.
Gtk3::WidgetClass::find_style_property ('Gtk3::Button', 'image-spacing')
my $button = Gtk3::Button->new;
Gtk3::WidgetClass::find_style_property ($button, 'image-spacing')
sub RENDER {
my ($cell, $cr, $widget, $background_area, $cell_area, $flags) = @_;
# do something
}
name_corrections => {
'Glib::IO::file_hash' => 'Glib::IO::File::hash'
}
class_static_methods => [
'Gtk3::Window::list_toplevels'
]
The function names refer to those after name corrections.
flatten_array_ref_return_for => [
'Gtk3::Window::list_toplevels'
]
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 => [
'Gtk3::TreeSelection::get_selected'
]
The function names refer to those after name corrections. Functions occurring in "handle_sentinel_boolean_for" may also occur in "class_static_methods".
sub Gtk3::Gdk::Event::_rebless {
my ($event) = @_;
return bless $event, lookup_real_package_for ($event);
}
Glib::Object::Introspection->invoke(
$basename, $namespace, $function, @args)
"Glib::Object::Introspection->invoke" returns whatever the function being invoked returns.
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.
...
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
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)