view release on metacpan or  search on metacpan

lib/Gtk2/api.pod  view on Meta::CPAN

You see from this that constructors for most widgets which allow mnemonics
will use mnemonics by default in their "new" methods.  For those who don't
guess this right off, Gtk2::Button->new_with_mnemonic is also available.
Cast macros are not necessary, and your code is a lot shorter.

=head2 Flags and Enums

Constants are handled as strings, because it's much more readable than numbers,
and because it's automagical thanks to the GType system.  Constants 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"];

And treating it as an array of strings (as in older versions) is still
supported:

  warn "control was down\n" if grep /control-mask/, @{ $event->state };

The gtk stock item stuff is a little different -- the GTK_STOCK_* constants
are actually macros which evaluate to strings, so they aren't handled by the
mechanism described above; you just specify the string, e.g., 
GTK_STOCK_OK => 'gtk-ok'. The full list of stock items can be found at 
http://developer.gnome.org/doc/API/2.0/gtk/gtk-Stock-Items.html

=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.  I could write a treatise on how we're handling reference counts and
object lifetimes, but all you need to know as perl developer is that it's
handled for you, and the object will be 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 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.  In Gtk2-Perl toplevel widgets like C<Gtk2::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 >>.

A major change from gtk-perl (the bindings for Gtk+-1.x) is that callbacks
take their arguments in the order proscribed by the C documentation, and only
one value is available for user data.  gtk-perl allowed you to pass multiple
values for user_data, and always brought in the user_data immediately after
the instance reference; this proved to be rather confusing, and did not follow
the C API reference, so we decided not to do that for gtk2-perl.

=head2 Miscellaneous

In C you can only return one value from a function, and it is a common practice
to modify pointers passed in to simulate returning multiple values.  In perl,
you can return lists; any functions which modify arguments have been changed
to return them instead.  A common idiom in gtk is returning gboolean, and