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.
.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
-Public datamembers are accessed normally as members of the object struct.
-Example where 'i' is as above a public data member:
+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 private data members are defined in a structure which is only available
-inside the .c file. You must access them using the structure _priv. Example
+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
-Note that the _priv structure is defined in the \fB<basename>-private.h\fR.
+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. In case you use the \fB--no-private-header\fR option, no
+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 third type is an argument type. It is a named datamember which
+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
.fi
This makes the argument settable even before the object is constructed, so
-that people can pass it to gtk_object_new function.
+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
+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
}
.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
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".
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