2.5 Using Objects

So far, you have seen a quite a bit of preparatory work with objects. This work is admittedly complex, and you are probably hoping that using the objects is easier. Thankfully, it is.

To create an object, use g_object_new( type , ..., NULL) , where type is the object's class type identifier. For example, to create a Media object with the default property values, use

 Media *media; media = g_object_new(TYPE_MEDIA, NULL);

If you want to set some of the properties when you create the object, try something like the following instead:

 /* create an object, setting some properties */ media = g_object_new(TYPE_MEDIA,                      "inventory-id", 42,                      "orig-package", FALSE,                      NULL);

Note	The property list always ends with NULL .

If you decide to follow tradition and write a generator function to create an object for you, conventions dictate that the generator name should be type_new() : for example, media_new() . You can always define a macro for this, but be careful with the variable arguments; not all C preprocessors support variable arguments.

If you did a tidy job of programming your classes ” in particular, if every attribute in your instance structure corresponds to a property, with the appropriate code in your initialization functions ” you don't need a generator function. If you stick to g_object_new() , you can specify properties in any order that you wish, easily add and delete properties, and in general, will not need to remember an additional set of function names . Furthermore, if you avoid generator functions, you will have a much easier time creating bindings for other programming languages.

2.5.1 Using Properties

Now that you know how to create an object and initialize its properties, you probably want to know how to set and retrieve those properties. The two functions for this are g_object_set() and g_object_get() ; their parameters are very similar to those of g_object_new() , as you can see in this example:

 guint nr; gboolean is_unpacked; << ... >> /* set new values */ g_print("Setting inventory-id = 37, orig-package = TRUE\n"); g_object_set(media,              "orig-package", TRUE,              "inventory-id", 37,              NULL); /* double-check those new values */ g_print("Verifying.. "); g_object_get(media,              "orig-package", &is_unpacked,              "inventory-id", &nr,              NULL); g_print("inventory-id = %d, orig-package = %s\n",         nr, is_unpacked ? "TRUE" : "FALSE");

To retrieve parameters with g_object_get() , you need to specify the address of the target memory location; g_object_get() fills the memory with the new values. Examples in the preceding code are &is_unpacked and &nr .

Note

Be careful not to mix up your types when accessing properties. That is, don't code something like g_object_get(media, "my-double", &my_int) . You may also need to cast certain constants when using them in conjunction with g_object_set() . This is one area where access functions may be a somewhat preferable option.

Here are a few more functions that work with properties:

g_object_set_property( object , name , value )

Sets a single property name in object to value .
g_object_get_property( object , name , addr )

Stores the property name from object in the memory at addr .
g_object_set_valist( object , name , varargs )

Like g_object_set_property() , but operates with variable arguments.
g_object_get_valist ( object , name , varargs )

Same as the preceding function, but retrieves the arguments instead of storing them.

2.5.2 Strong and Weak Object References

GObject uses a reference count to keep track of its objects. When you call g_object_new() , you're actually getting a reference to the object, and GObject makes a note with the reference count. If you want another reference to the same object, use g_object_ref( object ) to return another reference.

To remove a reference, call g_object_unref( object ) . All references to a single object are equal; there is no special treatment for an original reference, and as mentioned before, GObject removes an object when the reference count goes to zero.

Such references are sometimes known as strong references, because they determine when GObject destroys an object. However, there are also weak references that can be present when GObject performs its garbage collection. GObject manages these references to a certain extent; it has a list of the object pointers in memory. To create a weak reference, use

 g_object_add_weak_pointer(  object  ,  weak_ptr_addr  )

Here, object is a casted existing reference to an object, and weak_ptr_addr is the address of the new weak pointer. If GObject removes the object behind the weak reference, it sets the weak reference to NULL . Use g_object_remove_weak_pointer() with the same arguments to remove a weak pointer.

Note	You still must assign the weak pointer by hand.

Here are some examples of how to use references that build on the examples in the previous section:

 Media *media2, *media_weak;   << ... >> media_weak = NULL; /* set media2 to a strong reference from media */ media2 = g_object_ref(media); /* set media_weak to a weak reference to media2 */ media_weak = media2; g_object_add_weak_pointer(G_OBJECT(media2), (gpointer) &media_weak); /* remove one strong reference */ g_object_unref(media2); /* see if media_weak is NULL, meaning that object is gone */ if (media_weak == NULL) {    g_print("media_weak is NULL; object is gone\n"); } else {    g_print("media_weak is not NULL; object is still in memory\n"); } /* remove another reference */ g_object_unref(media); /* check the weak pointer again */ if (media_weak == NULL) {    g_print("media_weak is NULL; object is gone\n"); }

Don't confuse g_object_*_weak_pointer() with g_object_weak_*ref() . The latter function enables you to call a notification function when the GObject is destroyed , but will not be covered in this book. The weak pointer functions here just set the object pointer to NULL.