luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-03-03 14:42:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

Unify spelling of GObject and GType. Improve some wording. Update the

Browse Source 
* 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.

svn path=/trunk/; revision=5327
This commit is contained in:
Stefan Kost 2007-02-07 22:15:34 +00:00
parent 840d9bab26
commit b8fcf708d0
6 changed files with 122 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/reference/ChangeLog
View File

@ -1,3 +1,13 @@
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.

65
docs/reference/gobject/tut_gobject.xml
View File

@ -17,8 +17,8 @@
<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>
@ -207,7 +207,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
</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>
@ -217,7 +217,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
</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>
@ -227,19 +227,19 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
</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>
@ -250,7 +250,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
</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
@ -362,8 +362,9 @@ void g_object_run_dispose (GObject *object);
</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>
@ -376,9 +377,9 @@ void g_object_run_dispose (GObject *object);
</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>
@ -392,29 +393,33 @@ void g_object_run_dispose (GObject *object);
</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.
base_init is invoked once for each class structure.</entry>
@ -705,6 +710,14 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &amp;val);
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>
@ -721,6 +734,8 @@ g_object_set (G_OBJECT (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>
@ -730,11 +745,19 @@ g_object_set (G_OBJECT (foo),
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>

6
docs/reference/gobject/tut_gsignal.xml
View File

@ -496,9 +496,9 @@ void g_signal_emit_by_name (gpointer instance,
<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

48
docs/reference/gobject/tut_gtype.xml
View File

@ -240,7 +240,7 @@ struct _GTypeValueTable
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
@ -551,7 +551,7 @@ The class initialization process is entirely implemented in
</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
@ -583,7 +583,7 @@ The class initialization process is entirely implemented in
<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"/>
@ -599,18 +599,18 @@ The class initialization process is entirely implemented in
</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>
@ -621,18 +621,18 @@ The class initialization process is entirely implemented in
<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>
@ -648,8 +648,10 @@ The class initialization process is entirely implemented in
<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 ())
@ -820,7 +822,7 @@ maman_ibaz_base_init (gpointer g_iface)
<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"/>
@ -837,8 +839,9 @@ maman_ibaz_base_init (gpointer g_iface)
</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
@ -846,8 +849,9 @@ maman_ibaz_base_init (gpointer g_iface)
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>
@ -892,7 +896,7 @@ maman_ibaz_base_init (gpointer g_iface)
<para>
The above process can be summarized as follows:
<table>
<table id="ginterface-init-table">
<title>Interface Finalization</title>
<tgroup cols="3">
<colspec colwidth="*" colnum="1" align="left"/>
@ -908,14 +912,16 @@ maman_ibaz_base_init (gpointer g_iface)
</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>

29
docs/reference/gobject/tut_howto.xml
View File

@ -107,7 +107,6 @@
* Potentially, include other headers on which this header depends.
*/
/*
* Type macros.
*/
@ -144,7 +143,7 @@ GType maman_bar_get_type (void);
struct _MamanBar {
GObject parent;
/* private */
/*&lt; private &gt;*/
int hsize;
};
</programlisting>
@ -160,7 +159,7 @@ typedef struct _MamanBarPrivate MamanBarPrivate;
struct _MamanBar {
GObject parent;
/* private */
/*&lt; private &gt;*/
MamanBarPrivate *priv;
};
</programlisting>
@ -420,12 +419,12 @@ bar_dispose (GObject *obj)
{
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
@ -443,12 +442,6 @@ bar_finalize (GObject *obj)
{
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);
}
@ -460,6 +453,9 @@ bar_class_init (BarClass *klass)
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
@ -467,10 +463,9 @@ maman_bar_init (GTypeInstance *instance,
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>
@ -1101,9 +1096,9 @@ maman_bar_get_type (void)
<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>
@ -1591,7 +1586,7 @@ klass->write_signal_id =
<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>

4
docs/reference/gobject/tut_tools.xml
View File

@ -9,7 +9,7 @@
<title>GObject builder</title>
<para>
Writing gobjects can be a tedious task. It requires a lot of typing and just
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.
@ -23,7 +23,7 @@
</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