Firstly, see the GTK Tutorial. This document does not and will not take its place.
New Ground Being Broken. Word is that Mitch will have some docs for us "as soon as the set of widget constructors in libgimp is really consistant" (2000-01-30).
When you have have a drawable menu created for you, GIMP makes use of a constraint function to ask you if what should be listed in the menu. This way you can filter out drawables that are the wrong size, image, type, etc. From gimpmenu.h:
typedef gint (*GimpConstraintFunc) (gint32 image_id, gint32 drawable_id, gpointer data); GtkWidget* gimp_drawable_menu_new (GimpConstraintFunc constraint, GimpMenuCallback callback, gpointer data, gint32 active_drawable);
For every image,
the constraint function with the corresponding image ID and a
drawable ID of -1. If the constraint function likes that image
and returns TRUE, it's then called and asked about each
drawable in the image, one at a time. If the function returns
TRUE again, the drawable is added to the menu.
New Ground Being Broken
Internationalisation (abbreviated I18N) is the process of allowing your program to be viewed by users in their native language. Daniel Egger and Marc Lehmann maintain the documentation for I18N of GIMP plug-ins.