Release 0.91.2

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

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 9cada9a7ecafcee4cc130cf7afda4e12839c766a..fa5dd9b084ffed44ca78e291d3aff1465d32177c 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -201,6 +201,8 @@ without the GTK_ARG_ prefix.  For example:
   argument (CONSTRUCT) INT height get { ARG = self->height; };
 
 .fi
+This makes the argument settable even before the object is constructed, so
+that people can pass it to gtk_object_new function.
 .PP
 Methods:
 .PP
@@ -209,12 +211,12 @@ There is a whole array of possible methods.  The two normal,
 normal functions with a prototype in the header file.  Private methods
 are defined as static functions with prototypes at the top of the .c
 file.  Then there are signal, virtual and override methods.  You can also
-define init and init_class methods with a special definition if you want
+define init and class_init methods with a special definition if you want
 to add code to the constructors or you can just leave them out.
 .PP
 Argument lists:
 .PP
-For all but the init and init_class methods, you use the
+For all but the init and class_init methods, you use the
 following syntax for arguments.  The first argument can be just "self",
 which gob will translate into a pointer to the object instance.  The rest
 of the arguments are very similar to normal C arguments.  If the
@@ -251,7 +253,7 @@ default is 0, casted to the type of the method.  If you need to return
 something else then you can specify an "onerror" keyword after the
 prototype and after that a number, a token (an identifier) or a bit of C
 code enclosed in braces {}.  The braces will not be printed into the
-output, they just delimit the string.  For example
+output, they just delimit the string.  For example:
 .nf
 
   public void * get_something(self, int i (check >= 0)) onerror NULL {
@@ -260,6 +262,36 @@ output, they just delimit the string.  For example
 
 .fi
 .PP
+Constructor methods:
+.PP
+There are two methods that handle the cosntruction of an object, init and
+class_init.  You define them by just using the init or class_init keyword 
+with an untyped argument in the argument list.  The argument will be
+usable in your function as a pointer to your object or class depending if
+it's init or class_init.
+For example:
+.nf
+
+  init(object) {
+          /* initialize the object here */
+          object->a = 9;
+          object->b = 9;
+  }
+
+  class_init(class) {
+          /* initialize the class, this is rarely needed */
+          class->blah = NULL;
+  }
+
+.fi
+The class_init function is very rarely needed as all standard class
+initialization is taken care of for you by gob itself.  The init function
+should on the other hand be used whenever you need to construct or initialize
+anything in the object to put it into a sane state.  Sometimes you need
+some arguments, for this you should either use a construct method and a
+new function like many GTK+ widgets, and/or a CONSTRUCT or CONSTRUCT_ONLY
+type of an argument.
+.PP
 Virtual methods:
 .PP
 Virtual methods are basically pointers in the class structure,
@@ -329,6 +361,9 @@ class, you can use the PARENT_HANDLER macro with your arguments.  Example:
   }
 
 .fi
+If the function has a return value, then PARENT_HANDLER is an expression that
+you can use.  It will return whatever the parent handler returned, or the
+"onerror" expression if there was no parent handler.
 .PP
 Calling methods:
 .PP