mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 11:26:16 +01:00
748 lines
35 KiB
XML
748 lines
35 KiB
XML
<?xml version='1.0' encoding="ISO-8859-1"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
|
]>
|
|
<chapter id="chapter-gobject">
|
|
<title>The GObject base class</title>
|
|
|
|
<para>
|
|
The two previous chapters discussed the details of GLib's Dynamic Type System
|
|
and its signal control system. The GObject library also contains an implementation
|
|
for a base fundamental type named <type><link linkend="GObject">GObject</link></type>.
|
|
</para>
|
|
|
|
<para>
|
|
<type><link linkend="GObject">GObject</link></type> is a fundamental classed instantiable type. It implements:
|
|
<itemizedlist>
|
|
<listitem><para>Memory management with reference counting</para></listitem>
|
|
<listitem><para>Construction/Destruction of instances</para></listitem>
|
|
<listitem><para>Generic per-object properties with set/get function pairs</para></listitem>
|
|
<listitem><para>Easy use of signals</para></listitem>
|
|
</itemizedlist>
|
|
All the GNOME libraries which use the GLib type system (like GTK+ and GStreamer)
|
|
inherit from <type><link linkend="GObject">GObject</link></type> which is why it is important to understand
|
|
the details of how it works.
|
|
</para>
|
|
|
|
<sect1 id="gobject-instantiation">
|
|
<title>Object instantiation</title>
|
|
|
|
<para>
|
|
The <function><link linkend="g-object-new">g_object_new</link></function>
|
|
family of functions can be used to instantiate any GType which inherits
|
|
from the GObject base type. All these functions make sure the class and
|
|
instance structures have been correctly initialized by GLib's type system
|
|
and then invoke at one point or another the constructor class method
|
|
which is used to:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Allocate and clear memory through <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>,
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Initialize the object's instance with the construction properties.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
Although one can expect all class and instance members (except the fields
|
|
pointing to the parents) to be set to zero, some consider it good practice
|
|
to explicitly set them.
|
|
</para>
|
|
|
|
<para>
|
|
Objects which inherit from GObject are allowed to override this
|
|
constructor class method: they should however chain to their parent
|
|
constructor method before doing so:
|
|
<programlisting>
|
|
GObject *(* constructor) (GType gtype,
|
|
guint n_properties,
|
|
GObjectConstructParam *properties);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The example below shows how <type>MamanBar</type> overrides the parent's constructor:
|
|
<programlisting>
|
|
#define MAMAN_TYPE_BAR (maman_bar_get_type ())
|
|
#define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
|
|
#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
|
|
#define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
|
|
#define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
|
|
#define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))
|
|
|
|
typedef struct _MamanBar MamanBar;
|
|
typedef struct _MamanBarClass MamanBarClass;
|
|
|
|
struct _MamanBar
|
|
{
|
|
GObject parent_instance;
|
|
|
|
/* instance members */
|
|
};
|
|
|
|
struct _MamanBarClass
|
|
{
|
|
GObjectClass parent_class;
|
|
|
|
/* class members */
|
|
};
|
|
|
|
/* will create maman_bar_get_type and set maman_bar_parent_class */
|
|
G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
|
|
|
|
static GObject *
|
|
maman_bar_constructor (GType gtype,
|
|
guint n_properties,
|
|
GObjectConstructParam *properties)
|
|
{
|
|
GObject *obj;
|
|
|
|
{
|
|
/* Always chain up to the parent constructor */
|
|
obj = G_OBJECT_CLASS (maman_bar_parent_class)->constructor (gtype, n_properties, properties);
|
|
}
|
|
|
|
/* update the object state depending on constructor properties */
|
|
|
|
return obj;
|
|
}
|
|
|
|
static void
|
|
maman_bar_class_init (MamanBarClass *klass)
|
|
{
|
|
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
|
|
|
|
gobject_class->constructor = maman_bar_constructor;
|
|
}
|
|
|
|
static void
|
|
maman_bar_init (MamanBar *self)
|
|
{
|
|
/* initialize the object */
|
|
}
|
|
|
|
</programlisting>
|
|
If the user instantiates an object <type>MamanBar</type> with:
|
|
<programlisting>
|
|
MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
|
|
</programlisting>
|
|
If this is the first instantiation of such an object, the
|
|
<function>maman_bar_class_init</function> function will be invoked
|
|
after any <function>maman_bar_base_class_init</function> function.
|
|
This will make sure the class structure of this new object is
|
|
correctly initialized. Here, <function>maman_bar_class_init</function>
|
|
is expected to override the object's class methods and setup the
|
|
class' own methods. In the example above, the constructor method is
|
|
the only overridden method: it is set to
|
|
<function>maman_bar_constructor</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Once <function><link linkend="g-object-new">g_object_new</link></function> has obtained a reference to an initialized
|
|
class structure, it invokes its constructor method to create an instance of the new
|
|
object. Since it has just been overridden by <function>maman_bar_class_init</function>
|
|
to <function>maman_bar_constructor</function>, the latter is called and, because it
|
|
was implemented correctly, it chains up to its parent's constructor. In
|
|
order to find the parent class and chain up to the parent class
|
|
constructor, we can use the <literal>maman_bar_parent_class</literal>
|
|
pointer that has been set up for us by the
|
|
<literal>G_DEFINE_TYPE</literal> macro.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, at one point or another, <function>g_object_constructor</function> is invoked
|
|
by the last constructor in the chain. This function allocates the object's instance' buffer
|
|
through <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
|
|
which means that the instance_init function is invoked at this point if one
|
|
was registered. After instance_init returns, the object is fully initialized and should be
|
|
ready to answer any user-request. When <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
|
|
returns, <function>g_object_constructor</function> sets the construction properties
|
|
(i.e. the properties which were given to <function><link linkend="g-object-new">g_object_new</link></function>) and returns
|
|
to the user's constructor which is then allowed to do useful instance initialization...
|
|
</para>
|
|
|
|
<para>
|
|
The process described above might seem a bit complicated, but it can be
|
|
summarized easily by the table below which lists the functions invoked
|
|
by <function><link linkend="g-object-new">g_object_new</link></function>
|
|
and their order of invocation:
|
|
</para>
|
|
|
|
<para>
|
|
<table id="gobject-construction-table">
|
|
<title><function><link linkend="g-object-new">g_object_new</link></function></title>
|
|
<tgroup cols="3">
|
|
<colspec colwidth="*" colnum="1" align="left"/>
|
|
<colspec colwidth="*" colnum="2" align="left"/>
|
|
<colspec colwidth="8*" colnum="3" align="left"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Invocation time</entry>
|
|
<entry>Function Invoked</entry>
|
|
<entry>Function's parameters</entry>
|
|
<entry>Remark</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="3">First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
|
|
<entry>target type's base_init function</entry>
|
|
<entry>On the inheritance tree of classes from fundamental type to target type.
|
|
base_init is invoked once for each class structure.</entry>
|
|
<entry>
|
|
I have no real idea on how this can be used. If you have a good real-life
|
|
example of how a class' base_init can be used, please, let me know.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
|
|
<entry>target type's class_init function</entry>
|
|
<entry>On target type's class structure</entry>
|
|
<entry>
|
|
Here, you should make sure to initialize or override class methods (that is,
|
|
assign to each class' method its function pointer) and create the signals and
|
|
the properties associated to your object.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
|
|
<entry>interface' base_init function</entry>
|
|
<entry>On interface' vtable</entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
|
|
<entry>interface' interface_init function</entry>
|
|
<entry>On interface' vtable</entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="1">Each call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
|
|
<entry>target type's class constructor method: GObjectClass->constructor</entry>
|
|
<entry>On object's instance</entry>
|
|
<entry>
|
|
If you need to complete the object initialization after all the construction properties
|
|
are set, override the constructor method and make sure to chain up to the object's
|
|
parent class before doing your own initialization.
|
|
In doubt, do not override the constructor method.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>Each call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
|
|
<entry>type's instance_init function</entry>
|
|
<entry>On the inheritance tree of classes from fundamental type to target type.
|
|
the instance_init provided for each type is invoked once for each instance
|
|
structure.</entry>
|
|
<entry>
|
|
Provide an instance_init function to initialize your object before its construction
|
|
properties are set. This is the preferred way to initialize a GObject instance.
|
|
This function is equivalent to C++ constructors.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
|
|
<para>
|
|
Readers should feel concerned about one little twist in the order in
|
|
which functions are invoked: while, technically, the class' constructor
|
|
method is called <emphasis>before</emphasis> the GType's instance_init
|
|
function (since <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> which calls instance_init is called by
|
|
<function>g_object_constructor</function> which is the top-level class
|
|
constructor method and to which users are expected to chain to), the
|
|
user's code which runs in a user-provided constructor will always
|
|
run <emphasis>after</emphasis> GType's instance_init function since the
|
|
user-provided constructor <emphasis>must</emphasis> (you've been warned)
|
|
chain up <emphasis>before</emphasis> doing anything useful.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="gobject-memory">
|
|
<title>Object memory management</title>
|
|
|
|
<para>
|
|
The memory-management API for GObjects is a bit complicated but the idea behind it
|
|
is pretty simple: the goal is to provide a flexible model based on reference counting
|
|
which can be integrated in applications which use or require different memory management
|
|
models (such as garbage collection, aso...). The methods which are used to
|
|
manipulate this reference count are described below.
|
|
<programlisting>
|
|
/*
|
|
Refcounting
|
|
*/
|
|
gpointer g_object_ref (gpointer object);
|
|
void g_object_unref (gpointer object);
|
|
|
|
/*
|
|
* Weak References
|
|
*/
|
|
typedef void (*GWeakNotify) (gpointer data,
|
|
GObject *where_the_object_was);
|
|
|
|
void g_object_weak_ref (GObject *object,
|
|
GWeakNotify notify,
|
|
gpointer data);
|
|
void g_object_weak_unref (GObject *object,
|
|
GWeakNotify notify,
|
|
gpointer data);
|
|
void g_object_add_weak_pointer (GObject *object,
|
|
gpointer *weak_pointer_location);
|
|
void g_object_remove_weak_pointer (GObject *object,
|
|
gpointer *weak_pointer_location);
|
|
/*
|
|
* Cycle handling
|
|
*/
|
|
void g_object_run_dispose (GObject *object);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<sect2 id="gobject-memory-refcount">
|
|
<title>Reference count</title>
|
|
|
|
<para>
|
|
The functions <function><link linkend="g-object-ref">g_object_ref</link></function>/<function><link linkend="g-object-unref">g_object_unref</link></function> respectively
|
|
increase and decrease the reference count.These functions are thread-safe as of GLib 2.8.
|
|
The reference count is, unsurprisingly, initialized to one by
|
|
<function><link linkend="g-object-new">g_object_new</link></function> which means that the caller
|
|
is currently the sole owner of the newly-created reference.
|
|
When the reference count reaches zero, that is,
|
|
when <function><link linkend="g-object-unref">g_object_unref</link></function> is called by the last client holding
|
|
a reference to the object, the <emphasis>dispose</emphasis> and the
|
|
<emphasis>finalize</emphasis> class methods are invoked.
|
|
</para>
|
|
<para>
|
|
Finally, after <emphasis>finalize</emphasis> is invoked,
|
|
<function><link linkend="g-type-free-instance">g_type_free_instance</link></function> is called to free the object instance.
|
|
Depending on the memory allocation policy decided when the type was registered (through
|
|
one of the <function>g_type_register_*</function> functions), the object's instance
|
|
memory will be freed or returned to the object pool for this type.
|
|
Once the object has been freed, if it was the last instance of the type, the type's class
|
|
will be destroyed as described in <xref linkend="gtype-instantiable-classed"/> and
|
|
<xref linkend="gtype-non-instantiable-classed"/>.
|
|
</para>
|
|
|
|
<para>
|
|
The table below summarizes the destruction process of a GObject:
|
|
<table id="gobject-destruction-table">
|
|
<title><function><link linkend="g-object-unref">g_object_unref</link></function></title>
|
|
<tgroup cols="3">
|
|
<colspec colwidth="*" colnum="1" align="left"/>
|
|
<colspec colwidth="*" colnum="2" align="left"/>
|
|
<colspec colwidth="8*" colnum="3" align="left"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Invocation time</entry>
|
|
<entry>Function Invoked</entry>
|
|
<entry>Function's parameters</entry>
|
|
<entry>Remark</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry morerows="1">Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for an instance
|
|
of target type
|
|
</entry>
|
|
<entry>target type's dispose class function</entry>
|
|
<entry>GObject instance</entry>
|
|
<entry>
|
|
When dispose ends, the object should not hold any reference to any other
|
|
member object. The object is also expected to be able to answer client
|
|
method invocations (with possibly an error code but no memory violation)
|
|
until finalize is executed. dispose can be executed more than once.
|
|
dispose should chain up to its parent implementation just before returning
|
|
to the caller.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for an instance
|
|
of target type
|
|
</entry-->
|
|
<entry>target type's finalize class function</entry>
|
|
<entry>GObject instance</entry>
|
|
<entry>
|
|
Finalize is expected to complete the destruction process initiated by
|
|
dispose. It should complete the object's destruction. finalize will be
|
|
executed only once.
|
|
finalize should chain up to its parent implementation just before returning
|
|
to the caller.
|
|
The reason why the destruction process is split is two different phases is
|
|
explained in <xref linkend="gobject-memory-cycles"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="3">Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for the last
|
|
instance of target type
|
|
</entry>
|
|
<entry>interface' interface_finalize function</entry>
|
|
<entry>On interface' vtable</entry>
|
|
<entry>Never used in practice. Unlikely you will need it.</entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function>for the last
|
|
instance of target type
|
|
</entry-->
|
|
<entry>interface' base_finalize function</entry>
|
|
<entry>On interface' vtable</entry>
|
|
<entry>Never used in practice. Unlikely you will need it.</entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for the last
|
|
instance of target type
|
|
</entry-->
|
|
<entry>target type's class_finalize function</entry>
|
|
<entry>On target type's class structure</entry>
|
|
<entry>Never used in practice. Unlikely you will need it.</entry>
|
|
</row>
|
|
<row>
|
|
<!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for the last
|
|
instance of target type
|
|
</entry-->
|
|
<entry>type's base_finalize function</entry>
|
|
<entry>On the inheritance tree of classes from fundamental type to target type.
|
|
base_init is invoked once for each class structure.</entry>
|
|
<entry>Never used in practice. Unlikely you will need it.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="gobject-memory-weakref">
|
|
<title>Weak References</title>
|
|
|
|
<para>
|
|
Weak References are used to monitor object finalization:
|
|
<function><link linkend="g-object-weak-ref">g_object_weak_ref</link></function> adds a monitoring callback which does
|
|
not hold a reference to the object but which is invoked when the object runs
|
|
its dispose method. As such, each weak ref can be invoked more than once upon
|
|
object finalization (since dispose can run more than once during object
|
|
finalization).
|
|
</para>
|
|
|
|
<para>
|
|
<function><link linkend="g-object-weak-unref">g_object_weak_unref</link></function> can be used to remove a monitoring
|
|
callback from the object.
|
|
</para>
|
|
|
|
<para>
|
|
Weak References are also used to implement <function><link linkend="g-object-add-weak-pointer">g_object_add_weak_pointer</link></function>
|
|
and <function><link linkend="g-object-remove-weak-pointer">g_object_remove_weak_pointer</link></function>. These functions add a weak reference
|
|
to the object they are applied to which makes sure to nullify the pointer given by the user
|
|
when object is finalized.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="gobject-memory-cycles">
|
|
<title>Reference counts and cycles</title>
|
|
|
|
<para>
|
|
Note: the following section was inspired by James Henstridge. I guess this means that
|
|
all praise and all curses will be directly forwarded to him.
|
|
</para>
|
|
|
|
<para>
|
|
GObject's memory management model was designed to be easily integrated in existing code
|
|
using garbage collection. This is why the destruction process is split in two phases:
|
|
the first phase, executed in the dispose handler is supposed to release all references
|
|
to other member objects. The second phase, executed by the finalize handler is supposed
|
|
to complete the object's destruction process. Object methods should be able to run
|
|
without program error (that is, without segfault :) in-between the two phases.
|
|
</para>
|
|
|
|
<para>
|
|
This two-step destruction process is very useful to break reference counting cycles.
|
|
While the detection of the cycles is up to the external code, once the cycles have been
|
|
detected, the external code can invoke <function><link linkend="g-object-dispose">g_object_dispose</link></function> which
|
|
will indeed break any existing cycles since it will run the dispose handler associated
|
|
to the object and thus release all references to other objects.
|
|
</para>
|
|
|
|
<para>
|
|
Attentive readers might now have understood one of the rules about the dispose handler
|
|
we stated a bit sooner: the dispose handler can be invoked multiple times. Let's say we
|
|
have a reference count cycle: object A references B which itself references object A.
|
|
Let's say we have detected the cycle and we want to destroy the two objects. One way to
|
|
do this would be to invoke <function><link linkend="g-object-dispose">g_object_dispose</link></function> on one of the
|
|
objects.
|
|
</para>
|
|
|
|
<para>
|
|
If object A releases all its references to all objects, this means it releases its
|
|
reference to object B. If object B was not owned by anyone else, this is its last
|
|
reference count which means this last unref runs B's dispose handler which, in turn,
|
|
releases B's reference on object A. If this is A's last reference count, this last
|
|
unref runs A's dispose handler which is running for the second time before
|
|
A's finalize handler is invoked !
|
|
</para>
|
|
|
|
<para>
|
|
The above example, which might seem a bit contrived can really happen if your
|
|
GObject's are being handled by language bindings. I would thus suggest the rules stated above
|
|
for object destruction are closely followed. Otherwise, <emphasis>Bad Bad Things</emphasis>
|
|
will happen.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="gobject-properties">
|
|
<title>Object properties</title>
|
|
|
|
<para>
|
|
One of GObject's nice features is its generic get/set mechanism for object
|
|
properties. When an object
|
|
is instantiated, the object's class_init handler should be used to register
|
|
the object's properties with <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>
|
|
(implemented in <filename>gobject.c</filename>).
|
|
</para>
|
|
|
|
<para>
|
|
The best way to understand how object properties work is by looking at a real example
|
|
on how it is used:
|
|
<programlisting>
|
|
/************************************************/
|
|
/* Implementation */
|
|
/************************************************/
|
|
|
|
enum
|
|
{
|
|
PROP_0,
|
|
|
|
PROP_MAMAN_NAME,
|
|
PROP_PAPA_NUMBER
|
|
};
|
|
|
|
static void
|
|
maman_bar_set_property (GObject *object,
|
|
guint property_id,
|
|
const GValue *value,
|
|
GParamSpec *pspec)
|
|
{
|
|
MamanBar *self = MAMAN_BAR (object);
|
|
|
|
switch (property_id)
|
|
{
|
|
case PROP_MAMAN_NAME:
|
|
g_free (self->priv->name);
|
|
self->priv->name = g_value_dup_string (value);
|
|
g_print ("maman: %s\n", self->priv->name);
|
|
break;
|
|
|
|
case PROP_PAPA_NUMBER:
|
|
self->priv->papa_number = g_value_get_uchar (value);
|
|
g_print ("papa: %u\n", self->priv->papa_number);
|
|
break;
|
|
|
|
default:
|
|
/* We don't have any other property... */
|
|
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
|
|
break;
|
|
}
|
|
}
|
|
|
|
static void
|
|
maman_bar_get_property (GObject *object,
|
|
guint property_id,
|
|
GValue *value,
|
|
GParamSpec *pspec)
|
|
{
|
|
MamanBar *self = MAMAN_BAR (object);
|
|
|
|
switch (property_id)
|
|
{
|
|
case PROP_MAMAN_NAME:
|
|
g_value_set_string (value, self->priv->name);
|
|
break;
|
|
|
|
case PROP_PAPA_NUMBER:
|
|
g_value_set_uchar (value, self->priv->papa_number);
|
|
break;
|
|
|
|
default:
|
|
/* We don't have any other property... */
|
|
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
|
|
break;
|
|
}
|
|
}
|
|
|
|
static void
|
|
maman_bar_class_init (MamanBarClass *klass)
|
|
{
|
|
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
|
|
GParamSpec *pspec;
|
|
|
|
gobject_class->set_property = maman_bar_set_property;
|
|
gobject_class->get_property = maman_bar_get_property;
|
|
|
|
pspec = g_param_spec_string ("maman-name",
|
|
"Maman construct prop",
|
|
"Set maman's name",
|
|
"no-name-set" /* default value */,
|
|
G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
|
|
g_object_class_install_property (gobject_class,
|
|
PROP_MAMAN_NAME,
|
|
pspec);
|
|
|
|
pspec = g_param_spec_uchar ("papa-number",
|
|
"Number of current Papa",
|
|
"Set/Get papa's number",
|
|
0 /* minimum value */,
|
|
10 /* maximum value */,
|
|
2 /* default value */,
|
|
G_PARAM_READWRITE);
|
|
g_object_class_install_property (gobject_class,
|
|
PROP_PAPA_NUMBER,
|
|
pspec);
|
|
}
|
|
|
|
/************************************************/
|
|
/* Use */
|
|
/************************************************/
|
|
|
|
GObject *bar;
|
|
GValue val = { 0, };
|
|
|
|
bar = g_object_new (MAMAN_TYPE_SUBBAR, NULL);
|
|
|
|
g_value_init (&val, G_TYPE_CHAR);
|
|
g_value_set_char (&val, 11);
|
|
|
|
g_object_set_property (G_OBJECT (bar), "papa-number", &val);
|
|
|
|
g_value_unset (&val);
|
|
</programlisting>
|
|
The client code just above looks simple but a lot of things happen under the hood:
|
|
</para>
|
|
|
|
<para>
|
|
<function><link linkend="g-object-set-property">g_object_set_property</link></function> first ensures a property
|
|
with this name was registered in bar's class_init handler. If so, it calls
|
|
<function><link linkend="object-set-property">object_set_property</link></function> which first walks the class hierarchy,
|
|
from bottom, most derived type, to top, fundamental type to find the class
|
|
which registered that property. It then tries to convert the user-provided GValue
|
|
into a GValue whose type is that of the associated property.
|
|
</para>
|
|
|
|
<para>
|
|
If the user provides a signed char GValue, as is shown
|
|
here, and if the object's property was registered as an unsigned int,
|
|
<function><link linkend="g-value-transform">g_value_transform</link></function> will try to transform the input signed char into
|
|
an unsigned int. Of course, the success of the transformation depends on the availability
|
|
of the required transform function. In practice, there will almost always be a transformation
|
|
<footnote>
|
|
<para>Its behaviour might not be what you expect but it is up to you to actually avoid
|
|
relying on these transformations.
|
|
</para>
|
|
</footnote>
|
|
which matches and conversion will be carried out if needed.
|
|
</para>
|
|
|
|
<para>
|
|
After transformation, the <type><link linkend="GValue">GValue</link></type> is validated by
|
|
<function><link linkend="g-param-value-validate">g_param_value_validate</link></function> which makes sure the user's
|
|
data stored in the <type><link linkend="GValue">GValue</link></type> matches the characteristics specified by
|
|
the property's <type><link linkend="GParamSpec">GParamSpec</link></type>. Here, the <type><link linkend="GParamSpec">GParamSpec</link></type> we
|
|
provided in class_init has a validation function which makes sure that the GValue
|
|
contains a value which respects the minimum and maximum bounds of the
|
|
<type><link linkend="GParamSpec">GParamSpec</link></type>. In the example above, the client's GValue does not
|
|
respect these constraints (it is set to 11, while the maximum is 10). As such, the
|
|
<function><link linkend="g-object-set-property">g_object_set_property</link></function> function will return with an error.
|
|
</para>
|
|
|
|
<para>
|
|
If the user's GValue had been set to a valid value, <function><link linkend="g-object-set-property">g_object_set_property</link></function>
|
|
would have proceeded with calling the object's set_property class method. Here, since our
|
|
implementation of Foo did override this method, the code path would jump to
|
|
<function>foo_set_property</function> after having retrieved from the
|
|
<type><link linkend="GParamSpec">GParamSpec</link></type> the <emphasis>param_id</emphasis>
|
|
<footnote>
|
|
<para>
|
|
It should be noted that the param_id used here need only to uniquely identify each
|
|
<type><link linkend="GParamSpec">GParamSpec</link></type> within the <type><link linkend="FooClass">FooClass</link></type> such that the switch
|
|
used in the set and get methods actually works. Of course, this locally-unique
|
|
integer is purely an optimization: it would have been possible to use a set of
|
|
<emphasis>if (strcmp (a, b) == 0) {} else if (strcmp (a, b) == 0) {}</emphasis> statements.
|
|
</para>
|
|
</footnote>
|
|
which had been stored by
|
|
<function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
|
|
</para>
|
|
|
|
<para>
|
|
Once the property has been set by the object's set_property class method, the code path
|
|
returns to <function><link linkend="g-object-set-property">g_object_set_property</link></function> which calls
|
|
<function><link linkend="g-object-notify-queue-thaw">g_object_notify_queue_thaw</link></function>. This function makes sure that
|
|
the "notify" signal is emitted on the object's instance with the changed property as
|
|
parameter unless notifications were frozen by <function><link linkend="g-object-freeze-notify">g_object_freeze_notify</link></function>.
|
|
</para>
|
|
|
|
<para>
|
|
<function><link linkend="g-object-thaw-notify">g_object_thaw_notify</link></function> can be used to re-enable notification of
|
|
property modifications through the "notify" signal. It is important to remember that
|
|
even if properties are changed while property change notification is frozen, the "notify"
|
|
signal will be emitted once for each of these changed properties as soon as the property
|
|
change notification is thawed: no property change is lost for the "notify" signal. Signal
|
|
can only be delayed by the notification freezing mechanism.
|
|
</para>
|
|
|
|
<para>
|
|
It sounds like a tedious task to set up GValues every time when one wants to modify a property.
|
|
In practice one will rarely do this. The functions <function><link linkend="g-object-set-property">g_object_set_property</link></function>
|
|
and <function><link linkend="g-object-get-property">g_object_get_property</link></function>
|
|
are meant to be used by language bindings. For application there is an easier way and
|
|
that is described next.
|
|
</para>
|
|
|
|
<sect2 id="gobject-multi-properties">
|
|
<title>Accessing multiple properties at once</title>
|
|
|
|
<para>
|
|
It is interesting to note that the <function><link linkend="g-object-set">g_object_set</link></function> and
|
|
<function><link linkend="g-object-set-valist">g_object_set_valist</link></function> (vararg version) functions can be used to set
|
|
multiple properties at once. The client code shown above can then be re-written as:
|
|
<programlisting>
|
|
MamanBar *foo;
|
|
foo = /* */;
|
|
g_object_set (G_OBJECT (foo),
|
|
"papa-number", 2,
|
|
"maman-name", "test",
|
|
NULL);
|
|
</programlisting>
|
|
This saves us from managing the GValues that we were needing to handle when using
|
|
<function><link linkend="g-object-set-property">g_object_set_property</link></function>.
|
|
The code above will trigger one notify signal emission for each property modified.
|
|
</para>
|
|
|
|
<para>
|
|
Of course, the _get versions are also available: <function><link linkend="g-object-get">g_object_get</link></function>
|
|
and <function><link linkend="g-object-get-valist">g_object_get_valist</link></function> (vararg version) can be used to get numerous
|
|
properties at once.
|
|
</para>
|
|
|
|
<para>
|
|
These high level functions have one drawback - they don't provide a return result.
|
|
One should pay attention to the argument types and ranges when using them.
|
|
A known source of errors is to e.g. pass a gfloat instead of a gdouble and thus
|
|
shifting all subsequent parameters by four bytes. Also forgetting the terminating
|
|
NULL will lead to unexpected behaviour.
|
|
</para>
|
|
|
|
<para>
|
|
Really attentive readers now understand how <function><link linkend="g-object-new">g_object_new</link></function>,
|
|
<function><link linkend="g-object-newv">g_object_newv</link></function> and <function><link linkend="g-object-new-valist">g_object_new_valist</link></function>
|
|
work: they parse the user-provided variable number of parameters and invoke
|
|
<function><link linkend="g-object-set">g_object_set</link></function> on the parameters only after the object has been successfully constructed.
|
|
Of course, the "notify" signal will be emitted for each property set.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<!-- @todo tell here about how to pass use handle properties in derived classes -->
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|