RubyGems - glib2 - Versions diffs - 3.0.7-x64-mingw32 → 3.0.8-x64-mingw32 - Mend

glib2 3.0.7-x64-mingw32 → 3.0.8-x64-mingw32

Files changed (1062) hide show

data/vendor/local/share/gtk-doc/html/gobject/howto-interface.html CHANGED Viewed

@@ -3,12 +3,12 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>How to define and implement interfaces: GObject Reference Manual</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
 <link rel="home" href="index.html" title="GObject Reference Manual">
 <link rel="up" href="pt02.html" title="Part IV. Tutorial">
 <link rel="prev" href="howto-gobject-chainup.html" title="Chaining up">
 <link rel="next" href="howto-interface-implement.html" title="Implementing interfaces">
-<meta name="generator" content="GTK-Doc V1.21.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.24 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -33,11 +33,12 @@
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 <a name="howto-interface-define"></a>Defining interfaces</h2></div></div></div>
 <p>
-    The bulk of interface definition has already been shown in <a class="xref" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">the section called “Non-instantiable classed types: interfaces”</a>
-    but I feel it is needed to show exactly how to create an interface.
+    The theory behind how GObject interfaces work is given in
+    <a class="xref" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">the section called “Non-instantiable classed types: interfaces”</a>; this section covers how to
+    define and implement an interface.
   </p>
 <p>
-    As above, the first step is to get the header right. This interface
+    The first step is to get the header right. This interface
     defines two methods:
 </p>
 <div class="informalexample">
@@ -71,35 +72,51 @@
 25
 26
 27
