README ~~~~~~ gtklean - cleaner, safer C API for GTK+ generated directly from GTK+ headers DESCRIPTION ~~~~~~~~~~~ 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 :-) INSTALL ~~~~~~~ To install make_gtklean, its manpage and gtklean.h under /usr/local: make install For more details: make help When you download and install newer versions of GTK+ run ``make_gtklean'' without arguments to regenerate the gtklean.h file in the current directory. Note: It's better to incorporate the gtklean.h file into your GTK+ projects and include it directly rather than including an installed gtklean.h, particularly when distributing your source code. REQUIREMENTS ~~~~~~~~~~~~ make_gtklean requires GTK+ and Perl (only needed to regenerate gtklean.h) gtklean.h requires GTK+ 1.2.x and a C compiler COPYING ~~~~~~~ gtklean - cleaner, safer C API for GTK+ generated directly from GTK+ headers Copyright (C) 2000, 2001 raf This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA or visit http://www.gnu.org/copyleft/gpl.html HISTORY ~~~~~~~ 20000618 - Initial version (for GTK+ 1.2.8) 20000621 - Scrapped gui.c in favour of signal macros (now zero impact on binaries!) - Added support for signal names containing dashes (there are 5 of them) - Added handling of the signal arguments missed earlier - Added installation of gui.h to /usr/local/include to Makefile - Changed the signal macro prefix from GUISIG to GTKSIG - Renamed project to GTKlean (make_gui_h -> make_gtklean, gui.h -> gtklean.h) 20010623 - Updated for GTK+ 1.2.10 (1 new signal, new include directory) BUGS ~~~~ 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. TODO ~~~~ Prompt for/locate GTK+ sources if present to scan for signal names? (i.e. grep gtk_signal_new *.c) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ URL: http://raf.org/gtklean/ Date: 20010623 Author: raf