diff options
| author | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 21:12:06 -0400 |
|---|---|---|
| committer | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 21:12:06 -0400 |
| commit | 63e87c2d0c9d263f14c77b68f85c67d46ece82a9 (patch) | |
| tree | 6260365cbf7d24f37d27669e8538227fcb72e243 /gtk+-mingw/share/gtk-doc/html/gobject/chapter-gobject.html | |
| parent | a4460f6d9453bbd7e584937686449cef3e19f052 (diff) | |
Diffstat (limited to 'gtk+-mingw/share/gtk-doc/html/gobject/chapter-gobject.html')
| -rw-r--r-- | gtk+-mingw/share/gtk-doc/html/gobject/chapter-gobject.html | 290 |
1 files changed, 0 insertions, 290 deletions
diff --git a/gtk+-mingw/share/gtk-doc/html/gobject/chapter-gobject.html b/gtk+-mingw/share/gtk-doc/html/gobject/chapter-gobject.html deleted file mode 100644 index 8649629..0000000 --- a/gtk+-mingw/share/gtk-doc/html/gobject/chapter-gobject.html +++ /dev/null @@ -1,290 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<title>The GObject base class</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="index.html" title="GObject Reference Manual"> -<link rel="up" href="pt01.html" title="Part I. Concepts"> -<link rel="prev" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces"> -<link rel="next" href="gobject-memory.html" title="Object memory management"> -<meta name="generator" content="GTK-Doc V1.18 (XML mode)"> -<link rel="stylesheet" href="style.css" type="text/css"> -</head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> -<td><a accesskey="p" href="gtype-non-instantiable-classed.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> -<td><a accesskey="u" href="pt01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> -<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> -<th width="100%" align="center">GObject Reference Manual</th> -<td><a accesskey="n" href="gobject-memory.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> -</tr></table> -<div class="chapter"> -<div class="titlepage"><div><div><h2 class="title"> -<a name="chapter-gobject"></a>The GObject base class</h2></div></div></div> -<div class="toc"><dl> -<dt><span class="sect1"><a href="chapter-gobject.html#gobject-instantiation">Object instantiation</a></span></dt> -<dt><span class="sect1"><a href="gobject-memory.html">Object memory management</a></span></dt> -<dd><dl> -<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-refcount">Reference count</a></span></dt> -<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-weakref">Weak References</a></span></dt> -<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-cycles">Reference counts and cycles</a></span></dt> -</dl></dd> -<dt><span class="sect1"><a href="gobject-properties.html">Object properties</a></span></dt> -<dd><dl><dt><span class="sect2"><a href="gobject-properties.html#gobject-multi-properties">Accessing multiple properties at once</a></span></dt></dl></dd> -</dl></div> -<p> - The previous chapter discussed the details of GLib's Dynamic Type System. - The GObject library also contains an implementation for a base fundamental - type named <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>. - </p> -<p> - <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> is a fundamental classed instantiable type. It implements: - </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> -<li class="listitem"><p>Memory management with reference counting</p></li> -<li class="listitem"><p>Construction/Destruction of instances</p></li> -<li class="listitem"><p>Generic per-object properties with set/get function pairs</p></li> -<li class="listitem"><p>Easy use of signals</p></li> -</ul></div> -<p> - All the GNOME libraries which use the GLib type system (like GTK+ and GStreamer) - inherit from <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> which is why it is important to understand - the details of how it works. - </p> -<div class="sect1"> -<div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="gobject-instantiation"></a>Object instantiation</h2></div></div></div> -<p> - The <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> - family of functions can be used to instantiate any GType which inherits - from the GObject base type. All these functions make sure the class and - instance structures have been correctly initialized by GLib's type system - and then invoke at one point or another the constructor class method - which is used to: - </p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> -<li class="listitem"><p> - Allocate and clear memory through <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code>, - </p></li> -<li class="listitem"><p> - Initialize the object's instance with the construction properties. - </p></li> -</ul></div> -<p> - Although one can expect all class and instance members (except the fields - pointing to the parents) to be set to zero, some consider it good practice - to explicitly set them. - </p> -<p> - Objects which inherit from GObject are allowed to override this - constructor class method: they should however chain to their parent - constructor method before doing so: -</p> -<pre class="programlisting"> - GObject *(* constructor) (GType gtype, - guint n_properties, - GObjectConstructParam *properties); -</pre> -<p> - </p> -<p> - The example below shows how <span class="type">MamanBar</span> overrides the parent's constructor: -</p> -<pre class="programlisting"> -#define MAMAN_TYPE_BAR (maman_bar_get_type ()) -#define MAMAN_BAR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar)) -#define MAMAN_IS_BAR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR)) -#define MAMAN_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass)) -#define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR)) -#define MAMAN_BAR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass)) - -typedef struct _MamanBar MamanBar; -typedef struct _MamanBarClass MamanBarClass; - -struct _MamanBar -{ - GObject parent_instance; - - /* instance members */ -}; - -struct _MamanBarClass -{ - GObjectClass parent_class; - - /* class members */ -}; - -/* will create maman_bar_get_type and set maman_bar_parent_class */ -G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT); - -static GObject * -maman_bar_constructor (GType gtype, - guint n_properties, - GObjectConstructParam *properties) -{ - GObject *obj; - - { - /* Always chain up to the parent constructor */ - obj = G_OBJECT_CLASS (maman_bar_parent_class)->constructor (gtype, n_properties, properties); - } - - /* update the object state depending on constructor properties */ - - return obj; -} - -static void -maman_bar_class_init (MamanBarClass *klass) -{ - GObjectClass *gobject_class = G_OBJECT_CLASS (klass); - - gobject_class->constructor = maman_bar_constructor; -} - -static void -maman_bar_init (MamanBar *self) -{ - /* initialize the object */ -} - -</pre> -<p> - If the user instantiates an object <span class="type">MamanBar</span> with: -</p> -<pre class="programlisting"> -MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); -</pre> -<p> - If this is the first instantiation of such an object, the - <code class="function">maman_bar_class_init</code> function will be invoked - after any <code class="function">maman_bar_base_class_init</code> function. - This will make sure the class structure of this new object is - correctly initialized. Here, <code class="function">maman_bar_class_init</code> - is expected to override the object's class methods and setup the - class' own methods. In the example above, the constructor method is - the only overridden method: it is set to - <code class="function">maman_bar_constructor</code>. - </p> -<p> - Once <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> has obtained a reference to an initialized - class structure, it invokes its constructor method to create an instance of the new - object. Since it has just been overridden by <code class="function">maman_bar_class_init</code> - to <code class="function">maman_bar_constructor</code>, the latter is called and, because it - was implemented correctly, it chains up to its parent's constructor. In - order to find the parent class and chain up to the parent class - constructor, we can use the <code class="literal">maman_bar_parent_class</code> - pointer that has been set up for us by the - <code class="literal">G_DEFINE_TYPE</code> macro. - </p> -<p> - Finally, at one point or another, <code class="function">g_object_constructor</code> is invoked - by the last constructor in the chain. This function allocates the object's instance' buffer - through <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> - which means that the instance_init function is invoked at this point if one - was registered. After instance_init returns, the object is fully initialized and should be - ready to answer any user-request. When <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> - returns, <code class="function">g_object_constructor</code> sets the construction properties - (i.e. the properties which were given to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code>) and returns - to the user's constructor which is then allowed to do useful instance initialization... - </p> -<p> - The process described above might seem a bit complicated, but it can be - summarized easily by the table below which lists the functions invoked - by <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> - and their order of invocation: - </p> -<p> - </p> -<div class="table"> -<a name="gobject-construction-table"></a><p class="title"><b>Table 4. <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code></b></p> -<div class="table-contents"><table summary="g_object_new" border="1"> -<colgroup> -<col align="left"> -<col align="left"> -<col align="left"> -</colgroup> -<thead><tr> -<th align="left">Invocation time</th> -<th align="left">Function Invoked</th> -<th align="left">Function's parameters</th> -<th>Remark</th> -</tr></thead> -<tbody> -<tr> -<td rowspan="4" align="left">First call to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> for target type</td> -<td align="left">target type's base_init function</td> -<td align="left">On the inheritance tree of classes from fundamental type to target type. - base_init is invoked once for each class structure.</td> -<td> - I have no real idea on how this can be used. If you have a good real-life - example of how a class' base_init can be used, please, let me know. - </td> -</tr> -<tr> -<td align="left">target type's class_init function</td> -<td align="left">On target type's class structure</td> -<td> - Here, you should make sure to initialize or override class methods (that is, - assign to each class' method its function pointer) and create the signals and - the properties associated to your object. - </td> -</tr> -<tr> -<td align="left">interface' base_init function</td> -<td align="left">On interface' vtable</td> -<td> </td> -</tr> -<tr> -<td align="left">interface' interface_init function</td> -<td align="left">On interface' vtable</td> -<td> </td> -</tr> -<tr> -<td rowspan="2" align="left">Each call to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> for target type</td> -<td align="left">target type's class constructor method: GObjectClass->constructor</td> -<td align="left">On object's instance</td> -<td> - If you need to complete the object initialization after all the construction properties - are set, override the constructor method and make sure to chain up to the object's - parent class before doing your own initialization. - In doubt, do not override the constructor method. - </td> -</tr> -<tr> -<td align="left">type's instance_init function</td> -<td align="left">On the inheritance tree of classes from fundamental type to target type. - the instance_init provided for each type is invoked once for each instance - structure.</td> -<td> - Provide an instance_init function to initialize your object before its construction - properties are set. This is the preferred way to initialize a GObject instance. - This function is equivalent to C++ constructors. - </td> -</tr> -</tbody> -</table></div> -</div> -<p><br class="table-break"> - </p> -<p> - Readers should feel concerned about one little twist in the order in - which functions are invoked: while, technically, the class' constructor - method is called <span class="emphasis"><em>before</em></span> the GType's instance_init - function (since <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> which calls instance_init is called by - <code class="function">g_object_constructor</code> which is the top-level class - constructor method and to which users are expected to chain to), the - user's code which runs in a user-provided constructor will always - run <span class="emphasis"><em>after</em></span> GType's instance_init function since the - user-provided constructor <span class="emphasis"><em>must</em></span> (you've been warned) - chain up <span class="emphasis"><em>before</em></span> doing anything useful. - </p> -</div> -</div> -<div class="footer"> -<hr> - Generated by GTK-Doc V1.18</div> -</body> -</html>
\ No newline at end of file |