+2007-02-11 Stefan Kost <ensonic@users.sf.net>
+
+ * gobject/tut_gobject.xml:
+ * gobject/tut_gsignal.xml:
+ * gobject/tut_gtype.xml:
+ * gobject/tut_howto.xml:
+ * gobject/tut_intro.xml:
+ * gobject/tut_tools.xml:
+ Format XML to be more editable. Describe Interfaces better. Add a
+ footnote at first occurance of 'maman_'.
+
2007-02-08 Stefan Kost <ensonic@users.sf.net>
* gobject/tut_gobject.xml:
<?xml version='1.0' encoding="ISO-8859-1"?>
-
- <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>
+<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-instanciation">
+ <title>Object instanciation</title>
<para>
- <type><link linkend="GObject">GObject</link></type> is a fundamental classed instantiable type. It implements:
+ 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>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>
+ <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' instance with the construction properties.
+ </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.
+ 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>
- <sect1 id="gobject-instanciation">
- <title>Object instanciation</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' 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:
+ <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 type,
guint n_construct_properties,
GObjectConstructParam *construct_properties);
</programlisting>
- </para>
+ </para>
- The example below shows how <type>MamanBar</type> overrides the parent's constructor:
+ <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_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
-#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
+#define MAMAN_TYPE_BAR (maman_bar_get_type ())
+#define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
+#define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
+#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
#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))
return type;
}
</programlisting>
- If the user instantiates an object <type>MamanBar</type> with:
+ 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_b_class_init</function>
- function will be invoked after any <function>maman_b_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>
+</programlisting>
+ If this is the first instantiation of such an object, the <function>maman_b_class_init</function>
+ function will be invoked after any <function>maman_b_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>
- 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. The problem here
- is how we can find the parent constructor. An approach (used in GTK+ source code) would be
- to save the original constructor in a static variable from <function>maman_bar_class_init</function>
- and then to re-use it from <function>maman_bar_constructor</function>. This is clearly possible
- and very simple but I was told it was not nice and the prefered way is to use the
- <function><link linkend="g-type-class-peek">g_type_class_peek</link></function> and <function><link linkend="g-type-class-peek-parent">g_type_class_peek_parent</link></function> functions.
- </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. The problem here
+ is how we can find the parent constructor. An approach (used in GTK+ source code) would be
+ to save the original constructor in a static variable from <function>maman_bar_class_init</function>
+ and then to re-use it from <function>maman_bar_constructor</function>. This is clearly possible
+ and very simple but I was told it was not nice and the prefered way is to use the
+ <function><link linkend="g-type-class-peek">g_type_class_peek</link></function> and <function><link linkend="g-type-class-peek-parent">g_type_class_peek_parent</link></function> functions.
+ </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
- (ie: 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>
+ 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
+ (ie: 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>
- The process described above might seem a bit complicated (it <emphasis>is</emphasis> actually
- overly complicated in my opinion..) 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>
+ The process described above might seem a bit complicated (it <emphasis>is</emphasis> actually
+ overly complicated in my opinion..) 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>
- The array below lists the functions invoked by <function><link linkend="g-object-new">g_object_new</link></function> and
- their order of invocation:
-
-
<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>
+ The array below lists the functions invoked by <function><link linkend="g-object-new">g_object_new</link></function> and
+ their order of invocation:
+
+ <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>
- 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>
+ <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>
+ <sect1 id="gobject-memory">
+ <title>Object memory management</title>
- 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.
+ <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
/*
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);
+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,
/*
Cycle handling
*/
-void g_object_run_dispose (GObject *object);
+void g_object_run_dispose (GObject *object);
</programlisting>
- </para>
+ </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 currenly 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>
+ <sect2 id="gobject-memory-refcount">
+ <title>Reference count</title>
<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.
+ 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 currenly 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>
- 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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 !
+ 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.
+ 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>
<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
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:
MamanBar *self = (MamanBar *)instance;
}
-
static void
maman_bar_set_property (GObject *object,
guint property_id,
</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
which registered that property. It then tries to convert the user-provided GValue
into a GValue whose type if 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,
</footnote>
which matches and conversion will be caried 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
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
<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>
+ 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
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
</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:
+ <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 = /* */;
"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>
+ 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 know 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>
- <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 know 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 classe -->
-
</sect1>
- </chapter>
+</chapter>
<?xml version='1.0' encoding="ISO-8859-1"?>
- <chapter id="chapter-signal">
- <title>The GObject messaging system</title>
-
- <sect1 id="closure">
- <title>Closures</title>
-
- Closures are central to the concept of asynchronous signal delivery
- which is widely used throughout GTK+ and GNOME applications. A Closure is an
- abstraction, a generic representation of a callback. It is a small structure
- which contains three objects:
- <itemizedlist>
-
<listitem><para>a function pointer (the callback itself) whose prototype looks like:
+<chapter id="chapter-signal">
+ <title>The GObject messaging system</title>
+
+ <sect1 id="closure">
+ <title>Closures</title>
+
+ <para>
+ Closures are central to the concept of asynchronous signal delivery
+ which is widely used throughout GTK+ and GNOME applications. A Closure is an
+ abstraction, a generic representation of a callback. It is a small structure
+ which contains three objects:
+ <itemizedlist>
+ <listitem><para>a function pointer (the callback itself) whose prototype looks like:
<programlisting>
return_type function_callback (... , gpointer user_data);
</programlisting>
+ </para></listitem>
+ <listitem><para>
+ the user_data pointer which is passed to the callback upon invocation of the closure
</para></listitem>
- <listitem><para>
- the user_data pointer which is passed to the callback upon invocation of the closure
- </para></listitem>
- <listitem><para>
- a function pointer which represents the destructor of the closure: whenever the
- closure's refcount reaches zero, this function will be called before the closure
- structure is freed.
- </para></listitem>
- </itemizedlist>
- </para>
+ <listitem><para>
+ a function pointer which represents the destructor of the closure: whenever the
+ closure's refcount reaches zero, this function will be called before the closure
+ structure is freed.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The <type><link linkend="GClosure">GClosure</link></type> structure represents the common functionality of all
+ closure implementations: there exists a different Closure implementation for
+ each separate runtime which wants to use the GObject type system.
+ <footnote><para>
+ In Practice, Closures sit at the boundary of language runtimes: if you are
+ writing python code and one of your Python callback receives a signal from
+ one of GTK+ widgets, the C code in GTK+ needs to execute your Python
+ code. The Closure invoked by the GTK+ object invokes the Python callback:
+ it behaves as a normal C object for GTK+ and as a normal Python object for
+ python code.
+ </para></footnote>
+ The GObject library provides a simple <type><link linkend="GCClosure">GCClosure</link></type> type which
+ is a specific implementation of closures to be used with C/C++ callbacks.
+ </para>
+ <para>
+ A <type><link linkend="GClosure">GClosure</link></type> provides simple services:
+ <itemizedlist>
+ <listitem><para>
+ Invocation (<function><link linkend="g-closure-invoke">g_closure_invoke</link></function>): this is what closures
+ were created for: they hide the details of callback invocation from the
+ callback invocator.</para>
+ </listitem>
+ <listitem><para>
+ Notification: the closure notifies listeners of certain events such as
+ closure invocation, closure invalidation and closure finalization. Listeners
+ can be registered with <function><link linkend="g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</link></function>
+ (finalization notification), <function><link linkend="g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</link></function>
+ (invalidation notification) and
+ <function><link linkend="g-closure-add-marshal-guards">g_closure_add_marshal_guards</link></function> (invocation notification).
+ There exist symmetric de-registration functions for finalization and invalidation
+ events (<function><link linkend="g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</link></function> and
+ <function><link linkend="g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</link></function>) but not for the invocation
+ process.
+ <footnote><para>
+ Closures are refcounted and notify listeners of their destruction in a two-stage
+ process: the invalidation notifiers are invoked before the finalization notifiers.
+ </para></footnote></para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <sect2>
+ <title>C Closures</title>
<para>
- The <type><link linkend="GClosure">GClosure</link></type> structure represents the common functionality of all
- closure implementations: there exists a different Closure implementation for
- each separate runtime which wants to use the GObject type system.
- <footnote><para>
- In Practice, Closures sit at the boundary of language runtimes: if you are
- writing python code and one of your Python callback receives a signal from
- one of GTK+ widgets, the C code in GTK+ needs to execute your Python
- code. The Closure invoked by the GTK+ object invokes the Python callback:
- it behaves as a normal C object for GTK+ and as a normal Python object for
- python code.
- </para></footnote>
- The GObject library provides a simple <type><link linkend="GCClosure">GCClosure</link></type> type which
- is a specific implementation of closures to be used with C/C++ callbacks.
- </para>
- <para>
- A <type><link linkend="GClosure">GClosure</link></type> provides simple services:
- <itemizedlist>
- <listitem><para>
- Invocation (<function><link linkend="g-closure-invoke">g_closure_invoke</link></function>): this is what closures
- were created for: they hide the details of callback invocation from the
- callback invocator.
- </para></listitem>
- <listitem><para>
- Notification: the closure notifies listeners of certain events such as
- closure invocation, closure invalidation and closure finalization. Listeners
- can be registered with <function><link linkend="g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</link></function>
- (finalization notification), <function><link linkend="g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</link></function>
- (invalidation notification) and
- <function><link linkend="g-closure-add-marshal-guards">g_closure_add_marshal_guards</link></function> (invocation notification).
- There exist symmetric de-registration functions for finalization and invalidation
- events (<function><link linkend="g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</link></function> and
- <function><link linkend="g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</link></function>) but not for the invocation
- process.
- <footnote><para>
- Closures are refcounted and notify listeners of their destruction in a two-stage
- process: the invalidation notifiers are invoked before the finalization notifiers.
- </para></footnote>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <sect2>
- <title>C Closures</title>
-
- <para>
- If you are using C or C++
- to connect a callback to a given event, you will either use the simple <type><link linkend="GCClosure">GCClosure</link></type>s
- which have a pretty minimal API or the even simpler <function><link linkend="g-signal-connect">g_signal_connect</link></function>
- functions (which will be presented a bit later :).
- <programlisting>
+ If you are using C or C++
+ to connect a callback to a given event, you will either use the simple <type><link linkend="GCClosure">GCClosure</link></type>s
+ which have a pretty minimal API or the even simpler <function><link linkend="g-signal-connect">g_signal_connect</link></function>
+ functions (which will be presented a bit later :).
+<programlisting>
GClosure* g_cclosure_new (GCallback callback_func,
gpointer user_data,
GClosureNotify destroy_data);
GClosureNotify destroy_data);
GClosure* g_signal_type_cclosure_new (GType itype,
guint struct_offset);
- </programlisting>
- </para>
-
- <function><link linkend="g-cclosure-new">g_cclosure_new</link></function> will create a new closure which can invoke the
- user-provided callback_func with the user-provided user_data as last parameter. When the closure
- is finalized (second stage of the destruction process), it will invoke the destroy_data function
- if the user has supplied one.
- </para>
-
- <function><link linkend="g-cclosure-new-swap">g_cclosure_new_swap</link></function> will create a new closure which can invoke the
- user-provided callback_func with the user-provided user_data as first parameter (instead of being the
- last parameter as with <function><link linkend="g-cclosure-new">g_cclosure_new</link></function>). When the closure
- is finalized (second stage of the destruction process), it will invoke the destroy_data
- function if the user has supplied one.
- </para>
- </sect2>
-
- <sect2>
- <title>non-C closures (for the fearless).</title>
-
- As was explained above, Closures hide the details of callback invocation. In C,
- callback invocation is just like function invocation: it is a matter of creating
- the correct stack frame for the called function and executing a <emphasis>call</emphasis>
- assembly instruction.
- </para>
-
- C closure marshallers transform the array of GValues which represent
- the parameters to the target function into a C-style function parameter list, invoke
- the user-supplied C function with this new parameter list, get the return value of the
- function, transform it into a GValue and return this GValue to the marshaller caller.
- </para>
-
- The following code implements a simple marshaller in C for a C function which takes an
- integer as first parameter and returns void.
+</programlisting>
+ </para>
+
+ <para>
+ <function><link linkend="g-cclosure-new">g_cclosure_new</link></function> will create a new closure which can invoke the
+ user-provided callback_func with the user-provided user_data as last parameter. When the closure
+ is finalized (second stage of the destruction process), it will invoke the destroy_data function
+ if the user has supplied one.
+ </para>
+
+ <para>
+ <function><link linkend="g-cclosure-new-swap">g_cclosure_new_swap</link></function> will create a new closure which can invoke the
+ user-provided callback_func with the user-provided user_data as first parameter (instead of being the
+ last parameter as with <function><link linkend="g-cclosure-new">g_cclosure_new</link></function>). When the closure
+ is finalized (second stage of the destruction process), it will invoke the destroy_data
+ function if the user has supplied one.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>non-C closures (for the fearless).</title>
+
+ <para>
+ As was explained above, Closures hide the details of callback invocation. In C,
+ callback invocation is just like function invocation: it is a matter of creating
+ the correct stack frame for the called function and executing a <emphasis>call</emphasis>
+ assembly instruction.
+ </para>
+
+ <para>
+ C closure marshallers transform the array of GValues which represent
+ the parameters to the target function into a C-style function parameter list, invoke
+ the user-supplied C function with this new parameter list, get the return value of the
+ function, transform it into a GValue and return this GValue to the marshaller caller.
+ </para>
+
+ <para>
+ The following code implements a simple marshaller in C for a C function which takes an
+ integer as first parameter and returns void.
+<programlisting>
g_cclosure_marshal_VOID__INT (GClosure *closure,
GValue *return_value,
guint n_param_values,
g_marshal_value_peek_int (param_values + 1),
data2);
}
- </programlisting>
- </para>
-
- <para>
- Of course, there exist other kinds of marshallers. For example, James Henstridge
- wrote a generic Python marshaller which is used by all python Closures (a python closure
- is used to have python-based callback be invoked by the closure invocation process).
- This python marshaller transforms the input GValue list representing the function
- parameters into a Python tuple which is the equivalent structure in python (you can
- look in <function>pyg_closure_marshal</function> in <filename>pygtype.c</filename>
- in the <emphasis>pygobject</emphasis> module in GNOME cvs server).
- </para>
-
- </sect2>
- </sect1>
-
- <sect1 id="signal">
- <title>Signals</title>
-
- <para>
- GObject's signals have nothing to do with standard UNIX signals: they connect
- arbitrary application-specific events with any number of listeners.
- For example, in GTK+, every user event (keystroke or mouse move) is received
- from the X server and generates a GTK+ event under the form of a signal emission
- on a given object instance.
+</programlisting>
</para>
-
+
<para>
- Each signal is registered in the type system together with the type on which
- it can be emitted: users of the type are said to <emphasis>connect</emphasis>
- to the signal on a given type instance when they register a closure to be
- invoked upon the signal emission. Users can also emit the signal by themselves
- or stop the emission of the signal from within one of the closures connected
- to the signal.
+ Of course, there exist other kinds of marshallers. For example, James Henstridge
+ wrote a generic Python marshaller which is used by all python Closures (a python closure
+ is used to have python-based callback be invoked by the closure invocation process).
+ This python marshaller transforms the input GValue list representing the function
+ parameters into a Python tuple which is the equivalent structure in python (you can
+ look in <function>pyg_closure_marshal</function> in <filename>pygtype.c</filename>
+ in the <emphasis>pygobject</emphasis> module in GNOME cvs server).
</para>
- <para>
- When a signal is emitted on a given type instance, all the closures
- connected to this signal on this type instance will be invoked. All the closures
- connected to such a signal represent callbacks whose signature looks like:
+ </sect2>
+ </sect1>
+
+ <sect1 id="signal">
+ <title>Signals</title>
+
+ <para>
+ GObject's signals have nothing to do with standard UNIX signals: they connect
+ arbitrary application-specific events with any number of listeners.
+ For example, in GTK+, every user event (keystroke or mouse move) is received
+ from the X server and generates a GTK+ event under the form of a signal emission
+ on a given object instance.
+ </para>
+
+ <para>
+ Each signal is registered in the type system together with the type on which
+ it can be emitted: users of the type are said to <emphasis>connect</emphasis>
+ to the signal on a given type instance when they register a closure to be
+ invoked upon the signal emission. Users can also emit the signal by themselves
+ or stop the emission of the signal from within one of the closures connected
+ to the signal.
+ </para>
+
+ <para>
+ When a signal is emitted on a given type instance, all the closures
+ connected to this signal on this type instance will be invoked. All the closures
+ connected to such a signal represent callbacks whose signature looks like:
<programlisting>
return_type function_callback (gpointer instance, ... , gpointer user_data);
</programlisting>
- </para>
+ </para>
- <sect2 id="signal-registration">
- <title>Signal registration</title>
+ <sect2 id="signal-registration">
+ <title>Signal registration</title>
- <para>
- To register a new signal on an existing type, we can use any of <function><link linkend="g-signal-newv">g_signal_newv</link></function>,
- <function><link linkend="g-signal-new-valist">g_signal_new_valist</link></function> or <function><link linkend="g-signal-new">g_signal_new</link></function> functions:
+ To register a new signal on an existing type, we can use any of <function><link linkend="g-signal-newv">g_signal_newv</link></function>,
+ <function><link linkend="g-signal-new-valist">g_signal_new_valist</link></function> or <function><link linkend="g-signal-new">g_signal_new</link></function> functions:
<programlisting>
guint g_signal_newv (const gchar *signal_name,
GType itype,
guint n_params,
GType *param_types);
</programlisting>
- The number of parameters to these functions is a bit intimidating but they are relatively
- simple:
- <itemizedlist>
- <listitem><para>
- signal_name: is a string which can be used to uniquely identify a given signal.
- </para></listitem>
- <listitem><para>
- itype: is the instance type on which this signal can be emitted.
- </para></listitem>
- <listitem><para>
- signal_flags: partly defines the order in which closures which were connected to the
- signal are invoked.
- </para></listitem>
- <listitem><para>
- class_closure: this is the default closure for the signal: if it is not NULL upon
- the signal emission, it will be invoked upon this emission of the signal. The
- moment where this closure is invoked compared to other closures connected to that
- signal depends partly on the signal_flags.
- </para></listitem>
- <listitem><para>
- accumulator: this is a function pointer which is invoked after each closure
- has been invoked. If it returns FALSE, signal emission is stopped. If it returns
- TRUE, signal emission proceeds normally. It is also used to compute the return
- value of the signal based on the return value of all the invoked closures.
- </para></listitem>
- <listitem><para>
- accumulator_data: this pointer will be passed down to each invocation of the
- accumulator during emission.
- </para></listitem>
- <listitem><para>
- c_marshaller: this is the default C marshaller for any closure which is connected to
- this signal.
- </para></listitem>
- <listitem><para>
- return_type: this is the type of the return value of the signal.
- </para></listitem>
- <listitem><para>
- n_params: this is the number of parameters this signal takes.
- </para></listitem>
- <listitem><para>
- param_types: this is an array of GTypes which indicate the type of each parameter
- of the signal. The length of this array is indicated by n_params.
- </para></listitem>
- </itemizedlist>
+ The number of parameters to these functions is a bit intimidating but they are relatively
+ simple:
+ <itemizedlist>
+ signal_name: is a string which can be used to uniquely identify a given signal.
+ </para></listitem>
+ itype: is the instance type on which this signal can be emitted.
+ </para></listitem>
+ signal_flags: partly defines the order in which closures which were connected to the
+ signal are invoked.
+ </para></listitem>
+ class_closure: this is the default closure for the signal: if it is not NULL upon
+ the signal emission, it will be invoked upon this emission of the signal. The
+ moment where this closure is invoked compared to other closures connected to that
+ signal depends partly on the signal_flags.
+ </para></listitem>
+ accumulator: this is a function pointer which is invoked after each closure
+ has been invoked. If it returns FALSE, signal emission is stopped. If it returns
+ TRUE, signal emission proceeds normally. It is also used to compute the return
+ value of the signal based on the return value of all the invoked closures.
+ </para></listitem>
+ accumulator_data: this pointer will be passed down to each invocation of the
+ accumulator during emission.
+ </para></listitem>
+ c_marshaller: this is the default C marshaller for any closure which is connected to
+ this signal.
+ </para></listitem>
+ return_type: this is the type of the return value of the signal.
+ </para></listitem>
+ n_params: this is the number of parameters this signal takes.
+ </para></listitem>
+ param_types: this is an array of GTypes which indicate the type of each parameter
+ of the signal. The length of this array is indicated by n_params.
+ </para></listitem>
+ </itemizedlist>
</para>
- <para>
- As you can see from the above definition, a signal is basically a description
- of the closures which can be connected to this signal and a description of the
- order in which the closures connected to this signal will be invoked.
- </para>
-
- </sect2>
-
- <sect2 id="signal-connection">
- <title>Signal connection</title>
-
- <para>
- If you want to connect to a signal with a closure, you have three possibilities:
- <itemizedlist>
- <listitem><para>
- You can register a class closure at signal registration: this is a
- system-wide operation. i.e.: the class_closure will be invoked during each emission
- of a given signal on all the instances of the type which supports that signal.
- </para></listitem>
- <listitem><para>
- You can use <function><link linkend="g-signal-override-class-closure">g_signal_override_class_closure</link></function> which
- overrides the class_closure of a given type. It is possible to call this function
- only on a derived type of the type on which the signal was registered.
- This function is of use only to language bindings.
- </para></listitem>
- <listitem><para>
- You can register a closure with the <function><link linkend="g-signal-connect">g_signal_connect</link></function>
- family of functions. This is an instance-specific operation: the closure
- will be invoked only during emission of a given signal on a given instance.
- </para></listitem>
- </itemizedlist>
- It is also possible to connect a different kind of callback on a given signal:
- emission hooks are invoked whenever a given signal is emitted whatever the instance on
- which it is emitted. Emission hooks are used for example to get all mouse_clicked
- emissions in an application to be able to emit the small mouse click sound.
- Emission hooks are connected with <function><link linkend="g-signal-add-emission-hook">g_signal_add_emission_hook</link></function>
- and removed with <function><link linkend="g-signal-remove-emission-hook">g_signal_remove_emission_hook</link></function>.
- </para>
-
- <para>
- </para>
-
- </sect2>
-
- <sect2 id="signal-emission">
- <title>Signal emission</title>
-
- <para>
- Signal emission is done through the use of the <function><link linkend="g-signal-emit">g_signal_emit</link></function> family
- of functions.
+ <para>
+ As you can see from the above definition, a signal is basically a description
+ of the closures which can be connected to this signal and a description of the
+ order in which the closures connected to this signal will be invoked.
+ </para>
+
+ </sect2>
+
+ <sect2 id="signal-connection">
+ <title>Signal connection</title>
+
+ <para>
+ If you want to connect to a signal with a closure, you have three possibilities:
+ <itemizedlist>
+ <listitem><para>
+ You can register a class closure at signal registration: this is a
+ system-wide operation. i.e.: the class_closure will be invoked during each emission
+ of a given signal on all the instances of the type which supports that signal.
+ </para></listitem>
+ <listitem><para>
+ You can use <function><link linkend="g-signal-override-class-closure">g_signal_override_class_closure</link></function> which
+ overrides the class_closure of a given type. It is possible to call this function
+ only on a derived type of the type on which the signal was registered.
+ This function is of use only to language bindings.
+ </para></listitem>
+ <listitem><para>
+ You can register a closure with the <function><link linkend="g-signal-connect">g_signal_connect</link></function>
+ family of functions. This is an instance-specific operation: the closure
+ will be invoked only during emission of a given signal on a given instance.
+ </para></listitem>
+ </itemizedlist>
+ It is also possible to connect a different kind of callback on a given signal:
+ emission hooks are invoked whenever a given signal is emitted whatever the instance on
+ which it is emitted. Emission hooks are used for example to get all mouse_clicked
+ emissions in an application to be able to emit the small mouse click sound.
+ Emission hooks are connected with <function><link linkend="g-signal-add-emission-hook">g_signal_add_emission_hook</link></function>
+ and removed with <function><link linkend="g-signal-remove-emission-hook">g_signal_remove_emission_hook</link></function>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="signal-emission">
+ <title>Signal emission</title>
+
+ <para>
+ Signal emission is done through the use of the <function><link linkend="g-signal-emit">g_signal_emit</link></function> family
+ of functions.
<programlisting>
void g_signal_emitv (const GValue *instance_and_params,
- guint signal_id,
- GQuark detail,
- GValue *return_value);
+ guint signal_id,
+ GQuark detail,
+ GValue *return_value);
</programlisting>
- <itemizedlist>
- <listitem><para>
- The instance_and_params array of GValues contains the list of input
- parameters to the signal. The first element of the array is the
- instance pointer on which to invoke the signal. The following elements of
- the array contain the list of parameters to the signal.
- </para></listitem>
- <listitem><para>
- signal_id identifies the signal to invoke.
- </para></listitem>
- <listitem><para>
- detail identifies the specific detail of the signal to invoke. A detail is a kind of
- magic token/argument which is passed around during signal emission and which is used
- by closures connected to the signal to filter out unwanted signal emissions. In most
- cases, you can safely set this value to zero. See <xref linkend="signal-detail"/> for
- more details about this parameter.
- </para></listitem>
- <listitem><para>
- return_value holds the return value of the last closure invoked during emission if
- no accumulator was specified. If an accumulator was specified during signal creation,
- this accumulator is used to calculate the return_value as a function of the return
- values of all the closures invoked during emission.
- <footnote><para>
- James (again!!) gives a few non-trivial examples of accumulators:
- <quote>
- For instance, you may have an accumulator that ignores NULL returns from
- closures, and only accumulates the non-NULL ones. Another accumulator may try
- to return the list of values returned by the closures.
- </quote>
- </para></footnote>
- If no closure is invoked during
- emission, the return_value is nonetheless initialized to zero/null.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Internally, the GValue array is passed to the emission function proper,
- <function>signal_emit_unlocked_R</function> (implemented in <filename>gsignal.c</filename>).
- Signal emission can be decomposed in 5 steps:
- <itemizedlist>
- <listitem><para>
- <emphasis>RUN_FIRST</emphasis>: if the G_SIGNAL_RUN_FIRST flag was used
- during signal registration and if there exist a class_closure for this signal,
- the class_closure is invoked. Jump to <emphasis>EMISSION_HOOK</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>EMISSION_HOOK</emphasis>: if any emission hook was added to
- the signal, they are invoked from first to last added. Accumulate return values
- and jump to <emphasis>HANDLER_RUN_FIRST</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>HANDLER_RUN_FIRST</emphasis>: if any closure were connected
- with the <function><link linkend="g-signal-connect">g_signal_connect</link></function> family of
- functions, and if they are not blocked (with the <function><link linkend="g-signal-handler-block">g_signal_handler_block</link></function>
- family of functions) they are run here, from first to last connected.
- Jump to <emphasis>RUN_LAST</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>RUN_LAST</emphasis>: if the G_SIGNAL_RUN_LAST
- flag was set during registration and if a class_closure
- was set, it is invoked here. Jump to
- <emphasis>HANDLER_RUN_LAST</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>HANDLER_RUN_LAST</emphasis>: if any closure were connected
- with the <function>g_signal_connect_after</function> family of
- functions, if they were not invoked during HANDLER_RUN_FIRST and if they
- are not blocked, they are run here, from first to last connected.
- Jump to <emphasis>RUN_CLEANUP</emphasis> state.
- </para></listitem>
- <listitem><para>
- <emphasis>RUN_CLEANUP</emphasis>: if the G_SIGNAL_RUN_CLEANUP flag
- was set during registration and if a class_closure was set,
- it is invoked here. Signal emission is completed here.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- If, at any point during emission (except in RUN_CLEANUP state), one of the
- closures or emission hook stops the signal emission with
- <function><link linkend="g-signal-stop">g_signal_stop</link></function>, emission jumps to CLEANUP state.
- </para>
-
- <para>
- If, at any point during emission, one of the closures or emission hook
- emits the same signal on the same instance, emission is restarted from
- the RUN_FIRST state.
- </para>
-
- <para>
- The accumulator function is invoked in all states, after invocation
- of each closure (except in EMISSION_HOOK and CLEANUP). It accumulates
- the closure return value into the signal return value and returns TRUE or
- FALSE. If, at any point, it does not return TRUE, emission jumps to CLEANUP state.
- </para>
-
- <para>
- If no accumulator function was provided, the value returned by the last handler
- run will be returned by <function><link linkend="g-signal-emit">g_signal_emit</link></function>.
- </para>
-
- </sect2>
-
-
- <sect2 id="signal-detail">
- <title>The <emphasis>detail</emphasis> argument</title>
-
- <para>All the functions related to signal emission or signal connection have a parameter
- named the <emphasis>detail</emphasis>. Sometimes, this parameter is hidden by the API
- but it is always there, under one form or another.
- </para>
-
- <para>
- Of the three main connection functions,
- only one has an explicit detail parameter as a <type><link linkend="GQuark">GQuark</link></type>
- <footnote>
- <para>A GQuark is an integer which uniquely represents a string. It is possible to transform
- back and forth between the integer and string representations with the functions
- <function><link linkend="g-quark-from-string">g_quark_from_string</link></function> and <function><link linkend="g-quark-to-string">g_quark_to_string</link></function>.
- </para>
- </footnote>:
+ <itemizedlist>
+ The instance_and_params array of GValues contains the list of input
+ parameters to the signal. The first element of the array is the
+ instance pointer on which to invoke the signal. The following elements of
+ the array contain the list of parameters to the signal.
+ </para></listitem>
+ signal_id identifies the signal to invoke.
+ </para></listitem>
+ detail identifies the specific detail of the signal to invoke. A detail is a kind of
+ magic token/argument which is passed around during signal emission and which is used
+ by closures connected to the signal to filter out unwanted signal emissions. In most
+ cases, you can safely set this value to zero. See <xref linkend="signal-detail"/> for
+ more details about this parameter.
+ </para></listitem>
+ return_value holds the return value of the last closure invoked during emission if
+ no accumulator was specified. If an accumulator was specified during signal creation,
+ this accumulator is used to calculate the return_value as a function of the return
+ values of all the closures invoked during emission.
+ James (again!!) gives a few non-trivial examples of accumulators:
+ <quote>
+ For instance, you may have an accumulator that ignores NULL returns from
+ closures, and only accumulates the non-NULL ones. Another accumulator may try
+ to return the list of values returned by the closures.
+ </quote>
+ </para></footnote>
+ If no closure is invoked during
+ emission, the return_value is nonetheless initialized to zero/null.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ Internally, the GValue array is passed to the emission function proper,
+ <function>signal_emit_unlocked_R</function> (implemented in <filename>gsignal.c</filename>).
+ Signal emission can be decomposed in 5 steps:
+ <itemizedlist>
+ <emphasis>RUN_FIRST</emphasis>: if the G_SIGNAL_RUN_FIRST flag was used
+ during signal registration and if there exist a class_closure for this signal,
+ the class_closure is invoked. Jump to <emphasis>EMISSION_HOOK</emphasis> state.
+ </para></listitem>
+ <emphasis>EMISSION_HOOK</emphasis>: if any emission hook was added to
+ the signal, they are invoked from first to last added. Accumulate return values
+ and jump to <emphasis>HANDLER_RUN_FIRST</emphasis> state.
+ </para></listitem>
+ <emphasis>HANDLER_RUN_FIRST</emphasis>: if any closure were connected
+ with the <function><link linkend="g-signal-connect">g_signal_connect</link></function> family of
+ functions, and if they are not blocked (with the <function><link linkend="g-signal-handler-block">g_signal_handler_block</link></function>
+ family of functions) they are run here, from first to last connected.
+ Jump to <emphasis>RUN_LAST</emphasis> state.
+ </para></listitem>
+ <emphasis>RUN_LAST</emphasis>: if the G_SIGNAL_RUN_LAST
+ flag was set during registration and if a class_closure
+ was set, it is invoked here. Jump to
+ <emphasis>HANDLER_RUN_LAST</emphasis> state.
+ </para></listitem>
+ <emphasis>HANDLER_RUN_LAST</emphasis>: if any closure were connected
+ with the <function>g_signal_connect_after</function> family of
+ functions, if they were not invoked during HANDLER_RUN_FIRST and if they
+ are not blocked, they are run here, from first to last connected.
+ Jump to <emphasis>RUN_CLEANUP</emphasis> state.
+ </para></listitem>
+ <emphasis>RUN_CLEANUP</emphasis>: if the G_SIGNAL_RUN_CLEANUP flag
+ was set during registration and if a class_closure was set,
+ it is invoked here. Signal emission is completed here.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ If, at any point during emission (except in RUN_CLEANUP state), one of the
+ closures or emission hook stops the signal emission with
+ <function><link linkend="g-signal-stop">g_signal_stop</link></function>, emission jumps to CLEANUP state.
+ </para>
+
+ If, at any point during emission, one of the closures or emission hook
+ emits the same signal on the same instance, emission is restarted from
+ the RUN_FIRST state.
+ </para>
+
+ The accumulator function is invoked in all states, after invocation
+ of each closure (except in EMISSION_HOOK and CLEANUP). It accumulates
+ the closure return value into the signal return value and returns TRUE or
+ FALSE. If, at any point, it does not return TRUE, emission jumps to CLEANUP state.
+ </para>
+
+ If no accumulator function was provided, the value returned by the last handler
+ run will be returned by <function><link linkend="g-signal-emit">g_signal_emit</link></function>.
+ </para>
+
+ </sect2>
+
+
+ <sect2 id="signal-detail">
+ <title>The <emphasis>detail</emphasis> argument</title>
+
+
<para>All the functions related to signal emission or signal connection have a parameter
+ named the <emphasis>detail</emphasis>. Sometimes, this parameter is hidden by the API
+ but it is always there, under one form or another.
+ </para>
+
+ Of the three main connection functions,
+ only one has an explicit detail parameter as a <type><link linkend="GQuark">GQuark</link></type>
+ <footnote>
+
<para>A GQuark is an integer which uniquely represents a string. It is possible to transform
+ back and forth between the integer and string representations with the functions
+ <function><link linkend="g-quark-from-string">g_quark_from_string</link></function> and <function><link linkend="g-quark-to-string">g_quark_to_string</link></function>.
+ </para>
+ </footnote>:
<programlisting>
-gulong g_signal_connect_closure_by_id (gpointer instance,
- guint signal_id,
- GQuark detail,
- GClosure *closure,
- gboolean after);
+gulong g_signal_connect_closure_by_id (gpointer instance,
+ guint signal_id,
+ GQuark detail,
+ GClosure *closure,
+ gboolean after);
</programlisting>
- The two other functions hide the detail parameter in the signal name identification:
+ The two other functions hide the detail parameter in the signal name identification:
<programlisting>
-gulong g_signal_connect_closure (gpointer instance,
- const gchar *detailed_signal,
- GClosure *closure,
- gboolean after);
-gulong g_signal_connect_data (gpointer instance,
- const gchar *detailed_signal,
- GCallback c_handler,
- gpointer data,
- GClosureNotify destroy_data,
- GConnectFlags connect_flags);
+gulong g_signal_connect_closure (gpointer instance,
+ const gchar *detailed_signal,
+ GClosure *closure,
+ gboolean after);
+gulong g_signal_connect_data (gpointer instance,
+ const gchar *detailed_signal,
+ GCallback c_handler,
+ gpointer data,
+ GClosureNotify destroy_data,
+ GConnectFlags connect_flags);
</programlisting>
- Their detailed_signal parameter is a string which identifies the name of the signal
- to connect to. However, the format of this string is structured to look like
- <emphasis>signal_name::detail_name</emphasis>. Connecting to the signal
- named <emphasis>notify::cursor_position</emphasis> will actually connect to the signal
- named <emphasis>notify</emphasis> with the <emphasis>cursor_position</emphasis> name.
- Internally, the detail string is transformed to a GQuark if it is present.
- </para>
-
- <para>
- Of the four main signal emission functions, three have an explicit detail parameter as a
- <type><link linkend="GQuark">GQuark</link></type> again:
+ Their detailed_signal parameter is a string which identifies the name of the signal
+ to connect to. However, the format of this string is structured to look like
+ <emphasis>signal_name::detail_name</emphasis>. Connecting to the signal
+ named <emphasis>notify::cursor_position</emphasis> will actually connect to the signal
+ named <emphasis>notify</emphasis> with the <emphasis>cursor_position</emphasis> name.
+ Internally, the detail string is transformed to a GQuark if it is present.
+ </para>
+
+ Of the four main signal emission functions, three have an explicit detail parameter as a
+ <type><link linkend="GQuark">GQuark</link></type> again:
<programlisting>
void g_signal_emitv (const GValue *instance_and_params,
- guint signal_id,
- GQuark detail,
- GValue *return_value);
+ guint signal_id,
+ GQuark detail,
+ GValue *return_value);
void g_signal_emit_valist (gpointer instance,
- guint signal_id,
- GQuark detail,
- va_list var_args);
+ guint signal_id,
+ GQuark detail,
+ va_list var_args);
void g_signal_emit (gpointer instance,
- guint signal_id,
- GQuark detail,
- ...);
+ guint signal_id,
+ GQuark detail,
+ ...);
</programlisting>
- The fourth function hides it in its signal name parameter:
+ The fourth function hides it in its signal name parameter:
<programlisting>
void g_signal_emit_by_name (gpointer instance,
- const gchar *detailed_signal,
- ...);
+ const gchar *detailed_signal,
+ ...);
</programlisting>
- The format of the detailed_signal parameter is exactly the same as the format used by
- the <function><link linkend="g-signal-connect">g_signal_connect</link></function> functions: <emphasis>signal_name::detail_name</emphasis>.
- </para>
-
- <para>
- If a detail is provided by the user to the emission function, it is used during emission to match
- against the closures which also provide a detail.
- If the closures' detail does not match the detail provided by the user, they will not be invoked
- (even though they are connected to a signal which is being emitted).
- </para>
-
- <para>This completely optional filtering mechanism is mainly used as an optimization for signals
- which are often emitted for many different reasons: the clients can filter out which events they are
- interested into before the closure's marshalling code runs. For example, this is used extensively
- by the <emphasis>notify</emphasis> signal of GObject: whenever a property is modified on a GObject,
- instead of just emitting the <emphasis>notify</emphasis> signal, GObject associates as a detail to this
- signal emission the name of the property modified. This allows clients who wish to be notified of changes
- to only one property to filter most events before receiving them.
- </para>
-
- <para>As a simple rule, users can and should set the detail parameter to zero: this will disable completely
- this optional filtering.
- </para>
-
- </sect2>
-
- </sect1>
- </chapter>
+ The format of the detailed_signal parameter is exactly the same as the format used by
+ the <function><link linkend="g-signal-connect">g_signal_connect</link></function> functions: <emphasis>signal_name::detail_name</emphasis>.
+ </para>
+
+ <para>
+ If a detail is provided by the user to the emission function, it is used during emission to match
+ against the closures which also provide a detail.
+ If the closures' detail does not match the detail provided by the user, they will not be invoked
+ (even though they are connected to a signal which is being emitted).
+ </para>
+
+ <para>
+ This completely optional filtering mechanism is mainly used as an optimization for signals
+ which are often emitted for many different reasons: the clients can filter out which events they are
+ interested into before the closure's marshalling code runs. For example, this is used extensively
+ by the <emphasis>notify</emphasis> signal of GObject: whenever a property is modified on a GObject,
+ instead of just emitting the <emphasis>notify</emphasis> signal, GObject associates as a detail to this
+ signal emission the name of the property modified. This allows clients who wish to be notified of changes
+ to only one property to filter most events before receiving them.
+ </para>
+
+ <para>
+ As a simple rule, users can and should set the detail parameter to zero: this will disable completely
+ this optional filtering.
+ </para>
+
+ </sect2>
+
+ </sect1>
+</chapter>
+
<?xml version='1.0' encoding="ISO-8859-1"?>
- <chapter>
+ <chapter id="chapter-gtype">
<title>The Glib Dynamic Type System</title>
<para>
- A type, as manipulated by the Glib type system, is much more generic than what
- is usually understood as an Object type. It is best explained by looking at the
- structure and the functions used to register new types in the type system.
- <programlisting>
+ A type, as manipulated by the Glib type system, is much more generic than what
+ is usually understood as an Object type. It is best explained by looking at the
+ structure and the functions used to register new types in the type system.
typedef struct _GTypeInfo GTypeInfo;
struct _GTypeInfo
{
const GTypeInfo *info,
const GTypeFundamentalInfo *finfo,
GTypeFlags flags);
- </programlisting>
+ </programlisting>
</para>
<para>
- <function><link linkend="g-type-register-static">g_type_register_static</link></function> and
- <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function>
- are the C functions, defined in
- <filename>gtype.h</filename> and implemented in <filename>gtype.c</filename>
- which you should use to register a new <type><link linkend="GType">GType</link></type> in the program's type system.
- It is not likely you will ever need to use
- <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function> (you have to be Tim Janik
- to do that) but in case you want to, the last chapter explains how to create
- new fundamental types.
- <footnote>
- <para>
- Please, note that there exist another registration function: the
- <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>. We will not discuss this
- function here since its use is very similar to the <function>_static</function>
- version.
- </para>
- </footnote>
+ <function><link linkend="g-type-register-static">g_type_register_static</link></function> and
+ <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function>
+ are the C functions, defined in
+ <filename>gtype.h</filename> and implemented in <filename>gtype.c</filename>
+ which you should use to register a new <type><link linkend="GType">GType</link></type> in the program's type system.
+ It is not likely you will ever need to use
+ <function><link linkend="g-type-register-fundamental">g_type_register_fundamental</link></function> (you have to be Tim Janik
+ to do that) but in case you want to, the last chapter explains how to create
+ new fundamental types.
+ <footnote>
+ Please, note that there exist another registration function: the
+ <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>. We will not discuss this
+ function here since its use is very similar to the <function>_static</function>
+ version.
+ </para>
+ </footnote>
</para>
<para>
- Fundamental types are top-level types which do not derive from any other type
- while other non-fundamental types derive from other types.
- Upon initialization by <function><link linkend="g-type-init">g_type_init</link></function>, the type system not
- only initializes its internal data structures but it also registers a number of core
- types: some of these are fundamental types. Others are types derived from these
+ Fundamental types are top-level types which do not derive from any other type
+ while other non-fundamental types derive from other types.
+ Upon initialization by <function><link linkend="g-type-init">g_type_init</link></function>, the type system not
+ only initializes its internal data structures but it also registers a number of core
+ types: some of these are fundamental types. Others are types derived from these
fundamental types.
</para>
<para>
- Fundamental and non-Fundamental types are defined by:
- <itemizedlist>
- <listitem><para>
+ Fundamental and non-Fundamental types are defined by:
+ <itemizedlist>
class size: the class_size field in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
</para></listitem>
- <listitem><para>
class initialization functions (C++ constructor): the base_init and
class_init fields in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
</para></listitem>
- <listitem><para>
class destruction functions (C++ destructor): the base_finalize and
class_finalize fields in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
</para></listitem>
- <listitem><para>
instance size (C++ parameter to new): the instance_size field in
<type><link linkend="GTypeInfo">GTypeInfo</link></type>.
</para></listitem>
- <listitem><para>
instanciation policy (C++ type of new operator): the n_preallocs
field in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
</para></listitem>
- <listitem><para>
copy functions (C++ copy operators): the value_table field in
<type><link linkend="GTypeInfo">GTypeInfo</link></type>.
</para></listitem>
</para>
<sect1 id="gtype-copy">
- <title>Copy functions</title>
-
- <para>
- The major common point between <emphasis>all</emphasis> glib types (fundamental and
- non-fundamental, classed and non-classed, instantiable and non-instantiable) is that
- they can all be manipulated through a single API to copy/assign them.
- </para>
-
- <para>
- The <type><link linkend="GValue">GValue</link></type> structure is used as an abstract container for all of these
- types. Its simplistic API (defined in <filename>gobject/gvalue.h</filename>) can be
- used to invoke the value_table functions registered
- during type registration: for example <function><link linkend="g-value-copy">g_value_copy</link></function> copies the
- content of a <type><link linkend="GValue">GValue</link></type> to another <type><link linkend="GValue">GValue</link></type>. This is similar
- to a C++ assignment which invokes the C++ copy operator to modify the default
- bit-by-bit copy semantics of C++/C structures/classes.
- </para>
-
- <para>
- The following code shows how you can copy around a 64 bit integer, as well as a <type><link linkend="GObject">GObject</link></type>
- instance pointer (sample code for this is located in the source tarball for this document in
+ <title>Copy functions</title>
+
+ The major common point between <emphasis>all</emphasis> glib types (fundamental and
+ non-fundamental, classed and non-classed, instantiable and non-instantiable) is that
+ they can all be manipulated through a single API to copy/assign them.
+ </para>
+
+ The <type><link linkend="GValue">GValue</link></type> structure is used as an abstract container for all of these
+ types. Its simplistic API (defined in <filename>gobject/gvalue.h</filename>) can be
+ used to invoke the value_table functions registered
+ during type registration: for example <function><link linkend="g-value-copy">g_value_copy</link></function> copies the
+ content of a <type><link linkend="GValue">GValue</link></type> to another <type><link linkend="GValue">GValue</link></type>. This is similar
+ to a C++ assignment which invokes the C++ copy operator to modify the default
+ bit-by-bit copy semantics of C++/C structures/classes.
+ </para>
+
+ The following code shows how you can copy around a 64 bit integer, as well as a <type><link linkend="GObject">GObject</link></type>
+ instance pointer (sample code for this is located in the source tarball for this document in
<filename>sample/gtype/test.c</filename>):
<programlisting>
static void test_int (void)
g_object_unref (G_OBJECT (obj));
}
</programlisting>
- The important point about the above code is that the exact semantic of the copy calls
- is undefined since they depend on the implementation of the copy function. Certain
- copy functions might decide to allocate a new chunk of memory and then to copy the
- data from the source to the destination. Others might want to simply increment
- the reference count of the instance and copy the reference to the new GValue.
- </para>
-
- <para>
- The value_table used to specify these assignment functions is defined in
- <filename>gtype.h</filename> and is thoroughly described in the
- API documentation provided with GObject (for once ;-) which is why we will
- not detail its exact semantics.
- <programlisting>
+ The important point about the above code is that the exact semantic of the copy calls
+ is undefined since they depend on the implementation of the copy function. Certain
+ copy functions might decide to allocate a new chunk of memory and then to copy the
+ data from the source to the destination. Others might want to simply increment
+ the reference count of the instance and copy the reference to the new GValue.
+ </para>
+
+ The value_table used to specify these assignment functions is defined in
+ <filename>gtype.h</filename> and is thoroughly described in the
+ API documentation provided with GObject (for once ;-) which is why we will
+ not detail its exact semantics.
typedef struct _GTypeValueTable GTypeValueTable;
struct _GTypeValueTable
{
void (*value_init) (GValue *value);
void (*value_free) (GValue *value);
void (*value_copy) (const GValue *src_value,
- GValue *dest_value);
+ GValue *dest_value);
/* varargs functionality (optional) */
gpointer (*value_peek_pointer) (const GValue *value);
- gchar *collect_format;
+ gchar *collect_format;
gchar* (*collect_value) (GValue *value,
- guint n_collect_values,
- GTypeCValue *collect_values,
- guint collect_flags);
- gchar *lcopy_format;
+ guint n_collect_values,
+ GTypeCValue *collect_values,
+ guint collect_flags);
+ gchar *lcopy_format;
gchar* (*lcopy_value) (const GValue *value,
- guint n_collect_values,
- GTypeCValue *collect_values,
- guint collect_flags);
+ guint n_collect_values,
+ GTypeCValue *collect_values,
+ guint collect_flags);
};
- </programlisting>
- Interestingly, it is also very unlikely
- you will ever need to specify a value_table during type registration
- because these value_tables are inherited from the parent types for
- non-fundamental types which means that unless you want to write a
- fundamental type (not a great idea !), you will not need to provide
- a new value_table since you will inherit the value_table structure
- from your parent type.
- </para>
+ </programlisting>
+ Interestingly, it is also very unlikely
+ you will ever need to specify a value_table during type registration
+ because these value_tables are inherited from the parent types for
+ non-fundamental types which means that unless you want to write a
+ fundamental type (not a great idea !), you will not need to provide
+ a new value_table since you will inherit the value_table structure
+ from your parent type.
+ </para>
</sect1>
<sect1 id="gtype-conventions">
- <title>Conventions</title>
+ <title>Conventions</title>
<para>
- There are a number of conventions users are expected to follow when creating new types
- which are to be exported in a header file:
- <itemizedlist>
- <listitem><para>
+ There are a number of conventions users are expected to follow when creating new types
+ which are to be exported in a header file:
+ <itemizedlist>
Use the <function>object_method</function> pattern for function names: to invoke
the method named foo on an instance of object type bar, call
<function>bar_foo</function>.
</para></listitem>
- <listitem><para>Use prefixing to avoid namespace conflicts with other projects.
- If your library (or application) is named <emphasis>Maman</emphasis>,
+ <listitem><para>Use prefixing to avoid namespace conflicts with other projects.
+ If your library (or application) is named <emphasis>Maman</emphasis>,
+ <footnote>
+ <para>
+ <emphasis>Maman</emphasis> is the french word for <emphasis>mum</emphasis>
+ or <emphasis>mother</emphasis> - nothing more and nothing less.
+ </para>
+ </footnote>
+
prefix all your function names with <emphasis>maman_</emphasis>.
For example: <function>maman_object_method</function>.
</para></listitem>
- <listitem><para>Create a macro named <function>PREFIX_OBJECT_TYPE</function> which always
+
<listitem><para>Create a macro named <function>PREFIX_OBJECT_TYPE</function> which always
returns the GType for the associated object type. For an object of type
<emphasis>Bar</emphasis> in a libray prefixed by <emphasis>maman</emphasis>,
use: <function>MAMAN_BAR_TYPE</function>.
static variable or a function named <function>prefix_object_get_type</function>.
We will follow the function pattern wherever possible in this document.
</para></listitem>
- <listitem><para>Create a macro named <function>PREFIX_OBJECT (obj)</function> which
+
<listitem><para>Create a macro named <function>PREFIX_OBJECT (obj)</function> which
returns a pointer of type <type>PrefixObject</type>. This macro is used to enforce
static type safety by doing explicit casts wherever needed. It also enforces
dynamic type safety by doing runtime checks. It is possible to disable the dynamic
For example, we would create
<function>MAMAN_BAR (obj)</function> to keep the previous example.
</para></listitem>
- <listitem><para>If the type is classed, create a macro named
+
<listitem><para>If the type is classed, create a macro named
<function>PREFIX_OBJECT_CLASS (klass)</function>. This macro
is strictly equivalent to the previous casting macro: it does static casting with
dynamic type checking of class structures. It is expected to return a pointer
to a class structure of type <type>PrefixObjectClass</type>. Again, an example is:
<function>MAMAN_BAR_CLASS</function>.
</para></listitem>
- <listitem><para>Create a macro named <function>PREFIX_IS_BAR (obj)</function>: this macro is expected
+
<listitem><para>Create a macro named <function>PREFIX_IS_BAR (obj)</function>: this macro is expected
to return a <type>gboolean</type> which indicates whether or not the input
object instance pointer of type BAR.
</para></listitem>
- <listitem><para>If the type is classed, create a macro named
+
<listitem><para>If the type is classed, create a macro named
<function>PREFIX_IS_OBJECT_CLASS (klass)</function> which, as above, returns a boolean
if the input class pointer is a pointer to a class of type OBJECT.
</para></listitem>
- <listitem><para>If the type is classed, create a macro named
+
<listitem><para>If the type is classed, create a macro named
<function>PREFIX_OBJECT_GET_CLASS (obj)</function>
- which returns the class pointer associated to an instance of a given type. This macro
- is used for static and dynamic type safety purposes (just like the previous casting
- macros).
+ which returns the class pointer associated to an instance of a given type. This macro
+ is used for static and dynamic type safety purposes (just like the previous casting
+ macros).
</para></listitem>
- </itemizedlist>
- The implementation of these macros is pretty straightforward: a number of simple-to-use
- macros are provided in <filename>gtype.h</filename>. For the example we used above, we would
- write the following trivial code to declare the macros:
+ </itemizedlist>
+ The implementation of these macros is pretty straightforward: a number of simple-to-use
+ macros are provided in <filename>gtype.h</filename>. For the example we used above, we would
+ write the following trivial code to declare the macros:
<programlisting>
-#define MAMAN_BAR_TYPE (maman_bar_get_type ())
-#define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_BAR_TYPE, MamanBar))
-#define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_BAR_TYPE, MamanBarClass))
-#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_BAR_TYPE))
+#define MAMAN_BAR_TYPE (maman_bar_get_type ())
+#define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_BAR_TYPE, MamanBar))
+#define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_BAR_TYPE, MamanBarClass))
+#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_BAR_TYPE))
#define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_BAR_TYPE))
#define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_BAR_TYPE, MamanBarClass))
</programlisting>
</para>
<para>
- The following code shows how to implement the <function>maman_bar_get_type</function>
- function:
+ The following code shows how to implement the <function>maman_bar_get_type</function>
+ function:
<programlisting>
GType maman_bar_get_type (void)
{
</sect1>
<sect1 id="gtype-non-instantiable">
- <title>Non-Instantiable non-classed fundamental types</title>
-
- <para>
- A lot of types are not instantiable by the type system and do not have
- a class. Most of these types are fundamental trivial types such as <emphasis>gchar</emphasis>,
- registered in <function>g_value_types_init</function> (in <filename>gvaluetypes.c</filename>).
- </para>
-
- <para>
- To register such a type in the type system, you just need to fill the
- <type><link linkend="GTypeInfo">GTypeInfo</link></type> structure with zeros since these types are also most of the time
- fundamental:
- <programlisting>
+ <title>Non-Instantiable non-classed fundamental types</title>
+
+ A lot of types are not instantiable by the type system and do not have
+ a class. Most of these types are fundamental trivial types such as <emphasis>gchar</emphasis>,
+ registered in <function>g_value_types_init</function> (in <filename>gvaluetypes.c</filename>).
+ </para>
+
+ To register such a type in the type system, you just need to fill the
+ <type><link linkend="GTypeInfo">GTypeInfo</link></type> structure with zeros since these types are also most of the time
+ fundamental:
GTypeInfo info = {
- 0, /* class_size */
- NULL, /* base_init */
- NULL, /* base_destroy */
- NULL, /* class_init */
- NULL, /* class_destroy */
- NULL, /* class_data */
- 0, /* instance_size */
- 0, /* n_preallocs */
- NULL, /* instance_init */
- NULL, /* value_table */
+ 0, /* class_size */
+ NULL, /* base_init */
+ NULL, /* base_destroy */
+ NULL, /* class_init */
+ NULL, /* class_destroy */
+ NULL, /* class_data */
+ 0, /* instance_size */
+ 0, /* n_preallocs */
+ NULL, /* instance_init */
+ NULL, /* value_table */
};
static const GTypeValueTable value_table = {
- value_init_long0, /* value_init */
- NULL, /* value_free */
- value_copy_long0, /* value_copy */
- NULL, /* value_peek_pointer */
- "i", /* collect_format */
- value_collect_int, /* collect_value */
- "p", /* lcopy_format */
- value_lcopy_char, /* lcopy_value */
+ value_init_long0, /* value_init */
+ NULL, /* value_free */
+ value_copy_long0, /* value_copy */
+ NULL, /* value_peek_pointer */
+ "i", /* collect_format */
+ value_collect_int, /* collect_value */
+ "p", /* lcopy_format */
+ value_lcopy_char, /* lcopy_value */
};
info.value_table = &value_table;
type = g_type_register_fundamental (G_TYPE_CHAR, "gchar", &info, &finfo, 0);
- </programlisting>
- </para>
+ </programlisting>
+ </para>
- <para>
- Having non-instantiable types might seem a bit useless: what good is a type
- if you cannot instanciate an instance of that type ? Most of these types
- are used in conjunction with <type><link linkend="GValue">GValue</link></type>s: a GValue is initialized
- with an integer or a string and it is passed around by using the registered
- type's value_table. <type><link linkend="GValue">GValue</link></type>s (and by extension these trivial fundamental
- types) are most useful when used in conjunction with object properties and signals.
- </para>
+ Having non-instantiable types might seem a bit useless: what good is a type
+ if you cannot instanciate an instance of that type ? Most of these types
+ are used in conjunction with <type><link linkend="GValue">GValue</link></type>s: a GValue is initialized
+ with an integer or a string and it is passed around by using the registered
+ type's value_table. <type><link linkend="GValue">GValue</link></type>s (and by extension these trivial fundamental
+ types) are most useful when used in conjunction with object properties and signals.
+ </para>
</sect1>
<sect1 id="gtype-instantiable-classed">
- <title>Instantiable classed types: objects</title>
+ <title>Instantiable classed types: objects</title>
- <para>
- Types which are registered with a class and are declared instantiable are
- what most closely resembles an <emphasis>object</emphasis>.
+ Types which are registered with a class and are declared instantiable are
+ what most closely resembles an <emphasis>object</emphasis>.
Although <type><link linkend="GObject">GObject</link></type>s (detailed in <xref linkend="chapter-gobject"/>)
are the most well known type of instantiable
classed types, other kinds of similar objects used as the base of an inheritance
return type;
}
</programlisting>
- Upon the first call to <function>maman_bar_get_type</function>, the type named
+ Upon the first call to <function>maman_bar_get_type</function>, the type named
<emphasis>BarType</emphasis> will be registered in the type system as inheriting
from the type <emphasis>G_TYPE_OBJECT</emphasis>.
- </para>
+ </para>
- <para>
- Every object must define two structures: its class structure and its
- instance structure. All class structures must contain as first member
- a <type><link linkend="GTypeClass">GTypeClass</link></type> structure. All instance structures must contain as first
- member a <type><link linkend="GTypeInstance">GTypeInstance</link></type> structure. The declaration of these C types,
+ Every object must define two structures: its class structure and its
+ instance structure. All class structures must contain as first member
+ a <type><link linkend="GTypeClass">GTypeClass</link></type> structure. All instance structures must contain as first
+ member a <type><link linkend="GTypeInstance">GTypeInstance</link></type> structure. The declaration of these C types,
coming from <filename>gtype.h</filename> is shown below:
<programlisting>
struct _GTypeClass
GTypeClass *g_class;
};
</programlisting>
- These constraints allow the type system to make sure that every object instance
- (identified by a pointer to the object's instance structure) contains in its
- first bytes a pointer to the object's class structure.
- </para>
- <para>
- This relationship is best explained by an example: let's take object B which
- inherits from object A:
+ These constraints allow the type system to make sure that every object instance
+ (identified by a pointer to the object's instance structure) contains in its
+ first bytes a pointer to the object's class structure.
+ </para>
+ This relationship is best explained by an example: let's take object B which
+ inherits from object A:
<programlisting>
/* A definitions */
typedef struct {
void (*method_c) (void);
void (*method_d) (void);
} BClass;
-</programlisting>
- The C standard mandates that the first field of a C structure is stored starting
- in the first byte of the buffer used to hold the structure's fields in memory.
- This means that the first field of an instance of an object B is A's first field
- which in turn is GTypeInstance's first field which in turn is g_class, a pointer
- to B's class structure.
- </para>
-
- <para>
- Thanks to these simple conditions, it is possible to detect the type of every
- object instance by doing:
+</programlisting>
+ The C standard mandates that the first field of a C structure is stored starting
+ in the first byte of the buffer used to hold the structure's fields in memory.
+ This means that the first field of an instance of an object B is A's first field
+ which in turn is GTypeInstance's first field which in turn is g_class, a pointer
+ to B's class structure.
+ </para>
+
+ Thanks to these simple conditions, it is possible to detect the type of every
+ object instance by doing:
<programlisting>
B *b;
b->parent.parent.g_class->g_type
</programlisting>
- or, more quickly:
+ or, more quickly:
<programlisting>
B *b;
((GTypeInstance*)b)->g_class->g_type
</programlisting>
- </para>
+ </para>
+
+ <sect2 id="gtype-instantiable-classed-init-done">
+ <title>Initialization and Destruction</title>
- <para>
- Instanciation of these types can be done with
- <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>:
+ Instanciation of these types can be done with
+ <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>:
<programlisting>
GTypeInstance* g_type_create_instance (GType type);
void g_type_free_instance (GTypeInstance *instance);
</programlisting>
- <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> will lookup the type information
- structure associated to the type requested. Then, the instance size and instanciation
- policy (if the n_preallocs field is set to a non-zero value, the type system allocates
- the object's instance structures in chunks rather than mallocing for every instance)
- declared by the user are used to get a buffer to hold the object's instance
- structure.
- </para>
-
- <para>
- If this is the first instance of the object ever created, the type system must create
- a class structure: it allocates a buffer to hold the object's class structure and
- initializes it. It first copies the parent's class structure over this structure
- (if there is no parent, it initializes it to zero). It then invokes the
- base_class_initialization functions (<type><link linkend="GBaseInitFunc">GBaseInitFunc</link></type>) from topmost
- fundamental object to bottom-most most derived object. The object's class_init
- (<type><link linkend="GClassInitFunc">GClassInitFunc</link></type>) function is invoked afterwards to complete
- initialization of the class structure.
- Finally, the object's interfaces are initialized (we will discuss interface initialization
- in more detail later).
-<footnote id="class-init">
-<para>
-The class initialization process is entirely implemented in
-<function>type_class_init_Wm</function> in <filename>gtype.c</filename>.
-</para>
-</footnote>
- </para>
-
- <para>
- Once the type system has a pointer to an initialized class structure, it sets the object's
- instance class pointer to the object's class structure and invokes the object's
- instance_init (<type><link linkend="GInstanceInitFunc">GInstanceInitFunc</link></type>)functions, from top-most fundamental
- type to bottom-most most derived type.
- </para>
-
- <para>
- Object instance destruction through <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> is very simple:
- the instance structure is returned to the instance pool if there is one and if this was the
- last living instance of the object, the class is destroyed.
- </para>
-
- <para>
- Class destruction
- <footnote>
- <para>It is implemented in <function>type_data_finalize_class_U</function>
- (in <filename>gtype.c</filename>.
- </para>
- </footnote>
- (the concept of destruction is sometimes partly refered to as finalization
- in GType) is the symmetric process of the initialization: interfaces are
- destroyed first.
- Then, the most derived
- class_finalize (<type><link linkend="ClassFinalizeFunc">ClassFinalizeFunc</link></type>) function is invoked. The
- base_class_finalize (<type><link linkend="GBaseFinalizeFunc">GBaseFinalizeFunc</link></type>) functions are
- Finally invoked from bottom-most most-derived type to top-most fundamental type and
- the class structure is freed.
- </para>
-
- <para>
- As many readers have now understood it, the base initialization/finalization process is
- very similar to the C++ Constructor/Destructor paradigm. The practical details are quite different
- though and it is important not to get confused by the superficial similarities. Typically, what
- most users have grown to know as a C++ constructor (that is, a list of
- object methods invoked on the object instance once for each type of the inheritance hierachy) does
- not exist in GType and must be built on top of the facilities offered by GType. Similarly,
- GTypes have no instance destruction mechanism. It is
- the user's responsibility to implement correct destruction semantics on top
- of the existing GType code. (this is what GObject does. See
- <xref linkend="chapter-gobject"/>)
- </para>
-
- <para>
- For example, if the object B which derives from A is instantiated, GType will only invoke the
- instance_init callback of object B while a C++ runtime will invoke the constructor of the object
- type A first and then of the object type B. Furthermore, the C++ code equivalent to the base_init
- and class_init callbacks of GType is usually not needed because C++ cannot really create object
- types at runtime.
- </para>
-
- <para>
- The instanciation/finalization process can be summarized as follows:
- <table id="gtype-init-fini-table">
- <title>GType Instantiation/Finalization</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>
- </row>
- </thead>
- <tbody>
- <row>
- <entry morerows="2">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
- <entry>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>
- </row>
- <row>
- <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
- <entry>target type's class_init function</entry>
- <entry>On target type's class structure</entry>
- </row>
- <row>
- <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
- <entry>interface initialization, see
- <xref linkend="gtype-non-instantiable-classed-init"/></entry>
- <entry></entry>
- </row>
- <row>
- <entry>Each call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
- <entry>target type's instance_init function</entry>
- <entry>On object's instance</entry>
- </row>
- <row>
- <entry morerows="2">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry>
- <entry>interface destruction, see
- <xref linkend="gtype-non-instantiable-classed-dest"/></entry>
- <entry></entry>
- </row>
- <row>
- <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
- <entry>target type's class_finalize function</entry>
- <entry>On target type's class structure</entry>
- </row>
- <row>
- <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
- <entry>type's base_finalize function</entry>
- <entry>On the inheritance tree of classes from fundamental type to target type.
- base_finalize is invoked once for each class structure.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
+ <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> will lookup the type information
+ structure associated to the type requested. Then, the instance size and instanciation
+ policy (if the n_preallocs field is set to a non-zero value, the type system allocates
+ the object's instance structures in chunks rather than mallocing for every instance)
+ declared by the user are used to get a buffer to hold the object's instance
+ structure.
+ </para>
+
+ <para>
+ If this is the first instance of the object ever created, the type system must create
+ a class structure: it allocates a buffer to hold the object's class structure and
+ initializes it. It first copies the parent's class structure over this structure
+ (if there is no parent, it initializes it to zero). It then invokes the
+ base_class_initialization functions (<type><link linkend="GBaseInitFunc">GBaseInitFunc</link></type>) from topmost
+ fundamental object to bottom-most most derived object. The object's class_init
+ (<type><link linkend="GClassInitFunc">GClassInitFunc</link></type>) function is invoked afterwards to complete
+ initialization of the class structure.
+ Finally, the object's interfaces are initialized (we will discuss interface initialization
+ in more detail later).
+ <footnote id="class-init">
+ <para>
+ The class initialization process is entirely implemented in
+ <function>type_class_init_Wm</function> in <filename>gtype.c</filename>.
+ </para>
+ </footnote>
+ </para>
+
+ <para>
+ Once the type system has a pointer to an initialized class structure, it sets the object's
+ instance class pointer to the object's class structure and invokes the object's
+ instance_init (<type><link linkend="GInstanceInitFunc">GInstanceInitFunc</link></type>)functions, from top-most fundamental
+ type to bottom-most most derived type.
+ </para>
+
+ <para>
+ Object instance destruction through <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> is very simple:
+ the instance structure is returned to the instance pool if there is one and if this was the
+ last living instance of the object, the class is destroyed.
+ </para>
+
+
+ <para>
+ Class destruction
+ <footnote>
+ <para>It is implemented in <function>type_data_finalize_class_U</function>
+ (in <filename>gtype.c</filename>.
+ </para>
+ </footnote>
+ (the concept of destruction is sometimes partly refered to as finalization
+ in GType) is the symmetric process of the initialization: interfaces are
+ destroyed first.
+ Then, the most derived
+ class_finalize (<type><link linkend="ClassFinalizeFunc">ClassFinalizeFunc</link></type>) function is invoked. The
+ base_class_finalize (<type><link linkend="GBaseFinalizeFunc">GBaseFinalizeFunc</link></type>) functions are
+ Finally invoked from bottom-most most-derived type to top-most fundamental type and
+ the class structure is freed.
+ </para>
+
+ <para>
+ As many readers have now understood it, the base initialization/finalization process is
+ very similar to the C++ Constructor/Destructor paradigm. The practical details are quite different
+ though and it is important not to get confused by the superficial similarities. Typically, what
+ most users have grown to know as a C++ constructor (that is, a list of
+ object methods invoked on the object instance once for each type of the inheritance hierachy) does
+ not exist in GType and must be built on top of the facilities offered by GType. Similarly,
+ GTypes have no instance destruction mechanism. It is
+ the user's responsibility to implement correct destruction semantics on top
+ of the existing GType code. (this is what GObject does. See
+ <xref linkend="chapter-gobject"/>)
+ </para>
+
+ <para>
+ For example, if the object B which derives from A is instantiated, GType will only invoke the
+ instance_init callback of object B while a C++ runtime will invoke the constructor of the object
+ type A first and then of the object type B. Furthermore, the C++ code equivalent to the base_init
+ and class_init callbacks of GType is usually not needed because C++ cannot really create object
+ types at runtime.
+ </para>
+
+ <para>
+ The instanciation/finalization process can be summarized as follows:
+ <table id="gtype-init-fini-table">
+ <title>GType Instantiation/Finalization</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>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="2">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
+ <entry>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>
+ </row>
+ <row>
+ <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
+ <entry>target type's class_init function</entry>
+ <entry>On target type's class structure</entry>
+ </row>
+ <row>
+ <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry-->
+ <entry>interface initialization, see
+ <xref linkend="gtype-non-instantiable-classed-init"/></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Each call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
+ <entry>target type's instance_init function</entry>
+ <entry>On object's instance</entry>
+ </row>
+ <row>
+ <entry morerows="2">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry>
+ <entry>interface destruction, see
+ <xref linkend="gtype-non-instantiable-classed-dest"/></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
+ <entry>target type's class_finalize function</entry>
+ <entry>On target type's class structure</entry>
+ </row>
+ <row>
+ <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for target type</entry-->
+ <entry>type's base_finalize function</entry>
+ <entry>On the inheritance tree of classes from fundamental type to target type.
+ base_finalize is invoked once for each class structure.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ </sect2>
</sect1>
<sect1 id="gtype-non-instantiable-classed">
- <title>Non-instantiable classed types: Interfaces.</title>
+ <title>Non-instantiable classed types: Interfaces.</title>
- <para>
GType's Interfaces are very similar to Java's interfaces. They allow
to describe a common API that several classes will adhere to.
+ Imagine the play, pause and stop buttons on hifi equipment - those can
+ be seen as a playback interface. Once you know what the do, you can
+ control your cd-player, mp3-player or anything that uses these symbols.
To declare an interfacce you have to register a non-instantiable
classed type which derives from
- <type><link linkend="GTypeInterface">GTypeInterface</link></type>. The following piece of code declares such an interface.
+ <type><link linkend="GTypeInterface">GTypeInterface</link></type>. The following piece of code declares such an interface.
<programlisting>
#define MAMAN_IBAZ_TYPE (maman_ibaz_get_type ())
#define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_IBAZ_TYPE, MamanIbaz))
inheritance tree.
</para>
- <para>
- An interface is defined by only one structure which must contain as first member
- a <type><link linkend="GTypeInterface">GTypeInterface</link></type> structure. The interface structure is expected to
- contain the function pointers of the interface methods. It is good style to
- define helper functions for each of the interface methods which simply call
- the interface' method directly: <function>maman_ibaz_do_action</function>
- is one of these.
- </para>
-
- <para>
- Once an interface type is registered, you must register implementations for these
+ An interface is defined by only one structure which must contain as first member
+ a <type><link linkend="GTypeInterface">GTypeInterface</link></type> structure. The interface structure is expected to
+ contain the function pointers of the interface methods. It is good style to
+ define helper functions for each of the interface methods which simply call
+ the interface' method directly: <function>maman_ibaz_do_action</function>
+ is one of these.
+ </para>
+
+ Once an interface type is registered, you must register implementations for these
interfaces. The function named <function>maman_baz_get_type</function> registers
a new GType named MamanBaz which inherits from <type><link linkend="GObject">GObject</link></type> and which
implements the interface <type>MamanIBaz</type>.
return type;
}
</programlisting>
- </para>
-
- <para>
- <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function> records in the type system that
- a given type implements also <type>FooInterface</type>
- (<function>foo_interface_get_type</function> returns the type of
- <type>FooInterface</type>).
- The <type><link linkend="GInterfaceInfo">GInterfaceInfo</link></type> structure holds
- information about the implementation of the interface:
+ </para>
+
+ <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function> records in the type system that
+ a given type implements also <type>FooInterface</type>
+ (<function>foo_interface_get_type</function> returns the type of
+ <type>FooInterface</type>).
+ The <type><link linkend="GInterfaceInfo">GInterfaceInfo</link></type> structure holds
+ information about the implementation of the interface:
<programlisting>
struct _GInterfaceInfo
{
gpointer interface_data;
};
</programlisting>
- </para>
-
- <sect2 id="gtype-non-instantiable-classed-init">
- <title>Interface Initialization</title>
-
- <para>
- When an instantiable classed type which registered an interface implementation
- is created for the first time, its class structure is initialized following the process
- described in <xref linkend="gtype-instantiable-classed"/>. Once the class structure is
- initialized,the function <function>type_class_init_Wm</function> (implemented in <filename>
- gtype.c</filename>) initializes the interface implementations associated with
- that type by calling <function>type_iface_vtable_init_Wm</function> for each
- interface.
- </para>
-
- <para>
- First a memory buffer is allocated to hold the interface structure. The parent's
- interface structure is then copied over to the new interface structure (the parent
- interface is already initialized at that point). If there is no parent interface,
- the interface structure is initialized with zeros. The g_type and the g_instance_type
- fields are then initialized: g_type is set to the type of the most-derived interface
- and g_instance_type is set to the type of the most derived type which implements
- this interface.
- </para>
-
- <para>
- Finally, the interface' most-derived <function>base_init</function> function and then
- the implementation's <function>interface_init</function>
- function are invoked. It is important to understand that if there are multiple
- implementations of an interface the <function>base_init</function> and
- <function>interface_init</function> functions will be
- invoked once for each implementation initialized.
- </para>
-
- <para>
- It is thus common for base_init functions to hold a local static boolean variable
- which makes sure that the interface type is initialized only once even if there are
- multiple implementations of the interface:
+ </para>
+
+ <sect2 id="gtype-non-instantiable-classed-init">
+ <title>Interface Initialization</title>
+
+ When an instantiable classed type which registered an interface implementation
+ is created for the first time, its class structure is initialized following the process
+ described in <xref linkend="gtype-instantiable-classed"/>. Once the class structure is
+ initialized,the function <function>type_class_init_Wm</function> (implemented in <filename>
+ gtype.c</filename>) initializes the interface implementations associated with
+ that type by calling <function>type_iface_vtable_init_Wm</function> for each
+ interface.
+ </para>
+
+ First a memory buffer is allocated to hold the interface structure. The parent's
+ interface structure is then copied over to the new interface structure (the parent
+ interface is already initialized at that point). If there is no parent interface,
+ the interface structure is initialized with zeros. The g_type and the g_instance_type
+ fields are then initialized: g_type is set to the type of the most-derived interface
+ and g_instance_type is set to the type of the most derived type which implements
+ this interface.
+ </para>
+
+ Finally, the interface' most-derived <function>base_init</function> function and then
+ the implementation's <function>interface_init</function>
+ function are invoked. It is important to understand that if there are multiple
+ implementations of an interface the <function>base_init</function> and
+ <function>interface_init</function> functions will be
+ invoked once for each implementation initialized.
+ </para>
+
+ It is thus common for base_init functions to hold a local static boolean variable
+ which makes sure that the interface type is initialized only once even if there are
+ multiple implementations of the interface:
<programlisting>
static void
maman_ibaz_base_init (gpointer g_iface)
}
}
</programlisting>
- </para>
-
- <para>
- If you have found the stuff about interface hairy, you are right: it is hairy but
- there is not much I can do about it. What I can do is summarize what you need to know
- about interfaces:
- </para>
-
- <para>
- The above process can be summarized as follows:
- <table id="ginterface-init-table">
- <title>Interface Initialization</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">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for type
- implementing interface
+ </para>
+
+ If you have found the stuff about interface hairy, you are right: it is hairy but
+ there is not much I can do about it. What I can do is summarize what you need to know
+ about interfaces:
+ </para>
+
+ The above process can be summarized as follows:
+
<table id="ginterface-init-table">
+ <title>Interface Initialization</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">First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for type
+ implementing interface
</entry>
- <entry>interface' base_init function</entry>
- <entry>On interface' vtable</entry>
- <entry>Register interface' signals here (use a local static
- boolean variable as described above to make sure not to register them
- twice.).</entry>
- </row>
- <row>
- <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for type
- implementing interface
+ <entry>interface' base_init function</entry>
+ <entry>On interface' vtable</entry>
+ <entry>Register interface' signals here (use a local static
+ boolean variable as described above to make sure not to register them
+ twice.).</entry>
+ </row>
+ <row>
+ <!--entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for type
+ implementing interface
</entry-->
- <entry>interface' interface_init function</entry>
- <entry>On interface' vtable</entry>
- <entry>
- Initialize interface' implementation. That is, initialize the interface
- method pointers in the interface structure to the function's implementation.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- It is highly unlikely (ie: I do not know of <emphasis>anyone</emphasis> who actually
- used it) you will ever need other more fancy things such as the ones described in the
- following section (<xref linkend="gtype-non-instantiable-classed-dest"/>).
- </para>
-
- </sect2>
-
- <sect2 id="gtype-non-instantiable-classed-dest">
- <title>Interface Destruction</title>
-
- <para>
- When the last instance of an instantiable type which registered an interface implementation
- is destroyed, the interface's implementations associated to the type are destroyed by
- <function>type_iface_vtable_finalize_Wm</function> (in <filename>gtype.c</filename>).
- </para>
-
- <para>
- <function>type_iface_vtable_finalize_Wm</function> invokes first the implementation's
- <function>interface_finalize</function> function and then the interface's most-derived
- <function>base_finalize</function> function.
- </para>
-
- <para>
- Again, it is important to understand, as in
- <xref linkend="gtype-non-instantiable-classed-init"/>,
- that both <function>interface_finalize</function> and <function>base_finalize</function>
- are invoked exactly once for the destruction of each implementation of an interface. Thus,
- if you were to use one of these functions, you would need to use a static integer variable
- which would hold the number of instances of implementations of an interface such that
- the interface's class is destroyed only once (when the integer variable reaches zero).
- </para>
-
- <para>
- The above process can be summarized as follows:
- <table id="ginterface-init-table">
- <title>Interface Finalization</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>
- </row>
- </thead>
- <tbody>
- <row>
- <entry morerows="1">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for type
- implementing interface
+ <entry>interface' interface_init function</entry>
+ <entry>On interface' vtable</entry>
+ <entry>
+ Initialize interface' implementation. That is, initialize the interface
+ method pointers in the interface structure to the function's implementation.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ It is highly unlikely (ie: I do not know of <emphasis>anyone</emphasis> who actually
+ used it) you will ever need other more fancy things such as the ones described in the
+ following section (<xref linkend="gtype-non-instantiable-classed-dest"/>).
+ </para>
+
+ </sect2>
+
+ <sect2 id="gtype-non-instantiable-classed-dest">
+ <title>Interface Destruction</title>
+
+ When the last instance of an instantiable type which registered an interface implementation
+ is destroyed, the interface's implementations associated to the type are destroyed by
+ <function>type_iface_vtable_finalize_Wm</function> (in <filename>gtype.c</filename>).
+ </para>
+
+ <function>type_iface_vtable_finalize_Wm</function> invokes first the implementation's
+ <function>interface_finalize</function> function and then the interface's most-derived
+ <function>base_finalize</function> function.
+ </para>
+
+ Again, it is important to understand, as in
+ <xref linkend="gtype-non-instantiable-classed-init"/>,
+ that both <function>interface_finalize</function> and <function>base_finalize</function>
+ are invoked exactly once for the destruction of each implementation of an interface. Thus,
+ if you were to use one of these functions, you would need to use a static integer variable
+ which would hold the number of instances of implementations of an interface such that
+ the interface's class is destroyed only once (when the integer variable reaches zero).
+ </para>
+
+ The above process can be summarized as follows:
+
<table id="ginterface-init-table">
+ <title>Interface Finalization</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>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="1">Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for type
+ implementing interface
</entry>
- <entry>interface' interface_finalize function</entry>
- <entry>On interface' vtable</entry>
- </row>
- <row>
- <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function>for type
- implementing interface
+ <entry>interface' interface_finalize function</entry>
+ <entry>On interface' vtable</entry>
+ </row>
+ <row>
+ <!--entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function>for type
+ implementing interface
</entry-->
- <entry>interface' base_finalize function</entry>
- <entry>On interface' vtable</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
-
- <para>
- Now that you have read this section, you can forget about it. Please, forget it
- <emphasis>as soon as possible</emphasis>.
- </para>
+ <entry>interface' base_finalize function</entry>
+ <entry>On interface' vtable</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ Now that you have read this section, you can forget about it. Please, forget it
+ <emphasis>as soon as possible</emphasis>.
+ </para>
</sect2>
+<?xml version='1.0' encoding="ISO-8859-1"?>
<partintro>
<para>
This chapter tries to answer the real-life questions of users and presents
</para>
</partintro>
-<!--
- Howto GObject
--->
+<chapter id="howto-gobject">
+ <title>How To define and implement a new GObject?</title>
+
+ <para>
+ Clearly, this is one of the most common question people ask: they just want to crank code and
+ implement a subclass of a GObject. Sometimes because they want to create their own class hierarchy,
+ sometimes because they want to subclass one of GTK+'s widget. This chapter will focus on the
+ implementation of a subtype of GObject. The sample source code
+ associated to this section can be found in the documentation's source tarball, in the
+ <filename>sample/gobject</filename> directory:
+ <itemizedlist>
+ <listitem><para><filename>maman-bar.{h|c}</filename>: this is the source for a object which derives from
+ <type><link linkend="GObject">GObject</link></type> and which shows how to declare different types of methods on the object.
+ </para></listitem>
+ <listitem><para><filename>maman-subbar.{h|c}</filename>: this is the source for a object which derives from
+ <type>MamanBar</type> and which shows how to override some of its parent's methods.
+ </para></listitem>
+ <listitem><para><filename>maman-foo.{h|c}</filename>: this is the source for an object which derives from
+ <type><link linkend="GObject">GObject</link></type> and which declares a signal.
+ </para></listitem>
+ <listitem><para><filename>test.c</filename>: this is the main source which instantiates an instance of
+ type and exercises their API.
+ </para></listitem>
+ </itemizedlist>
+ </para>
- <chapter id="howto-gobject">
- <title>How To define and implement a new GObject?</title>
+ <sect1 id="howto-gobject-header">
+ <title>Boilerplate header code</title>
<para>
- Clearly, this is one of the most common question people ask: they just want to crank code and
- implement a subclass of a GObject. Sometimes because they want to create their own class hierarchy,
- sometimes because they want to subclass one of GTK+'s widget. This chapter will focus on the
- implementation of a subtype of GObject. The sample source code
- associated to this section can be found in the documentation's source tarball, in the
- <filename>sample/gobject</filename> directory:
+ The first step before writing the code for your GObject is to write the type's header which contains
+ the needed type, function and macro definitions. Each of these elements is nothing but a convention
+ which is followed not only by GTK+'s code but also by most users of GObject. If you feel the need
+ not to obey the rules stated below, think about it twice:
<itemizedlist>
- <listitem><para><filename>maman-bar.{h|c}</filename>: this is the source for a object which derives from
- <type><link linkend="GObject">GObject</link></type> and which shows how to declare different types of methods on the object.
- </para></listitem>
- <listitem><para><filename>maman-subbar.{h|c}</filename>: this is the source for a object which derives from
- <type>MamanBar</type> and which shows how to override some of its parent's methods.
- </para></listitem>
- <listitem><para><filename>maman-foo.{h|c}</filename>: this is the source for an object which derives from
- <type><link linkend="GObject">GObject</link></type> and which declares a signal.
- </para></listitem>
- <listitem><para><filename>test.c</filename>: this is the main source which instantiates an instance of
- type and exercises their API.
- </para></listitem>
+ <listitem><para>If your users are a bit accustomed to GTK+ code or any Glib code, they will
+ be a bit surprised and getting used to the conventions you decided upon will take time (money) and
+ will make them grumpy (not a good thing)
+ </para></listitem>
+ <listitem><para>
+ You must assess the fact that these conventions might have been designed by both smart
+ and experienced people: maybe they were at least partly right. Try to put your ego aside.
+ </para></listitem>
</itemizedlist>
</para>
- <sect1 id="howto-gobject-header">
- <title>Boilerplate header code</title>
-
- <para>
- The first step before writing the code for your GObject is to write the type's header which contains
- the needed type, function and macro definitions. Each of these elements is nothing but a convention
- which is followed not only by GTK+'s code but also by most users of GObject. If you feel the need
- not to obey the rules stated below, think about it twice:
- <itemizedlist>
- <listitem><para>If your users are a bit accustomed to GTK+ code or any Glib code, they will
- be a bit surprised and getting used to the conventions you decided upon will take time (money) and
- will make them grumpy (not a good thing)
- </para></listitem>
- <listitem><para>
- You must assess the fact that these conventions might have been designed by both smart
- and experienced people: maybe they were at least partly right. Try to put your ego aside.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Pick a name convention for your headers and source code and stick to it:
- <itemizedlist>
- <listitem><para>
- use a dash to separate the prefix from the typename: <filename>maman-bar.h</filename> and
- <filename>maman-bar.c</filename> (this is the convention used by Nautilus and most GNOME libraries).
- </para></listitem>
- <listitem><para>
- use an underscore to separate the prefix from the typename: <filename>maman_bar.h</filename> and
- <filename>maman_bar.c</filename>.
- </para></listitem>
- <listitem><para>
- Do not separate the prefix from the typename: <filename>mamanbar.h</filename> and
- <filename>mamanbar.c</filename>. (this is the convention used by GTK+)
- </para></listitem>
- </itemizedlist>
- I personally like the first solution better: it makes reading file names easier for those with poor
- eyesight like me.
- </para>
+ <para>
+ Pick a name convention for your headers and source code and stick to it:
+ <itemizedlist>
+ <listitem><para>
+ use a dash to separate the prefix from the typename: <filename>maman-bar.h</filename> and
+ <filename>maman-bar.c</filename> (this is the convention used by Nautilus and most GNOME libraries).
+ </para></listitem>
+ <listitem><para>
+ use an underscore to separate the prefix from the typename: <filename>maman_bar.h</filename> and
+ <filename>maman_bar.c</filename>.
+ </para></listitem>
+ <listitem><para>
+ Do not separate the prefix from the typename: <filename>mamanbar.h</filename> and
+ <filename>mamanbar.c</filename>. (this is the convention used by GTK+)
+ </para></listitem>
+ </itemizedlist>
+ I personally like the first solution better: it makes reading file names easier for those with poor
+ eyesight like me.
+ </para>
- When you need some private (internal) declarations in several (sub)classes,
- you can define them in a private header file which is often named by
- appending the <emphasis>private</emphasis> keyword to the public header name.
- For example, one could use <filename>maman-bar-private.h</filename>,
- <filename>maman_bar_private.h</filename> or <filename>mamanbarprivate.h</filename>.
- Typically, such private header files are not installed.
- </para>
+ <para>
+ When you need some private (internal) declarations in several (sub)classes,
+ you can define them in a private header file which is often named by
+ appending the <emphasis>private</emphasis> keyword to the public header name.
+ For example, one could use <filename>maman-bar-private.h</filename>,
+ <filename>maman_bar_private.h</filename> or <filename>mamanbarprivate.h</filename>.
+ Typically, such private header files are not installed.
+ </para>
- The basic conventions for any header which exposes a GType are described in
- <xref linkend="gtype-conventions"/>. Most GObject-based code also obeys onf of the following
- conventions: pick one and stick to it.
- <itemizedlist>
- If you want to declare a type named bar with prefix maman, name the type instance
- <function>MamanBar</function> and its class <function>MamanBarClass</function>
- (name is case-sensitive). It is customary to declare them with code similar to the
- following:
+ <para>
+ The basic conventions for any header which exposes a GType are described in
+ <xref linkend="gtype-conventions"/>. Most GObject-based code also obeys onf of the following
+ conventions: pick one and stick to it.
+ <itemizedlist>
+ <listitem><para>
+ If you want to declare a type named bar with prefix maman, name the type instance
+ <function>MamanBar</function> and its class <function>MamanBarClass</function>
+ (name is case-sensitive). It is customary to declare them with code similar to the
+ following:
<programlisting>
/*
* Copyright/Licensing information.
#endif
</programlisting>
- </para></listitem>
- Most GTK+ types declare their private fields in the public header with a /* private */ comment,
- relying on their user's intelligence not to try to play with these fields. Fields not marked private
- are considered public by default. The /* protected */ comment (same semantics as those of C++)
- is also used, mainly in the GType library, in code written by Tim Janik.
+ </para></listitem>
+ <listitem><para>
+ Most GTK+ types declare their private fields in the public header with a /* private */ comment,
+ relying on their user's intelligence not to try to play with these fields. Fields not marked private
+ are considered public by default. The /* protected */ comment (same semantics as those of C++)
+ is also used, mainly in the GType library, in code written by Tim Janik.
<programlisting>
struct _MamanBar {
GObject parent;
int hsize;
};
</programlisting>
- </para></listitem>
- All of Nautilus code and a lot of GNOME libraries use private indirection members, as described
- by Herb Sutter in his Pimpl articles
-
(see <ulink url="http://www.gotw.ca/gotw/024.htm">Compilation Firewalls</ulink>
-
and <ulink url="http://www.gotw.ca/gotw/028.htm">The Fast Pimpl Idiom</ulink>
- : he summarizes the different issues better than I will).
+ </para></listitem>
+ <listitem><para>
+ All of Nautilus code and a lot of GNOME libraries use private indirection members, as described
+ by Herb Sutter in his Pimpl articles
+ (see <ulink url="http://www.gotw.ca/gotw/024.htm">Compilation Firewalls</ulink>
+ and <ulink url="http://www.gotw.ca/gotw/028.htm">The Fast Pimpl Idiom</ulink>
+ : he summarizes the different issues better than I will).
<programlisting>
typedef struct _MamanBarPrivate MamanBarPrivate;
struct _MamanBar {
GObject parent;
-
+
/*< private >*/
MamanBarPrivate *priv;
};
</programlisting>
- <note><simpara>Do not call this <varname>private</varname>, as that is a registered c++ keyword.</simpara></note>
- The private structure is then defined in the .c file, instantiated in the object's
- <function>init</function> function and destroyed in the object's <function>finalize</function> function.
+ <note><simpara>Do not call this <varname>private</varname>, as that is a registered c++ keyword.</simpara></note>
+ The private structure is then defined in the .c file, instantiated in the object's
+ <function>init</function> function and destroyed in the object's <function>finalize</function> function.
<programlisting>
static void
maman_bar_finalize (GObject *object) {
/* do stuff */
}
</programlisting>
- </para></listitem>
-
- A similar alternative, available since Glib version 2.4, is to define a private structure in the .c file,
- declare it as a private structure in <function>maman_bar_class_init</function> using
- <function><link linkend="g-type-class-add-private">g_type_class_add_private</link></function>.
- Instead of allocating memory in <function>maman_bar_init</function> a pointer to the private memory area is
- stored in the instance to allow convenient access to this structure.
- A private structure will then be attached to each newly created object by the GObject system.
- You dont need to free or allocate the private structure, only the objects or pointers that it may contain.
- Another advantage of this to the previous version is that is lessens memory fragmentation,
- as the public and private parts of the instance memory are allocated at once.
+ </para></listitem>
+
+ <listitem><para>
+ A similar alternative, available since Glib version 2.4, is to define a private structure in the .c file,
+ declare it as a private structure in <function>maman_bar_class_init</function> using
+ <function><link linkend="g-type-class-add-private">g_type_class_add_private</link></function>.
+ Instead of allocating memory in <function>maman_bar_init</function> a pointer to the private memory area is
+ stored in the instance to allow convenient access to this structure.
+ A private structure will then be attached to each newly created object by the GObject system.
+ You dont need to free or allocate the private structure, only the objects or pointers that it may contain.
+ Another advantage of this to the previous version is that is lessens memory fragmentation,
+ as the public and private parts of the instance memory are allocated at once.
<programlisting>
typedef struct _MamanBarPrivate MamanBarPrivate;
/* do stuff */
}
</programlisting>
- </para></listitem>
+ </para></listitem>
- </itemizedlist>
- </para>
+ </itemizedlist>
+ </para>
- Finally, there are different header include conventions. Again, pick one and stick to it. I personally
- use indifferently any of the two, depending on the codebase I work on: the rule is consistency.
- <itemizedlist>
- Some people add at the top of their headers a number of #include directives to pull in
- all the headers needed to compile client code. This allows client code to simply
- #include "maman-bar.h".
- </para></listitem>
- Other do not #include anything and expect the client to #include themselves the headers
- they need before including your header. This speeds up compilation because it minimizes the
- amount of pre-processor work. This can be used in conjunction with the re-declaration of certain
- unused types in the client code to minimize compile-time dependencies and thus speed up
- compilation.
- </para></listitem>
- </itemizedlist>
- </para>
-
- </sect1>
+ <para>
+ Finally, there are different header include conventions. Again, pick one and stick to it. I personally
+ use indifferently any of the two, depending on the codebase I work on: the rule is consistency.
+ <itemizedlist>
+ <listitem><para>
+ Some people add at the top of their headers a number of #include directives to pull in
+ all the headers needed to compile client code. This allows client code to simply
+ #include "maman-bar.h".
+ </para></listitem>
+ <listitem><para>
+ Other do not #include anything and expect the client to #include themselves the headers
+ they need before including your header. This speeds up compilation because it minimizes the
+ amount of pre-processor work. This can be used in conjunction with the re-declaration of certain
+ unused types in the client code to minimize compile-time dependencies and thus speed up
+ compilation.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ </sect1>
- <sect1 id="howto-gobject-code">
- <title>Boilerplate code</title>
+ <sect1 id="howto-gobject-code">
+ <title>Boilerplate code</title>
- In your code, the first step is to #include the needed headers: depending on your header include strategy, this
- can be as simple as #include "maman-bar.h" or as complicated as tens of #include lines ending with
- #include "maman-bar.h":
+ <para>
+ In your code, the first step is to #include the needed headers: depending on your header include strategy, this
+ can be as simple as #include "maman-bar.h" or as complicated as tens of #include lines ending with
+ #include "maman-bar.h":
<programlisting>
/*
* Copyright information
* forward definitions
*/
</programlisting>
- </para>
+ </para>
- Implement <function>maman_bar_get_type</function> and make sure the code compiles:
+ <para>
+ Implement <function>maman_bar_get_type</function> and make sure the code compiles:
<programlisting>
GType
maman_bar_get_type (void)
return type;
}
</programlisting>
- </para>
- </sect1>
+ </para>
+ </sect1>
- <sect1 id="howto-gobject-construction">
- <title>Object Construction</title>
+ <sect1 id="howto-gobject-construction">
+ <title>Object Construction</title>
- People often get confused when trying to construct their GObjects because of the
- sheer number of different ways to hook into the objects's construction process: it is
- difficult to figure which is the <emphasis>correct</emphasis>, recommended way.
- </para>
+ <para>
+ People often get confused when trying to construct their GObjects because of the
+ sheer number of different ways to hook into the objects's construction process: it is
+ difficult to figure which is the <emphasis>correct</emphasis>, recommended way.
+ </para>
- <xref linkend="gobject-construction-table"/> shows what user-provided functions
- are invoked during object instanciation and in which order they are invoked.
- A user looking for the equivalent of the simple C++ constructor function should use
- the instance_init method. It will be invoked after all the parent's instance_init
- functions have been invoked. It cannot take arbitrary construction parameters
- (as in C++) but if your object needs arbitrary parameters to complete initialization,
- you can use construction properties.
- </para>
+ <para>
+ <xref linkend="gobject-construction-table"/> shows what user-provided functions
+ are invoked during object instanciation and in which order they are invoked.
+ A user looking for the equivalent of the simple C++ constructor function should use
+ the instance_init method. It will be invoked after all the parent's instance_init
+ functions have been invoked. It cannot take arbitrary construction parameters
+ (as in C++) but if your object needs arbitrary parameters to complete initialization,
+ you can use construction properties.
+ </para>
- Construction properties will be set only after all instance_init functions have run.
- No object reference will be returned to the client of <function><link linkend="g-object-new>">g_object_new></link></function>
- until all the construction properties have been set.
- </para>
+ <para>
+ Construction properties will be set only after all instance_init functions have run.
+ No object reference will be returned to the client of <function><link linkend="g-object-new>">g_object_new></link></function>
+ until all the construction properties have been set.
+ </para>
- As such, I would recommend writing the following code first:
+ <para>
+ As such, I would recommend writing the following code first:
<programlisting>
static void
maman_bar_init (GTypeInstance *instance,
*/
}
</programlisting>
- And make sure that you set <function>maman_bar_init</function> as the type's instance_init function
- in <function>maman_bar_get_type</function>. Make sure the code builds and runs: create an instance
- of the object and make sure <function>maman_bar_init</function> is called (add a
- <function><link linkend="g-print">g_print</link></function> call in it).
- </para>
+ And make sure that you set <function>maman_bar_init</function> as the type's instance_init function
+ in <function>maman_bar_get_type</function>. Make sure the code builds and runs: create an instance
+ of the object and make sure <function>maman_bar_init</function> is called (add a
+ <function><link linkend="g-print">g_print</link></function> call in it).
+ </para>
- Now, if you need special construction properties, install the properties in the class_init function,
- override the set and get methods and implement the get and set methods as described in
- <xref linkend="gobject-properties"/>. Make sure that these properties use a construct only
- <type><link linkend="GParamSpec">GParamSpec</link></type> by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps
- GType ensure that these properties are not set again later by malicious user code.
+ <para>
+ Now, if you need special construction properties, install the properties in the class_init function,
+ override the set and get methods and implement the get and set methods as described in
+ <xref linkend="gobject-properties"/>. Make sure that these properties use a construct only
+ <type><link linkend="GParamSpec">GParamSpec</link></type> by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps
+ GType ensure that these properties are not set again later by malicious user code.
<programlisting>
static void
bar_class_init (MamanBarClass *klass)
maman_param_spec);
}
</programlisting>
- If you need this, make sure you can build and run code similar to the code shown above. Make sure
- your construct properties can set correctly during construction, make sure you cannot set them
- afterwards and make sure that if your users do not call <function><link linkend="g-object-new">g_object_new</link></function>
- with the required construction properties, these will be initialized with the default values.
- </para>
+ If you need this, make sure you can build and run code similar to the code shown above. Make sure
+ your construct properties can set correctly during construction, make sure you cannot set them
+ afterwards and make sure that if your users do not call <function><link linkend="g-object-new">g_object_new</link></function>
+ with the required construction properties, these will be initialized with the default values.
+ </para>
- I consider good taste to halt program execution if a construction property is set its
- default value. This allows you to catch client code which does not give a reasonable
- value to the construction properties. Of course, you are free to disagree but you
- should have a good reason to do so.
- </para>
+ <para>
+ I consider good taste to halt program execution if a construction property is set its
+ default value. This allows you to catch client code which does not give a reasonable
+ value to the construction properties. Of course, you are free to disagree but you
+ should have a good reason to do so.
+ </para>
-
<para>Some people sometimes need to construct their object but only after the construction properties
- have been set. This is possible through the use of the constructor class method as described in
- <xref linkend="gobject-instanciation"/>. However, I have yet to see <emphasis>any</emphasis> reasonable
- use of this feature. As such, to initialize your object instances, use by default the base_init function
- and construction properties.
- </para>
- </sect1>
+ <para>Some people sometimes need to construct their object but only after the construction properties
+ have been set. This is possible through the use of the constructor class method as described in
+ <xref linkend="gobject-instanciation"/>. However, I have yet to see <emphasis>any</emphasis> reasonable
+ use of this feature. As such, to initialize your object instances, use by default the base_init function
+ and construction properties.
+ </para>
+ </sect1>
- <sect1 id="howto-gobject-destruction">
- <title>Object Destruction</title>
+ <sect1 id="howto-gobject-destruction">
+ <title>Object Destruction</title>
- Again, it is often difficult to figure out which mechanism to use to hook into the object's
- destruction process: when the last <function><link linkend="g-object-unref">g_object_unref</link></function> function call is made,
- a lot of things happen as described in <xref linkend="gobject-destruction-table"/>.
- </para>
+ <para>
+ Again, it is often difficult to figure out which mechanism to use to hook into the object's
+ destruction process: when the last <function><link linkend="g-object-unref">g_object_unref</link></function> function call is made,
+ a lot of things happen as described in <xref linkend="gobject-destruction-table"/>.
+ </para>
- The destruction process of your object must be split is two different phases: you must override
- both the dispose and the finalize class methods.
+ <para>
+ The destruction process of your object must be split is two different phases: you must override
+ both the dispose and the finalize class methods.
<programlisting>
struct _MamanBarPrivate {
gboolean dispose_has_run;
}
</programlisting>
- </para>
+ </para>
- Add similar code to your GObject, make sure the code still builds and runs: dispose and finalize must be called
- during the last unref.
- It is possible that object methods might be invoked after dispose is run and before finalize runs. GObject
- does not consider this to be a program error: you must gracefully detect this and neither crash nor warn
- the user. To do this, you need something like the following code at the start of each object method, to make
- sure the object's data is still valid before manipulating it:
+ <para>
+ Add similar code to your GObject, make sure the code still builds and runs: dispose and finalize must be called
+ during the last unref.
+ It is possible that object methods might be invoked after dispose is run and before finalize runs. GObject
+ does not consider this to be a program error: you must gracefully detect this and neither crash nor warn
+ the user. To do this, you need something like the following code at the start of each object method, to make
+ sure the object's data is still valid before manipulating it:
<programlisting>
if (self->private->dispose_has_run) {
/* Dispose has run. Data is not valid anymore. */
return;
}
</programlisting>
- </para>
- </sect1>
+ </para>
+ </sect1>
- <sect1 id="howto-gobject-methods">
- <title>Object methods</title>
+ <sect1 id="howto-gobject-methods">
+ <title>Object methods</title>
- Just as with C++, there are many different ways to define object
- methods and extend them: the following list and sections draw on C++ vocabulary.
- (Readers are expected to know basic C++ buzzwords. Those who have not had to
-
write C++ code recently can refer to e.g. <ulink url="http://www.cplusplus.com/doc/tutorial/"/> to refresh their
- memories.)
- <itemizedlist>
- non-virtual public methods,
- </para></listitem>
- virtual public methods and
- </para></listitem>
- virtual private methods
- </para></listitem>
- </itemizedlist>
- </para>
+ <para>
+ Just as with C++, there are many different ways to define object
+ methods and extend them: the following list and sections draw on C++ vocabulary.
+ (Readers are expected to know basic C++ buzzwords. Those who have not had to
+ write C++ code recently can refer to e.g. <ulink url="http://www.cplusplus.com/doc/tutorial/"/> to refresh their
+ memories.)
+ <itemizedlist>
+ <listitem><para>
+ non-virtual public methods,
+ </para></listitem>
+ <listitem><para>
+ virtual public methods and
+ </para></listitem>
+ <listitem><para>
+ virtual private methods
+ </para></listitem>
+ </itemizedlist>
+ </para>
- <sect2>
- <title>Non-virtual public methods</title>
+ <sect2>
+ <title>Non-virtual public methods</title>
- These are the simplest: you want to provide a simple method which can act on your object. All you need
- to do is to provide a function prototype in the header and an implementation of that prototype
- in the source file.
+ <para>
+ These are the simplest: you want to provide a simple method which can act on your object. All you need
+ to do is to provide a function prototype in the header and an implementation of that prototype
+ in the source file.
<programlisting>
/* declaration in the header. */
void maman_bar_do_action (MamanBar *self, /* parameters */);
/* do stuff here. */
}
</programlisting>
- </para>
+ </para>
-
<para>There is really nothing scary about this.</para>
- </sect2>
+ <para>There is really nothing scary about this.</para>
+ </sect2>
- <sect2>
- <title>Virtual public methods</title>
+ <sect2>
+ <title>Virtual public methods</title>
- This is the preferred way to create polymorphic GObjects. All you need to do is to
- define the common method and its class function in the public header, implement the
- common method in the source file and re-implement the class function in each object
- which inherits from you.
+ <para>
+ This is the preferred way to create polymorphic GObjects. All you need to do is to
+ define the common method and its class function in the public header, implement the
+ common method in the source file and re-implement the class function in each object
+ which inherits from you.
<programlisting>
/* declaration in maman-bar.h. */
struct _MamanBarClass {
MAMAN_BAR_GET_CLASS (self)->do_action (self, /* parameters */);
}
</programlisting>
- The code above simply redirects the do_action call to the relevant class function. Some users,
- concerned about performance, do not provide the <function>maman_bar_do_action</function>
- wrapper function and require users to dereference the class pointer themselves. This is not such
- a great idea in terms of encapsulation and makes it difficult to change the object's implementation
- afterwards, should this be needed.
- </para>
+ The code above simply redirects the do_action call to the relevant class function. Some users,
+ concerned about performance, do not provide the <function>maman_bar_do_action</function>
+ wrapper function and require users to dereference the class pointer themselves. This is not such
+ a great idea in terms of encapsulation and makes it difficult to change the object's implementation
+ afterwards, should this be needed.
+ </para>
- Other users, also concerned by performance issues, declare the <function>maman_bar_do_action</function>
- function inline in the header file. This, however, makes it difficult to change the
- object's implementation later (although easier than requiring users to directly dereference the class
- function) and is often difficult to write in a portable way (the <emphasis>inline</emphasis> keyword
- is not part of the C standard).
- </para>
+ <para>
+ Other users, also concerned by performance issues, declare the <function>maman_bar_do_action</function>
+ function inline in the header file. This, however, makes it difficult to change the
+ object's implementation later (although easier than requiring users to directly dereference the class
+ function) and is often difficult to write in a portable way (the <emphasis>inline</emphasis> keyword
+ is not part of the C standard).
+ </para>
- In doubt, unless a user shows you hard numbers about the performance cost of the function call,
- just <function>maman_bar_do_action</function> in the source file.
- </para>
+ <para>
+ In doubt, unless a user shows you hard numbers about the performance cost of the function call,
+ just <function>maman_bar_do_action</function> in the source file.
+ </para>
- Please, note that it is possible for you to provide a default implementation for this class method in
- the object's class_init function: initialize the klass->do_action field to a pointer to the actual
- implementation. You can also make this class method pure virtual by initializing the klass->do_action
- field to NULL:
+ <para>
+ Please, note that it is possible for you to provide a default implementation for this class method in
+ the object's class_init function: initialize the klass->do_action field to a pointer to the actual
+ implementation. You can also make this class method pure virtual by initializing the klass->do_action
+ field to NULL:
<programlisting>
static void
maman_bar_real_do_action_two (MamanBar *self, /* parameters */)
MAMAN_BAR_GET_CLASS (self)->do_action_two (self, /* parameters */);
}
</programlisting>
- </para>
- </sect2>
+ </para>
+ </sect2>
- <sect2>
- <title>Virtual private Methods</title>
+ <sect2>
+ <title>Virtual private Methods</title>
- These are very similar to Virtual Public methods. They just don't have a public function to call the
- function directly. The header file contains only a declaration of the class function:
+ <para>
+ These are very similar to Virtual Public methods. They just don't have a public function to call the
+ function directly. The header file contains only a declaration of the class function:
<programlisting>
/* declaration in maman-bar.h. */
struct _MamanBarClass {
};
void maman_bar_do_any_action (MamanBar *self, /* parameters */);
</programlisting>
- These class functions are often used to delegate part of the job to child classes:
+ These class functions are often used to delegate part of the job to child classes:
<programlisting>
/* this accessor function is static: it is not exported outside of this file. */
static void
/* other random code here */
}
</programlisting>
- </para>
+ </para>
- Again, it is possible to provide a default implementation for this private virtual class function:
+ <para>
+ Again, it is possible to provide a default implementation for this private virtual class function:
<programlisting>
static void
maman_bar_class_init (MamanBarClass *klass)
klass->do_specific_action_two = maman_bar_real_do_specific_action_two;
}
</programlisting>
- </para>
+ </para>
- Children can then implement the subclass with code such as:
+ <para>
+ Children can then implement the subclass with code such as:
<programlisting>
static void
maman_bar_subtype_class_init (MamanBarSubTypeClass *klass)
bar_class->do_specific_action_one = maman_bar_subtype_do_specific_action_one;
}
</programlisting>
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="howto-gobject-chainup">
- <title>Chaining up</title>
-
- <para>Chaining up is often loosely defined by the following set of conditions:
- <itemizedlist>
- <listitem><para>Parent class A defines a public virtual method named <function>foo</function> and
- provides a default implementation.</para></listitem>
- <listitem><para>Child class B re-implements method <function>foo</function>.</para></listitem>
- <listitem><para>In the method B::foo, the child class B calls its parent class method A::foo.</para></listitem>
- </itemizedlist>
- There are many uses to this idiom:
- <itemizedlist>
- <listitem><para>You need to change the behaviour of a class without modifying its code. You create
- a subclass to inherit its implementation, re-implement a public virtual method to modify the behaviour
- slightly and chain up to ensure that the previous behaviour is not really modifed, just extended.
- </para></listitem>
- <listitem><para>You are lazy, you have access to the source code of the parent class but you don't want
- to modify it to add method calls to new specialized method calls: it is faster to hack the child class
- to chain up than to modify the parent to call down.</para></listitem>
- <listitem><para>You need to implement the Chain Of Responsability pattern: each object of the inheritance
- tree chains up to its parent (typically, at the begining or the end of the method) to ensure that
- they each handler is run in turn.</para></listitem>
- </itemizedlist>
- I am personally not really convinced any of the last two uses are really a good idea but since this
- programming idiom is often used, this section attemps to explain how to implement it.
- </para>
+ </para>
+ </sect2>
+ </sect1>
- <para>To explicitely chain up to the implementation of the virtual method in the parent class,
- you first need a handle to the original parent class structure. This pointer can then be used to
- access the original class function pointer and invoke it directly.
- <footnote>
- <para>The <emphasis>original</emphasis> adjective used in this sentence is not innocuous. To fully
- understand its meaning, you need to recall how class structures are initialized: for each object type,
- the class structure associated to this object is created by first copying the class structure of its
- parent type (a simple <function>memcpy</function>) and then by invoking the class_init callback on
- the resulting class structure. Since the class_init callback is responsible for overwriting the class structure
- with the user re-implementations of the class methods, we cannot merely use the modified copy of the parent class
- structure stored in our derived instance. We want to get a copy of the class structure of an instance of the parent
- class.
- </para>
- </footnote>
- </para>
+ <sect1 id="howto-gobject-chainup">
+ <title>Chaining up</title>
+
+ <para>Chaining up is often loosely defined by the following set of conditions:
+ <itemizedlist>
+ <listitem><para>Parent class A defines a public virtual method named <function>foo</function> and
+ provides a default implementation.</para></listitem>
+ <listitem><para>Child class B re-implements method <function>foo</function>.</para></listitem>
+ <listitem><para>In the method B::foo, the child class B calls its parent class method A::foo.</para></listitem>
+ </itemizedlist>
+ There are many uses to this idiom:
+ <itemizedlist>
+ <listitem><para>You need to change the behaviour of a class without modifying its code. You create
+ a subclass to inherit its implementation, re-implement a public virtual method to modify the behaviour
+ slightly and chain up to ensure that the previous behaviour is not really modifed, just extended.
+ </para></listitem>
+ <listitem><para>You are lazy, you have access to the source code of the parent class but you don't want
+ to modify it to add method calls to new specialized method calls: it is faster to hack the child class
+ to chain up than to modify the parent to call down.</para></listitem>
+ <listitem><para>You need to implement the Chain Of Responsability pattern: each object of the inheritance
+ tree chains up to its parent (typically, at the begining or the end of the method) to ensure that
+ they each handler is run in turn.</para></listitem>
+ </itemizedlist>
+ I am personally not really convinced any of the last two uses are really a good idea but since this
+ programming idiom is often used, this section attemps to explain how to implement it.
+ </para>
- <para>The function <function><link linkend="g-type-class-peek-parent">g_type_class_peek_parent</link></function> is used to access the original parent
- class structure. Its input is a pointer to the class of the derived object and it returns a pointer
- to the original parent class structure. The code below shows how you could use it:
+ <para>
+ To explicitely chain up to the implementation of the virtual method in the parent class,
+ you first need a handle to the original parent class structure. This pointer can then be used to
+ access the original class function pointer and invoke it directly.
+ <footnote>
+ <para>
+ The <emphasis>original</emphasis> adjective used in this sentence is not innocuous. To fully
+ understand its meaning, you need to recall how class structures are initialized: for each object type,
+ the class structure associated to this object is created by first copying the class structure of its
+ parent type (a simple <function>memcpy</function>) and then by invoking the class_init callback on
+ the resulting class structure. Since the class_init callback is responsible for overwriting the class structure
+ with the user re-implementations of the class methods, we cannot merely use the modified copy of the parent class
+ structure stored in our derived instance. We want to get a copy of the class structure of an instance of the parent
+ class.
+ </para>
+ </footnote>
+ </para>
+
+ <para>The function <function><link linkend="g-type-class-peek-parent">g_type_class_peek_parent</link></function> is used to access the original parent
+ class structure. Its input is a pointer to the class of the derived object and it returns a pointer
+ to the original parent class structure. The code below shows how you could use it:
<programlisting>
static void
b_method_to_call (B *obj, int a)
/* do stuff after chain up */
}
</programlisting>
- A lot of people who use this idiom in GTK+ store the parent class structure pointer in a global static
- variable to avoid the costly call to <function><link linkend="g-type-class-peek-parent">g_type_class_peek_parent</link></function> for each function call.
- Typically, the class_init callback initializes the global static variable. <filename>gtk/gtkhscale.c</filename>
- does this.
- </para>
-
- </sect1>
-
- </chapter>
+ A lot of people who use this idiom in GTK+ store the parent class structure pointer in a global static
+ variable to avoid the costly call to <function><link linkend="g-type-class-peek-parent">g_type_class_peek_parent</link></function> for each function call.
+ Typically, the class_init callback initializes the global static variable. <filename>gtk/gtkhscale.c</filename>
+ does this.
+ </para>
-<!--
- End Howto GObject
--->
+ </sect1>
+</chapter>
+<!-- End Howto GObject -->
-<!--
- Howto Interfaces
--->
- <chapter id="howto-interface">
- <title>How To define and implement Interfaces?</title>
+<chapter id="howto-interface">
+ <title>How To define and implement Interfaces?</title>
- <sect1 id="howto-interface-define">
- <title>How To define Interfaces?</title>
-
- The bulk of interface definition has already been shown in <xref linkend="gtype-non-instantiable-classed"/>
- but I feel it is needed to show exactly how to create an interface. The sample source code
- associated to this section can be found in the documentation's source tarball, in the
- <filename>sample/interface/maman-ibaz.{h|c}</filename> file.
- </para>
+ <sect1 id="howto-interface-define">
+ <title>How To define Interfaces?</title>
+
+ <para>
+ The bulk of interface definition has already been shown in <xref linkend="gtype-non-instantiable-classed"/>
+ but I feel it is needed to show exactly how to create an interface. The sample source code
+ associated to this section can be found in the documentation's source tarball, in the
+ <filename>sample/interface/maman-ibaz.{h|c}</filename> file.
+ </para>
- As above, the first step is to get the header right:
+ <para>
+ As above, the first step is to get the header right:
<programlisting>
#ifndef MAMAN_IBAZ_H
#define MAMAN_IBAZ_H
#endif /*MAMAN_IBAZ_H*/
</programlisting>
- This code is the same as the code for a normal <type><link linkend="GType">GType</link></type>
- which derives from a <type><link linkend="GObject">GObject</link></type> except for a few details:
- <itemizedlist>
- The <function>_GET_CLASS</function> macro is called <function>_GET_INTERFACE</function>
- and not implemented with <function><link linkend="G_TYPE_INSTANCE_GET_CLASS">G_TYPE_INSTANCE_GET_CLASS</link></function>
- but with <function><link linkend="G_TYPE_INSTANCE_GET_INTERFACE">G_TYPE_INSTANCE_GET_INTERFACE</link></function>.
- </para></listitem>
- The instance type, <type>MamanIbaz</type> is not fully defined: it is used merely as an abstract
- type which represents an instance of whatever object which implements the interface.
- </para></listitem>
- </itemizedlist>
- </para>
+ This code is the same as the code for a normal <type><link linkend="GType">GType</link></type>
+ which derives from a <type><link linkend="GObject">GObject</link></type> except for a few details:
+ <itemizedlist>
+ <listitem><para>
+ The <function>_GET_CLASS</function> macro is called <function>_GET_INTERFACE</function>
+ and not implemented with <function><link linkend="G_TYPE_INSTANCE_GET_CLASS">G_TYPE_INSTANCE_GET_CLASS</link></function>
+ but with <function><link linkend="G_TYPE_INSTANCE_GET_INTERFACE">G_TYPE_INSTANCE_GET_INTERFACE</link></function>.
+ </para></listitem>
+ <listitem><para>
+ The instance type, <type>MamanIbaz</type> is not fully defined: it is used merely as an abstract
+ type which represents an instance of whatever object which implements the interface.
+ </para></listitem>
+ </itemizedlist>
+ </para>
- The implementation of the <type>MamanIbaz</type> type itself is trivial:
- <itemizedlist>
-
<listitem><para><function>maman_ibaz_get_type</function> registers the
- type in the type system.
- </para></listitem>
-
<listitem><para><function>maman_ibaz_base_init</function> is expected
- to register the interface's signals if there are any (we will see a bit
- (later how to use them). Make sure to use a static local boolean variable
- to make sure not to run the initialization code twice (as described in
- <xref linkend="gtype-non-instantiable-classed-init"/>,
- <function>base_init</function> is run once for each interface implementation
- instanciation)</para></listitem>
-
<listitem><para><function>maman_ibaz_do_action</function> dereferences the class
- structure to access its associated class function and calls it.
- </para></listitem>
- </itemizedlist>
+ <para>
+ The implementation of the <type>MamanIbaz</type> type itself is trivial:
+ <itemizedlist>
+ <listitem><para><function>maman_ibaz_get_type</function> registers the
+ type in the type system.
+ </para></listitem>
+ <listitem><para><function>maman_ibaz_base_init</function> is expected
+ to register the interface's signals if there are any (we will see a bit
+ (later how to use them). Make sure to use a static local boolean variable
+ to make sure not to run the initialization code twice (as described in
+ <xref linkend="gtype-non-instantiable-classed-init"/>,
+ <function>base_init</function> is run once for each interface implementation
+ instanciation)</para></listitem>
+ <listitem><para><function>maman_ibaz_do_action</function> dereferences the class
+ structure to access its associated class function and calls it.
+ </para></listitem>
+ </itemizedlist>
<programlisting>
static void
maman_ibaz_base_init (gpointer g_class)
</programlisting>
</para>
</sect1>
-
+
<sect1 id="howto-interface-implement">
<title>How To define implement an Interface?</title>
-
+
<para>
Once the interface is defined, implementing it is rather trivial. Source code showing how to do this
for the <type>IBaz</type> interface defined in the previous section is located in
<filename>sample/interface/maman-baz.{h|c}</filename>.
</para>
-
+
<para>
The first step is to define a normal GType. Here, we have decided to use a GType which derives from
GObject. Its name is <type>MamanBaz</type>:
There is clearly nothing specifically weird or scary about this header: it does not define any weird API
or derives from a weird type.
</para>
-
+
<para>
The second step is to implement <function>maman_baz_get_type</function>:
<programlisting>
the type system that this just-registered <type><link linkend="GType">GType</link></type> also implements the interface
<function>MAMAN_TYPE_IBAZ</function>.
</para>
-
+
<para>
<function>baz_interface_init</function>, the interface initialization function, is also pretty simple:
<programlisting>
defined by <type>MamanBaz</type>: <function>maman_baz_do_action</function> does nothing very useful
but it could :)
</para>
-
-</sect1>
-
-<sect1>
- <title>Interface definition prerequisites</title>
-
- <para>To specify that an interface requires the presence of other interfaces when implemented,
- GObject introduces the concept of <emphasis>prerequisites</emphasis>: it is possible to associate
- a list of prerequisite interfaces to an interface. For example, if object A wishes to implement interface
- I1, and if interface I1 has a prerequisite on interface I2, A has to implement both I1 and I2.
- </para>
-
- <para>The mechanism described above is, in practice, very similar to Java's interface I1 extends
- interface I2. The example below shows the GObject equivalent:
-
+
+ </sect1>
+
+ <sect1>
+ <title>Interface definition prerequisites</title>
+
+ <para>
+ To specify that an interface requires the presence of other interfaces when implemented,
+ GObject introduces the concept of <emphasis>prerequisites</emphasis>: it is possible to associate
+ a list of prerequisite interfaces to an interface. For example, if object A wishes to implement interface
+ I1, and if interface I1 has a prerequisite on interface I2, A has to implement both I1 and I2.
+ </para>
+
+ <para>
+ The mechanism described above is, in practice, very similar to Java's interface I1 extends
+ interface I2. The example below shows the GObject equivalent:
+
<programlisting>
type = g_type_register_static (G_TYPE_INTERFACE, "MamanIbar", &info, 0);
/* Make the MamanIbar interface require MamanIbaz interface. */
g_type_interface_add_prerequisite (type, MAMAN_TYPE_IBAZ);
</programlisting>
- The code shown above adds the MamanIbaz interface to the list of prerequisites of MamanIbar while the
- code below shows how an implementation can implement both interfaces and register their implementations:
+ The code shown above adds the MamanIbaz interface to the list of prerequisites of MamanIbar while the
+ code below shows how an implementation can implement both interfaces and register their implementations:
<programlisting>
static void ibar_do_another_action (MamanBar *self)
{
iface->do_action = (void (*) (MamanIbaz *self))ibaz_do_action;
}
-
static void
bar_instance_init (GTypeInstance *instance,
gpointer g_class)
self->instance_member = 0x666;
}
-
GType
maman_bar_get_type (void)
{
return type;
}
</programlisting>
- It is very important to notice that the order in which interface implementations are added to the main object
- is not random: <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function> must be invoked first on the interfaces which have
- no prerequisites and then on the others.
-</para>
-
- <para>
- Complete source code showing how to define the MamanIbar interface which requires MamanIbaz and how to
- implement the MamanIbar interface is located in <filename>sample/interface/maman-ibar.{h|c}</filename>
- and <filename>sample/interface/maman-bar.{h|c}</filename>.
- </para>
-
-</sect1>
-
-<sect1 id="howto-interface-properties">
- <title>Interface Properties</title>
-
- <para>Starting from version 2.4 of glib, GObject interfaces can also have properties.
- Declaration of the interface properties is similar to declaring the properties of
- ordinary GObject types as explained in <xref linkend="gobject-properties"/>,
- except that <function><link linkend="g-object-interface-install-property">g_object_interface_install_property</link></function> is used to
- declare the properties instead of <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
- </para>
-
- <para>To include a property named 'name' of type <type>string</type> in the
- <type>maman_ibaz</type> interface example code above, we only need to add one
- <footnote>
- <para>
- That really is one line extended to six for the sake of clarity
- </para>
- </footnote>
- line in the <function>maman_ibaz_base_init</function>
- <footnote>
- <para>
- The <function><link linkend="g-object-interface-install-property">g_object_interface_install_property</link></function> can also be called from
- <function>class_init</function> but it must not be called after that point.
- </para>
- </footnote>
- as shown below:
+ It is very important to notice that the order in which interface implementations are added to the main object
+ is not random: <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function> must be invoked first on the interfaces which have
+ no prerequisites and then on the others.
+ </para>
+
+ <para>
+ Complete source code showing how to define the MamanIbar interface which requires MamanIbaz and how to
+ implement the MamanIbar interface is located in <filename>sample/interface/maman-ibar.{h|c}</filename>
+ and <filename>sample/interface/maman-bar.{h|c}</filename>.
+ </para>
+
+ </sect1>
+
+ <sect1 id="howto-interface-properties">
+ <title>Interface Properties</title>
+
+ <para>
+ Starting from version 2.4 of glib, GObject interfaces can also have properties.
+ Declaration of the interface properties is similar to declaring the properties of
+ ordinary GObject types as explained in <xref linkend="gobject-properties"/>,
+ except that <function><link linkend="g-object-interface-install-property">g_object_interface_install_property</link></function> is used to
+ declare the properties instead of <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
+ </para>
+
+ <para>
+ To include a property named 'name' of type <type>string</type> in the
+ <type>maman_ibaz</type> interface example code above, we only need to add one
+ <footnote>
+ <para>
+ That really is one line extended to six for the sake of clarity
+ </para>
+ </footnote>
+ line in the <function>maman_ibaz_base_init</function>
+ <footnote>
+ <para>
+ The <function><link linkend="g-object-interface-install-property">g_object_interface_install_property</link></function> can also be called from
+ <function>class_init</function> but it must not be called after that point.
+ </para>
+ </footnote>
+ as shown below:
<programlisting>
static void
maman_ibaz_base_init (gpointer g_iface)
/* create interface signals here. */
g_object_interface_install_property (g_iface,
- g_param_spec_string ("name",
- "maman_ibaz_name",
- "Name of the MamanIbaz",
- "maman",
- G_PARAM_READWRITE));
+ g_param_spec_string ("name",
+ "maman_ibaz_name",
+ "Name of the MamanIbaz",
+ "maman",
+ G_PARAM_READWRITE));
initialized = TRUE;
}
}
</programlisting>
- </para>
-
- <para>One point worth noting is that the declared property wasn't assigned an
- integer ID. The reason being that integer IDs of properities are utilized only
- inside the get and set methods and since interfaces do not implement properties,
- there is no need to assign integer IDs to interface properties.
- </para>
+ </para>
- <para>The story for the implementers of the interface is also quite trivial.
- An implementer shall declare and define it's properties in the usual way as
- explained in <xref linkend="gobject-properties"/>, except for one small
- change: it shall declare the properties of the interface it implements using
- <function><link linkend="g-object-class-override-property">g_object_class_override_property</link></function> instead of
- <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>. The following code snipet
- shows the modifications needed in the <type>MamanBaz</type> declaration and
- implementation above:
+ <para>
+ One point worth noting is that the declared property wasn't assigned an
+ integer ID. The reason being that integer IDs of properities are utilized only
+ inside the get and set methods and since interfaces do not implement properties,
+ there is no need to assign integer IDs to interface properties.
+ </para>
+
+ <para>
+ The story for the implementers of the interface is also quite trivial.
+ An implementer shall declare and define it's properties in the usual way as
+ explained in <xref linkend="gobject-properties"/>, except for one small
+ change: it shall declare the properties of the interface it implements using
+ <function><link linkend="g-object-class-override-property">g_object_class_override_property</link></function> instead of
+ <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>. The following code snipet
+ shows the modifications needed in the <type>MamanBaz</type> declaration and
+ implementation above:
<programlisting>
struct _MamanBaz {
GObject parent;
gint instance_member;
- gchar *name; /* placeholder for property */
+ gchar *name; /* placeholder for property */
};
enum
}
</programlisting>
- </para>
-
-</sect1>
-
-
+ </para>
+
+ </sect1>
</chapter>
+<!-- End Howto Interfaces -->
-<!--
- End Howto Interfaces
--->
-
-
-<!--
- start Howto Signals
--->
-
-
- <chapter id="howto-signals">
- <title>Howto create and use signals</title>
+<chapter id="howto-signals">
+ <title>Howto create and use signals</title>
- <para>
- The signal system which was built in GType is pretty complex and flexible: it is possible for its users
- to connect at runtime any number of callbacks (implemented in any language for which a binding exists)
- <footnote>
- <para>A python callback can be connected to any signal on any C-based GObject.
- </para>
- </footnote>
-
- to any signal and to stop the emission of any signal at any
- state of the signal emission process. This flexibility makes it possible to use GSignal for much more than
- just emit events which can be received by numerous clients.
+ <para>
+ The signal system which was built in GType is pretty complex and flexible: it is possible for its users
+ to connect at runtime any number of callbacks (implemented in any language for which a binding exists)
+ <footnote>
+ <para>A python callback can be connected to any signal on any C-based GObject.
</para>
+ </footnote>
-<sect1 id="howto-simple-signals">
-<title>Simple use of signals</title>
+ to any signal and to stop the emission of any signal at any
+ state of the signal emission process. This flexibility makes it possible to use GSignal for much more than
+ just emit events which can be received by numerous clients.
+ </para>
+
+ <sect1 id="howto-simple-signals">
+ <title>Simple use of signals</title>
-<para>The most basic use of signals is to implement simple event notification: for example, if we have a
-MamanFile object, and if this object has a write method, we might wish to be notified whenever someone
-uses this method. The code below shows how the user can connect a callback to the write signal. Full code
-for this simple example is located in <filename>sample/signal/maman-file.{h|c}</filename> and
-in <filename>sample/signal/test.c</filename>
+ <para>
+ The most basic use of signals is to implement simple event notification: for example, if we have a
+ MamanFile object, and if this object has a write method, we might wish to be notified whenever someone
+ uses this method. The code below shows how the user can connect a callback to the write signal. Full code
+ for this simple example is located in <filename>sample/signal/maman-file.{h|c}</filename> and
+ in <filename>sample/signal/test.c</filename>
<programlisting>
file = g_object_new (MAMAN_FILE_TYPE, NULL);
maman_file_write (file, buffer, 50);
</programlisting>
-</para>
-
-<para>
-The <type>MamanFile</type> signal is registered in the class_init function:
+ </para>
+
+ The <type>MamanFile</type> signal is registered in the class_init function:
<programlisting>
klass->write_signal_id =
g_signal_newv ("write",
0 /* n_params */,
NULL /* param_types */);
</programlisting>
-and the signal is emited in <function>maman_file_write</function>:
+ and the signal is emited in <function>maman_file_write</function>:
<programlisting>
void maman_file_write (MamanFile *self, guint8 *buffer, guint32 size)
{
NULL);
}
</programlisting>
-As shown above, you can safely set the details parameter to zero if you do not know what it can be used for.
-For a discussion of what you could used it for, see <xref linkend="signal-detail"/>
-</para>
-
- <para>
-The signature of the signal handler in the above example is defined as
-<function>g_cclosure_marshal_VOID__VOID</function>. Its name follows
-a simple convention which encodes the function parameter and return value
-types in the function name. Specifically, the value infront of the double
-underscore is the type of the return value, while the value(s) after the
-double underscore denote the parameter types.
-The header <filename>gobject/gmarshal.h</filename> defines a set of commonly
-needed closures that one can use.
- </para>
-
-</sect1>
-
-
-<sect1>
-<title>How to provide more flexibility to users?</title>
-
-<para>The previous implementation does the job but the signal facility of GObject can be used to provide
-even more flexibility to this file change notification mechanism. One of the key ideas is to make the process
-of writing data to the file part of the signal emission process to allow users to be notified either
-before or after the data is written to the file.
-</para>
-
-<para>To integrate the process of writing the data to the file into the signal emission mechanism, we can
-register a default class closure for this signal which will be invoked during the signal emission, just like
-any other user-connected signal handler.
-</para>
-
-<para>The first step to implement this idea is to change the signature of the signal: we need to pass
-around the buffer to write and its size. To do this, we use our own marshaller which will be generated
-through glib's genmarshall tool. We thus create a file named <filename>marshall.list</filename> which contains
-the following single line:
+ As shown above, you can safely set the details parameter to zero if you do not know what it can be used for.
+ For a discussion of what you could used it for, see <xref linkend="signal-detail"/>
+ </para>
+
+ <para>
+ The signature of the signal handler in the above example is defined as
+ <function>g_cclosure_marshal_VOID__VOID</function>. Its name follows
+ a simple convention which encodes the function parameter and return value
+ types in the function name. Specifically, the value infront of the double
+ underscore is the type of the return value, while the value(s) after the
+ double underscore denote the parameter types.
+ The header <filename>gobject/gmarshal.h</filename> defines a set of commonly
+ needed closures that one can use.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>How to provide more flexibility to users?</title>
+
+ <para>
+ The previous implementation does the job but the signal facility of GObject can be used to provide
+ even more flexibility to this file change notification mechanism. One of the key ideas is to make the process
+ of writing data to the file part of the signal emission process to allow users to be notified either
+ before or after the data is written to the file.
+ </para>
+
+ <para>
+ To integrate the process of writing the data to the file into the signal emission mechanism, we can
+ register a default class closure for this signal which will be invoked during the signal emission, just like
+ any other user-connected signal handler.
+ </para>
+
+ <para>
+ The first step to implement this idea is to change the signature of the signal: we need to pass
+ around the buffer to write and its size. To do this, we use our own marshaller which will be generated
+ through glib's genmarshall tool. We thus create a file named <filename>marshall.list</filename> which contains
+ the following single line:
<programlisting>
VOID:POINTER,UINT
</programlisting>
-and use the Makefile provided in <filename>sample/signal/Makefile</filename> to generate the file named
-<filename>maman-file-complex-marshall.c</filename>. This C file is finally included in
-<filename>maman-file-complex.c</filename>.
-</para>
-
-<para>Once the marshaller is present, we register the signal and its marshaller in the class_init function
-of the object <type>MamanFileComplex</type> (full source for this object is included in
-<filename>sample/signal/maman-file-complex.{h|c}</filename>):
+ and use the Makefile provided in <filename>sample/signal/Makefile</filename> to generate the file named
+ <filename>maman-file-complex-marshall.c</filename>. This C file is finally included in
+ <filename>maman-file-complex.c</filename>.
+ </para>
+
+ <para>
+ Once the marshaller is present, we register the signal and its marshaller in the class_init function
+ of the object <type>MamanFileComplex</type> (full source for this object is included in
+ <filename>sample/signal/maman-file-complex.{h|c}</filename>):
<programlisting>
GClosure *default_closure;
GType param_types[2];
2 /* n_params */,
param_types /* param_types */);
</programlisting>
-The code shown above first creates the closure which contains the code to complete the file write. This
-closure is registered as the default class_closure of the newly created signal.
-</para>
+ The code shown above first creates the closure which contains the code to complete the file write. This
+ closure is registered as the default class_closure of the newly created signal.
+ </para>
-<para>
-Of course, you need to implement completely the code for the default closure since I just provided
-a skeleton:
+ Of course, you need to implement completely the code for the default closure since I just provided
+ a skeleton:
<programlisting>
static void
default_write_signal_handler (GObject *obj, guint8 *buffer, guint size, gpointer user_data)
g_print ("default signal handler: 0x%x %u\n", buffer, size);
}
</programlisting>
-</para>
+ </para>
-<para>Finally, the client code must invoke the <function>maman_file_complex_write</function> function which
-triggers the signal emission:
+ <para>
+ Finally, the client code must invoke the <function>maman_file_complex_write</function> function which
+ triggers the signal emission:
<programlisting>
void maman_file_complex_write (MamanFileComplex *self, guint8 *buffer, guint size)
{
buffer, size);
}
</programlisting>
-</para>
-
-<para>The client code (as shown in <filename>sample/signal/test.c</filename> and below) can now connect signal handlers before
-and after the file write is completed: since the default signal handler which does the write itself runs during the
-RUN_LAST phase of the signal emission, it will run after all handlers connected with <function><link linkend="g-signal-connect">g_signal_connect</link></function>
-and before all handlers connected with <function><link linkend="g-signal-connect-after">g_signal_connect_after</link></function>. If you intent to write a GObject
-which emits signals, I would thus urge you to create all your signals with the G_SIGNAL_RUN_LAST such that your users
-have a maximum of flexibility as to when to get the event. Here, we combined it with G_SIGNAL_NO_RECURSE and
-G_SIGNAL_NO_HOOKS to ensure our users will not try to do really weird things with our GObject. I strongly advise you
-to do the same unless you really know why (in which case you really know the inner workings of GSignal by heart and
-you are not reading this).
-</para>
-
-<para>
+ </para>
+
+ <para>
+ The client code (as shown in <filename>sample/signal/test.c</filename> and below) can now connect signal handlers before
+ and after the file write is completed: since the default signal handler which does the write itself runs during the
+ RUN_LAST phase of the signal emission, it will run after all handlers connected with <function><link linkend="g-signal-connect">g_signal_connect</link></function>
+ and before all handlers connected with <function><link linkend="g-signal-connect-after">g_signal_connect_after</link></function>. If you intent to write a GObject
+ which emits signals, I would thus urge you to create all your signals with the G_SIGNAL_RUN_LAST such that your users
+ have a maximum of flexibility as to when to get the event. Here, we combined it with G_SIGNAL_NO_RECURSE and
+ G_SIGNAL_NO_HOOKS to ensure our users will not try to do really weird things with our GObject. I strongly advise you
+ to do the same unless you really know why (in which case you really know the inner workings of GSignal by heart and
+ you are not reading this).
+ </para>
+
+ <para>
<programlisting>
static void complex_write_event_before (GObject *file, guint8 *buffer, guint size, gpointer user_data)
{
g_object_unref (G_OBJECT (file));
}
</programlisting>
-The code above generates the following output on my machine:
+ The code above generates the following output on my machine:
<programlisting>
Complex Write event before: 0xbfffe280, 50
default signal handler: 0xbfffe280 50
Complex Write event after: 0xbfffe280, 50
</programlisting>
-</para>
-
-
- <sect2>
- <title>How most people do the same thing with less code</title>
-
-
<para>For many historic reasons related to how the ancestor of GObject used to work in GTK+ 1.x versions,
- there is a much <emphasis>simpler</emphasis>
- <footnote>
-
<para>I personally think that this method is horribly mind-twisting: it adds a new indirection
- which unecessarily complicates the overall code path. However, because this method is widely used
- by all of GTK+ and GObject code, readers need to understand it. The reason why this is done that way
- in most of GTK+ is related to the fact that the ancestor of GObject did not provide any other way to
- create a signal with a default handler than this one. Some people have tried to justify that it is done
- that way because it is better, faster (I am extremly doubtfull about the faster bit. As a matter of fact,
- the better bit also mystifies me ;-). I have the feeling no one really knows and everyone does it
- because they copy/pasted code from code which did the same. It is probably better to leave this
- specific trivia to hacker legends domain...
- </para>
- </footnote>
- way to create a signal with a default handler than to create
- a closure by hand and to use the <function><link linkend="g-signal-newv">g_signal_newv</link></function>.
- </para>
-
-
<para>For example, <function><link linkend="g-signal-new">g_signal_new</link></function> can be used to create a signal which uses a default
- handler which is stored in the class structure of the object. More specifically, the class structure
- contains a function pointer which is accessed during signal emission to invoke the default handler and
- the user is expected to provide to <function><link linkend="g-signal-new">g_signal_new</link></function> the offset from the start of the
- class structure to the function pointer.
- <footnote>
-
<para>I would like to point out here that the reason why the default handler of a signal is named everywhere
- a class_closure is probably related to the fact that it used to be really a function pointer stored in
- the class structure.
- </para>
- </footnote>
- </para>
-
-
<para>The following code shows the declaration of the <type>MamanFileSimple</type> class structure which contains
- the <function>write</function> function pointer.
+ </para>
+
+
+ <sect2>
+ <title>How most people do the same thing with less code</title>
+
+ <para>For many historic reasons related to how the ancestor of GObject used to work in GTK+ 1.x versions,
+ there is a much <emphasis>simpler</emphasis>
+ <footnote>
+ <para>I personally think that this method is horribly mind-twisting: it adds a new indirection
+ which unecessarily complicates the overall code path. However, because this method is widely used
+ by all of GTK+ and GObject code, readers need to understand it. The reason why this is done that way
+ in most of GTK+ is related to the fact that the ancestor of GObject did not provide any other way to
+ create a signal with a default handler than this one. Some people have tried to justify that it is done
+ that way because it is better, faster (I am extremly doubtfull about the faster bit. As a matter of fact,
+ the better bit also mystifies me ;-). I have the feeling no one really knows and everyone does it
+ because they copy/pasted code from code which did the same. It is probably better to leave this
+ specific trivia to hacker legends domain...
+ </para>
+ </footnote>
+ way to create a signal with a default handler than to create
+ a closure by hand and to use the <function><link linkend="g-signal-newv">g_signal_newv</link></function>.
+ </para>
+
+ <para>For example, <function><link linkend="g-signal-new">g_signal_new</link></function> can be used to create a signal which uses a default
+ handler which is stored in the class structure of the object. More specifically, the class structure
+ contains a function pointer which is accessed during signal emission to invoke the default handler and
+ the user is expected to provide to <function><link linkend="g-signal-new">g_signal_new</link></function> the offset from the start of the
+ class structure to the function pointer.
+ <footnote>
+ <para>I would like to point out here that the reason why the default handler of a signal is named everywhere
+ a class_closure is probably related to the fact that it used to be really a function pointer stored in
+ the class structure.
+ </para>
+ </footnote>
+ </para>
+
+ <para>The following code shows the declaration of the <type>MamanFileSimple</type> class structure which contains
+ the <function>write</function> function pointer.
<programlisting>
struct _MamanFileSimpleClass {
GObjectClass parent;
void (*write) (MamanFileSimple *self, guint8 *buffer, guint size);
};
</programlisting>
- The <function>write</function> function pointer is initialied in the class_init function of the object
- to <function>default_write_signal_handler</function>:
+ The <function>write</function> function pointer is initialied in the class_init function of the object
+ to <function>default_write_signal_handler</function>:
<programlisting>
static void
maman_file_simple_class_init (gpointer g_class,
Of note, here, is the 4th argument to the function: it is an integer calculated by the <function><link linkend="G-STRUCT-OFFSET">G_STRUCT_OFFSET</link></function>
macro which indicates the offset of the member <emphasis>write</emphasis> from the start of the
<type>MamanFileSimpleClass</type> class structure.
- <footnote>
- <para>GSignal uses this offset to create a special wrapper closure
- which first retrieves the target function pointer before calling it.
- </para>
- </footnote>
- </para>
-
- <para>
- While the complete code for this type of default handler looks less clutered as shown in
- <filename>sample/signal/maman-file-simple.{h|c}</filename>, it contains numerous subtleties.
- The main subtle point which everyone must be aware of is that the signature of the default
- handler created that way does not have a user_data argument:
- <function>default_write_signal_handler</function> is different in
- <filename>sample/signal/maman-file-complex.c</filename> and in
- <filename>sample/signal/maman-file-simple.c</filename>.
- </para>
-
- <para>If you have doubts about which method to use, I would advise you to use the second one which
- involves <function><link linkend="g-signal-new">g_signal_new</link></function> rather than <function><link linkend="g-signal-newv">g_signal_newv</link></function>:
- it is better to write code which looks like the vast majority of other GTK+/GObject code than to
- do it your own way. However, now, you know why.
- </para>
-
- </sect2>
-
-
-</sect1>
-
-
-
-<sect1>
- <title>How users can abuse signals (and why some think it is good)</title>
+ <footnote>
+ <para>GSignal uses this offset to create a special wrapper closure
+ which first retrieves the target function pointer before calling it.
+ </para>
+ </footnote>
+ </para>
- <para>Now that you know how to create signals to which the users can connect easily and at any point in
- the signal emission process thanks to <function><link linkend="g-signal-connect">g_signal_connect</link></function>,
- <function><link linkend="g-signal-connect-after">g_signal_connect_after</link></function> and G_SIGNAL_RUN_LAST, it is time to look into how your
- users can and will screw you. This is also interesting to know how you too, can screw other people.
- This will make you feel good and eleet.
- </para>
+ <para>
+ While the complete code for this type of default handler looks less clutered as shown in
+ <filename>sample/signal/maman-file-simple.{h|c}</filename>, it contains numerous subtleties.
+ The main subtle point which everyone must be aware of is that the signature of the default
+ handler created that way does not have a user_data argument:
+ <function>default_write_signal_handler</function> is different in
+ <filename>sample/signal/maman-file-complex.c</filename> and in
+ <filename>sample/signal/maman-file-simple.c</filename>.
+ </para>
- <para>The users can:
- <itemizedlist>
- <listitem><para>stop the emission of the signal at anytime</para></listitem>
- <listitem><para>override the default handler of the signal if it is stored as a function
- pointer in the class structure (which is the prefered way to create a default signal handler,
- as discussed in the previous section).</para></listitem>
- </itemizedlist>
- </para>
+ <para>If you have doubts about which method to use, I would advise you to use the second one which
+ involves <function><link linkend="g-signal-new">g_signal_new</link></function> rather than <function><link linkend="g-signal-newv">g_signal_newv</link></function>:
+ it is better to write code which looks like the vast majority of other GTK+/GObject code than to
+ do it your own way. However, now, you know why.
+ </para>
- <para>In both cases, the original programmer should be as careful as possible to write code which is
- resistant to the fact that the default handler of the signal might not able to run. This is obviously
- not the case in the example used in the previous sections since the write to the file depends on whether
- or not the default handler runs (however, this might be your goal: to allow the user to prevent the file
- write if he wishes to).
- </para>
+ </sect2>
- <para>If all you want to do is to stop the signal emission from one of the callbacks you connected yourself,
- you can call <function><link linkend="g-signal-stop-by-name">g_signal_stop_by_name</link></function>. Its use is very simple which is why I won't detail
- it further.
- </para>
+ </sect1>
- <para>If the signal's default handler is just a class function pointer, it is also possible to override
- it yourself from the class_init function of a type which derives from the parent. That way, when the signal
- is emitted, the parent class will use the function provided by the child as a signal default handler.
- Of course, it is also possible (and recommended) to chain up from the child to the parent's default signal
- handler to ensure the integrity of the parent object.
- </para>
- <para>Overriding a class method and chaining up was demonstrated in <xref linkend="howto-gobject-methods"/>
- which is why I won't bother to show exactly how to do it here again.</para>
+ <sect1>
+ <title>How users can abuse signals (and why some think it is good)</title>
+ <para>Now that you know how to create signals to which the users can connect easily and at any point in
+ the signal emission process thanks to <function><link linkend="g-signal-connect">g_signal_connect</link></function>,
+ <function><link linkend="g-signal-connect-after">g_signal_connect_after</link></function> and G_SIGNAL_RUN_LAST, it is time to look into how your
+ users can and will screw you. This is also interesting to know how you too, can screw other people.
+ This will make you feel good and eleet.
+ </para>
+
+ <para>
+ The users can:
+ <itemizedlist>
+ <listitem><para>stop the emission of the signal at anytime</para></listitem>
+ <listitem><para>override the default handler of the signal if it is stored as a function
+ pointer in the class structure (which is the prefered way to create a default signal handler,
+ as discussed in the previous section).</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ In both cases, the original programmer should be as careful as possible to write code which is
+ resistant to the fact that the default handler of the signal might not able to run. This is obviously
+ not the case in the example used in the previous sections since the write to the file depends on whether
+ or not the default handler runs (however, this might be your goal: to allow the user to prevent the file
+ write if he wishes to).
+ </para>
+
+ <para>
+ If all you want to do is to stop the signal emission from one of the callbacks you connected yourself,
+ you can call <function><link linkend="g-signal-stop-by-name">g_signal_stop_by_name</link></function>. Its use is very simple which is why I won't detail
+ it further.
+ </para>
+
+ <para>
+ If the signal's default handler is just a class function pointer, it is also possible to override
+ it yourself from the class_init function of a type which derives from the parent. That way, when the signal
+ is emitted, the parent class will use the function provided by the child as a signal default handler.
+ Of course, it is also possible (and recommended) to chain up from the child to the parent's default signal
+ handler to ensure the integrity of the parent object.
+ </para>
+
+ <para>
+ Overriding a class method and chaining up was demonstrated in <xref linkend="howto-gobject-methods"/>
+ which is why I won't bother to show exactly how to do it here again.
+ </para>
-</sect1>
+ </sect1>
</chapter>
<!--
<sect2>
- <title>Warning on signal creation and default closure</title>
+ <title>Warning on signal creation and default closure</title>
- Most of the existing code I have seen up to now (in both GTK+, GNOME libraries and
- many GTK+ and GNOME applications) using signals uses a small
- variation of the default handler pattern I have shown in the previous section.
- </para>
+ <para>
+ Most of the existing code I have seen up to now (in both GTK+, GNOME libraries and
+ many GTK+ and GNOME applications) using signals uses a small
+ variation of the default handler pattern I have shown in the previous section.
+ </para>
- Usually, the <function><link linkend="g-signal-new">g_signal_new</link></function> function is preferred over
- <function><link linkend="g-signal-newv">g_signal_newv</link></function>. When <function><link linkend="g-signal-new">g_signal_new</link></function>
- is used, the default closure is exported as a class function. For example,
- <filename>gobject.h</filename> contains the declaration of <type><link linkend="GObjectClass">GObjectClass</link></type>
- whose notify class function is the default handler for the <emphasis>notify</emphasis>
- signal:
+ <para>
+ Usually, the <function><link linkend="g-signal-new">g_signal_new</link></function> function is preferred over
+ <function><link linkend="g-signal-newv">g_signal_newv</link></function>. When <function><link linkend="g-signal-new">g_signal_new</link></function>
+ is used, the default closure is exported as a class function. For example,
+ <filename>gobject.h</filename> contains the declaration of <type><link linkend="GObjectClass">GObjectClass</link></type>
+ whose notify class function is the default handler for the <emphasis>notify</emphasis>
+ signal:
<programlisting>
struct _GObjectClass
{
GParamSpec *pspec);
};
</programlisting>
- </para>
+ </para>
- <filename>gobject.c</filename>'s <function><link linkend="g-object-do-class-init">g_object_do_class_init</link></function> function
- registers the <emphasis>notify</emphasis> signal and initializes this class function
- to NULL:
+ <para>
+ <filename>gobject.c</filename>'s <function><link linkend="g-object-do-class-init">g_object_do_class_init</link></function> function
+ registers the <emphasis>notify</emphasis> signal and initializes this class function
+ to NULL:
<programlisting>
static void
g_object_do_class_init (GObjectClass *class)
1, G_TYPE_PARAM);
}
</programlisting>
- <function><link linkend="g-signal-new">g_signal_new</link></function> creates a <type><link linkend="GClosure">GClosure</link></type> which dereferences the
- type's class structure to access the class function pointer and invoke it if it not NULL. The
- class function is ignored it is set to NULL.
- </para>
-
- <para>
- To understand the reason for such a complex scheme to access the signal's default handler,
- you must remember the whole reason for the use of these signals. The goal here is to delegate
- a part of the process to the user without requiring the user to subclass the object to override
- one of the class functions. The alternative to subclassing, that is, the use of signals
- to delegate processing to the user, is, however, a bit less optimal in terms of speed: rather
- than just dereferencing a function pointer in a class structure, you must start the whole
- process of signal emission which is a bit heavyweight.
- </para>
-
- <para>
- This is why some people decided to use class functions for some signal's default handlers:
- rather than having users connect a handler to the signal and stop the signal emission
- from within that handler, you just need to override the default class function which is
- supposedly more efficient.
- </para>
-
- </sect2>
--->
+ <function><link linkend="g-signal-new">g_signal_new</link></function> creates a <type><link linkend="GClosure">GClosure</link></type> which dereferences the
+ type's class structure to access the class function pointer and invoke it if it not NULL. The
+ class function is ignored it is set to NULL.
+ </para>
+ <para>
+ To understand the reason for such a complex scheme to access the signal's default handler,
+ you must remember the whole reason for the use of these signals. The goal here is to delegate
+ a part of the process to the user without requiring the user to subclass the object to override
+ one of the class functions. The alternative to subclassing, that is, the use of signals
+ to delegate processing to the user, is, however, a bit less optimal in terms of speed: rather
+ than just dereferencing a function pointer in a class structure, you must start the whole
+ process of signal emission which is a bit heavyweight.
+ </para>
-<!--
- <capter1 id="howto-doc">
- <title>How to generate API documentation for your type?</title>
+ <para>
+ This is why some people decided to use class functions for some signal's default handlers:
+ rather than having users connect a handler to the signal and stop the signal emission
+ from within that handler, you just need to override the default class function which is
+ supposedly more efficient.
+ </para>
- </chapter>
+ </sect2>
-->
+
-<chapter>
-<title>Background</title>
-
-<para>
-GObject, and its lower-level type system, GType, are used by GTK+ and most GNOME libraries to
-provide:
-<itemizedlist>
-<listitem><para>object-oriented C-based APIs and</para></listitem>
-<listitem><para>automatic transparent API bindings to other compiled
-or interpreted languages.</para></listitem>
-</itemizedlist>
-</para>
-
-<para>A lot of programmers are used to work with compiled-only or dynamically interpreted-only
-languages and do not understand the challenges associated with cross-language interoperability.
-This introduction tries to provide an insight into these challenges. describes briefly
-the solution choosen by GLib.
-</para>
-
-<para>The following chapters go into greater detail into how GType and GObject work and
-how you can use them as a C programmer. It is useful to keep in mind that
-allowing access to C objects from other interpreted languages was one of the major design
-goals: this can often explain the sometimes rather convoluted APIs and features present
-in this library.
-</para>
-
-<sect1>
-<title>Data types and programming</title>
-
-<para>
-One could say (I have seen such definitions used in some textbooks on programming language theory)
-that a programming language is merely a way to create data types and manipulate them. Most languages
-provide a number of language-native types and a few primitives to create more complex types based
-on these primitive types.
-</para>
-
-<para>
-In C, the language provides types such as <emphasis>char</emphasis>, <emphasis>long</emphasis>,
-<emphasis>pointer</emphasis>. During compilation of C code, the compiler maps these
-language types to the compiler's target architecture machine types. If you are using a C interpreter
-(I have never seen one myself but it is possible :), the interpreter (the program which interprets
-the source code and executes it) maps the language types to the machine types of the target machine at
-runtime, during the program execution (or just before execution if it uses a Just In Time compiler engine).
-</para>
-
-<para>Perl and Python which are interpreted languages do not really provide type definitions similar
-to those used by C. Perl and Python programmers manipulate variables and the type of the variables
-is decided only upon the first assignment or upon the first use which forces a type on the variable.
-The interpreter also often provides a lot of automatic conversions from one type to the other. For example,
-in Perl, a variable which holds an integer can be automatically converted to a string given the
-required context:
+<?xml version='1.0' encoding="ISO-8859-1"?>
+<chapter id="chapter-intro">
+ <title>Background</title>
+
+ <para>
+ GObject, and its lower-level type system, GType, are used by GTK+ and most GNOME libraries to
+ provide:
+ <itemizedlist>
+ <listitem><para>object-oriented C-based APIs and</para></listitem>
+ <listitem><para>automatic transparent API bindings to other compiled
+ or interpreted languages.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ A lot of programmers are used to work with compiled-only or dynamically interpreted-only
+ languages and do not understand the challenges associated with cross-language interoperability.
+ This introduction tries to provide an insight into these challenges. describes briefly
+ the solution choosen by GLib.
+ </para>
+
+ <para>
+ The following chapters go into greater detail into how GType and GObject work and
+ how you can use them as a C programmer. It is useful to keep in mind that
+ allowing access to C objects from other interpreted languages was one of the major design
+ goals: this can often explain the sometimes rather convoluted APIs and features present
+ in this library.
+ </para>
+
+ <sect1>
+ <title>Data types and programming</title>
+
+ <para>
+ One could say (I have seen such definitions used in some textbooks on programming language theory)
+ that a programming language is merely a way to create data types and manipulate them. Most languages
+ provide a number of language-native types and a few primitives to create more complex types based
+ on these primitive types.
+ </para>
+
+ <para>
+ In C, the language provides types such as <emphasis>char</emphasis>, <emphasis>long</emphasis>,
+ <emphasis>pointer</emphasis>. During compilation of C code, the compiler maps these
+ language types to the compiler's target architecture machine types. If you are using a C interpreter
+ (I have never seen one myself but it is possible :), the interpreter (the program which interprets
+ the source code and executes it) maps the language types to the machine types of the target machine at
+ runtime, during the program execution (or just before execution if it uses a Just In Time compiler engine).
+ </para>
+
+ <para>
+ Perl and Python which are interpreted languages do not really provide type definitions similar
+ to those used by C. Perl and Python programmers manipulate variables and the type of the variables
+ is decided only upon the first assignment or upon the first use which forces a type on the variable.
+ The interpreter also often provides a lot of automatic conversions from one type to the other. For example,
+ in Perl, a variable which holds an integer can be automatically converted to a string given the
+ required context:
<programlisting>
my $tmp = 10;
print "this is an integer converted to a string:" . $tmp . "\n";
</programlisting>
-Of course, it is also often possible to explicitely specify conversions when the default conversions provided
-by the language are not intuitive.
-</para>
-
-</sect1>
-
-<sect1>
-<title>Exporting a C API</title>
-
-<para>C APIs are defined by a set of functions and global variables which are usually exported from a
-binary. C functions have an arbitrary number of arguments and one return value. Each function is thus
-uniquely identified by the function name and the set of C types which describe the function arguments
-and return value. The global variables exported by the API are similarly identified by their name and
-their type.
-</para>
-
-<para>
-A C API is thus merely defined by a set of names to which a set of types are associated. If you know the
-function calling convention and the mapping of the C types to the machine types used by the platform you
-are on, you can resolve the name of each function to find where the code associated to this function
-is located in memory, and then construct a valid argument list for the function. Finally, all you have to
-do is triger a call to the target C function with the argument list.
-</para>
-
-<para>
-For the sake of discussion, here is a sample C function and the associated 32 bit x86
-assembly code generated by gcc on my linux box:
+ Of course, it is also often possible to explicitely specify conversions when the default conversions provided
+ by the language are not intuitive.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Exporting a C API</title>
+
+ <para>
+ C APIs are defined by a set of functions and global variables which are usually exported from a
+ binary. C functions have an arbitrary number of arguments and one return value. Each function is thus
+ uniquely identified by the function name and the set of C types which describe the function arguments
+ and return value. The global variables exported by the API are similarly identified by their name and
+ their type.
+ </para>
+
+ <para>
+ A C API is thus merely defined by a set of names to which a set of types are associated. If you know the
+ function calling convention and the mapping of the C types to the machine types used by the platform you
+ are on, you can resolve the name of each function to find where the code associated to this function
+ is located in memory, and then construct a valid argument list for the function. Finally, all you have to
+ do is triger a call to the target C function with the argument list.
+ </para>
+
+ <para>
+ For the sake of discussion, here is a sample C function and the associated 32 bit x86
+ assembly code generated by gcc on my linux box:
<programlisting>
static void function_foo (int foo)
{}
push $0xa
call 0x80482f4 <function_foo>
</programlisting>
-The assembly code shown above is pretty straightforward: the first instruction pushes
-the hexadecimal value 0xa (decimal value 10) as a 32 bit integer on the stack and calls
-<function>function_foo</function>. As you can see, C function calls are implemented by
-gcc by native function calls (this is probably the fastest implementation possible).
-</para>
-
-<para>
-Now, let's say we want to call the C function <function>function_foo</function> from
-a python program. To do this, the python interpreter needs to:
-<itemizedlist>
-<listitem><para>Find where the function is located. This means probably find the binary generated by the C compiler
-which exports this functions.</para></listitem>
-<listitem><para>Load the code of the function in executable memory.</para></listitem>
-<listitem><para>Convert the python parameters to C-compatible parameters before calling
-the function.</para></listitem>
-<listitem><para>Call the function with the right calling convention</para></listitem>
-<listitem><para>Convert the return values of the C function to python-compatible
-variables to return them to the python code.</para></listitem>
-</itemizedlist>
-</para>
-
-<para>The process described above is pretty complex and there are a lot of ways to make it entirely automatic
-and transparent to the C and the Python programmers:
-<itemizedlist>
-<listitem><para>The first solution is to write by hand a lot of glue code, once for each function exported or imported,
-which does the python to C parameter conversion and the C to python return value conversion. This glue code is then
-linked with the interpreter which allows python programs to call a python functions which delegates the work to the
-C function.</para></listitem>
-<listitem><para>Another nicer solution is to automatically generate the glue code, once for each function exported or
-imported, with a special compiler which
-reads the original function signature.</para></listitem>
-<listitem><para>The solution used by GLib is to use the GType library which holds at runtime a description of
-all the objects manipulated by the programmer. This so-called <emphasis>dynamic type</emphasis><footnote>
-<para>
- There are numerous different implementations of dynamic type systems: all C++
- compilers have one, Java and .NET have one too. A dynamic type system allows you
- to get information about every instantiated object at runtime. It can be implemented
- by a process-specific database: every new object created registers the characteristics
- of its associated type in the type system. It can also be implemented by introspection
- interfaces. The common point between all these different type systems and implementations
- is that they all allow you to query for object metadata at runtime.
-</para>
-</footnote>
-
- library is then
-used by special generic glue code to automatically convert function parameters and function calling conventions
-between different runtime domains.</para></listitem>
-</itemizedlist>
-The greatest advantage of the solution implemented by GType is that the glue code sitting at the runtime domain
-boundaries is written once: the figure below states this more clearly.
-<figure>
- <mediaobject>
- <imageobject> <!-- this is for HTML output -->
- <imagedata fileref="glue.png" format="PNG" align="center"/>
- </imageobject>
- <imageobject> <!-- this is for PDF output -->
- <imagedata fileref="glue.jpg" format="JPG" align="center"/>
- </imageobject>
- </mediaobject>
-</figure>
-
-Currently, there exist at least Python and Perl generic glue code which makes it possible to use
-C objects written with GType directly in Python or Perl, with a minimum amount of work: there
-is no need to generate huge amounts of glue code either automatically or by hand.
-</para>
-
-<para>Although that goal was arguably laudable, its pursuit has had a major influence on
-the whole GType/GObject library. C programmers are likely to be puzzled at the complexity
-of the features exposed in the following chapters if they forget that the GType/GObject library
-was not only designed to offer OO-like features to C programmers but also transparent
-cross-language interoperability.
-</para>
-
-</sect1>
+ The assembly code shown above is pretty straightforward: the first instruction pushes
+ the hexadecimal value 0xa (decimal value 10) as a 32 bit integer on the stack and calls
+ <function>function_foo</function>. As you can see, C function calls are implemented by
+ gcc by native function calls (this is probably the fastest implementation possible).
+ </para>
+
+ <para>
+ Now, let's say we want to call the C function <function>function_foo</function> from
+ a python program. To do this, the python interpreter needs to:
+ <itemizedlist>
+ <listitem><para>Find where the function is located. This means probably find the binary generated by the C compiler
+ which exports this functions.</para></listitem>
+ <listitem><para>Load the code of the function in executable memory.</para></listitem>
+ <listitem><para>Convert the python parameters to C-compatible parameters before calling
+ the function.</para></listitem>
+ <listitem><para>Call the function with the right calling convention</para></listitem>
+ <listitem><para>Convert the return values of the C function to python-compatible
+ variables to return them to the python code.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The process described above is pretty complex and there are a lot of ways to make it entirely automatic
+ and transparent to the C and the Python programmers:
+ <itemizedlist>
+ <listitem><para>The first solution is to write by hand a lot of glue code, once for each function exported or imported,
+ which does the python to C parameter conversion and the C to python return value conversion. This glue code is then
+ linked with the interpreter which allows python programs to call a python functions which delegates the work to the
+ C function.</para></listitem>
+ <listitem><para>Another nicer solution is to automatically generate the glue code, once for each function exported or
+ imported, with a special compiler which
+ reads the original function signature.</para></listitem>
+ <listitem><para>The solution used by GLib is to use the GType library which holds at runtime a description of
+ all the objects manipulated by the programmer. This so-called <emphasis>dynamic type</emphasis>
+ <footnote>
+ <para>
+ There are numerous different implementations of dynamic type systems: all C++
+ compilers have one, Java and .NET have one too. A dynamic type system allows you
+ to get information about every instantiated object at runtime. It can be implemented
+ by a process-specific database: every new object created registers the characteristics
+ of its associated type in the type system. It can also be implemented by introspection
+ interfaces. The common point between all these different type systems and implementations
+ is that they all allow you to query for object metadata at runtime.
+ </para>
+ </footnote>
+ library is then used by special generic glue code to automatically convert function parameters and
+ function calling conventions between different runtime domains.</para></listitem>
+ </itemizedlist>
+ The greatest advantage of the solution implemented by GType is that the glue code sitting at the runtime domain
+ boundaries is written once: the figure below states this more clearly.
+ <figure>
+ <mediaobject>
+ <imageobject> <!-- this is for HTML output -->
+ <imagedata fileref="glue.png" format="PNG" align="center"/>
+ </imageobject>
+ <imageobject> <!-- this is for PDF output -->
+ <imagedata fileref="glue.jpg" format="JPG" align="center"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ Currently, there exist at least Python and Perl generic glue code which makes it possible to use
+ C objects written with GType directly in Python or Perl, with a minimum amount of work: there
+ is no need to generate huge amounts of glue code either automatically or by hand.
+ </para>
+
+ <para>
+ Although that goal was arguably laudable, its pursuit has had a major influence on
+ the whole GType/GObject library. C programmers are likely to be puzzled at the complexity
+ of the features exposed in the following chapters if they forget that the GType/GObject library
+ was not only designed to offer OO-like features to C programmers but also transparent
+ cross-language interoperability.
+ </para>
+
+ </sect1>
</chapter>
+<?xml version='1.0' encoding="ISO-8859-1"?>
<partintro>
<para>
Several useful developer tools have been build around GObject technology.
projects / platform / upstream / glib.git / commitdiff