X-Git-Url: http://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/b17287deb56775a49030d738d8c8c0e9cd15f9fe..3b10bbd3a88d6e16146414d91d06bb2f36347bfc:/doc/gob.1.in diff --git a/doc/gob.1.in b/doc/gob.1.in index 6717d3e..df1472b 100644 --- a/doc/gob.1.in +++ b/doc/gob.1.in @@ -230,14 +230,86 @@ 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: +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 +366,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 +457,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", @@ -575,6 +720,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