]> git.draconx.ca Git - gob-dx.git/blobdiff - doc/gob.1.in
Release 0.93.4
[gob-dx.git] / doc / gob.1.in
index 6717d3e2a89cbeace89fe7367c710e33217d0f1a..5afe3bbc9b5a2313af6818de8614bac7b55f40fd 100644 (file)
@@ -188,14 +188,14 @@ For example:
 .PP
 Data members:
 .PP
-There are four types of data members.  Three of them are normal
-data numbers, and one is a virtual one, usually linked to a normal
-data member.  The three normal data members are public, protected and
-private.  Public and protected are basically just entries in the object
-structure, while private has it's own dynamically allocated private
-structure.  Protected members are always put after the public one in the
-structure and are marked protected in the header file.  There is only one
-identifier allowed per typename unlike in normal C.  Example:
+There are five types of data members.  Three of them are normal data numbers,
+one is class wide (global) in scope and one is a virtual one, usually linked to
+a normal data member or a class wide data member.  The three normal data
+members are public, protected and private.  Public and protected are basically
+just entries in the object structure, while private has it's own dynamically
+allocated private structure.  Protected members are always put after the public
+one in the structure and are marked protected in the header file.  There is
+only one identifier allowed per typename unlike in normal C.  Example:
 .nf
 
   public int i;
@@ -230,14 +230,104 @@ In case you use the \fB--no-private-header\fR option, no
 private header file is created and you can only access the _priv pointer
 below the class definition in the .gob file.
 .PP
-The fourth type is an argument type.  It is a named data member which
-is one of the features of the GTK+ object system.  You need to define a get
-and a set handler.  They are fragments of C code that will be used to 
-get the value or set the value of the argument.  Inside them you can use the
-define ARG to which you assign the data or get the data.  You can also use
-the identifier "self" as pointer to the object instance.  The type is
-defined as one of the gtk type enums, but without the GTK_TYPE_ prefix.
-For example:
+Classwide data members:
+.PP
+Sometimes you want a datamember to be shared by all objects.  You then need
+the "classwide" scope keyword.  So for example the following adds a global
+member foo:
+.nf
+
+  classwide int foo;
+
+.fi
+To access the member you do the standard voodoo of getting the class from the
+object and casting it to your class pointer.  Thus the following would work:
+.nf
+
+  SELF_CLASS(GTK_OBJECT(object)->klass)->foo = 20;
+
+.fi
+.PP
+Automatic Initialization (0.93.0 and higher only):
+.PP
+You can automatically initialize the public private and protected data members
+without having to add an init method.  The advantage here is that
+initialization is kept close to the definition of the data member and thus
+it's easier to check.  To do this, just add a '=' followed by a number or
+a token.  It is also possible to include arbitrary C code for more elaborate
+initializations by putting it all in curly braces.  Note that the curly braces
+will not be printed into the output, but since gob does not C parsing it needs
+them to figure out where the C code ends.  The code will be inserted into the
+init method, above the user defined body.  So for example the following
+will initialize an integer to -1 and a string with a newly allocated string
+of "hello".
+.nf
+
+  public int foo = -1;
+  private char *bar = {g_strdup("hello")};
+
+.fi
+.PP
+Automatic Destruction (0.93.0 and higher only):
+.PP
+Most data stored as pointers needs to have a function called when the object
+is destroyed, to either free it or give up a reference.  Gob will let you
+define a function to be called on the data the object is destroyed.  This is
+achieved by putting 'destroywith' followed by a function name after the
+variable definition.  It is only called if the data you defined this on
+is not NULL, so you cans specify functions which do not handle NULL.  It
+is very much like the GDestroyNotify function used in GTK+ and glib in many
+places.  Unlike many other places, gob will not enforce any kind of type
+safety here so be a little bit more careful.  Any function you give it will
+be called as a "void function(void *)".  It will in fact be cast into such
+a form before called.  This is to avoid spurious warnings for gtk calls to
+subclass methods.  The function needs not be of that form, it just has to
+take one argument which is the pointer to the data.  You should also not
+define this on any non-pointer data as the results may be undefined.
+Example:
+.nf
+
+  public Gtk:Widget *window = NULL
+          destroywith gtk_widget_destroy;
+  public char *foo = {g_strdup("bar")}
+          destroywith g_free;
+
+.fi
+Note that the function name you give must be a real function and not macro.
+Also note that this is always called in the "finalize" method of GtkObject.
+.PP
+Sometimes you may want to run arbitrary code on destruction.  While this can
+be perfectly well done in the destroy handler.  Depending on the style you
+may want to include all destruction/initialization code together with the
+definition of the data member.  Thus you may want to put arbitrary code which
+will then be inserted into the "finalize" method of GtkObject.  This can be
+done with the "destroy" keyword followed by arbitrary code in curly braces.  
+Inside this code a macro called VAR will be define which refers to your
+variable.  So for example destroying a GString can be either done with
+a helper routine or the following code:
+.nf
+
+  public GString *string = {g_string_new(NULL)}
+          destroy {
+                 if(VAR) g_string_free(VAR, TRUE);
+         };
+
+.fi
+The thing to remember with these is that there are many ways to do this
+and you'd better be consistent in your code in how you use the above things.
+Also defining a helper routine that will do the destruction will be a nicer
+thing to do if that's a possibility.  The "destroy" keyword with code does
+take up more space in the file and it may become more cluttered.
+.PP
+GTK+ Arguments:
+.PP
+The fourth type of a data member an argument type.  It is a named data member
+which is one of the features of the GTK+ object system.  You need to define a
+get and a set handler.  They are fragments of C code that will be used to get
+the value or set the value of the argument.  Inside them you can use the define
+ARG to which you assign the data or get the data.  You can also use the
+identifier "self" as pointer to the object instance.  The type is defined as
+one of the gtk type enums, but without the GTK_TYPE_ prefix.  For example:
 .nf
 
   public int height;