-28</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="preproc">#ifndef</span><span class="normal"> __MAMAN_IBAZ_H__</span>
-<span class="preproc">#define</span><span class="normal"> __MAMAN_IBAZ_H__</span>
+28
+29
+30
+31
+32
+33
+34
+35
+36</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="comment">/*</span>
+<span class="comment"> * Copyright/Licensing information.</span>
+<span class="comment"> */</span>
-<span class="preproc">#include</span><span class="normal"> </span><span class="string">&lt;glib-object.h&gt;</span>
+<span class="gtkdoc ppc">#ifndef __VIEWER_EDITABLE_H__</span>
+<span class="gtkdoc ppc">#define __VIEWER_EDITABLE_H__</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_TYPE_IBAZ</span><span class="normal">                 </span><span class="symbol">(</span><span class="function">maman_ibaz_get_type</span><span class="normal"> </span><span class="symbol">())</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_IBAZ</span><span class="symbol">(</span><span class="normal">obj</span><span class="symbol">)</span><span class="normal">                 </span><span class="symbol">(</span><span class="function"><a href="gobject-Type-Information.html#G-TYPE-CHECK-INSTANCE-CAST:CAPS">G_TYPE_CHECK_INSTANCE_CAST</a></span><span class="normal"> </span><span class="symbol">((</span><span class="normal">obj</span><span class="symbol">),</span><span class="normal"> MAMAN_TYPE_IBAZ</span><span class="symbol">,</span><span class="normal"> MamanIbaz</span><span class="symbol">))</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_IS_IBAZ</span><span class="symbol">(</span><span class="normal">obj</span><span class="symbol">)</span><span class="normal">              </span><span class="symbol">(</span><span class="function"><a href="gobject-Type-Information.html#G-TYPE-CHECK-INSTANCE-TYPE:CAPS">G_TYPE_CHECK_INSTANCE_TYPE</a></span><span class="normal"> </span><span class="symbol">((</span><span class="normal">obj</span><span class="symbol">),</span><span class="normal"> MAMAN_TYPE_IBAZ</span><span class="symbol">))</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_IBAZ_GET_INTERFACE</span><span class="symbol">(</span><span class="normal">inst</span><span class="symbol">)</span><span class="normal">  </span><span class="symbol">(</span><span class="function"><a href="gobject-Type-Information.html#G-TYPE-INSTANCE-GET-INTERFACE:CAPS">G_TYPE_INSTANCE_GET_INTERFACE</a></span><span class="normal"> </span><span class="symbol">((</span><span class="normal">inst</span><span class="symbol">),</span><span class="normal"> MAMAN_TYPE_IBAZ</span><span class="symbol">,</span><span class="normal"> MamanIbazInterface</span><span class="symbol">))</span>
+<span class="gtkdoc ppc">#include &lt;glib-object.h&gt;</span>
+G_BEGIN_DECLS
-<span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanIbaz</span><span class="normal">               MamanIbaz</span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* dummy object */</span>
-<span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanIbazInterface</span><span class="normal">      MamanIbazInterface</span><span class="symbol">;</span>
+<span class="gtkdoc ppc">#define VIEWER_TYPE_EDITABLE viewer_editable_get_type ()</span>
+<span class="function"><a href="gobject-Type-Information.html#G-DECLARE-INTERFACE:CAPS">G_DECLARE_INTERFACE</a></span> <span class="gtkdoc opt">(</span>ViewerEditable<span class="gtkdoc opt">,</span> viewer_editable<span class="gtkdoc opt">,</span> VIEWER<span class="gtkdoc opt">,</span> EDITABLE<span class="gtkdoc opt">,</span> GObject<span class="gtkdoc opt">)</span>
-<span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanIbazInterface</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="usertype">GTypeInterface</span><span class="normal"> parent_iface</span><span class="symbol">;</span>
+<span class="gtkdoc kwb">struct</span> _ViewerEditableInterface
+<span class="gtkdoc opt">{</span>
+  GTypeInterface parent_iface<span class="gtkdoc opt">;</span>
-<span class="normal">  </span><span class="type">void</span><span class="normal"> </span><span class="symbol">(*</span><span class="normal">do_action</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanIbaz</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">);</span>
-<span class="normal">  </span><span class="type">void</span><span class="normal"> </span><span class="symbol">(*</span><span class="normal">do_something</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanIbaz</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">);</span>
-<span class="cbracket">}</span><span class="symbol">;</span>
+  <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>save<span class="gtkdoc opt">) (</span>ViewerEditable  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                GError         <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>
+  <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>undo<span class="gtkdoc opt">) (</span>ViewerEditable  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                guint            n_steps<span class="gtkdoc opt">);</span>
+  <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>redo<span class="gtkdoc opt">) (</span>ViewerEditable  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                guint            n_steps<span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">};</span>
-<span class="usertype">GType</span><span class="normal"> </span><span class="function">maman_ibaz_get_type</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">);</span>
+<span class="gtkdoc kwb">void</span> <span class="function">viewer_editable_save</span> <span class="gtkdoc opt">(</span>ViewerEditable  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                           GError         <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>
+<span class="gtkdoc kwb">void</span> <span class="function">viewer_editable_undo</span> <span class="gtkdoc opt">(</span>ViewerEditable  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                           guint            n_steps<span class="gtkdoc opt">);</span>
+<span class="gtkdoc kwb">void</span> <span class="function">viewer_editable_redo</span> <span class="gtkdoc opt">(</span>ViewerEditable  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                           guint            n_steps<span class="gtkdoc opt">);</span>
-<span class="type">void</span><span class="normal"> </span><span class="function">maman_ibaz_do_action</span><span class="normal">    </span><span class="symbol">(</span><span class="usertype">MamanIbaz</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">);</span>
-<span class="type">void</span><span class="normal"> </span><span class="function">maman_ibaz_do_something</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanIbaz</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">);</span>
+G_END_DECLS
-<span class="preproc">#endif</span><span class="normal"> </span><span class="comment">/* __MAMAN_IBAZ_H__ */</span></pre></td>
+<span class="gtkdoc ppc">#endif</span> <span class="comment">/* __VIEWER_EDITABLE_H__ */</span><span class="gtkdoc ppc"></span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -111,38 +128,38 @@
     </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem"><p>
-        The <code class="function">_GET_CLASS</code> macro is called <code class="function">_GET_INTERFACE</code>
-                  and not implemented with <code class="function"><a class="link" href="gobject-Type-Information.html#G-TYPE-INSTANCE-GET-CLASS:CAPS" title="G_TYPE_INSTANCE_GET_CLASS()">G_TYPE_INSTANCE_GET_CLASS</a></code>
-                  but with <code class="function"><a class="link" href="gobject-Type-Information.html#G-TYPE-INSTANCE-GET-INTERFACE:CAPS" title="G_TYPE_INSTANCE_GET_INTERFACE()">G_TYPE_INSTANCE_GET_INTERFACE</a></code>.
+        The <code class="function">_GET_CLASS</code> function is called
+        <code class="function">_GET_IFACE</code> (and is defined by
+        <a class="link" href="gobject-Type-Information.html#G-DECLARE-INTERFACE:CAPS" title="G_DECLARE_INTERFACE()"><code class="function">G_DECLARE_INTERFACE</code></a>).
       </p></li>
 <li class="listitem"><p>
-        The instance type, <span class="type">MamanIbaz</span> is not fully defined: it is
+        The instance type, <span class="type">ViewerEditable</span>, is not fully defined: it is
         used merely as an abstract type which represents an instance of
         whatever object which implements the interface.
       </p></li>
 <li class="listitem"><p>
-        The parent of the <span class="type">MamanIbazInterface</span> is not
-        <span class="type">GObjectClass</span> but <span class="type">GTypeInterface</span>.
+        The parent of the <span class="type">ViewerEditableInterface</span> is
+        <span class="type">GTypeInterface</span>, not <span class="type">GObjectClass</span>.
       </p></li>
 </ul></div>
 <p>
   </p>
 <p>
-    The implementation of the <span class="type">MamanIbaz</span> type itself is trivial:
+    The implementation of the <span class="type">ViewerEditable</span> type itself is trivial:
     </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem"><p><code class="function"><a class="link" href="gobject-Type-Information.html#G-DEFINE-INTERFACE:CAPS" title="G_DEFINE_INTERFACE()">G_DEFINE_INTERFACE</a></code>
-       creates a <code class="function">maman_ibaz_get_type</code> function which registers the
+       creates a <code class="function">viewer_editable_get_type</code> function which registers the
        type in the type system. The third argument is used to define a
        <a class="link" href="howto-interface-prerequisite.html" title="Interface definition prerequisites">prerequisite interface</a>
        (which we'll talk about more later). Just pass <code class="code">0</code> for this
        argument when an interface has no prerequisite.
        </p></li>
-<li class="listitem"><p><code class="function">maman_ibaz_default_init</code> is expected
+<li class="listitem"><p><code class="function">viewer_editable_default_init</code> is expected
       to register the interface's signals if there are any (we will see a bit
       later how to use them).</p></li>
-<li class="listitem"><p>The interface methods <code class="function">maman_ibaz_do_action</code>
-      and <code class="function">maman_ibaz_do_something</code> dereference the interface
+<li class="listitem"><p>The interface methods <code class="function">viewer_editable_save</code>,
+      <code class="function">viewer_editable_undo</code> and <code class="function">viewer_editable_redo</code> dereference the interface
       structure to access its associated interface function and call it.
       </p></li>
 </ul></div>
@@ -174,30 +191,78 @@
 20
 21
 22
-23</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="function"><a href="gobject-Type-Information.html#G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">MamanIbaz</span><span class="symbol">,</span><span class="normal"> maman_ibaz</span><span class="symbol">,</span><span class="normal"> </span><span class="number">0</span><span class="symbol">);</span>
-<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
-<span class="function">maman_ibaz_default_init</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanIbazInterface</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">iface</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">    </span><span class="comment">/* add properties and signals to the interface here */</span>
-<span class="cbracket">}</span>
-<span class="type">void</span>
-<span class="function">maman_ibaz_do_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanIbaz</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">MAMAN_IS_IBAZ</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">));</span>
-<span class="normal">  </span><span class="function">MAMAN_IBAZ_GET_INTERFACE</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">)-&gt;</span><span class="function">do_action</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">);</span>
-<span class="cbracket">}</span>
-<span class="type">void</span>
-<span class="function">maman_ibaz_do_something</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanIbaz</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">MAMAN_IS_IBAZ</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">));</span>
-<span class="normal">  </span><span class="function">MAMAN_IBAZ_GET_INTERFACE</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">)-&gt;</span><span class="function">do_something</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">);</span>
-<span class="cbracket">}</span></pre></td>
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="function"><a href="gobject-Type-Information.html#G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</a></span> <span class="gtkdoc opt">(</span>ViewerEditable<span class="gtkdoc opt">,</span> viewer_editable<span class="gtkdoc opt">,</span> G_TYPE_OBJECT<span class="gtkdoc opt">);</span>
+<span class="gtkdoc kwb">static void</span>
+<span class="function">viewer_editable_default_init</span> <span class="gtkdoc opt">(</span>ViewerEditableInterface <span class="gtkdoc opt">*</span>iface<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+    <span class="comment">/* add properties and signals to the interface here */</span>
+<span class="gtkdoc opt">}</span>
+<span class="gtkdoc kwb">void</span>
+<span class="function">viewer_editable_save</span> <span class="gtkdoc opt">(</span>ViewerEditable  <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                      GError         <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  ViewerEditableInterface <span class="gtkdoc opt">*</span>iface<span class="gtkdoc opt">;</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span><span class="function">VIEWER_IS_EDITABLE</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">));</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span>error <span class="gtkdoc opt">==</span> NULL <span class="gtkdoc opt">|| *</span>error <span class="gtkdoc opt">==</span> NULL<span class="gtkdoc opt">);</span>
+  iface <span class="gtkdoc opt">=</span> <span class="function">VIEWER_EDITABLE_GET_IFACE</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">);</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span>iface<span class="gtkdoc opt">-&gt;</span>save <span class="gtkdoc opt">!=</span> NULL<span class="gtkdoc opt">);</span>
+  iface<span class="gtkdoc opt">-&gt;</span><span class="function">save</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">,</span> error<span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">}</span>
+<span class="gtkdoc kwb">void</span>
+<span class="function">viewer_editable_undo</span> <span class="gtkdoc opt">(</span>ViewerEditable <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                      guint           n_steps<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  ViewerEditableInterface <span class="gtkdoc opt">*</span>iface<span class="gtkdoc opt">;</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span><span class="function">VIEWER_IS_EDITABLE</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">));</span>
+  iface <span class="gtkdoc opt">=</span> <span class="function">VIEWER_EDITABLE_GET_IFACE</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">);</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span>iface<span class="gtkdoc opt">-&gt;</span>undo <span class="gtkdoc opt">!=</span> NULL<span class="gtkdoc opt">);</span>
+  iface<span class="gtkdoc opt">-&gt;</span><span class="function">undo</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">,</span> n_steps<span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">}</span>
+<span class="gtkdoc kwb">void</span>
+<span class="function">viewer_editable_redo</span> <span class="gtkdoc opt">(</span>ViewerEditable <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                      guint           n_steps<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  ViewerEditableInterface <span class="gtkdoc opt">*</span>iface<span class="gtkdoc opt">;</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span><span class="function">VIEWER_IS_EDITABLE</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">));</span>
+  iface <span class="gtkdoc opt">=</span> <span class="function">VIEWER_EDITABLE_GET_IFACE</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">);</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span>iface<span class="gtkdoc opt">-&gt;</span>redo <span class="gtkdoc opt">!=</span> NULL<span class="gtkdoc opt">);</span>
+  iface<span class="gtkdoc opt">-&gt;</span><span class="function">redo</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">,</span> n_steps<span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -208,7 +273,6 @@
 </div>
 </div>
 <div class="footer">
-<hr>
-          Generated by GTK-Doc V1.21.1</div>
+<hr>Generated by GTK-Doc V1.24</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/howto-signals.html CHANGED Viewed

@@ -3,12 +3,12 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>How to create and use signals: GObject Reference Manual</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
 <link rel="home" href="index.html" title="GObject Reference Manual">
 <link rel="up" href="pt02.html" title="Part IV. Tutorial">
 <link rel="prev" href="howto-interface-override.html" title="Overriding interface methods">
 <link rel="next" href="pt03.html" title="Part V. Related Tools">
-<meta name="generator" content="GTK-Doc V1.21.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.24 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -24,24 +24,24 @@
 <a name="howto-signals"></a>How to create and use signals</h2></div></div></div>
 <div class="toc"><dl class="toc"><dt><span class="sect1"><a href="howto-signals.html#howto-simple-signals">Simple use of signals</a></span></dt></dl></div>
 <p>
-    The signal system which was built in GType is pretty complex and
+    The signal system in GType is pretty complex and
     flexible: it is possible for its users to connect at runtime any
     number of callbacks (implemented in any language for which a binding
     exists)
-    <a href="#ftn.id-1.6.5.2.1" class="footnote" name="id-1.6.5.2.1"><sup class="footnote">[12]</sup></a>
+    <a href="#ftn.id-1.6.5.2.1" class="footnote" name="id-1.6.5.2.1"><sup class="footnote">[8]</sup></a>
     to any signal and to stop the emission of any signal at any
     state of the signal emission process. This flexibility makes it
-    possible to use GSignal for much more than just emit signals which
-    can be received by numerous clients.
+    possible to use GSignal for much more than just emitting signals to
+    multiple clients.
   </p>
 <div class="sect1">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 <a name="howto-simple-signals"></a>Simple use of signals</h2></div></div></div>
 <p>
-      The most basic use of signals is to implement simple event
-      notification: for example, if we have a MamanFile object, and
-      if this object has a write method, we might wish to be notified
-      whenever someone has changed something via our MamanFile instance.
+      The most basic use of signals is to implement event
+      notification. For example, given a <span class="type">ViewerFile</span> object with
+      a <code class="function">write</code> method, a signal could be emitted whenever
+      the file is changed using that method.
       The code below shows how the user can connect a callback to the
       "changed" signal.
 </p>
@@ -54,11 +54,11 @@
 3
 4
 5</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="normal">file </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="gobject-The-Base-Object-Type.html#g-object-new">g_object_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">MAMAN_FILE_TYPE</span><span class="symbol">,</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
+        <td class="listing_code"><pre class="programlisting">file <span class="gtkdoc opt">=</span> <span class="function"><a href="gobject-The-Base-Object-Type.html#g-object-new">g_object_new</a></span> <span class="gtkdoc opt">(</span>VIEWER_FILE_TYPE<span class="gtkdoc opt">,</span> NULL<span class="gtkdoc opt">);</span>
-<span class="function"><a href="gobject-Signals.html#g-signal-connect">g_signal_connect</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">file</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"changed"</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">changed_event</span><span class="symbol">),</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
+<span class="function"><a href="gobject-Signals.html#g-signal-connect">g_signal_connect</a></span> <span class="gtkdoc opt">(</span>file<span class="gtkdoc opt">,</span> <span class="string">&quot;changed&quot;</span><span class="gtkdoc opt">, (</span>GCallback<span class="gtkdoc opt">)</span> changed_event<span class="gtkdoc opt">,</span> NULL<span class="gtkdoc opt">);</span>
-<span class="function">maman_file_write</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">file</span><span class="symbol">,</span><span class="normal"> buffer</span><span class="symbol">,</span><span class="normal"> </span><span class="function">strlen</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">buffer</span><span class="symbol">));</span></pre></td>
+<span class="function">viewer_file_write</span> <span class="gtkdoc opt">(</span>file<span class="gtkdoc opt">,</span> buffer<span class="gtkdoc opt">,</span> <span class="function">strlen</span> <span class="gtkdoc opt">(</span>buffer<span class="gtkdoc opt">));</span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -67,8 +67,8 @@
 <p>
     </p>
 <p>
