view release on metacpan or  search on metacpan

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

=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 
modifying several arguments if the function returns TRUE; for such functions,
the perl wrapper just returns an empty list on failure.

  in C:  foo_get_baz_and_quux (foo, &baz, &quux);
  in perl:  ($baz, $quux) = $foo->get_baz_and_quux;

Most things that take or return a GList, GSList, or array of values will use
native perl arrays (or the argument stack) instead.

You don't need to specify string lengths, although string length
parameters should still be available for functions dealing with binary
strings. You can always use C<substr> to pass different parts of a string.

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 = Gtk2::Gdk::Pixbuf->new_from_file ($filename);
      $image->set_from_pixbuf ($pixbuf);
   };
   if ($@) {
      print "$@\n"; # prints the possibly-localized error message
      if (Glib::Error::matches ($@, 'Gtk2::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 L<Glib::Error> for more information.

=head1 MISSING METHODS

=over

=item g_object_ref	=> no replacement

=item g_object_unref	=> no replacement

=item g_boxed_free	=> no replacement

The bindings do automatic memory management. You should never need to use these.

=item gtk_timeout_add    => Glib::Timeout->add

=item gtk_timeout_remove => Glib::Source->remove

=item gtk_idle_add       => Glib::Idle->add

=item gtk_idle_remove    => Glib::Source->remove

=item gtk_input_add      => Glib::IO->add_watch

=item gtk_input_remove   => Glib::Source->remove

The gtk_* functions are deprecated in favor of the g_* ones.  Gtk2::Helper
has a wrapper for Glib::IO->add_watch which makes it behave more
like gtk_input_add.

=item gtk_accel_group_from_accel_closure => no replacement

Because of the use of Perl subroutine references in place of GClosures, there
is no way to preserve at the Perl level the one-to-one mapping between
GtkAccelGroups and GClosures.  Without that mapping, this function is useless.

=back


=head1 RENAMED METHODS

=over

=item gtk_aspect_frame_set	=> $aspect_frame->set_params

Avoid a clash with $gobject->set.

=back


=head1 DIFFERENT CALL SIGNATURES OR SEMANTICS

As a general rule function that take a pair of parameters, a list and the
number of elements in that list, will normally omit the number of elements
and just accept a variable number of arguments that will be converted into
the list and number of elements.  In many instances parameters have been
reordered so that this will work.  See below for exceptions and specific
cases that are not detailed in the generated Perl API reference.

=over

=item Gtk2::ScrollBar vs. GtkScrollbar

These classes were incorrectly written with a capital C<B> in version 1.00
and below.  They have been renamed in version 1.01 and the old way to
write them is deprecated, but supported.

=item Gtk2::ItemFactory::create_items

The n_entries parameter has been omitted and callback_data is accepted as the
first parameter. All parameters after that are considered to be entries.

=item Gtk2::List::insert_items

Position and items parameters flipped order so that an open ended parameter