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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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>