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/howto-gobject-construction.html ADDED Viewed

@@ -0,0 +1,113 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Object Construction</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="howto-gobject.html" title="How to define and implement a new GObject">
+<link rel="prev" href="howto-gobject-code.html" title="Boilerplate code">
+<link rel="next" href="howto-gobject-destruction.html" title="Object Destruction">
+<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="howto-gobject-code.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="howto-gobject.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="howto-gobject-destruction.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Object Construction">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="howto-gobject-construction"></a>Object Construction</h2></div></div></div>
+<p>
+      People often get confused when trying to construct their GObjects because of the
+      sheer number of different ways to hook into the objects's construction process: it is
+      difficult to figure which is the <span class="emphasis"><em>correct</em></span>, recommended way.
+    </p>
+<p>
+      <a class="xref" href="chapter-gobject.html#gobject-construction-table" title="Table 4. g_object_new">Table 4, “g_object_new”</a> shows what user-provided functions
+      are invoked during object instantiation and in which order they are invoked.
+      A user looking for the equivalent of the simple C++ constructor function should use
+      the instance_init method. It will be invoked after all the parent's instance_init
+      functions have been invoked. It cannot take arbitrary construction parameters
+      (as in C++) but if your object needs arbitrary parameters to complete initialization,
+      you can use construction properties.
+    </p>
+<p>
+      Construction properties will be set only after all instance_init functions have run.
+      No object reference will be returned to the client of <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>
+      until all the construction properties have been set.
+    </p>
+<p>
+      As such, I would recommend writing the following code first:
+</p>
+<pre class="programlisting">
+static void
+maman_bar_init (MamanBar *self)
+{
+  self-&gt;priv = MAMAN_BAR_GET_PRIVATE (self);
+  /* initialize all public and private members to reasonable default values. */
+  /* If you need specific construction properties to complete initialization,
+   * delay initialization completion until the property is set.
+   */
+}
+</pre>
+<p>
+    </p>
+<p>
+      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
+      <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>. Make sure that these properties use a construct only
+      <span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec" title="GParamSpec">GParamSpec</a></span> 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.
+</p>
+<pre class="programlisting">
+static void
+bar_class_init (MamanBarClass *klass)
+{
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+  GParamSpec *maman_param_spec;
+  gobject_class-&gt;set_property = bar_set_property;
+  gobject_class-&gt;get_property = bar_get_property;
+  maman_param_spec = g_param_spec_string ("maman",
+                                          "Maman construct prop",
+                                          "Set maman's name",
+                                          "no-name-set" /* default value */,
+                                          G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
+  g_object_class_install_property (gobject_class,
+                                   PROP_MAMAN,
+                                   maman_param_spec);
+}
+</pre>
+<p>
+      If you need this, make sure you can build and run code similar to the code shown above. Make sure
+      your construct properties can set correctly during construction, make sure you cannot set them
+      afterwards and make sure that if your users do not call <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>
+      with the required construction properties, these will be initialized with the default values.
+    </p>
+<p>
+      I consider good taste to halt program execution if a construction property is set its
+      default value. This allows you to catch client code which does not give a reasonable
+      value to the construction properties. Of course, you are free to disagree but you
+      should have a good reason to do so.
+    </p>
+<p>
+      Some people sometimes need to construct their object but only after
+      the construction properties have been set. This is possible through
+      the use of the constructor class method as described in
+      <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or, more simply, using
+      the constructed class method available since GLib 2.12.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.14</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-destruction.html ADDED Viewed

@@ -0,0 +1,122 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Object Destruction</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="howto-gobject.html" title="How to define and implement a new GObject">
+<link rel="prev" href="howto-gobject-construction.html" title="Object Construction">
+<link rel="next" href="howto-gobject-methods.html" title="Object methods">
+<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="howto-gobject-construction.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="howto-gobject.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="howto-gobject-methods.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Object Destruction">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="howto-gobject-destruction"></a>Object Destruction</h2></div></div></div>
+<p>
+      Again, it is often difficult to figure out which mechanism to use to
+      hook into the object's destruction process: when the last
+      <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-unref" title="g_object_unref ()">g_object_unref</a></code>
+      function call is made, a lot of things happen as described in
+      <a class="xref" href="gobject-memory.html#gobject-destruction-table" title="Table 5. g_object_unref">Table 5, “g_object_unref”</a>.
+    </p>
+<p>
+      The destruction process of your object might be split in two different
+      phases: dispose and the finalize.
+</p>
+<pre class="programlisting">
+#define MAMAN_BAR_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), MAMAN_TYPE_BAR, MamanBarPrivate))
+struct _MamanBarPrivate
+{
+  GObject *an_object;
+  gchar *a_string;
+};
+G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
+static void
+maman_bar_dispose (GObject *gobject)
+{
+  MamanBar *self = MAMAN_BAR (gobject);
+  /*
+   * In dispose, you are supposed to free all types referenced from this
+   * object which might themselves hold a reference to self. Generally,
+   * the most simple solution is to unref all members on which you own a
+   * reference.
+   */
+  /* dispose might be called multiple times, so we must guard against
+   * calling g_object_unref() on an invalid GObject.
+   */
+  if (self-&gt;priv-&gt;an_object)
+    {
+      g_object_unref (self-&gt;priv-&gt;an_object);
+      self-&gt;priv-&gt;an_object = NULL;
+    }
+  /* Chain up to the parent class */
+  G_OBJECT_CLASS (maman_bar_parent_class)-&gt;dispose (gobject);
+}
+static void
+maman_bar_finalize (GObject *gobject)
+{
+  MamanBar *self = MAMAN_BAR (gobject);
+  g_free (self-&gt;priv-&gt;a_string);
+  /* Chain up to the parent class */
+  G_OBJECT_CLASS (maman_bar_parent_class)-&gt;finalize (gobject);
+}
+static void
+maman_bar_class_init (MamanBarClass *klass)
+{
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+  gobject_class-&gt;dispose = maman_bar_dispose;
+  gobject_class-&gt;finalize = maman_bar_finalize;
+  g_type_class_add_private (klass, sizeof (MamanBarPrivate));
+}
+static void
+maman_bar_init (MamanBar *self);
+{
+  self-&gt;priv = MAMAN_BAR_GET_PRIVATE (self);
+  self-&gt;priv-&gt;an_object = g_object_new (MAMAN_TYPE_BAZ, NULL);
+  self-&gt;priv-&gt;a_string = g_strdup ("Maman");
+}
+</pre>
+<p>
+    </p>
+<p>
+      Add similar code to your GObject, make sure the code still builds
+      and runs: dispose and finalize must be called during the last unref.
+    </p>
+<p>
+      It is possible that object methods might be invoked after dispose is
+      run and before finalize runs. GObject does not consider this to be a
+      program error: you must gracefully detect this and neither crash nor
+      warn the user.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.14</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-methods.html ADDED Viewed

@@ -0,0 +1,257 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Object methods</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="howto-gobject.html" title="How to define and implement a new GObject">
+<link rel="prev" href="howto-gobject-destruction.html" title="Object Destruction">
+<link rel="next" href="howto-gobject-chainup.html" title="Chaining up">
+<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="howto-gobject-destruction.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="howto-gobject.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="howto-gobject-chainup.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Object methods">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="howto-gobject-methods"></a>Object methods</h2></div></div></div>
+<p>
+      Just as with C++, there are many different ways to define object
+      methods and extend them: the following list and sections draw on
+      C++ vocabulary. (Readers are expected to know basic C++ buzzwords.
+      Those who have not had to write C++ code recently can refer to e.g.
+      <a class="ulink" href="http://www.cplusplus.com/doc/tutorial/" target="_top">http://www.cplusplus.com/doc/tutorial/</a> to refresh
+      their memories.)
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+            non-virtual public methods,
+          </p></li>
+<li class="listitem"><p>
+            virtual public methods and
+          </p></li>
+<li class="listitem"><p>
+            virtual private methods
+          </p></li>
+</ul></div>
+<p>
+    </p>
+<div class="sect2" title="Non-virtual public methods">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id597147"></a>Non-virtual public methods</h3></div></div></div>
+<p>
+        These are the simplest: you want to provide a simple method which
+        can act on your object. All you need to do is to provide a function
+        prototype in the header and an implementation of that prototype
+        in the source file.
+</p>
+<pre class="programlisting">
+/* declaration in the header. */
+void maman_bar_do_action (MamanBar *self, /* parameters */);
+/* implementation in the source file */
+void
+maman_bar_do_action (MamanBar *self, /* parameters */)
+{
+  g_return_if_fail (MAMAN_IS_BAR (self));
+  /* do stuff here. */
+}
+</pre>
+<p>
+      </p>
+<p>There is really nothing scary about this.</p>
+</div>
+<div class="sect2" title="Virtual public methods">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id597172"></a>Virtual public methods</h3></div></div></div>
+<p>
+        This is the preferred way to create polymorphic GObjects. All you
+        need to do is to define the common method and its class function in
+        the public header, implement the common method in the source file
+        and re-implement the class function in each object which inherits
+        from you.
+</p>
+<pre class="programlisting">
+/* declaration in maman-bar.h. */
+struct _MamanBarClass
+{
+  GObjectClass parent_class;
+  /* stuff */
+  void (*do_action) (MamanBar *self, /* parameters */);
+};
+void maman_bar_do_action (MamanBar *self, /* parameters */);
+/* implementation in maman-bar.c */
+void
+maman_bar_do_action (MamanBar *self, /* parameters */)
+{
+  g_return_if_fail (MAMAN_IS_BAR (self));
+  MAMAN_BAR_GET_CLASS (self)-&gt;do_action (self, /* parameters */);
+}
+</pre>
+<p>
+        The code above simply redirects the do_action call to the relevant
+        class function. Some users, concerned about performance, do not
+        provide the <code class="function">maman_bar_do_action</code> wrapper function
+        and require users to dereference the class pointer themselves. This
+        is not such a great idea in terms of encapsulation and makes it
+        difficult to change the object's implementation afterwards, should
+        this be needed.
+      </p>
+<p>
+        Other users, also concerned by performance issues, declare
+        the <code class="function">maman_bar_do_action</code> function inline in the
+        header file. This, however, makes it difficult to change the
+        object's implementation later (although easier than requiring users
+        to directly dereference the class function) and is often difficult
+        to write in a portable way (the <span class="emphasis"><em>inline</em></span> keyword
+        is part of the C99 standard but not every compiler supports it).
+      </p>
+<p>
+        In doubt, unless a user shows you hard numbers about the performance
+        cost of the function call, just implement <code class="function">maman_bar_do_action</code>
+        in the source file.
+      </p>
+<p>
+        Please, note that it is possible for you to provide a default
+        implementation for this class method in the object's
+        <code class="function">class_init</code> function: initialize the
+        klass-&gt;do_action field to a pointer to the actual implementation.
+        You can also make this class method pure virtual by initializing
+        the klass-&gt;do_action field to NULL:
+</p>
+<pre class="programlisting">
+static void
+maman_bar_real_do_action_two (MamanBar *self, /* parameters */)
+{
+  /* Default implementation for the virtual method. */
+}
+static void
+maman_bar_class_init (BarClass *klass)
+{
+  /* pure virtual method: mandates implementation in children. */
+  klass-&gt;do_action_one = NULL;
+  /* merely virtual method. */
+  klass-&gt;do_action_two = maman_bar_real_do_action_two;
+}
+void
+maman_bar_do_action_one (MamanBar *self, /* parameters */)
+{
+  g_return_if_fail (MAMAN_IS_BAR (self));
+  MAMAN_BAR_GET_CLASS (self)-&gt;do_action_one (self, /* parameters */);
+}
+void
+maman_bar_do_action_two (MamanBar *self, /* parameters */)
+{
+  g_return_if_fail (MAMAN_IS_BAR (self));
+  MAMAN_BAR_GET_CLASS (self)-&gt;do_action_two (self, /* parameters */);
+}
+</pre>
+<p>
+      </p>
+</div>
+<div class="sect2" title="Virtual private Methods">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id597256"></a>Virtual private Methods</h3></div></div></div>
+<p>
+        These are very similar to Virtual Public methods. They just don't
+        have a public function to call the function directly. The header
+        file contains only a declaration of the class function:
+</p>
+<pre class="programlisting">
+/* declaration in maman-bar.h. */
+struct _MamanBarClass
+{
+  GObjectClass parent;
+  /* stuff */
+  void (* helper_do_specific_action) (MamanBar *self, /* parameters */);
+};
+void maman_bar_do_any_action (MamanBar *self, /* parameters */);
+</pre>
+<p>
+        These class functions are often used to delegate part of the job
+        to child classes:
+</p>
+<pre class="programlisting">
+/* this accessor function is static: it is not exported outside of this file. */
+static void
+maman_bar_do_specific_action (MamanBar *self, /* parameters */)
+{
+  MAMAN_BAR_GET_CLASS (self)-&gt;do_specific_action (self, /* parameters */);
+}
+void
+maman_bar_do_any_action (MamanBar *self, /* parameters */)
+{
+  /* random code here */
+  /*
+   * Try to execute the requested action. Maybe the requested action
+   * cannot be implemented here. So, we delegate its implementation
+   * to the child class:
+   */
+  maman_bar_do_specific_action (self, /* parameters */);
+  /* other random code here */
+}
+</pre>
+<p>
+      </p>
+<p>
+        Again, it is possible to provide a default implementation for this
+        private virtual class function:
+</p>
+<pre class="programlisting">
+static void
+maman_bar_class_init (MamanBarClass *klass)
+{
+  /* pure virtual method: mandates implementation in children. */
+  klass-&gt;do_specific_action_one = NULL;
+  /* merely virtual method. */
+  klass-&gt;do_specific_action_two = maman_bar_real_do_specific_action_two;
+}
+</pre>
+<p>
+      </p>
+<p>
+        Children can then implement the subclass with code such as:
+</p>
+<pre class="programlisting">
+static void
+maman_bar_subtype_class_init (MamanBarSubTypeClass *klass)
+{
+  MamanBarClass *bar_class = MAMAN_BAR_CLASS (klass);
+  /* implement pure virtual class function. */
+  bar_class-&gt;do_specific_action_one = maman_bar_subtype_do_specific_action_one;
+}
+</pre>
+<p>
+      </p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.14</div>
+</body>
+</html>