.SH SYNOPSIS
.PP
.B gob [-?] [-h] [--help] [--version] [-w] [--exit-on-warn]
-[--no-exit-on-warn] [--for-cpp] [--no-touch-headers] file
+[--no-exit-on-warn] [--for-cpp] [--no-gnu] [--always-private-header]
+[--no-private-header] [--no-touch-headers] file
.SH DESCRIPTION
.PP
GTK+ Object Builder is a simple preprocessor for easily creating
.B -w
.TP
.B --exit-on-warn
-Exit with an errorcode even when you encounter a warning.
+Exit with an error code even when you encounter a warning.
.TP
.B --no-exit-on-warn
Exit with an error only on errors, not on warnings, this is the default.
.B --for-cpp
Generate C++ code.
.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
+correctly even on non-GNU compilers. This option is for purists only.
+(using GNU extensions some warnings are eliminated, some ugly hacks and there
+is better argument type safety, so it's good to use them)
+.TP
.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),
This option implicitly negates --no-private-header
.TP
.B --no-private-header
-Never create a private header file. If we use any private datamembers,
+Never create a private header file. If we use any private data members,
define the private data structure at the point in the .c source where
the class definition begins. This option implicitly negates
--always-private-header
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
-case of parsing errors. The output should not be editted by hand, and
+case of parsing errors. The output should not be edited by hand, and
you should only edit the .gob file.
.SH INCLUDING NORMAL C CODE IN THE OUTPUT FILES
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
+The fourth type is an argument type. It is a named data member 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
.PP
-If you don't define a set or a get handler it will be a readonly
-or a writeonly argument. If you want to add extra argument flags, add
+If you don't define a set or a get handler it will be a read-only
+or a write-only argument. If you want to add extra argument flags, add
them into parenthesis after the argument keyword, separated by '|' and
without the GTK_ARG_ prefix. For example:
.nf
CONSTRUCT_ONLY flag which makes the argument only available during
construction of the object.
.PP
+Since 0.92.1, gob creates macros which can be used for type safe access to
+gtk arguments. The macros are called <type>_ARG_<argument name>(x) and
+<type>_GET_ARG_<argument name>(x). They define both the string and the
+value part of the argument. So for setting an argument of height, one would
+use (for object type My:Object):
+.nf
+
+ gtk_object_set(GTK_OBJECT(object),
+ MY_OBJECT_ARG_HEIGHT(7),
+ NULL);
+
+.fi
+And for getting, you would use:
+.nf
+
+ int height;
+ gtk_object_set(GTK_OBJECT(object),
+ MY_OBJECT_GET_ARG_HEIGHT(&height),
+ NULL);
+
+.fi
+Note however that the type safety only works completely on GNU C compilers.
+The code will compile on other compilers but with minimal type safety.
+.PP
+To get good type safety on POINTER types however, you should specify
+an optional C type that gob should use. For other then POINTER types
+this is redundant but possible. To do this, place '(type <c type>)'
+right after the GTK+ type. Example:
+.nf
+
+ argument POINTER (type char *) foo set { /* foo */ } get { /* bar */ };
+
+.fi
+.PP
Methods:
.PP
There is a whole array of possible methods. The three normal,
.PP
Constructor methods:
.PP
-There are two methods that handle the cosntruction of an object, init and
+There are two methods that handle the construction 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
}
.fi
+.PP
+
+.SH DEALING WITH DIFFERENT GOB VERSIONS
+.PP
+Defines:
+.PP
+In your generated C file, you can use the defines GOB_VERSION_MAJOR
+GOB_VERSION_MINOR and GOB_VERSION_PATCHLEVEL if you wish to for example
+use a feature that is only available in some newer gob version. Note however
+that you can only use these defines in the C code portions of your .gob file,
+and #ifdef's cannot span multiple functions. Check the BUGS section
+for more on using the C preprocessor and gob. Also note that these
+have only been available since the 0.92.1 version of gob.
+.PP
+Minimum version requires:
+.PP
+You can also make your .gob file require at least certain version of gob. You
+do this by putting 'requires x.y.z' (where x.y.z is the version number) outside
+of any C block, comment or class, usually you should make this the first line
+in the file or close to the top. If gob finds this and the version of gob used
+to compile the code is lower then that listed in the require, gob will generate
+an error and exit. For example to require that gob version 0.92.1 or higher
+be used to compile a file, put this at the top of that file:
+.nf
+
+ requires 0.92.1
+
+.fi
+It should be noted however that this feature was not added until 0.92.1, and
+so if the file gets compiled by a lower version, gob would generate a
+syntax error. Thus by putting in a requires line, you are implicitly
+requiring at least 0.92.1.
.SH C++ MODE
.PP
There is a C++ mode so that gob creates C++ compiler friendly files. You need
to use the --for-cpp argument to gob. This will make the generated file have
-a .cc instead of a .c extention, and several things will be adjusted to
+a .cc instead of a .c extension, and several things will be adjusted to
make it all work for a C++ compiler. One thing that will be missing is an
alias to the new method, as that clashes with C++, so instead you'll have to
use the full name of the method inside your code. Also note that gob does
not use any C++ features, this option will just make the generated code
compile with a C++ compiler.
+.SH IDENTIFIER CONFLICTS
+.PP
+Gob will need to define some local varibles and functions in the generated
+files, so you need to take some precaution not to conflict with these. The
+general rule of thumb is that all of these start with three underscores. There
+is one, "parent_class" which doesn't because it's intended for use in your
+code. For virtuals or signals, you cannot use the identifier __parent__
+which is used for the parent of the object. You should actually never access
+__parent__ either as it not guaranteed that it will stay named this way.
+Data members cannot be named __parent__ nor _priv. For methods, you cannot
+use the identifiers "init" or "class_init" unless you mean the constructor
+methods. You shouldn't generally use 3 underscores even in override method
+argument lists and virtual and signal method names as it might confuse the
+PARENT_HANDLER macro. In fact avoiding all names with three underscores is
+the best policy when working with gob.
+
.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