+2007-02-08 Stefan Kost <ensonic@users.sf.net>
+
+ * gobject/tut_gobject.xml:
+ * gobject/tut_gsignal.xml:
+ * gobject/tut_gtype.xml:
+ * gobject/tut_howto.xml:
+ * gobject/tut_tools.xml:
+ Unify spelling of GObject and GType. Improve some wording. Update the
+ usage of private data. Make tables use row-spans and add id's to them.
+
2007-01-30 Matthias Clasen <mclasen@redhat.com>
* gobject/tmpl/gsignal.sgml: Correct a typo.
<listitem><para>Generic per-object properties with set/get function pairs</para></listitem>
<listitem><para>Easy use of signals</para></listitem>
</itemizedlist>
- All the GTK+ objects and all of the objects in GNOME libraries which use the GLib type
- system inherit from <type><link linkend="GObject">GObject</link></type> which is why it is important to understand
+ 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>
</thead>
<tbody>
<row>
- <entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
+ <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>
</row>
<row>
- <entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
+ <!--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>
</entry>
</row>
<row>
- <entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
+ <!--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>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>Each call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
+ <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>
</entry>
</row>
<row>
- <entry>Each call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
+ <!--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
<entry>Function's parameters</entry>
<entry>Remark</entry>
</row>
- </thead>
+ </thead>
<tbody>
<row>
- <entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for an instance
- of target type</entry>
+ <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>
</entry>
</row>
<row>
- <entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for an instance
+ <!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for an instance
of target type
- </entry>
+ </entry-->
<entry>target type's finalize class function</entry>
<entry>GObject instance</entry>
<entry>
</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 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>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>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>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.
+ <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>
<function><link linkend="g-value-transform">g_value_transform</link></function> will try to transform the input signed char into
an unsigned int. Of course, the success of the transformation depends on the availability
of the required transform function. In practice, there will almost always be a transformation
- <footnote>
-
<para>Its behaviour might not be what you expect but it is up to you to actually avoid
- relying on these transformations.
- </para>
- </footnote>
+ <footnote>
+ <para>Its behaviour might not be what you expect but it is up to you to actually avoid
+ relying on these transformations.
+ </para>
+ </footnote>
which matches and conversion will be caried out if needed.
</para>
<para>
Once the property has been set by the object's set_property class method, the code path
returns to <function><link linkend="g-object-set-property">g_object_set_property</link></function> which calls
- <function><link linkend="g-object-notify-queue-thaw">g_object_notify_queue_thaw</link></function>. This function makes sure that
- the "notify" signal is emitted on the object's instance with the changed property as
- parameter unless notifications were frozen by <function><link linkend="g-object-freeze-notify">g_object_freeze_notify</link></function>.
+ <function><link linkend="g-object-notify-queue-thaw">g_object_notify_queue_thaw</link></function>. This function makes sure that
+ the "notify" signal is emitted on the object's instance with the changed property as
+ parameter unless notifications were frozen by <function><link linkend="g-object-freeze-notify">g_object_freeze_notify</link></function>.
</para>
<para>
change notification is thawn: no property change is lost for the "notify" signal. Signal
can only be delayed by the notification freezing mechanism.
</para>
+
+ <para>
+ It sounds like a tedious task to set up GValues everytime when one wants to modify a property.
+ In practice one will rarely do this. The functions <function><link linkend="g-object-set-property">g_object_set_property</link></function>
+ and <function><link linkend="g-object-get-property">g_object_get_property</link></function>
+ are meant to be used by language bindings. For application there is an easier way and
+ that is described next.
+ </para>
<sect2 id="gobject-multi-properties">
<title>Accessing multiple properties at once</title>
"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>
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 each pair of parameters only after the object has been successfully constructed.
+ <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>
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. The closures which provided a detail will not
- be invoked (even though they are connected to a signal which is being emitted) if their detail
- does not match the detail provided by the user.
+ 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
For example: <function>maman_object_method</function>.
</para></listitem>
<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
+ 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>.
It is common although not a convention to implement this macro using either a global
</para>
</footnote>
(the concept of destruction is sometimes partly refered to as finalization
- in Gtype) is the symmetric process of the initialization: interfaces are
+ 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
<para>
The instanciation/finalization process can be summarized as follows:
- <table>
+ <table id="gtype-init-fini-table">
<title>GType Instantiation/Finalization</title>
<tgroup cols="3">
<colspec colwidth="*" colnum="1" align="left"/>
</thead>
<tbody>
<row>
- <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for target type</entry>
+ <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>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>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>
<entry>On object's instance</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 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>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>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>
<title>Non-instantiable classed types: Interfaces.</title>
<para>
- GType's Interfaces are very similar to Java's interfaces. To declare one of these
- you have to register a non-instantiable classed type which derives from
+ GType's Interfaces are very similar to Java's interfaces. They allow
+ to describe a common API that several classes will adhere to.
+ 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.
<programlisting>
#define MAMAN_IBAZ_TYPE (maman_ibaz_get_type ())
<para>
The above process can be summarized as follows:
- <table>
+ <table id="ginterface-init-table">
<title>Interface Initialization</title>
<tgroup cols="3">
<colspec colwidth="*" colnum="1" align="left"/>
</thead>
<tbody>
<row>
- <entry>First call to <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> for type
- implementing interface</entry>
+ <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
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>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>
</para>
<para>
- The above process can be summarized as follows:
- <table>
+ 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"/>
</thead>
<tbody>
<row>
- <entry>Last call to <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> for type
- implementing interface</entry>
+ <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>
+ <!--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>
* Potentially, include other headers on which this header depends.
*/
-
/*
* Type macros.
*/
struct _MamanBar {
GObject parent;
- /* private */
+ /*< private >*/
int hsize;
};
</programlisting>
struct _MamanBar {
GObject parent;
- /* private */
+ /*< private >*/
MamanBarPrivate *priv;
};
</programlisting>
{
MamanBar *self = (MamanBar *)obj;
- if (self->private->dispose_has_run) {
+ if (self->priv->dispose_has_run) {
/* If dispose did already run, return. */
return;
}
/* Make sure dispose does not run twice. */
- object->private->dispose_has_run = TRUE;
+ object->priv->dispose_has_run = TRUE;
/*
* In dispose, you are supposed to free all types referenced from this
{
MamanBar *self = (MamanBar *)obj;
- /*
- * Here, complete object destruction.
- * You might not need to do much...
- */
- g_free (self->private);
-
/* Chain up to the parent class */
G_OBJECT_CLASS (parent_class)->finalize (obj);
}
gobject_class->dispose = bar_dispose;
gobject_class->finalize = bar_finalize;
+
+ parent_class = g_type_class_peek_parent (klass);
+ g_type_class_add_private(klass,sizeof(MamanBarPrivate));
}
static void
gpointer g_class)
{
MamanBar *self = (MamanBar *)instance;
- self->private = g_new0 (MamanBarPrivate, 1);
- self->private->dispose_has_run = FALSE;
+ self->priv = G_TYPE_INSTANCE_GET_PRIVATE(self, BT_TYPE_PATTERN, BtPatternPrivate);
+ self->priv->dispose_has_run = FALSE;
- parent_class = g_type_class_peek_parent (klass);
}
</programlisting>
</para>
<sect1 id="howto-interface-properties">
<title>Interface Properties</title>
- <para>Starting from version 2.4 of glib, gobject interfaces can also have properties.
+ <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"/>,
+ 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>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
+ 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>
<partintro>
- Several useful developer tools have been build around GObject technology.
- The next sections briefly introduce them and link to the respective project pages.
- </para>
+ <para>
+ Several useful developer tools have been build around GObject technology.
+ The next sections briefly introduce them and link to the respective project pages.
+ </para>
</partintro>
<chapter id="tools-gob">
<title>GObject builder</title>
<para>
- Writing gobjects can be a tedious task. It requires a lot of typing and just
- doing a copy/paste requires a great deal of care.
- One obvious idea is to use some sort of templates for the class skeletons.
- and then run them through a special tool to generate the real C files.
-
<ulink url="http://www.5z.com/jirka/gob.html">GOB/</ulink> (or GOB2) is such
- a tool. It is a preprocessor which can be used to build GObjects
- with inline C code so that there is no need to edit the generated C code.
- The syntax is inspired by Java and Yacc or Lex. The implementation is
- intentionally kept simple: the inline C code provided by the user
- is not parsed.
+ Writing GObjects can be a tedious task. It requires a lot of typing and just
+ doing a copy/paste requires a great deal of care.
+ One obvious idea is to use some sort of templates for the class skeletons.
+ and then run them through a special tool to generate the real C files.
+ <ulink url="http://www.5z.com/jirka/gob.html">GOB/</ulink> (or GOB2) is such
+ a tool. It is a preprocessor which can be used to build GObjects
+ with inline C code so that there is no need to edit the generated C code.
+ The syntax is inspired by Java and Yacc or Lex. The implementation is
+ intentionally kept simple: the inline C code provided by the user
+ is not parsed.
</para>
</chapter>
<chapter id="tools-ginspector">
- <title>Graphical inspection of Gobjects</title>
+ <title>Graphical inspection of GObjects</title>
<para>
Yet another tool that you may find helpful when working with
projects / platform / upstream / glib.git / commitdiff