GOB \- The GTK+ Object Builder
.SH SYNOPSIS
.PP
-.B gob [-?] [-h] [--help] [--version] [-w] [--exit-on-warn]
-[--no-exit-on-warn] [--for-cpp] [--no-gnu] [--always-private-header]
-[--no-private-header] [--no-touch-headers] file
+.B gob
+[ option ] ...
+file
.SH DESCRIPTION
.PP
GTK+ Object Builder is a simple preprocessor for easily creating
.B --for-cpp
Generate C++ code.
.TP
+.B --no-extern-c
+Never add the extern "C" to the header.
+.TP
.B --no-gnu
Never generate any code with GNU C extensions. However all the GNU C
extensions are always wrapped in #ifdef __GNUC__, so code using them compiles
define the private data structure at the point in the .c source where
the class definition begins. This option implicitly negates
--always-private-header
+.TP
+.B -n
+.TP
+.B --no-write
+Do not write any output files, just check syntax of the input file.
.SH TYPENAMES
.PP
.SH INCLUDING NORMAL C CODE IN THE OUTPUT FILES
.PP
To include some code directly in the output C file begin with '%{'
-on an empty line and end the code with a '%}' on an empty line. To
-put the code in the output header file, start the code with a '%h{'.
-For example:
+on an empty line and end the code with a '%}' on an empty line. These
+sections will appear in the output files in the order they are given.
+There are several other \fIsections\fR to which you can put code. You can
+put it in the 'header' section (which can be abbreviated 'h') and it will
+go into the public header file. You can also put it in the 'privateheader'
+section (abbreviated 'ph') which will make the code go into the private
+header file. Sometimes you want some code (other includes) to appear before
+the extern "C" and the protecting define. To do this you can put them
+into the 'headertop' (or 'ht') section. You may wish to include code or
+comments in all the files, which you can do by putting them into the 'all'
+(or 'a') section. Similarly, code you wish to appear at the top of all
+files go in the 'alltop' (or 'at') section. For example:
.nf
+ %alltop{
+ /* this will be on top of all output files */
+ %}
+
+ %headertop{
+ /* this will be on top of the public header */
+ %}
+
+ %privateheader{
+ /* this will go into the private header file */
+ %}
+
%h{
/* will be included in the header */
void somefunc(int i);
%}
+ %a{
+ /* will be included in all files */
+ %}
+
%{
/* will be included in the C file */
void somefunc(int i)
For example:
.nf
- init(object) {
+ init(self) {
/* initialize the object here */
- object->a = 9;
- object->b = 9;
+ self->a = 9;
+ self->b = 9;
}
class_init(class) {
If you don't define a "first" or a "last", the default will be taken as
"last".
.PP
+You can also add additional flags. You do this just like with the argument
+flags, although this is probably very rare. These are the GTK_RUN_* flags,
+and you can add them without the GTK_RUN_ prefix into a parenthesis, just
+after the "signal" keyword. By default all public signals are GTK_RUN_ACTION.
+.PP
Override methods:
.PP
If you need to override some method (a signal or a virtual method
.fi
.PP
+Casts:
+.PP
+There are some standard casts defined for you. Instead of using the full
+macros inside the .c file, you can use SELF, IS_SELF and SELF_CLASS. Using
+these makes it easier to for example change classnames around. There is
+however no self type, so if you're declaring a pointer to your object, you
+still have to use the full type.
.SH DEALING WITH DIFFERENT GOB VERSIONS
.PP
PARENT_HANDLER macro. In fact avoiding all names with three underscores is
the best policy when working with gob.
+.SH USING GTK-DOC STYLE INLINE DOCUMENTATION
+.PP
+If you want to use gtk-doc style inline documentation for your objects, you
+can do one of two things. First, you could include the inline documentation
+comments in your %{ %} section which will then be put verbatim into the
+output source file. This is the way you should use for functions you define
+outside of the class.
+.PP
+For class methods, you should use a gtk+ style comment, however it can be
+indented any number of tabs or spaces and you can use the short method name
+without the type prefix. Gob will automatically try to extract these and
+translate to full names and put them in the output source file. An example
+would be:
+.fi
+
+ class Gtk:Button:Example from Gtk:Button {
+ /**
+ * new:
+ *
+ * Makes a new #GtkButtonExample widget
+ *
+ * Returns: a new widget
+ **/
+ public
+ GtkWidget *
+ new(void)
+ {
+ return GTK_WIDGET(GET_NEW);
+ }
+ }
+
+.fi
+If the function you are documenting is a signal or a virtual then it will
+be documentating the wrapper that starts that virtual function or emits
+that signal.
+
+.SH DEALING WITH CIRCULAR HEADERS
+.PP
+Sometimes you may need to use an object of type MyObjectA in the MyObjectB
+class and vice versa. Obviously you can't include headers for both. So you
+need to just declare the typedef in the header of A for B, and the other way
+around as well. The headers generated since v0.92.2 include a protecting
+define before it declares the typedef. This define is the
+__TYPEDEF_<upper case object name>__. So inside my-object-a.h there will be
+this:
+.nf
+
+ #ifndef __TYPEDEF_MY_OBJECT_A__
+ #define __TYPEDEF_MY_OBJECT_A__
+ typedef struct _MyObjectA MyObjectA;
+ #endif
+
+.fi
+Now instead of including my-object-a.h in the header section of
+my-object-b.gob, just copy the above code there and you're set for using
+MyObjectA as a type in the method parameters and public types.
+.PP
+Another way to get out of this problem is if you can use those types only
+in the private members, in which case they won't be in the generated public
+header.
+
.SH BUGS
.PP
Also the lexer does not actually parse the C code, so I'm sure that some corner
projects / gob-dx.git / blobdiff