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

[Tim Janik <timj gtk org>]

On 25 Aug 1998, Marius Vollmer wrote:

> 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.

well, they actually do matter. the reason i changed the typenames
to correspond to actuall typedefs (the ones for GtkEnum, GtkFlags and
GtkBoxed are still missing but need to be added somewhen) is that all
type names need to correspond to actually existing typedefs in C, C++
and probably even other languages. this is required by source generators,
might that be GUI buildres, glue code generators or what else.

further, the GtkArg system relies on type names to adhere to specifc
namespace conventions, which must not interfere with existing or
temptative argument names, so having a type name like "signal" is not
possible.

>  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?

nope, GTK_TYPE_CHAR and friends do not correspond to a "character" type
that's used to store possible chracters for different font systems like
e.g. unicode representation, but it corresponds to the C type `signed char'.
a certain signal can for instance have a guchar parameter that is used for
certain flags, or with a defined value range from 1..4 to indicate
certain behaviour (action signals).

> 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.

i'm not sure how you want to achive this, GUI buiders for instance
might wnt to distinguish callback arguments from signal arguments,
one of the main differences is that a callback type has a
defined signature, but signal handlers do not.

> 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.

hm, could you give concrete examples for possible uses of the above?

> * 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').

again, i'm not sure on how you intend to fit this into the actual
type system. at least for the GtkArg functions, the in/out behaviour
it pretty much defined.

> * 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 had that for enums and flags already, some time ago, and it didn't 
find the widest acceptance for most people, that's why owen jumped
in and created the above mentioned perl script.
a bunch of the gtk functions should really be easy to convert into an
appriopriate .defs file format, using a smart prototype parser.
the results could then be adapted for some functions that need special
casing.
also, not all widget writers are aware of the usage and means of the
.defs file formats, requiring them to put GTK_DEFFUNC() macros into
the header would but a burden on them that is, imho, unjustified.

> 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.
> 
> 

---
ciaoTJ