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.

There is documentation and software to download at the Gtk-Perl homepage

HTML Tutorial

Stephen Wilhelm <swilhelm at theriver.com> has pretty well finished (10 June 2001) 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 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 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 and 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 distribution 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_container_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.2.4/devel-docs/ in my gnome-libs-devel rpm package or directory devel-docs/ in the source tree.

Mailing lists

A good 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'

Glade-Perl

Of course, the Glade-Perl homepage has the latest documentation and useful links that I know about.