GOB \- The GTK+ Object Builder
.SH SYNOPSIS
.PP
-.B gob [-?] [-h] [-w] [--exit-on-warn] [--no-exit-on-warn] [--for-cpp]
-[--no-touch-headers] file
+.B gob [-?] [-h] [--help] [--version] [-w] [--exit-on-warn]
+[--no-exit-on-warn] [--for-cpp] [--no-touch-headers] file
.SH DESCRIPTION
.PP
GTK+ Object Builder is a simple preprocessor for easily creating
.B -?
.TP
.B -h
+.TP
+.B --help
Display a simple help screen.
.TP
+.B --version
+Display version information (note, --version was not added until 0.92.0)
+.TP
.B -w
.TP
.B --exit-on-warn
.B --no-touch-headers
Don't touch the generated header file unless it really changed, this avoids
spurious rebuilds, but can confuse some make systems (automake in particular),
-so it is not enabled by default.
-
+so it is not enabled by default. Private header is still touched even if
+unchanged however.
+.TP
+.B --always-private-header
+Always create a \fB<basename>-private.h\fR file, even if it would be empty.
+Otherwise, it is only created when there are private data members in the class.
+This option implicitly negates --no-private-header
+.TP
+.B --no-private-header
+Never create a private header file. If we use any private datamembers,
+define the private data structure at the point in the .c source where
+the class definition begins. This option implicitly negates
+--always-private-header
.SH TYPENAMES
.PP
.PP
The filenames are created from the typename. The words are
separated by '-' and all in lower case. For example for an object named
-"Gtk:New:Button", the files are gtk-new-button.c and gtk-new-button.h.
-The header file is created to be human readable and to be used as a
+"Gtk:New:Button", the files are \fBgtk-new-button.c\fR and
+\fBgtk-new-button.h\fR.
+If you are using C++ mode, the output .c file will in fact be a .cc file.
+If you have any private data members, a private header file will also
+be created, called \fB<basename>-private.h\fR (for the example above it
+would be gtk-new-button-private.h).
+The public header file is created to be human readable and to be used as a
reference to the object. The .c source file is not created as a human
readable source and is littered with #line statements, which make the
compiler attempt to point you to the right line in your .gob file in
.fi
+.SH INCLUDE FILES
+.PP
+Gob will automatically include the class header file at the top of the .c
+source file. If you wish to include it somewhere else, put the include
+into some %{ %} section above the class definition, and gob will not include
+it automatically. This way you can avoid circular includes and control
+where in the file do you want to include the header.
+.PP
+If you made any data members private, gob will also create a source file
+that will be called \fB<basename>-private.h\fR. Same rule as above applies
+for this just as it does for the regular header file. If you do explicitly
+include the regular header file, you should always include this private
+header file below it. That is, if you use any private data members. If you
+don't, the private header file automatically includes the public header file,
+and thus the public header file will be indirectly included at the very top
+of the file.
+
.SH MAKING A NEW CLASS
.PP
The class header:
.PP
Data members:
.PP
-There are three types of data members. Two of them are normal
-data numbers, and one is a virtual one, usually linked to a normal public
-data member. The two normal data members are public or private. They are
-basically just copied into the object directly. There is only one
+There are four types of data members. Three of them are normal
+data numbers, and one is a virtual one, usually linked to a normal
+data member. The three normal data members are public, protected and
+private. Public and protected are basically just entries in the object
+structure, while private has it's own dynamically allocated private
+structure. Protected members are always put after the public one in the
+structure and are marked protected in the header file. There is only one
identifier allowed per typename unlike in normal C. Example:
.nf
public int i;
private GtkWidget *h;
+ protected long k;
.fi
.PP
-The private members are not currently protected from outside use,
-they are just marked by a comment in the header file, this will most likely
-be somehow solved in some future version.
+Public and protected data members are accessed normally as members of
+the object struct. Example where 'i' is as above a public data member:
+.nf
+
+ object->i = 1;
+
+.fi
.PP
-The third type is an argument type. It is a named datamember which
+The private data members are defined in a structure which is only available
+inside the .c file, or by including a private header file. You must access
+them using the structure _priv. Example
+where 'h' is the private data member (as in the above example):
+.nf
+
+ object->_priv->h = NULL;
+
+.fi
+The _priv structure is defined in the \fB<basename>-private.h\fR.
+This file is automatically included if you don't include it yourself. You
+should always explicitly include it if you explicitly also include the main
+header file.
+.PP
+In case you use the \fB--no-private-header\fR option, no
+private header file is created and you can only access the _priv pointer
+below the class definition in the .gob file.
+.PP
+The fourth type is an argument type. It is a named datamember which
is one of the features of the GTK+ object system. You need to define a get
and a set handler. They are fragments of C code that will be used to
get the value or set the value of the argument. Inside them you can use the
argument (CONSTRUCT) INT height get { ARG = self->height; };
.fi
+This makes the argument settable even before the object is constructed, so
+that people can pass it to gtk_object_new function. Useful is also
+CONSTRUCT_ONLY flag which makes the argument only available during
+construction of the object.
.PP
Methods:
.PP
-There is a whole array of possible methods. The two normal,
-"familiar" method types are private and public. Public are defined as
-normal functions with a prototype in the header file. Private methods
+There is a whole array of possible methods. The three normal,
+"familiar" method types are private, protected and public. Public are
+defined as normal functions with a prototype in the header file.
+Protected methods are defined as normal methods (which you can call from other
+files), but their prototype is placed in the private header file. Private
+methods
are defined as static functions with prototypes at the top of the .c
-file. Then there are signal, virtual and override methods. You can also
-define init and init_class methods with a special definition if you want
+file. Then there are signal, virtual and override methods. More on those
+later. You can also
+define init and class_init methods with a special definition if you want
to add code to the constructors or you can just leave them out.
+You can also not define a body for a method, by just using ';' instead of a
+body. This will define an empty function. You can't do this for non-void
+regular public, private or protected methods, however it is acceptable for
+non-void virtual, signal and override methods.
.PP
Argument lists:
.PP
-For all but the init and init_class methods, you use the
+For all but the init and class_init methods, you use the
following syntax for arguments. The first argument can be just "self",
which gob will translate into a pointer to the object instance. The rest
of the arguments are very similar to normal C arguments. If the
something else then you can specify an "onerror" keyword after the
prototype and after that a number, a token (an identifier) or a bit of C
code enclosed in braces {}. The braces will not be printed into the
-output, they just delimit the string. For example
+output, they just delimit the string. For example:
.nf
public void * get_something(self, int i (check >= 0)) onerror NULL {
}
.fi
+The onerror value is also used in overrides that have a return value, in
+case there isn't a parent method, PARENT_HANDLER will return it. More about
+this later.
+.PP
+Constructor methods:
+.PP
+There are two methods that handle the cosntruction of an object, init and
+class_init. You define them by just using the init or class_init keyword
+with an untyped argument in the argument list. The argument will be
+usable in your function as a pointer to your object or class depending if
+it's init or class_init.
+For example:
+.nf
+
+ init(object) {
+ /* initialize the object here */
+ object->a = 9;
+ object->b = 9;
+ }
+
+ class_init(class) {
+ /* initialize the class, this is rarely needed */
+ class->blah = NULL;
+ }
+
+.fi
+The class_init function is very rarely needed as all standard class
+initialization is taken care of for you by gob itself. The init function
+should on the other hand be used whenever you need to construct or initialize
+anything in the object to put it into a sane state. Sometimes you need
+some arguments, for this you should either use a construct method and a
+new function like many GTK+ widgets, and/or a CONSTRUCT or CONSTRUCT_ONLY
+type of an argument.
.PP
Virtual methods:
.PP
which makes calling the methods he same as public methods. This type of
method is just a little bit "slower" then normal functions, but not as
slow as signals. You define them by using "virtual" keyword before the
-prototype. If you put the keyword "private" right after the "virtual"
+prototype. If you put the keyword "private" right after the "virtual"
keyword, the wrapper will not be a public method, but a private one.
+You can do the same with "protected" to make a protected wrapper.
.PP
Signals:
.PP
.fi
.PP
If you don't want the wrapper that emits the signal to be public, you can
-include the keyword "private" after the "signal" keyword. This will make
-the wrapper a normal private method.
+include the keyword "private" after the "signal" keyword. This will make
+the wrapper a normal private method. You can also make a protected wrapper
+by using "protected" instead of "private".
.PP
If you don't define a "first" or a "last", the default will be taken as
"last".
/* some code here */
PARENT_HANDLER(self, wid);
}
+
.fi
+If the function has a return value, then PARENT_HANDLER is an expression that
+you can use. It will return whatever the parent handler returned, or the
+"onerror" expression if there was no parent handler.
.PP
Calling methods:
.PP
will fetch a new object, so a fairly standard new method would look like:
.nf
- public GtkWidget *
+ public GtkObject *
new(void) {
GtkObject *ret;
ret = GTK_OBJECT (GET_NEW);
.SH BUGS
.PP
-The generated header file is included as the first file in the .c file, no
-matter what. This means that you will have to put things that need to be
-included before that, into an %h{ } section.
-.PP
Also the lexer does not actually parse the C code, so I'm sure that some corner
cases or maybe even some not so corner cases of C syntax might confuse gob
completely. If you find any, send me the source that makes it go gaga and I'll
probably never will. In the future, I might add #if 0 as a comment but
that's about as far as I can really take it and even that is problematic.
Basically, if you use gob, just don't use the C preprocessor too extensively.
+.PP
+Comments will not get through to the generated files unless inside C code.
+This makes using something like gtk-doc harder. However I'm planning to
+fix this somehow.
.SH AUTHOR
.PP
projects / gob-dx.git / blobdiff