Config4GNU is written in C, a programming language that provides
no object-oriented capabilities. Nevertheless, Config4GNU is
very object-oriented. This is accomplished through use of the
GObject type system, which gives object-oriented capabilities
to C.
2.1.1. Correspondence of source files to object classes
Config4GNU attempts to create one C source file and one header
file for every class implemented. The file is named after
the class. E.g. the XMLFileNode class is implemented in the
files xmlfilenode.c and
xmlfilenode.h.
2.1.2. Creating and Freeing objects
New objects are created by calling the appropriate new
functions of the class. There may be more than one way
to create an object, so there might be multiple new methods
with different names, e.g. xmlfilenode_new_from_file().
GObject uses reference-counting to determine when an object
should be freed from memory. When an object is created, it
starts with a reference count of 1. As other parts of the
program depend on the object to exist, they call
g_object_ref() to increase the reference count. When they
no longer need the object, they use g_object_unref() to
decrease the reference count. When the reference count
drops to zero, the object is cleaned up from memory.
2.1.3. Casting objects
In true object-oriented languages, you can use a pointer to
a subtype object as if it was a pointer to a supertype
object. For example you can pass a 'Cat' where an 'Animal'
was required. Since C does not know what is a subtype of
what, we use special macros to cast from one type to another.
These macros are of the form CLASS (obj), where CLASS is the
name of the class and obj is an instance of any object. It
returns the same object as the specified type. In addition,
the macro includes a check to make sure the cast is allowed.
You can also use the IS_CLASS macros, where CLASS is the name
of the class. This returns %TRUE if the object is a member
of that class, and %FALSE otherwise.
2.1.4. Writing safe code
Using pointers in C are dangerous. Just one wrong use and
your program will likely end in a segmentation fault. If this
happens, the only way to know what happened is to open up the
debugger. GLib provides the following functions to check that
pointers are being used correctly and to provide some
information when things go wrong.
Use the g_return_if_fail() and
g_return_val_if_fail() macros to check the validity of
parameters.
Use the g_assert() macro whenever you
dereference a pointer without explicitly checking that the
pointer is not %NULL.
2.1.5. GObject properties
GObject provides the capability to register properities of
classes. You can create special routines to get and set the
values of these properties. This capability can be handy for
binding languages and programs that need dynamic discovery of
object properties (this is what LibGlade does for Gtk/Gnome
applications). Try to make as many of your object properties
available as possible.
2.1.6. Signals
Not used in Config4GNU yet, but will be soon.
2.1.7. Non-objects: strings, GLists, etc.
Some commonly used data-types in Config4GNU are the standard
C null-terminated string and a linked list data type provided
by GLib. GLib provides other data types as well, so when you
encounter one be sure to consult the GLib documenation.
C strings are often created by g_strdup() or g_strdup_printf().
They should be freed using g_free(). Sometimes the created
string is passed as the result of a function. In this case
the caller is responsible for freeing the string. Other times,
a function just returns a pointer to a string that had
already existed and should not be freed by the user. Always
check the documentation when encountering for the first time
a function that returns a string. Ideally, all functions that
return a const char * should not be freed, and all functions
that return a char * should be freed.
The linked list data type is the #GList type. To use a #GList,
consult one of the many examples found throughout the
source code.