RubyGems - atk - Versions diffs - 0.90.2-x86-mingw32 - Mend

atk 0.90.2-x86-mingw32

Files changed (849) hide show

data/vendor/local/share/gtk-doc/html/gobject/gtype-conventions.html ADDED Viewed

@@ -0,0 +1,143 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Conventions</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="GObject Reference Manual">
+<link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System">
+<link rel="prev" href="chapter-gtype.html" title="The GLib Dynamic Type System">
+<link rel="next" href="gtype-non-instantiable.html" title="Non-instantiable non-classed fundamental types">
+<meta name="generator" content="GTK-Doc V1.14 (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="chapter-gtype.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="chapter-gtype.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="gtype-non-instantiable.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Conventions">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="gtype-conventions"></a>Conventions</h2></div></div></div>
+<p>
+        There are a number of conventions users are expected to follow when creating new types
+        which are to be exported in a header file:
+        </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+            Use the <code class="function">object_method</code> pattern for function names: to invoke
+            the method named foo on an instance of object type bar, call
+            <code class="function">bar_foo</code>.
+          </p></li>
+<li class="listitem"><p>Use prefixing to avoid namespace conflicts with other projects.
+            If your library (or application) is named <span class="emphasis"><em>Maman</em></span>,
+            <sup>[<a name="id529029" href="#ftn.id529029" class="footnote">3</a>]</sup>
+            prefix all your function names with <span class="emphasis"><em>maman_</em></span>.
+            For example: <code class="function">maman_object_method</code>.
+          </p></li>
+<li class="listitem"><p>Create a macro named <code class="function">PREFIX_TYPE_OBJECT</code> which always
+            returns the GType for the associated object type. For an object of type
+            <span class="emphasis"><em>Bar</em></span> in a library prefixed by <span class="emphasis"><em>maman</em></span>,
+            use: <code class="function">MAMAN_TYPE_BAR</code>.
+            It is common although not a convention to implement this macro using either a global
+            static variable or a function named <code class="function">prefix_object_get_type</code>.
+            We will follow the function pattern wherever possible in this document.
+          </p></li>
+<li class="listitem"><p>Create a macro named <code class="function">PREFIX_OBJECT (obj)</code> which
+            returns a pointer of type <span class="type">PrefixObject</span>. This macro is used to enforce
+            static type safety by doing explicit casts wherever needed. It also enforces
+            dynamic type safety by doing runtime checks. It is possible to disable the dynamic
+            type checks in production builds (see <a href="./../glib/glib/glib-building.html">building glib</a>).
+            For example, we would create
+            <code class="function">MAMAN_BAR (obj)</code> to keep the previous example.
+          </p></li>
+<li class="listitem"><p>If the type is classed, create a macro named
+            <code class="function">PREFIX_OBJECT_CLASS (klass)</code>. This macro
+            is strictly equivalent to the previous casting macro: it does static casting with
+            dynamic type checking of class structures. It is expected to return a pointer
+            to a class structure of type <span class="type">PrefixObjectClass</span>. Again, an example is:
+            <code class="function">MAMAN_BAR_CLASS</code>.
+          </p></li>
+<li class="listitem"><p>Create a macro named <code class="function">PREFIX_IS_BAR (obj)</code>: this macro is expected
+            to return a <span class="type">gboolean</span> which indicates whether or not the input
+            object instance pointer of type BAR.
+          </p></li>
+<li class="listitem"><p>If the type is classed, create a macro named
+            <code class="function">PREFIX_IS_OBJECT_CLASS (klass)</code> which, as above, returns a boolean
+            if the input class pointer is a pointer to a class of type OBJECT.
+          </p></li>
+<li class="listitem"><p>If the type is classed, create a macro named
+            <code class="function">PREFIX_OBJECT_GET_CLASS (obj)</code>
+            which returns the class pointer associated to an instance of a given type. This macro
+            is used for static and dynamic type safety purposes (just like the previous casting
+            macros).
+          </p></li>
+</ul></div>
+<p>
+        The implementation of these macros is pretty straightforward: a number of simple-to-use
+        macros are provided in <code class="filename">gtype.h</code>. For the example we used above, we would
+        write the following trivial code to declare the macros:
+</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_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
+#define MAMAN_IS_BAR(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
+#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))
+</pre>
+<p>
+        </p>
+<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">Note</h3>
+<p>Stick to the naming <code class="varname">klass</code> as <code class="varname">class</code> is a registered c++ keyword.</p>
+</div>
+<p>
+      </p>
+<p>
+        The following code shows how to implement the <code class="function">maman_bar_get_type</code>
+        function:
+</p>
+<pre class="programlisting">
+GType maman_bar_get_type (void)
+{
+  static GType type = 0;
+  if (type == 0) {
+    static const GTypeInfo info = {
+      /* You fill this structure. */
+    };
+    type = g_type_register_static (G_TYPE_OBJECT,
+                                   "MamanBarType",
+                                   &amp;info, 0);
+  }
+  return type;
+}
+</pre>
+<p>
+      </p>
+<p>
+        When having no special requirements you also can use the <code class="function">G_DEFINE_TYPE</code>
+	macro:
+</p>
+<pre class="programlisting">
+G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)
+</pre>
+<p>
+      </p>
+<div class="footnotes">
+<br><hr width="100" align="left">
+<div class="footnote"><p><sup>[<a name="ftn.id529029" href="#id529029" class="para">3</a>] </sup>
+                <span class="emphasis"><em>Maman</em></span> is the French word for <span class="emphasis"><em>mum</em></span>
+                or <span class="emphasis"><em>mother</em></span> - nothing more and nothing less.
+              </p></div>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.14</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gobject/gtype-instantiable-classed.html ADDED Viewed

