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>


_______________________________________________
gtk-perl-list mailing list
gtk-perl-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-perl-list