07e7719441
2006-10-08 Matthias Clasen <mclasen@redhat.com> * Apply a cleanup patch by Kjartan Maraas (#341812)
178 lines
4.4 KiB
Plaintext
178 lines
4.4 KiB
Plaintext
Overview:
|
|
========
|
|
|
|
This file describes the way that autogeneration
|
|
works within the GTK+ source code.
|
|
|
|
The following files in the gdk/ subdirectory
|
|
are autogenerated:
|
|
|
|
gdkkeysyms.h
|
|
gdkcursors.h
|
|
|
|
The following files in the gtk/ subdirectory
|
|
are autogenerated:
|
|
|
|
gtk.defs
|
|
Description of GTK+ types (and some functions) in a lisp-style
|
|
format.
|
|
gtktypebuiltins.h
|
|
Header file including declarations for internal types
|
|
gtktypebuiltins_vars.c
|
|
Variables for type values for internal types.
|
|
gtktypebuiltins_ids.c
|
|
Arrays holding information about each internal type.
|
|
gtktypebuiltins_evals.c
|
|
Arrays holding mapping between enumeration values
|
|
and strings.
|
|
|
|
gtkmarshal.c
|
|
gtkmarshal.h
|
|
Autogenerated signal marshallers
|
|
|
|
GDK
|
|
===
|
|
|
|
gdkkeysyms.h and gdkcursors.h are generated from
|
|
the corresponding header files
|
|
|
|
X11/cursorfont.h
|
|
X11/keysymdef.h
|
|
|
|
by some simple sed scripts. These are not actually
|
|
run automatically because we want all the keysyms
|
|
even on systems with a limited set.
|
|
So the Gdk rule to generate both files (X-derived-headers)
|
|
only needs to be rerun for every new release of the X Window
|
|
System.
|
|
|
|
GTK+ - type definitions
|
|
=======================
|
|
|
|
The type definitions are generated from several sources:
|
|
|
|
gtk-boxed.defs - definitions for boxed types
|
|
GTK+ header files
|
|
GDK header files
|
|
|
|
The makeenums.pl script does a heuristic parse of
|
|
the header files and extracts all enumerations declarations.
|
|
It also recognizes a number of pseudo-comments in the
|
|
header files:
|
|
|
|
Two of these apply to individual enumeration values:
|
|
|
|
/*< skip >*/
|
|
|
|
This enumeration value should be skipped.
|
|
|
|
/*< nick=NICK >*/
|
|
|
|
The nickname for this value should NICK instead of the
|
|
normally guessed value. For instance:
|
|
|
|
typedef enum {
|
|
GTK_TARGET_SAME_APP = 1 << 0, /*< nick=same-app >*/
|
|
GTK_TARGET_SAME_WIDGET = 1 << 1 /*< nick=same-widget >*/
|
|
} GtkTargetFlags;
|
|
|
|
makes the nicks "same-app" and "same-widget", instead of
|
|
"app" and "widget" that would normally be used.
|
|
|
|
The other two apply to entire enumeration declarations.
|
|
|
|
/*< prefix=PREFIX >*/
|
|
|
|
Specifies the prefix to be removed from the enumeration
|
|
values to generate nicknames.
|
|
|
|
/*< flags >*/
|
|
|
|
Specifies that this enumeration is used as a bitfield.
|
|
(makenums.pl normally guesses this from the presence of values
|
|
with << operators). For instance:
|
|
|
|
typedef enum /*< flags >*/
|
|
{
|
|
GDK_IM_PREEDIT_AREA = 0x0001,
|
|
GDK_IM_PREEDIT_CALLBACKS = 0x0002,
|
|
[ ... ]
|
|
} GdkIMStyle;
|
|
|
|
makeenums.pl can be run into two modes:
|
|
|
|
1) Generate the gtktypebuiltins_eval.c file (this
|
|
contains arrays holding the mapping of
|
|
string <=> enumeration value)
|
|
|
|
2) Generate the enumeration portion of gtk.defs.
|
|
|
|
The enumeration portion is added to the boxed type
|
|
declarations in gtk-boxed.defs to create gtk.defs.
|
|
|
|
The makeetypes.awk program takes the gtk.defs file, and
|
|
from that generates various files depending on the
|
|
third parameter passed to it:
|
|
|
|
macros: gtktypebuiltins.h
|
|
variables: gtktypebuiltins_vars.c
|
|
entries: gtktypebuiltins_ids.c
|
|
|
|
GTK+ - marshallers
|
|
==================
|
|
|
|
The files gtkmarshal.c and gtkmarshal.h include declarations
|
|
and definitions for the marshallers needed inside of
|
|
GTK+. The marshallers to be generated are listed in
|
|
the file gtkmashal.list, which is processed
|
|
by genmarshal.pl.
|
|
|
|
The format of this file is a list of lines:
|
|
|
|
<retval-type>:<arg1-type>,<arg2-type>,<arg3-type>
|
|
|
|
e.g.:
|
|
|
|
BOOL:POINTER,STRING,STRING,POINTER
|
|
|
|
A marshaller is generated for each line in the file.
|
|
The possible types are:
|
|
|
|
NONE
|
|
BOOL
|
|
CHAR
|
|
INT
|
|
UINT
|
|
LONG
|
|
ULONG
|
|
FLOAT
|
|
DOUBLE
|
|
STRING
|
|
ENUM
|
|
FLAGS
|
|
BOXED
|
|
POINTER
|
|
OBJECT
|
|
FOREIGN (gpointer data, GtkDestroyNotify notify)
|
|
C_CALLBACK (GtkFunction func, gpointer func_data)
|
|
SIGNAL (GtkSignalFunc f, gpointer data)
|
|
ARGS (gint n_args, GtkArg *args)
|
|
CALLBACK (GtkCallBackMarshal marshall,
|
|
gpointer data,
|
|
GtkDestroyNotify Notify)
|
|
|
|
Some of these types map to multiple return values - these
|
|
are marked above with the return types in parentheses.
|
|
|
|
NOTES
|
|
=====
|
|
|
|
When autogenerating GTK+ files, the autogenerated
|
|
files are often rebuild resulting in the same result.
|
|
|
|
To prevent unnecessary rebuilds of the entire directory, some files
|
|
that multiple other source files depend on are not actually written
|
|
to directly. Instead, an intermediate file is written, which
|
|
is then compared to the old file, and only if it is different
|
|
is it copied into the final location.
|