Gtk2::api man page on aLinux

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
aLinux logo
[printable version]

api(3)		      User Contributed Perl Documentation		api(3)

NAME
       Gtk2::api - Mapping the Gtk+ C API to perl

ABSTRACT
       The Gtk2 module attempts to stick as close as is reasonable to the C
       API, to minimize the need to maintain documentation which is nearly a
       copy of the C API reference documentation.  However, the world is not
       perfect, and the mappings between C and perl are not as clean and
       predictable as you might wish.  Thus, this page described the basics of
       how to map the C API to the perl API, and lists various points in the
       API which follow neither the C API documentation nor the mapping
       principles.

DESCRIPTION
       The canonical documentation is the C API reference at
       http://developer.gnome.org/doc/API/gtk/ and
       http://developer.gnome.org/doc/API/gdk/

       There are two main sections: 'BINDING BASICS' describes the principles
       on which the bindings work; understanding these can lead you to guess
       the proper syntax to use for any given function described in the C API
       reference.  The second section lists various specific points of
       difference which don't necessarily correspond with what you expect;
       this section is in three main parts: missing methods, renamed methods,
       and different call signatures.

BINDING BASICS
       We avoid deprecated APIs.  Many functions refer to C concepts which are
       alien to the bindings.  Many things have replacements.

       Deprecated Stuff Isn't Bound

       Things that were marked as deprecated at gtk+ 2.0.0 do not appear in
       the bindings.  This means that gtk+-1.x's GtkCList, GtkTree, and
       GtkText are not available.  The notable exception is GtkList, which is
       available solely in support of GtkCombo (which was itself replaced by
       GtkComboBox in 2.4); it should not be used under any other
       circumstances.  If you really need access to these old widgets, search
       the web for "Gtk2::Deprecated".

       Some other things were deprecated during the gtk+ 2.x series, e.g.
       GtkOptionMenu was deprecated in favor of GtkComboBox in 2.4.  Things
       that were marked as deprecated during the 2.x series will not be
       removed, basically because older versions do not have the replacements,
       and removing them would break backward compatibility.

       Namespaces and Objects

       The namespaces of the C libraries are mapped to perl packages according
       to scope, although in some cases the distinction may seem rather
       arbitrary:

	g_ => Glib  (the Glib module - distributed separately)
	gtk_ => Gtk2
	gdk_ => Gtk2::Gdk
	gdk_pixbuf_ => Gtk2::Gdk::Pixbuf
	pango_ => Gtk2::Pango

       Objects 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.
       This goes for GBoxed, GObject, and even things like Glib::String and
       Glib::Int (which are needed for specifying column types in the
       Gtk2::TreeModel).  (Flags and enums are special -- see below.)

	GtkButton => Gtk2::Button
	GdkPixbuf => Gtk2::Gdk::Pixbuf
	GtkScrolledWindow => Gtk2::ScrolledWindow
	PangoFontDescription => Gtk2::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 syntax 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 = Gtk2::CheckButton->new ('_Something');
	   $b->set_active (1);
	   $b->show;

       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.

       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 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

       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.

       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 "substr" to pass different parts of a
       string.

       Anything that uses GError in C will "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 "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 Glib::Error for
       more information.

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

	 $widget->signal_connect (event => \&event_handler, $user_data);
	 $button->signal_connect (clicked => sub { warn "hi!\n" });

       Note that the $user_data is optional, and with perl closures, you don't
       often need it.

       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.

MISSING METHODS
       g_object_ref   => no replacement
       g_object_unref => no replacement
       g_boxed_free   => no replacement
	   The bindings do automatic memory management. You should never need
	   to use these.

       gtk_timeout_add	  => Glib::Timeout->add
       gtk_timeout_remove => Glib::Source->remove
       gtk_idle_add	  => Glib::Idle->add
       gtk_idle_remove	  => Glib::Source->remove
       gtk_input_add	  => Glib::IO->add_watch
       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.

       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.

RENAMED METHODS
       gtk_aspect_frame_set	=> $aspect_frame->set_params
	   Avoid a clash with $gobject->set.

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.

       Gtk2::ScrollBar vs. GtkScrollbar
	   These classes were incorrectly written with a capital "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.

       Gtk2::ItemFactory::create_items
	   The n_entries parameter has been ommited and callback_data is
	   accepted as the first parameter. All parameters after that are
	   considered to be entries.

       Gtk2::List::insert_items
	   Position and items parameters flipped order so that an open ended
	   parameter list could be used. "$list->insert_items($position,
	   $item1, $item2, ...)"  (Note that GtkList and GtkListItem are
	   deprecated and only included because GtkCombo still makes use of
	   them, they are subject to removal at any point so you should not
	   utilize them unless absolutely necessary.)

       Gtk2::Notebook::append_page
       Gtk2::Notebook::prepend_page
       Gtk2::Notebook::insert_page
	   The C API for these functions requires a GtkWidget for the
	   tab_label, since you can set any widget you like to be the tab
	   label.  However, the most common use is a plain Gtk2::Label; so
	   these three functions will stringify anything passed to tab_label
	   that's not a GtkWidget and wrap a Gtk2::Label around it for you.

	   Note that the "_menu" versions of these functions do not do this.

       Gtk2::AccelGroup::connect
       Gtk2::AccelGroup::disconnect
	   Where a GClosure is wanted by the C stuff, a perl subroutine
	   reference suffices.	However, because of this, there are a few
	   subtle differences in sematics.  a GClosure may be connected to
	   only one GtkAccelGroup; however, a perl subroutine may be connected
	   to many GtkAccelGroups (because at the binding level, a new
	   GClosure is created on each call to ->connect).  Thus,
	   $accel_group->disconnect will disconnect the first group it finds
	   to be connected to the given perl subroutine.  To disconnect all
	   groups attached to a subroutine, you can call disconnect with the
	   same subroutine reference (or name) until it stops returning true.

       Gtk2::Clipboard::set_with_data
       Gtk2::Clipboard::set_with_owner
	   In C, these functions take an array of GtkTargetEntries and the
	   number of elements in that array as the second and third
	   parameters.	In Perl, the number of target entries is implied by
	   the number of items on the stack, and the target entries are
	   supplied as a list at the end of the parameter list:

	    $clipboard->set_with_data (\&get_func, \&clear_func, $user_data,
				       @target_entries);
	    $clipboard->set_with_owner (\&get_func, \&clear_func, $owner,
					@target_entries);

SEE ALSO
       The canonical documentation is the C API reference at
       http://developer.gnome.org/doc/API/gtk/ and
       http://developer.gnome.org/doc/API/gdk/

       Gtk2 includes a full suite of automatically-generated API reference POD
       for the Perl API -- see Gtk2::index for the starting point.

       There should be a similar document for Glib --- link to it here when it
       exists.

AUTHOR
       muppet <scott at asofyet dot org>

COPYRIGHT
       Copyright (C) 2003 by the gtk2-perl team (see the file AUTHORS for the
       full list)

       This library is free software; you can redistribute it and/or modify it
       under the terms of the GNU Library General Public License as published
       by the Free Software Foundation; either version 2.1 of the License, or
       (at your option) any later version.

       This library is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
       Library General Public License for more details.

       You should have received a copy of the GNU Library General Public
       License along with this library; if not, write to the Free Software
       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
       USA.

perl v5.10.0			  2004-09-07				api(3)
[top]

List of man pages available for aLinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net