Some notes on Gtk-Perl documentation

The Gtk-Perl maintainers have started to document the bindings and if you build Gtk-Perl yourself docs should be produced then. Examples of what is produced are the reference manual of modules and functions, and some data structures and types (currently enumerations and flags).

Gtk-Perl package documentation

• Pod versions of the same files are in the Gtk-Perl build/ directory after you have called 'perl Makefile.PL'.
  You can turn them into cross referenced HTML files by calling:

        pod2html perl-gtk-ref.pod > perl-gtk-ref.html
        pod2html perl-gtk-ds.pod  > perl-gtk-ds.html
      

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

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_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 CVS dir.

Mailing lists

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 List in Gtk-Perl' is much better than 'Help, I'm a newbie'