@@ -294,6 +384,79 @@ right after the GTK+ type.  Example:
 
 .fi
 .PP
+Sometimes it can become tiresome to type in the set and get handlers if
+they are trivial.  So gob since version 0.93.0 provides automatic argument
+linking to data members.  There are three different cases it handles, direct
+link (keyword 'link'), string linking (keyword 'stringlink') and object
+linking (keyword 'objectlink').  You just place the keyword after the argument
+name instead of the get/set handlers.  It will link to a data member of the
+same name that was defined earlier in the input file.  Best is to see examples:
+.nf
+
+  public int foo;
+  argument INT foo link;
+
+.fi
+is just like
+.nf
+
+  public int foo;
+  argument INT (type int) foo
+  get { ARG = self->foo; }
+  set { self->foo = ARG; };
+
+.fi
+Similiarly,
+.nf
+
+  private char * foo;
+  argument POINTER foo stringlink;
+
+.fi
+is just like
+.nf
+
+  private char * foo;
+  argument POINTER (type char *) foo
+  get {
+        ARG = self->_priv->foo;
+  } set {
+       g_free(self->_priv->foo);
+        self->_priv->foo = g_strdup(ARG);
+  }
+
+.fi
+And for the objectlink we would have:
+.nf
+
+  public Gtk:Object * foo;
+  argument POINTER foo objectlink;
+
+.fi
+is just like
+.nf
+
+  protected Gtk:Object * foo;
+  argument POINTER (type Gtk:Object *) foo
+  get {
+        ARG = self->foo;
+  } set {
+        if(self->foo)
+                gtk_object_unref(self->foo);
+        self->foo = ARG;
+        if(self->foo)
+                gtk_object_ref(self->foo);
+  }
+
+.fi
+.PP
+As you see it will handle NULLs correctly (for the string, g_free and g_strdup
+handle NULLs).  And it will also handle private, protected and public members.
+Also you should notice that when the get is used, only a pointer is always
+returned for both objectlink and strinklink.  So you should treat the returned
+value with care and never free it (and notice that it will only be around
+until you set the argument to something else or destroy the object).
+.PP
 Methods:
 .PP
 There is a whole array of possible methods.  The three normal,
@@ -312,7 +475,7 @@ body.  This will define an empty function.  You can't do this for non-void
 regular public, private or protected methods, however it is acceptable for
 non-void virtual, signal and override methods.
 .PP
-Argument lists:
+Function argument lists:
 .PP
 For all but the init and class_init methods, you use the
 following syntax for arguments.  The first argument can be just "self",
@@ -363,6 +526,22 @@ The onerror value is also used in overrides that have a return value, in
 case there isn't a parent method, PARENT_HANDLER will return it.  More about
 this later.
 .PP
+Default return:
+.PP
+Some signal and virtual methods have a return type.  But what happens if
+there is no default handler and no one connects to a signal.  GOB will
+normally have the wrappers return whatever you specify with onerror or '0'
+if you haven't specified anything.  But since 0.93.2 you can specify a default
+return value with the keyword 'defreturn'.  It's use is identical to the
+use of onerror, and you can in fact use both at the same time.  Example
+.nf
+
+  virtual int get_some_int(self) onerror -1 defreturn 10 ;
+
+.fi
+That is an empty virtual method (in C++ terms a pure virtual).  If you never
+specify any handler for it in the derived children it will just return 10.
+.PP
 Constructor methods:
 .PP
 There are two methods that handle the construction of an object, init and
@@ -575,6 +754,11 @@ methods.  You shouldn't generally use 3 underscores even in override method
 argument lists and virtual and signal method names as it might confuse the
 PARENT_HANDLER macro.  In fact avoiding all names with three underscores is
 the best policy when working with gob.
+.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,
+PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR and
+GOB_VERSION_PATCHLEVEL.
 
 .SH USING GTK-DOC STYLE INLINE DOCUMENTATION
 .PP