.\"
.\" gob manual page
-.\" (C) 1999 George Lebl <jirka@5z.com>
+.\" (C) 1999,2000,2001 George Lebl <jirka@5z.com>
.\"
.\" This manual page is covered by the terms of the GNU General
.\" Public License.
.\"
-.TH GOB 1 "GOB @VERSION@"
+.TH GOB2 1 "GOB2 @VERSION@"
.SH NAME
-GOB \- The GTK+ Object Builder
+GOB2 \- The GObject Builder
.SH SYNOPSIS
.PP
.B gob
[ option ] ...
file
+.SH OUT OF DATE
+.PP
+This manual is out of date. I will be updating it when I can but it
+mostly covers the GOB 1.0.x versions and not GOB2 yet. There ARE wrong
+things in this manual for now. Keep that in mind. However most things
+still apply. Just not all.
+
.SH DESCRIPTION
.PP
-GTK+ Object Builder is a simple preprocessor for easily creating
-GTK+ objects. It does not parse any C code and ignores any C errors. It
+GObject Builder is a simple preprocessor for easily creating
+GObject objects. It does not parse any C code and ignores any C errors. It
is in spirit similar to things like lex or yacc.
.SH OPTIONS
Display a simple help screen.
.TP
.B --version
-Display version information (note, --version was not added until 0.92.0)
+Display version information
.TP
.B -w --exit-on-warn
Exit with an error code even when you encounter a warning.
.nf
int height;
- gtk_object_set (GTK_OBJECT (object),
+ gtk_object_get (GTK_OBJECT (object),
MY_OBJECT_GET_ARG_HEIGHT (&height),
NULL);
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
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
+You can also automatically export get and set methods for each of the arguments
+by appending '(export)' flag before the get and set statements. For example:
+.nf
+
+ public int foo;
+ argument INT (type int) foo (export)
+ get { ARG = self->foo; }
+ set { self->foo = ARG; };
+
+.fi
+Will export public methods get_foo(self) and set_foo(self, int foo) for you
+automatically. Note that this behaviour is new in 1.0.10.
+.PP
Methods:
.PP
There is a whole array of possible methods. The three normal,
Method names:
.PP
Inside the code, aliases are set for the methods, so that you don't
-have to type the class name before each call, just the name of the method.
+have to type the class name before each call, just type \fBself_\fR instead
+of the name of the class. So to call a method called \fBblah\fR, you
+would use the name \fBself_blah\fR.
Example:
.nf
private int
- foo(self)
+ foo (self)
{
return self->len;
}
private int
- bar(self,int i)
+ bar (self,int i)
{
- return foo(self) + i;
+ return self_foo (self) + i;
}
.fi
.PP
-Underscore removal (0.93.5+):
-.PP
-Sometimes this causes conflicts with other libraries. For example a library
-might have already used the identifier foo. You can prepend an underscore to
-the name in the .gob file. This will make the local short alias have an
-initial underscore, but it will not change the name of the actual name of the
-function. For example:
-.nf
- class My:Object from Gtk:Object {
- public void
- _foo(self) {
- /* foo body */
- }
- public void
- bar(self) {
- /* short calling convention */
- _foo(self);
- /* long calling convention */
- my_object_foo(self);
- }
- }
-.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 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 necessary and would make the code behave in weird ways.
-.PP
Making new objects:
.PP
You should define a new method which should be a normal public method. Inside
.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). So in 1.0.7 it is now possible
+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
.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 variables and functions in the generated
rather then "name".
.PP
There are a couple of defines which you shouldn't be redefining in the code
-or other headers. These are SELF, IS_SELF, SELF_CLASS, ARG, VAR,
+or other headers. These are SELF, IS_SELF, SELF_CLASS, SELF_TYPE, ARG, VAR,
PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR and
GOB_VERSION_PATCHLEVEL.
.PP
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
projects / gob-dx.git / blobdiff