Release 1.0.12

[gob-dx.git] / doc / gob.1.in

diff --git a/doc/gob.1.in b/doc/gob.1.in
index d5d817bccfa295ea146339d1b09f5462f308d244..644be0bcda76821b45ba5f5f0545dbaec99f9176 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -391,7 +391,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 +466,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 +481,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,
@@ -669,6 +682,10 @@ signal "changed" to a function "foo", you would do:
 
 .fi
 .PP
+Note that if you are compiling with GTK+2, this will not work.  You must 
+only use this with gtk_signal_connect_full.  Also the above macros don't
+exist in gob2, where typesafe signals are handled another way.
+.PP
 Override methods:
 .PP
 If you need to override some method (a signal or a virtual method
@@ -824,6 +841,64 @@ 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 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 variables and functions in the generated
@@ -1010,8 +1085,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