This tutorial is for people new to using the gtk2-perl bindings, but not necessarily those new to Perl itself. We will assume you already know such things as how Perl's object oriented system works, how Perl does subroutines, hashes as argument lists, etc. and such things are described better elsewhere.

There are some things to keep in mind, especially if you are familiar with using GTK+ in C. The Gtk2::api POD page that is distributed with gtk2-perl outlines what you will need to know, but some of it will be repeated here for clarity.

The biggest thing to keep in mind is that gtk2-perl fully utilizes the ideas of packages in Perl. The namespaces in C have been mapped to package names in Perl and exploit Perl's OO syntax for many things. For example:

This list is nowhere near exhaustive, however common sense dictates in most areas. A good idea of the full breakdown of namespace-to-package conversion can be seen by looking at the POD documentation index on the gtk2-perl website.

This namespace mapping is also used for the various widgets and elements in GTK+. For example:

These mappings are also pretty common sense most of the time. See the aformentioned POD index for a full list.

gtk2-perl has an automatic POD generation system for documentation as well. perldoc Gtk2::Button, for example, will give you a nice manpage-like page:

      
      Gtk2::Button(3)       User Contributed Perl Documentation      Gtk2::Button(3)

NAME
       Gtk2::Button

HIERARCHY
         Glib::Object
         +----Gtk2::Object
               +----Gtk2::Widget
                     +----Gtk2::Container
                           +----Gtk2::Bin
                                 +----Gtk2::Button

INTERFACES
         Gtk2::Atk::ImplementorIface

MNEMONICS
       Mnemonics are "memory aids"; in GTK+, a mnemonic is an underlined char-
       acter which corresponds to a keyboard accelerator.  For a button, that
       means pressing Alt and that key activates the button.

       For convenience, Gtk2-Perl uses mnemonics by default on widgets that
       support them.  If characters in label string are preceded by an under-
       score, they are underlined.  If you need a literal underscore character
       in a label, use '__' (two underscores).  If you don't want to use
       mnemonics at all, use the non-mnemonic version explicitly (e.g.
       "Gtk2::Button::new_with_label").

METHODS
       widget = Gtk2::Button->new


       widget = Gtk2::Button->new ($mnemonic)


           * $mnemonic (string) used to label the widget, see "MNEMONICS"

[...]

    

Here you can see the widget hierarchy as well as a list of methods. Each pod page also includes available signals, properties, and a list of references to other pages.

Due to the Perl object system, casting is unnecessary, thus making your programs shorter and easier to understand. In addition, the constructors for most widgets that support mnemonics will take the mnemonic as an argument, avoiding the use of the 'new_with_mnemonic' call. The function is still bound in the bindings, however, for those who wish to stay strict to the C API.

Constants such as GTK_WINDOW_TOPLEVEL are handled as strings in Perl. In the same manner as the functions and namespaces, constant names are transformed into their Perl counterparts by a simple method: strip off the namespace prefix, lowercase the constant, and replace _ with -. For example:

Note that the bindings will still accept underscores. The bindings will also accept the full C constant name as a string, for clarity.

For flags that need to be OR'd together, use an array of strings instead, such as qw/foo bar baz/. For times when you need to check if a field is set, the & operator works like you would expect it to in C due to some Perl overloading magic. [more to come]