-      The <span class="type">MamanFile</span> signal is registered in the class_init
-      function:
+      The <span class="type">ViewerFile</span> signal is registered in the
+      <code class="function">class_init</code> function:
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -85,24 +85,24 @@
 9
 10
 11</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="normal">file_signals</span><span class="symbol">[</span><span class="normal">CHANGED</span><span class="symbol">]</span><span class="normal"> </span><span class="symbol">=</span><span class="normal"> </span>
-<span class="normal">  </span><span class="function"><a href="gobject-Signals.html#g-signal-newv">g_signal_newv</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"changed"</span><span class="symbol">,</span>
-<span class="normal">                 </span><span class="function"><a href="gobject-Type-Information.html#G-TYPE-FROM-CLASS:CAPS">G_TYPE_FROM_CLASS</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gobject_class</span><span class="symbol">),</span>
-<span class="normal">                 <a href="gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">G_SIGNAL_RUN_LAST</a> </span><span class="symbol">|</span><span class="normal"> <a href="gobject-Signals.html#G-SIGNAL-NO-RECURSE:CAPS">G_SIGNAL_NO_RECURSE</a> </span><span class="symbol">|</span><span class="normal"> <a href="gobject-Signals.html#G-SIGNAL-NO-HOOKS:CAPS">G_SIGNAL_NO_HOOKS</a></span><span class="symbol">,</span>
-<span class="normal">                 <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="comment">/* closure */</span><span class="symbol">,</span>
-<span class="normal">                 <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="comment">/* accumulator */</span><span class="symbol">,</span>
-<span class="normal">                 <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="comment">/* accumulator data */</span><span class="symbol">,</span>
-<span class="normal">                 <a href="gobject-Closures.html#g-cclosure-marshal-VOID--VOID">g_cclosure_marshal_VOID__VOID</a></span><span class="symbol">,</span>
-<span class="normal">                 <a href="gobject-Type-Information.html#G-TYPE-NONE:CAPS">G_TYPE_NONE</a> </span><span class="comment">/* return_type */</span><span class="symbol">,</span>
-<span class="normal">                 </span><span class="number">0</span><span class="normal">     </span><span class="comment">/* n_params */</span><span class="symbol">,</span>
-<span class="normal">                 <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a>  </span><span class="comment">/* param_types */</span><span class="symbol">);</span></pre></td>
+        <td class="listing_code"><pre class="programlisting">file_signals<span class="gtkdoc opt">[</span>CHANGED<span class="gtkdoc opt">] =</span>
+  <span class="function"><a href="gobject-Signals.html#g-signal-newv">g_signal_newv</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;changed&quot;</span><span class="gtkdoc opt">,</span>
+                 <span class="function"><a href="gobject-Type-Information.html#G-TYPE-FROM-CLASS:CAPS">G_TYPE_FROM_CLASS</a></span> <span class="gtkdoc opt">(</span>object_class<span class="gtkdoc opt">),</span>
+                 G_SIGNAL_RUN_LAST <span class="gtkdoc opt">|</span> G_SIGNAL_NO_RECURSE <span class="gtkdoc opt">|</span> G_SIGNAL_NO_HOOKS<span class="gtkdoc opt">,</span>
+                 NULL <span class="comment">/* closure */</span><span class="gtkdoc opt">,</span>
+                 NULL <span class="comment">/* accumulator */</span><span class="gtkdoc opt">,</span>
+                 NULL <span class="comment">/* accumulator data */</span><span class="gtkdoc opt">,</span>
+                 NULL <span class="comment">/* C marshaller */</span><span class="gtkdoc opt">,</span>
+                 G_TYPE_NONE <span class="comment">/* return_type */</span><span class="gtkdoc opt">,</span>
+                 <span class="number">0</span>     <span class="comment">/* n_params */</span><span class="gtkdoc opt">,</span>
+                 NULL  <span class="comment">/* param_types */</span><span class="gtkdoc opt">);</span></pre></td>
       </tr>
     </tbody>
   </table>
 </div>
 <p>
