view release on metacpan or  search on metacpan

lib/Glib/Object/Introspection.pm  view on Meta::CPAN

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.

=head2 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 L<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"];

=head2 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
C<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
C<copy>.  Structs from C<copy> or C<new> are yours and live as long as
referred to from Perl.

=head2 Callbacks

Use normal Perl callback/closure tricks with callbacks.  The most common use
you'll have for callbacks is with the L<Glib> C<signal_connect> method:

  $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 L<perlsub/Persistent variables with closures>).

The userdata is held in a scalar, initialized from what you give in
C<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 C<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
L<perlobj/Two-Phased Garbage Collection> about this generally.  Toplevel
widgets like C<Gtk3::Window> always need an explicit C<< $widget->destroy >> so
their C<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 C<< $widget->get_ancestor >>.

=head2 Exception handling

Anything that uses GError in C will C<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 C<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 ($@) {