@@ -0,0 +1,287 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Instantiable classed types: objects</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="GObject Reference Manual">
+<link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System">
+<link rel="prev" href="gtype-non-instantiable.html" title="Non-instantiable non-classed fundamental types">
+<link rel="next" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">
+<meta name="generator" content="GTK-Doc V1.14 (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.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="chapter-gtype.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="gtype-non-instantiable-classed.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Instantiable classed types: objects">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="gtype-instantiable-classed"></a>Instantiable classed types: objects</h2></div></div></div>
+<p>
+          Types which are registered with a class and are declared instantiable are
+          what most closely resembles an <span class="emphasis"><em>object</em></span>.
+          Although <span class="type"><a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a></span>s (detailed in <a class="xref" href="chapter-gobject.html" title="The GObject base class"><i>The GObject base class</i></a>)
+          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
+          features described below.
+        </p>
+<p>
+          For example, the code below shows how you could register
+          such a fundamental object type in the type system:
+</p>
+<pre class="programlisting">
+typedef struct {
+  GObject parent;
+  /* instance members */
+  int field_a;
+} MamanBar;
+typedef struct {
+  GObjectClass parent;
+  /* class members */
+  void (*do_action_public_virtual) (MamanBar *self, guint8 i);
+  void (*do_action_public_pure_virtual) (MamanBar *self, guint8 i);
+} MamanBarClass;
+#define MAMAN_TYPE_BAR (maman_bar_get_type ())
+GType
+maman_bar_get_type (void)
+{
+  static GType type = 0;
+  if (type == 0) {
+    static const GTypeInfo info = {
+      sizeof (MamanBarClass),
+      NULL,           /* base_init */
+      NULL,           /* base_finalize */
+      (GClassInitFunc) foo_class_init,
+      NULL,           /* class_finalize */
+      NULL,           /* class_data */
+      sizeof (MamanBar),
+      0,              /* n_preallocs */
+      (GInstanceInitFunc) NULL /* instance_init */
+    };
+    type = g_type_register_static (G_TYPE_OBJECT,
+                                   "BarType",
+                                   &amp;info, 0);
+  }
+  return type;
+}
+</pre>
+<p>
+          Upon the first call to <code class="function">maman_bar_get_type</code>, the type named
+          <span class="emphasis"><em>BarType</em></span> will be registered in the type system as inheriting
+          from the type <span class="emphasis"><em>G_TYPE_OBJECT</em></span>.
+        </p>
+<p>
+          Every object must define two structures: its class structure and its
+          instance structure. All class structures must contain as first member
+          a <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeClass" title="GTypeClass">GTypeClass</a></span> structure. All instance structures must contain as first
+          member a <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInstance" title="GTypeInstance">GTypeInstance</a></span> structure. The declaration of these C types,
+          coming from <code class="filename">gtype.h</code> is shown below:
+</p>
+<pre class="programlisting">
+struct _GTypeClass
+{
+  GType g_type;
+};
+struct _GTypeInstance
+{
+  GTypeClass *g_class;
+};
+</pre>
+<p>
+          These constraints allow the type system to make sure that every object instance
+          (identified by a pointer to the object's instance structure) contains in its
+          first bytes a pointer to the object's class structure.
+        </p>
+<p>
+          This relationship is best explained by an example: let's take object B which
+          inherits from object A:
+</p>
+<pre class="programlisting">
+/* A definitions */
+typedef struct {
+  GTypeInstance parent;
+  int field_a;
+  int field_b;
+} A;
+typedef struct {
+  GTypeClass parent_class;
+  void (*method_a) (void);
+  void (*method_b) (void);
+} AClass;
+/* B definitions. */
+typedef struct {
+  A parent;
+  int field_c;
+  int field_d;
+} B;
+typedef struct {
+  AClass parent_class;
+  void (*method_c) (void);
+  void (*method_d) (void);
+} BClass;
+</pre>
+<p>
+          The C standard mandates that the first field of a C structure is stored starting
+          in the first byte of the buffer used to hold the structure's fields in memory.
+          This means that the first field of an instance of an object B is A's first field
+          which in turn is GTypeInstance's first field which in turn is g_class, a pointer
+          to B's class structure.
+        </p>
+<p>
+          Thanks to these simple conditions, it is possible to detect the type of every
+          object instance by doing:
+</p>
+<pre class="programlisting">
+B *b;
+b-&gt;parent.parent.g_class-&gt;g_type
+</pre>
+<p>
+          or, more quickly:
+</p>
+<pre class="programlisting">
+B *b;
+((GTypeInstance*)b)-&gt;g_class-&gt;g_type
+</pre>
+<p>
+        </p>
+<div class="sect2" title="Initialization and Destruction">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="gtype-instantiable-classed-init-done"></a>Initialization and Destruction</h3></div></div></div>
+<p>
+            instantiation of these types can be done with
+            <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>
+<pre class="programlisting">
+GTypeInstance* g_type_create_instance (GType          type);
+void           g_type_free_instance   (GTypeInstance *instance);
+</pre>
+<p>
+            <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> will look up the type information
+            structure associated to the type requested. Then, the instance size and instantiation
+            policy (if the n_preallocs field is set to a non-zero value, the type system allocates
+            the object's instance structures in chunks rather than mallocing for every instance)
+            declared by the user are used to get a buffer to hold the object's instance
+            structure.
+          </p>
+<p>
+            If this is the first instance of the object ever created, the type system must create
+            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 (<span class="type"><a class="link" href="gobject-Type-Information.html#GBaseInitFunc" title="GBaseInitFunc ()">GBaseInitFunc</a></span>) from topmost
+            fundamental object to bottom-most most derived object. The object's class_init
+            (<span class="type"><a class="link" href="gobject-Type-Information.html#GClassInitFunc" title="GClassInitFunc ()">GClassInitFunc</a></span>) 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).
+          </p>
+<p>
+            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 (<span class="type"><a class="link" href="gobject-Type-Information.html#GInstanceInitFunc" title="GInstanceInitFunc ()">GInstanceInitFunc</a></span>)functions, from top-most fundamental
+            type to bottom-most most derived type.
+          </p>
+<p>
+            Object instance destruction through <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-free-instance" title="g_type_free_instance ()">g_type_free_instance</a></code> is very simple:
+            the instance structure is returned to the instance pool if there is one and if this was the
+            last living instance of the object, the class is destroyed.
+          </p>
+<p>
+            Class destruction (the concept of destruction is sometimes partly
+            referred to as finalization in GType) is the symmetric process of
+            the initialization: interfaces are destroyed first.
+            Then, the most derived
+            class_finalize (<span class="type">ClassFinalizeFunc</span>) function is invoked. The
+            base_class_finalize (<span class="type"><a class="link" href="gobject-Type-Information.html#GBaseFinalizeFunc" title="GBaseFinalizeFunc ()">GBaseFinalizeFunc</a></span>) functions are
+            Finally invoked from bottom-most most-derived type to top-most fundamental type and
+            the class structure is freed.
+          </p>
+<p>
+            As many readers have now understood it, the base initialization/finalization process is
+            very similar to the C++ constructor/destructor paradigm. The practical details are different
+            though and it is important not to get confused by superficial similarities.
+            GTypes have no instance destruction mechanism. It is
+            the user's responsibility to implement correct destruction semantics on top
+            of the existing GType code. (this is what GObject does. See
+            <a class="xref" href="chapter-gobject.html" title="The GObject base class"><i>The GObject base class</i></a>)
+           Furthermore, C++ code equivalent to the base_init
+           and class_init callbacks of GType is usually not needed because C++ cannot really create object
+           types at runtime.
+          </p>
+<p>
+            The instantiation/finalization process can be summarized as follows:
+            </p>
+<div class="table">
+<a name="gtype-init-fini-table"></a><p class="title"><b>Table 1. GType Instantiation/Finalization</b></p>
+<div class="table-contents"><table summary="GType Instantiation/Finalization" 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>
+</tr></thead>
+<tbody>
+<tr>
+<td rowspan="3" align="left">First call to <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> for target type</td>
+<td align="left">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>
+</tr>
+<tr>
+<td align="left">target type's class_init function</td>
+<td align="left">On target type's class structure</td>
+</tr>
+<tr>
+<td align="left">interface initialization, see
+                      <a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-init" title="Interface Initialization">the section called “Interface Initialization”</a>
+</td>
+<td align="left"> </td>
+</tr>
+<tr>
+<td align="left">Each call to <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> for target type</td>
+<td align="left">target type's instance_init function</td>
+<td align="left">On object's instance</td>
+</tr>
+<tr>
+<td rowspan="3" align="left">Last call to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-free-instance" title="g_type_free_instance ()">g_type_free_instance</a></code> for target type</td>
+<td align="left">interface destruction, see
+                      <a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-dest" title="Interface Destruction">the section called “Interface Destruction”</a>
+</td>
+<td align="left"> </td>
+</tr>
+<tr>
+<td align="left">target type's class_finalize function</td>
+<td align="left">On target type's class structure</td>
+</tr>
+<tr>
+<td align="left">type's base_finalize function</td>
+<td align="left">On the inheritance tree of classes from fundamental type to target type.
+                      base_finalize is invoked once for each class structure.</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<p><br class="table-break">
+          </p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.14</div>
+</body>
+</html>