[Gnome-bindings] Ok, here we go...

[Guillaume Laurent <glaurent worldnet fr>]

Looking at the list of subscribers, it seems that everybody who's in
the game has subscribed, except for Andreas and Marius, whom I'm
taking the liberty to cc: since they wrote
gnome-libs/devel-docs/gnome-language-bindings.tex. This is a very good
previous effort of what we're trying to do (Andreas, Marius, if you're
still working on bindings please subscribe :-)

So I suggest we start trying to assemble this guidelines which we've
been talking about.

Here's a start, I've tried to break the points down into
subsections. Comments are preceded by a '***'. If you follow-up,
please change the subject appropriately :-).


GtkObjects definition :

- state which fields are private, public.

- public data members are best avoided, provide accessors (*real*
  ones, not macros.

- avoid macros in general (except those for the GTK+ type system of
  course)

- use const on char* whenever appropriate.

- for functions returning a pointer, state who's owning it (e.g. if
  it's up to the user to free it).

- in function names, try to avoid keywords, e.g. gtk_foo_map() which
  could be turned into GtkFoo::map(), but 'map' is a Perl keyword and
  C++ algorithm (of course it's pretty hard to do, you can't know
  every keyword of every language, just apply general common sense).


*** I'm not sure about the validity of the next one : it is drawn from a
section from gnome-language-bindings.tex, which says that wrapping the
subclassing of a GtkObject is hard/impossible, but we have done it in
Gtk--, and I suspect some (most ?) of you guys have done it as
well. You tell me :

- do not force the user to subclass an object to use it



GtkObjects functions :

- passed pointers should be deep-copied (useful for GCed languages,
  and not only those actually, we've had this pb in C++ as well)

- when providing C-array based APIs like GtkItemFactory or
  GnomeUIInfo, also export the low-level functions which operate on
  one element of these array (like gtk_item_factory_create_item()).

- the gtk_foo_new() (or gnome_foo_new()) call should just call
  gtk_type_new(). If more initialisation needs to be done, the ptr
  should be passed to a gtk_foo_configure() call.

*** This last one is an old Gtk-- specific issue - may be some of you need
it as well ? The reason behind it is that Gtk-- provides its own
GtkType, so we never use gtk_foo_new() directly.


Callbacks, signals :

*** Fortunately, closures are coming in GTK+ 1.4, which should solve
    the issue altogether, but before that, this one, directly from
    gnome-language-bindings.tex, is still valid :

- callbacks must always carry one freely setable pointer
  argument. Callbacks should also have a DestroyNotify.

- signals : state if the user can directly call them or can only
  connect them.

Other types :

- use opaque types (with a constructor and most of all a destructor)

- have a consistent memory management policy



Well, that's all I can think about. Off to you guys. :-)

-- 
					Guillaume.
					http://www.telegraph-road.org