Yes, I'm writing some documentation! + more GtkType stuff

[Marius Vollmer <mvo zagadka ping de>]

Mahlzeit,

yes, I've started to write some documentation on the Gtk+ type system
and the static definition file gtk.defs.  While doing this I want to
clean it up and extend it to the point where gtk.defs is useful out of
the box for everyone.

I'm about to commit the first few pages of the language parody that I
call English to the repo and I would be very happy if someone could
read them over and give feedback.  I'm much slower than I thought I
would be, so I think its best to commit the stuff on a regular basis
although it doesn't really `compile' yet.

Meanwhile, here are some rough thoughts I want to pursue in the
future.[1]

* Names of fundamental types

Right now, the names of fundamental types are:

    { GTK_TYPE_NONE,		"void" },
    { GTK_TYPE_CHAR,		"gchar" },
    { GTK_TYPE_UCHAR,		"guchar" },
    { GTK_TYPE_BOOL,		"gboolean" },
    { GTK_TYPE_INT,		"gint" },
    { GTK_TYPE_UINT,		"guint" },
    { GTK_TYPE_LONG,		"glong" },
    { GTK_TYPE_ULONG,		"gulong" },
    { GTK_TYPE_FLOAT,		"gfloat" },
    { GTK_TYPE_DOUBLE,		"gdouble" },
    { GTK_TYPE_STRING,		"GtkString" },
    { GTK_TYPE_ENUM,		"GtkEnum" },
    { GTK_TYPE_FLAGS,		"GtkFlags" },
    { GTK_TYPE_BOXED,		"GtkBoxed" },
    { GTK_TYPE_POINTER,		"gpointer" },
    
    { GTK_TYPE_SIGNAL,		"GtkSignal" },
    { GTK_TYPE_ARGS,		"GtkArgs" },
    { GTK_TYPE_CALLBACK,	"GtkCallback" },
    { GTK_TYPE_C_CALLBACK,	"GtkCCallback" },
    { GTK_TYPE_FOREIGN,		"GtkForeign" },

I would like to change them to something more straighforward, because
I don't think it really matters and I want to match them to the static
description files and therefore want to keep them simple.  What about

    { GTK_TYPE_NONE,		"none" },      // make it match
    { GTK_TYPE_CHAR,		"char" },
    { GTK_TYPE_UCHAR,		"uchar" },     // this is going away, I'd say
    { GTK_TYPE_BOOL,		"bool" },
    { GTK_TYPE_INT,		"int" },
    { GTK_TYPE_UINT,		"uint" },
    { GTK_TYPE_LONG,		"long" },
    { GTK_TYPE_ULONG,		"ulong" },
    { GTK_TYPE_FLOAT,		"float" },
    { GTK_TYPE_DOUBLE,		"double" },
    { GTK_TYPE_STRING,		"string" },
    { GTK_TYPE_ENUM,		"enum" },
    { GTK_TYPE_FLAGS,		"flags" },
    { GTK_TYPE_BOXED,		"boxed" },
    { GTK_TYPE_POINTER,		"%pointer%" },  // don't use this
    
    { GTK_TYPE_SIGNAL,		"signal" },     // this should go away, too
    { GTK_TYPE_ARGS,		"args" },
    { GTK_TYPE_CALLBACK,	"callback" },
    { GTK_TYPE_C_CALLBACK,	"c_callback" }, // don't use this
    { GTK_TYPE_FOREIGN,		"foreign" },    // really needed?
                                                // could use `boxed'

* `Fundamental' cleanups

GTK_TYPE_CHAR should really be a character and not a byte.  When we
move to unicode or something, GTK_TYPE_CHAR should be the right thing.
Thus, there is no such thing as an unsigned character and
GTK_TYPE_UCHAR should go away.  To compensate let's have GTK_TYPE_BYTE
and GTK_TYPE_UBYTE.  Should we go the whole way and totally follow
Java?

GTK_TYPE_SIGNAL should be replaced by GTK_TYPE_CALLBACK, but I'm not
sure what the consequences would be.  GTK_TYPE_C_CALLBACK needs to go,
too.  Even more unsure about this one.

GTK_TYPE_FOREIGN looks much like GTK_TYPE_BOXED with run-time
information about its copy/destroy functions.

* Composite types

We should have support for lists and vectors (one dimensional arrays).
The static type system has no problem to express this with names like

    "(slist GtkWidget)"

for a GSList of GtkWidgets (or derived).

For the run-time representation, I plan to introduce a new fundamental
type for each `fundamental' composite type (GSList, GList, counted
vector, zero terminated vector, maybe vector of a certain fixed
length) and then derive a new type from these for each concrete
instantiation.  Like

    GtkType gtk_type_register_slist (GtkType content);

This function would create a new type that is derived from
GTK_TYPE_SLIST and store the content type somewhere into the `klass'
of this new type.  When such a type already exists, it is returned
unchanged, of course.  I don't expect to get very many different type
registrations.  The most controversial case is probably

    GtkType gtk_type_register_vec (GtkType content, int length);

GTK_TYPE_ARGS is a composite type, too.

* Modes

We need to deal with `pass by reference'.  I'd like to add modes to
argument specifications (and also to values when they are used as
arguments in the signal system (I'think I'm a bit confusing here)).
Mode `in' is what we have now, modes `inout' and `out' are the obvious
extensions.  I want to allow outward modes only for composite types so
that the calling conventions are completely unaffected by the mode of
an argument.  The typical case of

    void foo (int *x_ret);

would have to be declared as a function taking a vector of fixed
length 1 with content type "int" and mode `out' (or `inout').

* Definitions in header files

If I understand the current arrangement correctly, then the enum/flags
part of gtk.defs is generated from all header files by a magic Perl[2]
script.  The an awk script kicks in to generate some of the type
introspection database of Gtk from gtk.defs.  The rest is generated by
the same Perl script that generated gtk.defs, but not from gtk.defs.

This is too contorted for my tastes (and the awk script doesn't really
grok the *.defs syntax).  I would prefer a straight approach: One
program extracts *all* of gtk.defs from the header files.  Then
another program (or maybe the same in another mode) reads this
gtk.defs file and generates the needed data structures for Gtk's
databases.  The program that reads gtk.defs should really understand
what it reads, that is, it should parse the Lisp into an internal form
and then work with that.

The extraction of gtk.defs from the header files should be very
straightforward with as little guessing as possible.  I'd prefer the
most direct approach: let the people explicitely write the
`define-func', `define-whatever' forms into the code.  Like

    GtkWidget gtk_button_new_with_label (char *label);

    GTK_DEF (define-func gtk_button_new_with_label
               GtkWidget
               ((string label)))

or maybe more convenient

    GTK_DEFFUNC (GtkWidget gtk_button_new_with_label (string label))

This might get a bit verbose for enumerations and flags, tho.

We need to make this infrastructure available to widget writers so
that they can easily pull off the same stunts as Gtk.

Ok, that's it for tonight.

- Marius


Silly stuff:[3]

[1] We can't let Tim make all the proposals, now can we?
[2] I briefly thought I had another MULE problem but then I figured
    that Perl really looks like this.
[3] Because I'm doing too much supposedly serious stuff at work
    right now.