Release 1.99.1

[gob-dx.git] / 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 81aa107e361bd31c5f0dca22d48b033e18649850..adf08b01903875b632d792f5219ab59d58e76ab9 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob2.1.in
@@ -1,22 +1,29 @@
 .\"
 .\" gob manual page
 .\"
 .\" 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.  
 .\"
 .\" 
 .\" 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
 .SH NAME

-GOB \- The GTK+ Object Builder
+GOB2 \- The GObject Builder

 .SH SYNOPSIS
 .PP
 .B gob
 [ option ] ...
 file
 .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
 .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
 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 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.
 .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;
 .nf
 
   int height;

-  gtk_object_set (GTK_OBJECT (object),
+  gtk_object_get (GTK_OBJECT (object),

                   MY_OBJECT_GET_ARG_HEIGHT (&height),
                   NULL);
 
                   MY_OBJECT_GET_ARG_HEIGHT (&height),
                   NULL);
 


@@ -466,11 +473,11 @@ is just like
   get {
         ARG = self->foo;
   } set {
   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;
                 gtk_object_unref(self->foo);
         self->foo = ARG;

-        if(self->foo)
-                gtk_object_ref(self->foo);

   }
 
 .fi
   }
 
 .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 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,
 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
 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
 Example:
 .nf
 
   private int

-  foo(self)
+  foo (self)

   {
          return self->len;
   }
   
   private int
   {
          return self->len;
   }
   
   private int

-  bar(self,int i)
+  bar (self,int i)

   {
   {

-         return foo(self) + i;
+         return self_foo (self) + i;

   }
 
 .fi
 .PP
   }
 
 .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
 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
 .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
 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
 
 
 .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
 .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
 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
 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.
 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
 .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