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:
+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;
.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,
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",
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
projects / gob-dx.git / blobdiff