-      and the signal is emitted in <code class="function">maman_file_write</code>:
+      and the signal is emitted in <code class="function">viewer_file_write</code>:
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -117,52 +117,59 @@
 7
 8
 9
-10</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="type">void</span>
-<span class="function">maman_file_write</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanFile</span><span class="normal">    </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span>
-<span class="normal">                  </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">guchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">buffer</span><span class="symbol">,</span>
-<span class="normal">                  </span><span class="usertype">gssize</span><span class="normal">        size</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="comment">/* First write data. */</span>
+10
+11
+12
+13</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">void</span>
+<span class="function">viewer_file_write</span> <span class="gtkdoc opt">(</span>ViewerFile   <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span>
+                   <span class="gtkdoc kwb">const</span> guint8 <span class="gtkdoc opt">*</span>buffer<span class="gtkdoc opt">,</span>
+                   gsize         size<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span><span class="function">VIEWER_IS_FILE</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">));</span>
+  <span class="function"><a href="../glib/glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a></span> <span class="gtkdoc opt">(</span>buffer <span class="gtkdoc opt">!=</span> NULL <span class="gtkdoc opt">||</span> size <span class="gtkdoc opt">==</span> <span class="number">0</span><span class="gtkdoc opt">);</span>
+  <span class="comment">/* First write data. */</span>
-<span class="normal">  </span><span class="comment">/* Then, notify user of data written. */</span>
-<span class="normal">  </span><span class="function"><a href="gobject-Signals.html#g-signal-emit">g_signal_emit</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> file_signals</span><span class="symbol">[</span><span class="normal">CHANGED</span><span class="symbol">],</span><span class="normal"> </span><span class="number">0</span><span class="normal"> </span><span class="comment">/* details */</span><span class="symbol">);</span>
-<span class="cbracket">}</span></pre></td>
+  <span class="comment">/* Then, notify user of data written. */</span>
+  <span class="function"><a href="gobject-Signals.html#g-signal-emit">g_signal_emit</a></span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">,</span> file_signals<span class="gtkdoc opt">[</span>CHANGED<span class="gtkdoc opt">],</span> <span class="number">0</span> <span class="comment">/* details */</span><span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
 </div>
 <p>
