mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-09-20 09:16:15 +02:00
docs: fix docbook validity
'type' must be inside of 'link'.
This commit is contained in:
Stefan Kost
parent
409f7db894
commit
58e5b01fbc
@ -8,11 +8,11 @@
|
||||
<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>.
|
||||
for a base fundamental type named <link linkend="GObject"><type>GObject</type></link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<type><link linkend="GObject">GObject</link></type> is a fundamental classed instantiable type. It implements:
|
||||
<link linkend="GObject"><type>GObject</type></link> 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>
|
||||
@ -20,7 +20,7 @@
|
||||
<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
|
||||
inherit from <link linkend="GObject"><type>GObject</type></link> which is why it is important to understand
|
||||
the details of how it works.
|
||||
</para>
|
||||
|
||||
@ -641,13 +641,14 @@ g_value_unset (&val);
|
||||
</para>
|
||||
|
||||
<para>
|
||||
After transformation, the <type><link linkend="GValue">GValue</link></type> is validated by
|
||||
After transformation, the <link linkend="GValue"><type>GValue</type></link> is validated by
|
||||
<function><link linkend="g-param-value-validate">g_param_value_validate</link></function> which makes sure the user's
|
||||
data stored in the <type><link linkend="GValue">GValue</link></type> matches the characteristics specified by
|
||||
the property's <type><link linkend="GParamSpec">GParamSpec</link></type>. Here, the <type><link linkend="GParamSpec">GParamSpec</link></type> we
|
||||
data stored in the <link linkend="GValue"><type>GValue</type></link> matches the characteristics specified by
|
||||
the property's <link linkend="GParamSpec"><type>GParamSpec</type></link>.
|
||||
Here, the <link linkend="GParamSpec"><type>GParamSpec</type></link> we
|
||||
provided in class_init has a validation function which makes sure that the GValue
|
||||
contains a value which respects the minimum and maximum bounds of the
|
||||
<type><link linkend="GParamSpec">GParamSpec</link></type>. In the example above, the client's GValue does not
|
||||
<link linkend="GParamSpec"><type>GParamSpec</type></link>. In the example above, the client's GValue does not
|
||||
respect these constraints (it is set to 11, while the maximum is 10). As such, the
|
||||
<function><link linkend="g-object-set-property">g_object_set_property</link></function> function will return with an error.
|
||||
</para>
|
||||
@ -657,11 +658,11 @@ g_value_unset (&val);
|
||||
would have proceeded with calling the object's set_property class method. Here, since our
|
||||
implementation of Foo did override this method, the code path would jump to
|
||||
<function>foo_set_property</function> after having retrieved from the
|
||||
<type><link linkend="GParamSpec">GParamSpec</link></type> the <emphasis>param_id</emphasis>
|
||||
<link linkend="GParamSpec"><type>GParamSpec</type></link> 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
|
||||
<link linkend="GParamSpec"><type>GParamSpec</type></link> within the <link linkend="FooClass"><type>FooClass</type></link> 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.
|
||||
|
||||
@ -31,7 +31,7 @@ return_type function_callback (... , gpointer user_data);
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <type><link linkend="GClosure">GClosure</link></type> structure represents the common functionality of all
|
||||
The <link linkend="GClosure"><type>GClosure</type></link> 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>
|
||||
@ -42,11 +42,11 @@ return_type function_callback (... , gpointer user_data);
|
||||
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
|
||||
The GObject library provides a simple <link linkend="GCClosure"><type>GCClosure</type></link> 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:
|
||||
A <link linkend="GClosure"><type>GClosure</type></link> provides simple services:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Invocation (<function><link linkend="g-closure-invoke">g_closure_invoke</link></function>): this is what closures
|
||||
@ -77,7 +77,7 @@ return_type function_callback (... , gpointer user_data);
|
||||
|
||||
<para>
|
||||
If you are using C or C++
|
||||
to connect a callback to a given event, you will either use simple <type><link linkend="GCClosure">GCClosure</link></type>s
|
||||
to connect a callback to a given event, you will either use simple <link linkend="GCClosure"><type>GCClosure</type></link>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>
|
||||
@ -432,7 +432,7 @@ void g_signal_emitv (const GValue *instance_and_params,
|
||||
|
||||
<para>
|
||||
Of the three main connection functions,
|
||||
only one has an explicit detail parameter as a <type><link linkend="GQuark">GQuark</link></type>
|
||||
only one has an explicit detail parameter as a <link linkend="GQuark"><type>GQuark</type></link>
|
||||
<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
|
||||
@ -469,7 +469,7 @@ gulong g_signal_connect_data (gpointer instance,
|
||||
|
||||
<para>
|
||||
Of the four main signal emission functions, three have an explicit detail parameter as a
|
||||
<type><link linkend="GQuark">GQuark</link></type> again:
|
||||
<link linkend="GQuark"><type>GQuark</type></link> again:
|
||||
<programlisting>
|
||||
void g_signal_emitv (const GValue *instance_and_params,
|
||||
guint signal_id,
|
||||
|
||||
@ -49,7 +49,7 @@ GType g_type_register_fundamental (GType type_id,
|
||||
<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.
|
||||
which you should use to register a new <link linkend="GType"><type>GType</type></link> 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
|
||||
@ -77,34 +77,34 @@ GType g_type_register_fundamental (GType type_id,
|
||||
Fundamental and non-fundamental types are defined by:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
class size: the class_size field in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
|
||||
class size: the class_size field in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
class initialization functions (C++ constructor): the base_init and
|
||||
class_init fields in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
|
||||
class_init fields in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
class destruction functions (C++ destructor): the base_finalize and
|
||||
class_finalize fields in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
|
||||
class_finalize fields in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
instance size (C++ parameter to new): the instance_size field in
|
||||
<type><link linkend="GTypeInfo">GTypeInfo</link></type>.
|
||||
<link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
instantiation policy (C++ type of new operator): the n_preallocs
|
||||
field in <type><link linkend="GTypeInfo">GTypeInfo</link></type>.
|
||||
field in <link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
copy functions (C++ copy operators): the value_table field in
|
||||
<type><link linkend="GTypeInfo">GTypeInfo</link></type>.
|
||||
<link linkend="GTypeInfo"><type>GTypeInfo</type></link>.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
type characteristic flags: <type><link linkend="GTypeFlags">GTypeFlags</link></type>.
|
||||
type characteristic flags: <link linkend="GTypeFlags"><type>GTypeFlags</type></link>.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
Fundamental types are also defined by a set of <type><link linkend="GTypeFundamentalFlags">GTypeFundamentalFlags</link></type>
|
||||
which are stored in a <type><link linkend="GTypeFundamentalInfo">GTypeFundamentalInfo</link></type>.
|
||||
Fundamental types are also defined by a set of <link linkend="GTypeFundamentalFlags"><type>GTypeFundamentalFlags</type></link>
|
||||
which are stored in a <link linkend="GTypeFundamentalInfo"><type>GTypeFundamentalInfo</type></link>.
|
||||
Non-fundamental types are furthermore defined by the type of their parent which is
|
||||
passed as the parent_type parameter to <function><link linkend="g-type-register-static">g_type_register_static</link></function>
|
||||
and <function><link linkend="g-type-register-dynamic">g_type_register_dynamic</link></function>.
|
||||
@ -120,17 +120,17 @@ GType g_type_register_fundamental (GType type_id,
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <type><link linkend="GValue">GValue</link></type> structure is used as an abstract container for all of these
|
||||
The <link linkend="GValue"><type>GValue</type></link> 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
|
||||
content of a <link linkend="GValue"><type>GValue</type></link> to another <link linkend="GValue"><type>GValue</type></link>. 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>
|
||||
The following code shows how you can copy around a 64 bit integer, as well as a <link linkend="GObject"><type>GObject</type></link>
|
||||
instance pointer (sample code for this is located in the source tarball for this document in
|
||||
<filename>sample/gtype/test.c</filename>):
|
||||
<programlisting>
|
||||
@ -342,7 +342,7 @@ G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)
|
||||
|
||||
<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
|
||||
<link linkend="GTypeInfo"><type>GTypeInfo</type></link> structure with zeros since these types are also most of the time
|
||||
fundamental:
|
||||
<programlisting>
|
||||
GTypeInfo info = {
|
||||
@ -376,9 +376,9 @@ G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)
|
||||
<para>
|
||||
Having non-instantiable types might seem a bit useless: what good is a type
|
||||
if you cannot instantiate 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
|
||||
are used in conjunction with <link linkend="GValue"><type>GValue</type></link>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
|
||||
type's value_table. <link linkend="GValue"><type>GValue</type></link>s (and by extension these trivial fundamental
|
||||
types) are most useful when used in conjunction with object properties and signals.
|
||||
</para>
|
||||
|
||||
@ -390,7 +390,7 @@ G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)
|
||||
<para>
|
||||
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"/>)
|
||||
Although <link linkend="GObject"><type>GObject</type></link>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
|
||||
hierarchy have been externally developed and they are all built on the fundamental
|
||||
@ -448,8 +448,8 @@ maman_bar_get_type (void)
|
||||
<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,
|
||||
a <link linkend="GTypeClass"><type>GTypeClass</type></link> structure. All instance structures must contain as first
|
||||
member a <link linkend="GTypeInstance"><type>GTypeInstance</type></link> structure. The declaration of these C types,
|
||||
coming from <filename>gtype.h</filename> is shown below:
|
||||
<programlisting>
|
||||
struct _GTypeClass
|
||||
@ -537,9 +537,9 @@ void g_type_free_instance (GTypeInstance *instance);
|
||||
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
|
||||
base_class_initialization functions (<link linkend="GBaseInitFunc"><type>GBaseInitFunc</type></link>) 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
|
||||
(<link linkend="GClassInitFunc"><type>GClassInitFunc</type></link>) 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).
|
||||
@ -548,7 +548,7 @@ void g_type_free_instance (GTypeInstance *instance);
|
||||
<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
|
||||
instance_init (<link linkend="GInstanceInitFunc"><type>GInstanceInitFunc</type></link>)functions, from top-most fundamental
|
||||
type to bottom-most most derived type.
|
||||
</para>
|
||||
|
||||
@ -564,8 +564,8 @@ void g_type_free_instance (GTypeInstance *instance);
|
||||
referred 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
|
||||
class_finalize (<link linkend="ClassFinalizeFunc"><type>ClassFinalizeFunc</type></link>) function is invoked. The
|
||||
base_class_finalize (<link linkend="GBaseFinalizeFunc"><type>GBaseFinalizeFunc</type></link>) functions are
|
||||
Finally invoked from bottom-most most-derived type to top-most fundamental type and
|
||||
the class structure is freed.
|
||||
</para>
|
||||
@ -659,7 +659,7 @@ void g_type_free_instance (GTypeInstance *instance);
|
||||
control your CD player, MP3 player or anything that uses these symbols.
|
||||
To declare an interface 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.
|
||||
<link linkend="GTypeInterface"><type>GTypeInterface</type></link>. 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))
|
||||
@ -694,7 +694,7 @@ void maman_ibaz_do_action (MamanIbaz *self)
|
||||
|
||||
<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
|
||||
a <link linkend="GTypeInterface"><type>GTypeInterface</type></link> 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>
|
||||
@ -704,7 +704,7 @@ void maman_ibaz_do_action (MamanIbaz *self)
|
||||
<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
|
||||
a new GType named MamanBaz which inherits from <link linkend="GObject"><type>GObject</type></link> and which
|
||||
implements the interface <type>MamanIBaz</type>.
|
||||
<programlisting>
|
||||
static void maman_baz_do_action (MamanIbaz *self)
|
||||
@ -759,7 +759,7 @@ maman_baz_get_type (void)
|
||||
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
|
||||
The <link linkend="GInterfaceInfo"><type>GInterfaceInfo</type></link> structure holds
|
||||
information about the implementation of the interface:
|
||||
<programlisting>
|
||||
struct _GInterfaceInfo
|
||||
|
||||
@ -339,7 +339,7 @@ maman_bar_init (MamanBar *self)
|
||||
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
|
||||
<link linkend="GParamSpec"><type>GParamSpec</type></link> 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
|
||||
@ -820,8 +820,8 @@ void maman_ibaz_do_action (MamanIbaz *self);
|
||||
|
||||
#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:
|
||||
This code is the same as the code for a normal <link linkend="GType"><type>GType</type></link>
|
||||
which derives from a <link linkend="GObject"><type>GObject</type></link> except for a few details:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
The <function>_GET_CLASS</function> macro is called <function>_GET_INTERFACE</function>
|
||||
@ -1652,7 +1652,7 @@ klass->write_signal_id =
|
||||
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>
|
||||
<filename>gobject.h</filename> contains the declaration of <link linkend="GObjectClass"><type>GObjectClass</type></link>
|
||||
whose notify class function is the default handler for the <emphasis>notify</emphasis>
|
||||
signal:
|
||||
<programlisting>
|
||||
@ -1693,7 +1693,7 @@ 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
|
||||
<function><link linkend="g-signal-new">g_signal_new</link></function> creates a <link linkend="GClosure"><type>GClosure</type></link> 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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user