luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-09-20 09:16:15 +02: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.

85
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
@ -359,11 +359,12 @@ void g_object_run_dispose (GObject *object);
<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>
@ -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,31 +393,35 @@ 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.
<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>
@ -649,11 +654,11 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &amp;val);
<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>
@ -691,9 +696,9 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &amp;val);
<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>
@ -704,6 +709,14 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &amp;val);
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>
@ -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>
@ -729,12 +744,20 @@ g_object_set (G_OBJECT (foo),
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>

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

50
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>
@ -891,8 +895,8 @@ maman_ibaz_base_init (gpointer g_iface)
</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"/>
@ -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>

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

@ -1,29 +1,29 @@
<partintro>
<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>
<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