Re: Gtk::perl documentation?

["muppet" <scott asofyet org>]

Tom Jennings said:
> Oh no need to apologize; I wasn't clear, and thanks for the hints. I map C
> to perl OK (with occasional screwups :-) but I find a lot of things don't
> map, or the transformations aren't obvious to me, eg.
> gtk_button_new_with_mnemonic() maps to... what? not
> 'Gtk::Button_with_mnemonic-> new' or other variations I've tried.

[see below for the answer!]

> But that's only part of it; for example I coded my menus explicitly, then
> later stumble upon GtkItemFactory, which appears like it might be some
> higher-level (and smarter) way to assemble menus. I found
> references to *_STOCK_* items the same way; those look easy to
> implement, the reference may be adequate here, but the mere existence of
> these things is the mystery. Obviously knowing available structural models
> up front would beat reading a reference in alpha order.


the 40k-foot overviews in the API reference and tutorials are good, because
they introduce the basic concepts for the hard stuff, like TreeView and
TextBuffer and other such things.

as for documenting the perl stuff....  there are too many GTK functions to
document in perl, especially if the docs would be 95% copied.   it's wasteful
and error-prone.   i think we'd be best off providing a document which
describes the general principles behind how the bindings map C to perl, and
detail specific places where the perl API is different from the C one.


here's a brain-dump that might serve as the beginnings of that document for
new-gtk2-perl, which is modelled after gtk-perl:



in general:

namespaces are mapped according to package and scope.  some are toplevel, some
are not.

  gtk_ = namespace => Gtk2::
  gdk_ = namespace => Gtk2::Gdk::

  objects get their own namespace, in a way
  e.g., GtkButton => Gtk2::Button
        GdkPixbuf => Gtk2::Gdk::Pixbuf
        GtkScrolledWindow => Gtk2::ScrolledWindow
        PangoFontDescription => Gtk2::Pango::FontDescription

  thus, b = gtk_button_new_with_mnemonic (str); becomes
  $b = Gtk2::Button->new_with_mnemonic ($str);
  $b->show; # gtk_widget_show

if you can't guess, then it's been poorly chosen.

constructors and class static methods (ones that work on various objects, not
necessary of a single object) take a class *name* as the first parameter. 
object methods take an object reference as the first parameter.  (exactly like
the very basic perl oo stuff!)  any method within an object's ascenstry may be
called directly on that object's reference, without the C-style casting
(again, exactly like basic perl oo stuff).

constants are handled as strings, for readability, and because it can happen
automagically thanks to the GType system.  in general, strip the prefix,
lowercase 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 bitwise-or strings, so you provide a
reference to an array of them instead.  anonymous arrays are useful here, and
an empty anonymous array is a great way to say 'no flags'.

    FOO_BAR_BAZ | FOO_BAR_QUU | FOO_BAR_QUUX => [qw/baz quu quux/]
    0 => []

note that if you don't like the short form or aren't sure what it would be,
you can just stringify the full form, e.g.:

   'GTK_WINDOW_TOPLEVEL' is equivalent to 'toplevel'

the _STOCK_ stuff is a little different; you actually give the stock id
string, e.g., GTK_STOCK_OK => 'gtk-ok'.  i don't know where the docs are for
that, but it's been my first guess every time.


the next huge difference is calling conventions and other principles:

you don't do reference-handling for memory handling in perl.  the bindings
take care of it for you.  never worry with ref/unref/free again.  (warning:
that's in new-gtk2-perl and new-gtk2-perl)


in C you can only return one thing, but perl lets you return a list. 
therefore, anything in C that looks like this:

  foo_get_baz_and_quux (foo, &baz, &quux);

would look like this:

  ($baz, $quux) = $foo->get_baz_and_quux;

again, as expected.


you will never see a GType in perl; use only package names.


most things that take or return GList/GSList/arrays will use native perl
arrays instead.  we make heavy use of the perl argument stack.


you don't need to specify string lengths.


anything that uses GError in C will croak on failure, setting $@ to the
returned error message.  the idealogy 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 { $pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename); };
   if ($@) {
        # couldn't open the file, $@ has the message
   } else {
        # do something with $pixbuf
   }

this has the added advantage of letting you bunch things together as you would
with a try/throw/catch block in C++.


use normal perl callback/closure tricks with new-gtk2-perl callbacks.  in a
large number of the more esoteric cases, the callbacks aren't needed, because
they are GDestroyNotify functions; at the binding level, these are used to
take care of the perl scalar reference counts, so that everything should just
work magically and you'll never have to worry about it.



there.  just about everything you need to know.  what else?  =)


-- 
muppet <scott asofyet org>