-      As shown above, you can safely set the details parameter to zero if
-      you do not know what it can be used for. For a discussion of what you
-      could used it for, see <a class="xref" href="signal.html#signal-detail" title="The detail argument">the section called “The <span class="emphasis"><em>detail</em></span> argument”</a>
+      As shown above, the details parameter can safely be set to zero if no
+      detail needs to be conveyed. For a discussion of what it can be used for,
+      see <a class="xref" href="signal.html#signal-detail" title="The detail argument">the section called “The <span class="emphasis"><em>detail</em></span> argument”</a>
     </p>
 <p>
-      The signature of the signal handler in the above example is defined as
-      <code class="function">g_cclosure_marshal_VOID__VOID</code>. Its name follows
-      a simple convention which encodes the function parameter and return value
-      types in the function name. Specifically, the value in front of the
-      double underscore is the type of the return value, while the value(s)
-      after the double underscore denote the parameter types.
+      The C signal marshaller should always be <code class="literal">NULL</code>, in which
+      case the best marshaller for the given closure type will be chosen by
+      GLib. This may be an internal marshaller specific to the closure type, or
+      <code class="function">g_cclosure_marshal_generic</code>, which implements generic
+      conversion of arrays of parameters to C callback invocations. GLib used to
+      require the user to write or generate a type-specific marshaller and pass
+      that, but that has been deprecated in favour of automatic selection of
+      marshallers.
     </p>
 <p>
