Writing a wrapper-friendly API
There's more to being easy to wrap into other languages than merely
writing in C. Designing a C API which is wrapper-friendly requires a
bit more care. Here are some Gnome-specific guidelines.
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).
- 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 take no mandatory
arguments and just call gtk_type_new(), plus a seperate
gtk_foo_construct() function if more initialisation needs to be
done.
Callbacks, signals
- callbacks must always carry one freely setable pointer
argument. Callbacks should also have a DestroyNotify. (GTK+ 1.4 and
closures should solve this problem altogether).
- 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
