Release 1.0.12

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

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 7d0c285f5053538208a5c90ccc699af8e811083d..644be0bcda76821b45ba5f5f0545dbaec99f9176 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -382,18 +382,18 @@ value part of the argument.  So for setting an argument of height, one would
 use (for object type My:Object):
 .nf
 
 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;
 
 .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_get (GTK_OBJECT (object),
+                  MY_OBJECT_GET_ARG_HEIGHT (&height),
+                  NULL);

 
 .fi
 Note however that the type safety only works completely on GNU C compilers.
 
 .fi
 Note however that the type safety only works completely on GNU C compilers.


@@ -466,11 +466,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 +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 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,


@@ -654,6 +667,25 @@ flags, although this is probably very rare.  These are the GTK_RUN_* flags,
 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
 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
+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
 Override methods:
 .PP
 If you need to override some method (a signal or a virtual method


@@ -809,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.
 
 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
 .SH IDENTIFIER CONFLICTS
 .PP
 Gob will need to define some local variables and functions in the generated


@@ -995,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.
 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