-      The header <code class="filename">gobject/gmarshal.h</code> defines a set of
-      commonly needed closures that one can use. If you want to have complex
-      marshallers for your signals you should probably use glib-genmarshal
-      to autogenerate them from a file containing their return and
-      parameter types.
+      Note that <code class="function">g_cclosure_marshal_generic</code> is slower than
+      non-generic marshallers, so should be avoided for performance critical
+      code. However, performance critical code should rarely be using signals
+      anyway, as emitting a signal blocks on emitting it to all listeners, which
+      has potentially unbounded cost.
     </p>
 </div>
 <div class="footnotes">
 <br><hr style="width:100; text-align:left;margin-left: 0">
-<div id="ftn.id-1.6.5.2.1" class="footnote"><p><a href="#id-1.6.5.2.1" class="para"><sup class="para">[12] </sup></a>A Python callback can be connected to any signal on any
+<div id="ftn.id-1.6.5.2.1" class="footnote"><p><a href="#id-1.6.5.2.1" class="para"><sup class="para">[8] </sup></a>A Python callback can be connected to any signal on any
       C-based GObject, and vice versa, assuming that the Python object
       inherits from GObject.</p></div>
 </div>
 </div>
 <div class="footer">
-<hr>
-          Generated by GTK-Doc V1.21.1</div>
+<hr>Generated by GTK-Doc V1.24</div>
 </body>
 </html>