make_gtklean - generate gtklean.h directly from installed GTK+ header files


    make_gtklean [gtk-include-directory]


The C interface to the GTK+ library is too long winded and hence error prone and makes maintenance harder than it needs to be. This is caused by C only having a single name space. The designers of GTK+ had to produce a long winded interface if they were to do the job properly in a single namespace language (which they did).

Fortunately, using this long winded interface is not compulsory for GTK+ client code. make_gtklean scans the installed GTK+ header files and generates a header file, gtklean.h, that provides a cleaner and less error prone C interface to the GTK+ library.

gtklean.h contains a macro for each GTK+ function prototype or macro that begins with ``gtk_'' and renames it so the ``gtk_'' is missing. This is to reduce visual clutter in GTK+ client code and to increase the effectiveness of name completion in editors like vim. The functions prototyped in gtkmain.h are not renamed.

Some of the arguments to these functions are pointers to GTK+ objects (e.g. GtkWidget). These arguments should always be passed via the appropriate run time type checking and casting macros (e.g. GTK_WIDGET). The macros generated will pass these arguments via the appropriate casting macro so we need never type or see these macros in GTK+ client code (greatly reducing visual clutter) and we can't forget to include them (less error prone).

GTK+ uses string constants as signal names (e.g. "clicked"). This means that typing errors in GTK+ client code result in run time errors rather than compile time errors.

To remedy this, gtklean.h defines a macro for each GTK+ signal. The function macros mentioned earlier include extra handling for functions that take signal arguments so GTK+ client code can supply signal arguments as normal but without the double quotes (e.g. clicked). These will be translated into uses of the signal macros so any typing errors will be caught at compile time (definitely preferable). One thing to note is that some signal names use underscore to separate words while others use dash. The identifiers that they are replaced with all use underscore (by necessity) so there's no need to remember which signal uses which separator.

Also defined in gtklean.h are some further shortcuts for the pathologically lazy. Currently, this only includes box_pack for box_pack_start.

make_gtklean can be run to generate a new gtklean.h file whenever GTK+ itself is updated unless the style of the GTK+ header files changes significantly. The GTK+ header files are extremely well written with a clear and simple style so I don't think this will happen. Of course, if I'm wrong, or the changes to the GTK+ header files needed to break this are less significant than I think, I'll update make_gtklean :-)

If make_gtklean fails to find the GTK+ header file directory, specify it as a command line argument.


Little could be done to enhance the GTK+ functions that have variable argument lists. The corresponding macros do strip off the leading gtk_ but there is no special treatment of their arguments so the GTK_WIDGET() style casts are still required for these functions.

Note that when passing pointers to GTK+ functions as arguments to other GTK+ functions, the entire function name must be specified. If the preceeding ``gtk_'' is missing, the C preprocessor will try to invoke the corresponding macro.


20010623 raf <>