Some notes on Gtk-Perl documentation

Firstly, make sure that you have the latest Gtk-Perl (or at the very least version 0.6123). Older versions have too many errors and omissions.

HTML Tutorial

Stephen Wilhelm has finished 34 chapters (18 April 2000) of his excellent online tutorial for Gtk-Perl. It follows the Gtk+ Tutorial style and has some very pretty syntax highlighting for the code examples :)

You can now download a tarball of the whole site from the tutorial homepage so that you have a Gtk-Perl tutorial/manual for use when you are off-line.

I have learnt a lot from the tutorial and examples and I think that this is (or very soon will be) the best way to start with Gtk-Perl.

Gtk-Perl package documentation

If you need a complete reference of all the Gtk-Perl modules and their methods and data structures the Gtk-Perl maintainers have automated the building of documention for the bindings. and if you build Gtk-Perl yourself, up-to-date docs will be produced then.

Pod versions of the files are in the build/ directory of each module after you have called 'perl Makefile.PL'.
You can turn them into cross referenced HTML files by calling e.g.:
```
      pod2html perl-gtk-ref.pod > perl-gtk-ref.html
      pod2html perl-gtk-ds.pod  > perl-gtk-ds.html
    
```
Online HTML examples of what is produced are
- the reference manual of modules and functions
- some data structures and types (currently enumerations and flags).
You may be able to learn something from the Gtk-Perl distribution .xs files
The file NOTES in Gtk-Perl also gives some programming guidelines and information about Gtk-Perl naming.

Other distributions and source files

Gtk documentation
Since Gtk-Perl mimics the toolkits so regularly, I use the Gtk+ documentation gtk-docs-html-1.1.1 IIRC a tar.gz from the gtk+ download site There is also a tutorial at www.gtk.org/pub/gtk/tutorial/
If you have the gtk+ sources, read the .[ch] files
All the source files are clearly named but the main confusion is likely to come from the Gtk-Perl structure which is much more obviously object oriented. For example, gtk_container_add is bound as Gtk::Container->add() and this method is inherited by all containers. So, to add a widget to a TreeItem that inherits as follows
```
         GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkItem
                                     +----GtkTreeItem
        
```
you must get a ref $ti_ref to the TreeItem and then call $ti_ref->add() rather than gtk_conatiner_add() as you would in C.

Gnome documentation
Again, if you have the gnome sources, read the .[ch] files
/usr/doc/gnome-libs-devel-1.0.8/devel-docs/ in my gnome-libs-devel rpm package or directory devel-docs/ in the source tree.

Mailing lists

A good new source of information about using the Gtk-Perl bindings and Gtk programming in general is the gtk-perl-list mailing list. You can subscribe by sending an email to gtk-perl-list-request@redhat.com with a subject of 'subscribe' (without the quotes). Then follow the instructions that will be emailed to you and confirm the request.

The gtk-perl-list grew out of gtk-list@redhat.com and there is still plenty to learn from that list too.

Please don't post long code examples or attachments and definitely no HTML :-) Also use a meaningful subject line, 'How do I add text to a Gtk::List' is much better than 'Help, I'm a newbie'

Some notes on Gtk-Perl documentation

HTML Tutorial

Gtk-Perl package documentation

Other distributions and source files

Gtk documentation

Gnome documentation

Mailing lists