X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/714b58ab4606ed4d40cec3702cb378938f8c883f:/doc/gob.1.in..7231d76fbf4ae0b501af648e1216b88714aa7353:/doc/gob2.1.in diff --git a/doc/gob.1.in b/doc/gob2.1.in similarity index 92% rename from doc/gob.1.in rename to doc/gob2.1.in index 81aa107..adf08b0 100644 --- a/doc/gob.1.in +++ b/doc/gob2.1.in @@ -1,22 +1,29 @@ .\" .\" gob manual page -.\" (C) 1999 George Lebl +.\" (C) 1999,2000,2001 George Lebl .\" .\" 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 @@ -26,7 +33,7 @@ is in spirit similar to things like lex or yacc. 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. @@ -391,7 +398,7 @@ And for getting, you would use: .nf int height; - gtk_object_set (GTK_OBJECT (object), + gtk_object_get (GTK_OBJECT (object), MY_OBJECT_GET_ARG_HEIGHT (&height), NULL); @@ -466,11 +473,11 @@ is just like 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 @@ -481,6 +488,19 @@ 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 +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, @@ -696,55 +716,26 @@ you can use. It will return whatever the parent handler returned, or the 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 @@ -828,7 +819,8 @@ compile with a C++ compiler. .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 @@ -842,6 +834,45 @@ get_type, with no arguments. Example: .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 @@ -866,7 +897,7 @@ the same as defining it as "name" except that the local alias will be "_name" 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 @@ -1028,8 +1059,7 @@ 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. +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