.SH OPTIONS
.PP
.TP
-.B -?
-.TP
-.B -h
-.TP
-.B --help
+.B -? -h --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 -w --exit-on-warn
Exit with an error code even when you encounter a warning.
.TP
.B --no-exit-on-warn
the class definition begins. This option implicitly negates
--always-private-header
.TP
-.B -n
-.TP
-.B --no-write
+.B -n --no-write
Do not write any output files, just check syntax of the input file.
.TP
.B --no-lines
Do not print out the '#line' statements into the output. Useful for debugging
-the autogenerated generated code.
+the auto-generated generated code.
.TP
.B --no-self-alias
Do not create the Self and SelfClass type aliases and the SELF, IS_SELF
.TP
.B --no-kill-underscores
Do not remove the initial underscore from method names.
+.TP
+.B --always-private-struct
+Always include the private pointer in the public header file. This is useful for
+files which are part of a library and you want to reserve the right to add some
+private data members without breaking binary compatibility.
.SH TYPENAMES
.PP
.PP
The data is zeroed out after being destroyed. This is to make debugging easier
in case your code might try to access an already destroyed object. In case
-you have overriden the destroy method, your code will be run first and
+you have overridden the destroy method, your code will be run first and
only then will the destructors be called. You should not however make any
assumptions about the order at which the destructors are called. If you have
interdependencies between destructors for different data members, you will
use (for object type My:Object):
.nf
- gtk_object_set(GTK_OBJECT(object),
- MY_OBJECT_ARG_HEIGHT(7),
- NULL);
+ 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);
+ 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.
set { self->foo = ARG; };
.fi
-Similiarly,
+Similarly,
.nf
private char * foo;
private char * foo;
argument POINTER (type char *) foo
get {
- ARG = self->_priv->foo;
+ ARG = g_strdup(self->_priv->foo);
} set {
g_free(self->_priv->foo);
self->_priv->foo = g_strdup(ARG);
get {
ARG = self->foo;
} set {
- if(self->foo)
+ if(ARG != NULL)
+ gtk_object_ref(ARG);
+ if(self->foo != NULL)
gtk_object_unref(self->foo);
self->foo = ARG;
- if(self->foo)
- gtk_object_ref(self->foo);
}
.fi
.PP
As you see it will handle NULLs correctly (for the string, g_free and g_strdup
handle NULLs). And it will also handle private, protected and public members.
-Also you should notice that when the get is used, only a pointer is always
-returned for both objectlink and strinklink. So you should treat the returned
-value with care and never free it (and notice that it will only be around
-until you set the argument to something else or destroy the object).
+For objectlink, just a pointer is returned on get, if you wish to keep it around,
+you should call gtk_object_ref on it. For stringlink, get makes a copy of
+the string which you should free after use. This is the behaviour since 1.0.2.
.PP
Methods:
.PP
...
}
+.fi
or
+.nf
signal last NONE(NONE) void foo(self);
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
+Since 1.0.6, gob creates wrapper signal macros for signal connection
+typesafety, at least on gnu compilers. These macros are named
+<type>_SIGNAL_<signal name>(func), where func is the function pointer. This
+pointer must be of the correct type, or you will get an initialization from
+wrong pointer type warning. This macro, much like the argument macros, wraps
+both the name and the function pointer parameters. For example to connect a
+signal "changed" to a function "foo", you would do:
+.nf
+
+ gtk_signal_connect (GTK_OBJECT (object),
+ MY_OBJECT_SIGNAL_CHANGED (foo),
+ NULL);
+
+.fi
+.PP
Override methods:
.PP
If you need to override some method (a signal or a virtual method
}
.fi
Thus you see that the "_foo" method still generates the method "my_object_foo"
-just as "foo" would generate. You can turn off this behaviour if you depend
-on the old (pre 0.93.5) behaviour with the --no-kill-underscores option. This
+just as "foo" would generate. You can turn off this behavior if you depend
+on the old (pre 0.93.5) behavior with the --no-kill-underscores option. This
also means that if both "_foo" and "foo" are defined, it is treated as a
conflict.
.PP
This does not apply to override methods. Override methods are special beasts
-and this is not neccessary and would make the code behave in weird ways.
+and this is not necessary and would make the code behave in weird ways.
.PP
Making new objects:
.PP
public GtkObject *
new(void) {
- GtkObject *ret;
- ret = GTK_OBJECT (GET_NEW);
- return ret;
+ GtkObject *ret = GET_NEW;
+ return GTK_OBJECT (ret);
}
.fi
.PP
+You should not a subtle peculiarity of the GTK+ object system here. If there is any
+code inside the GTK_OBJECT macro argument, it will get executed multiple times. This
+means that things such as GTK_OBJECT(GET_NEW) would actually create 4 objects, leaking
+3 of them. A good rule is to be careful with all macros.
+.PP
Self alias 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.
+these makes it easier to for example change class names around.
.PP
Self alias types:
.PP
not use any C++ features, this option will just make the generated code
compile with a C++ compiler.
+.SH OVERRIDING THE GET_TYPE METHOD
+.PP
+The get_type is not really a method, but a function which initializes your
+object. Recently objects appeared which require you to make a custom
+get_type function (BonoboXObject currently, see next section for direct
+BonoboXObject support). So in 1.0.7 it is now possible
+to override this function. To do so, just define a new public method called
+get_type, with no arguments. Example:
+.nf
+
+ public GtkType
+ get_type (void)
+ {
+ /* code goes here */
+ return some_type;
+ }
+
+.fi
+
+.SH DIRECT BonoboXObject SUPPORT
+.PP
+If you want to build a BonoboXObject class gob has direct support for these
+classes since 1.0.9. Just create a new object that derives from
+Bonobo:X:Object. Then use a "BonoboX" class flag with the interface name as an
+argument. The interface name should be as you would type it in C, that is with
+underscores as namespace separators. Then you add the methods (using exact
+same names as in the idl file) and prepend those methods with a BonoboX
+keyword. For example imagine you have an interface GNOME/Foo/SomeInterface,
+with a method fooBar that takes a single string:
+.nf
+
+ class Foo:Some:Interface from Bonobo:X:Object
+ (BonoboX GNOME_Foo_SomeInterface) {
+
+ BonoboX
+ private void
+ fooBar (PortableServer_Servant servant,
+ const CORBA_char *string,
+ CORBA_Environment *ev)
+ {
+ Self *self = SELF (bonobo_object_from_servant (servant));
+
+ /* your code here */
+ }
+
+ /* rest of class */
+ }
+
+.fi
+Note that the implementation method can be private, in fact that's probably
+a good idea to do. It won't work to make this a signal, it can however
+be a virtual. Note that the method prototype must match the one from the
+interface header file, or you will get a bad assignment warning. You should
+check the header file generated by orbit-idl and see the epv structure
+for the correct prototypes if you can't figure them out from the idl itself.
+Also note that the first argument is not "self", but the servant and you must
+use bonobo_object_from_servant function to get the actual object pointer.
+
.SH IDENTIFIER CONFLICTS
.PP
-Gob will need to define some local varibles and functions in the generated
+Gob will need to define some local variables 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
the best policy when working with gob.
.PP
Also note that starting with version 0.93.5, method names that start with a
-an underscore are eqivalent to the names without the initial underscore. This
+an underscore are equivalent to the names without the initial underscore. This
is done to avoid conflicts with the aliases. Thus you can define the method
as "_name", if "name" happens to be some standard library function. This is
the same as defining it as "name" except that the local alias will be "_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
+.nf
class Gtk:Button:Example from Gtk:Button {
/**
.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
+be documenting the wrapper that starts that virtual function or emits
that signal.
.SH DEALING WITH CIRCULAR HEADERS
in the private members, in which case they won't be in the generated public
header.
+.SH BUILDING WITH MAKE
+.PP
+If you are using normal makefiles, what you need to do is to add a generic
+rule for .gob files. So you would include the following in the Makefile
+and then just use the .c and .h files as usual (make sure the space
+before the 'gob' is a tab, not spaces):
+.nf
+
+ %.c %.h %-private.h: %.gob
+ gob $<
+
+.fi
+
+.SH BUILDING WITH AUTOCONF and AUTOMAKE
+.PP
+This is a little bit more involved. Basically the first thing to do is to
+check for GOB in your configure.in file. You can use the supplied m4 macro
+which will also check the version of gob. Basically you include this:
+.nf
+
+ GOB_CHECK(0.93.4)
+
+.fi
+This will replace @GOB@ in your makefiles with the full path of gob. Thus
+when adding the generic rule to your Makefile.am file, it should look like:
+.nf
+
+ %.c %.h %-private.h: %.gob
+ @GOB@ $<
+
+.fi
+.PP
+For Makefile.am you have to set up a couple more things. First you have to
+include the generated .c and .h files into BUILT_SOURCES variable. You
+have to include both the .gob and the .c and .h files in the SOURCES for your
+program.
+
+.SH DEBUGGING
+.PP
+GOB does several things to make debugging the code easier. First it adds
+preprocessor commands into the output c file that point to the correct places
+in your .gob input file. However sometimes there might be some bigger
+confusion and this is just not helpful. In this case you will probably want
+to have gcc point you directly at the generated files. For this use
+the --no-lines command line option. You should also note that these commands
+are not generated for the public header file at all. If there is an error which
+points you to the public header file, make sure you fix this error in the .gob
+file, otherwise your changes will not have any effect after gob recompiles the
+sources again.
+.PP
+Sometimes you might want to know which method you are in for some debugging
+output. GOB will define __GOB_FUNCTION__ macro, which is just a string constant
+with a pretty name of the method.
+
.SH BUGS
.PP
-Also the lexer does not actually parse the C code, so I'm sure that some corner
+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
try to make the lexer try to handle it properly, but no promises.
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.
+This is not the case for gtk-doc style comments which are supported.
+.PP
+The short name aliases are actually implemented as pointers to functions. Thus
+if you want to get the pointer of a function using the short name alias you
+can't use the '&'. Thus:
+.nf
+
+ void (*foo)(Self *);
+
+ /* this will NOT work */
+ foo = &short_name;
+
+ /* this will work */
+ foo = short_name;
+
+ /* Both of these will work */
+ foo = &my_class_long_name;
+ foo = my_class_long_name;
+
+.fi
.SH AUTHOR
.PP