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

glib2 3.0.7-x86-mingw32 → 3.0.8-x86-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 (1058) hide show

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

@@ -3,12 +3,12 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>Object methods: 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="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="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.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">
@@ -45,10 +45,10 @@
     </p>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="id-1.6.3.7.3"></a>Non-virtual public methods</h3></div></div></div>
+<a name="non-virtual-public-methods"></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
+        These are the simplest, providing a simple method which
+        acts on the object. Provide a function
         prototype in the header and an implementation of that prototype
         in the source file.
 </p>
@@ -66,18 +66,24 @@
 8
 9
 10
-11</pre></td>
+11
+12
+13
+14</pre></td>
         <td class="listing_code"><pre class="programlisting"><span class="comment">/* declaration in the header. */</span>
-<span class="type">void</span><span class="normal"> </span><span class="function">maman_bar_do_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
+<span class="gtkdoc kwb">void</span> <span class="function">viewer_file_open</span> <span class="gtkdoc opt">(</span>ViewerFile  <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="comment">/* implementation in the source file */</span>
-<span class="type">void</span>
-<span class="function">maman_bar_do_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</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_BAR</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">));</span>
+<span class="gtkdoc kwb">void</span>
+<span class="function">viewer_file_open</span> <span class="gtkdoc opt">(</span>ViewerFile  <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>
+  <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>error <span class="gtkdoc opt">==</span> NULL <span class="gtkdoc opt">|| *</span>error <span class="gtkdoc opt">==</span> NULL<span class="gtkdoc opt">);</span>
-<span class="normal">  </span><span class="comment">/* do stuff here. */</span>
-<span class="cbracket">}</span></pre></td>
+  <span class="comment">/* do stuff here. */</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -88,13 +94,38 @@
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="id-1.6.3.7.4"></a>Virtual public methods</h3></div></div></div>
+<a name="virtual-public-methods"></a>Virtual public methods</h3></div></div></div>
+<p>
+        This is the preferred way to create GObjects with overridable methods:
+        </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>
+            Define the common method and its virtual function in the
+            class structure in the public header
+          </p></li>
+<li class="listitem"><p>
+            Define the common method in the header file and implement it in the
+            source file
+          </p></li>
+<li class="listitem"><p>
+            Implement a base version of the virtual function in the source
+            file and initialize the virtual function pointer to this
+            implementation in the object’s <code class="function">class_init</code>
+            function; or leave it as <code class="constant">NULL</code> for a ‘pure
+            virtual’ method which must be overridden by derived classes
+          </p></li>
+<li class="listitem"><p>
+            Re-implement the virtual function in each derived class which needs
+            to override it
+          </p></li>
+</ul></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>
+<p>
+        Note that virtual functions can only be defined if the class is
+        derivable, declared using
+        <a class="link" href="gobject-Type-Information.html#G-DECLARE-DERIVABLE-TYPE:CAPS" title="G_DECLARE_DERIVABLE_TYPE()"><code class="function">G_DECLARE_DERIVABLE_TYPE</code></a>
+        so the class structure can be defined.
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -118,42 +149,75 @@
 16
 17
 18
-19</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="comment">/* declaration in maman-bar.h. */</span>
-<span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanBarClass</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="usertype">GObjectClass</span><span class="normal"> parent_class</span><span class="symbol">;</span>
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="comment">/* declaration in viewer-file.h. */</span>
+<span class="gtkdoc ppc">#define VIEWER_TYPE_FILE viewer_file_get_type ()</span>
+<span class="function"><a href="gobject-Type-Information.html#G-DECLARE-DERIVABLE-TYPE:CAPS">G_DECLARE_DERIVABLE_TYPE</a></span> <span class="gtkdoc opt">(</span>ViewerFile<span class="gtkdoc opt">,</span> viewer_file<span class="gtkdoc opt">,</span> VIEWER<span class="gtkdoc opt">,</span> <span class="gtkdoc kwb">FILE</span><span class="gtkdoc opt">,</span> GObject<span class="gtkdoc opt">)</span>
+<span class="gtkdoc kwb">struct</span> _ViewerFileClass
+<span class="gtkdoc opt">{</span>
+  GObjectClass parent_class<span class="gtkdoc opt">;</span>
+  <span class="comment">/* stuff */</span>
+  <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>open<span class="gtkdoc opt">) (</span>ViewerFile  <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="comment">/* Padding to allow adding up to 12 new virtual functions without</span>
+<span class="comment">   * breaking ABI. */</span>
+  gpointer padding<span class="gtkdoc opt">[</span><span class="number">12</span><span class="gtkdoc opt">];</span>
+<span class="gtkdoc opt">};</span>
-<span class="normal">  </span><span class="comment">/* stuff */</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">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
-<span class="cbracket">}</span><span class="symbol">;</span>
+<span class="gtkdoc kwb">void</span> <span class="function">viewer_file_open</span> <span class="gtkdoc opt">(</span>ViewerFile  <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="type">void</span><span class="normal"> </span><span class="function">maman_bar_do_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
+<span class="comment">/* implementation in viewer-file.c */</span>
+<span class="gtkdoc kwb">void</span>
+<span class="function">viewer_file_open</span> <span class="gtkdoc opt">(</span>ViewerFile  <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>
+  ViewerFileClass <span class="gtkdoc opt">*</span>klass<span class="gtkdoc opt">;</span>
-<span class="comment">/* implementation in maman-bar.c */</span>
-<span class="type">void</span>
-<span class="function">maman_bar_do_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</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_BAR</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">));</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>error <span class="gtkdoc opt">==</span> NULL <span class="gtkdoc opt">|| *</span>error <span class="gtkdoc opt">==</span> NULL<span class="gtkdoc opt">);</span>
-<span class="normal">  </span><span class="function">MAMAN_BAR_GET_CLASS</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="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
-<span class="cbracket">}</span></pre></td>
+  klass <span class="gtkdoc opt">=</span> <span class="function">VIEWER_FILE_GET_CLASS</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>klass<span class="gtkdoc opt">-&gt;</span>open <span class="gtkdoc opt">!=</span> NULL<span class="gtkdoc opt">);</span>
+  klass<span class="gtkdoc opt">-&gt;</span><span class="function">open</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">,</span> error<span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
 </div>
 <p>
-        The code above simply redirects the do_action call to the relevant
-        class function.
+        The code above simply redirects the <code class="function">open</code> call
+        to the relevant virtual function.
       </p>
 <p>
-        Please, note that it is possible for you to provide a default
+        It is possible 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.
+        <code class="function">klass-&gt;open</code> field to a pointer to the
+        actual implementation.
         By default, class methods that are not inherited are initialized to
-        NULL, and thus are to be considered "pure virtual".
+        <code class="function">NULL</code>, and thus are to be considered "pure virtual".
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -202,51 +266,69 @@
 41
 42
 43
-44</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
-<span class="function">maman_bar_real_do_action_two</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="comment">/* Default implementation for the virtual method. */</span>
-<span class="cbracket">}</span>
-<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
-<span class="function">maman_bar_class_init</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">BarClass</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">klass</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="comment">/* this is not necessary, except for demonstration purposes.</span>
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">static void</span>
+<span class="function">viewer_file_real_close</span> <span class="gtkdoc opt">(</span>ViewerFile  <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>
+  <span class="comment">/* Default implementation for the virtual method. */</span>
+<span class="gtkdoc opt">}</span>
+<span class="gtkdoc kwb">static void</span>
+<span class="function">viewer_file_class_init</span> <span class="gtkdoc opt">(</span>ViewerFileClass <span class="gtkdoc opt">*</span>klass<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  <span class="comment">/* this is not necessary, except for demonstration purposes.</span>
 <span class="comment">   *</span>
 <span class="comment">   * pure virtual method: mandates implementation in children.</span>
 <span class="comment">   */</span>
-<span class="normal">  klass</span><span class="symbol">-&gt;</span><span class="normal">do_action_one </span><span class="symbol">=</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
+  klass<span class="gtkdoc opt">-&gt;</span>open <span class="gtkdoc opt">=</span> NULL<span class="gtkdoc opt">;</span>
+  <span class="comment">/* merely virtual method. */</span>
+  klass<span class="gtkdoc opt">-&gt;</span>close <span class="gtkdoc opt">=</span> viewer_file_real_close<span class="gtkdoc opt">;</span>
+<span class="gtkdoc opt">}</span>
-<span class="normal">  </span><span class="comment">/* merely virtual method. */</span>
-<span class="normal">  klass</span><span class="symbol">-&gt;</span><span class="normal">do_action_two </span><span class="symbol">=</span><span class="normal"> maman_bar_real_do_action_two</span><span class="symbol">;</span>
-<span class="cbracket">}</span>
+<span class="gtkdoc kwb">void</span>
+<span class="function">viewer_file_open</span> <span class="gtkdoc opt">(</span>ViewerFile  <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>
+  ViewerFileClass <span class="gtkdoc opt">*</span>klass<span class="gtkdoc opt">;</span>
-<span class="type">void</span>
-<span class="function">maman_bar_do_action_one</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</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_BAR</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">));</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>error <span class="gtkdoc opt">==</span> NULL <span class="gtkdoc opt">|| *</span>error <span class="gtkdoc opt">==</span> NULL<span class="gtkdoc opt">);</span>
-<span class="normal">  </span><span class="comment">/* if the method is purely virtual, then it is a good idea to</span>
+  klass <span class="gtkdoc opt">=</span> <span class="function">VIEWER_FILE_GET_CLASS</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">);</span>
+  <span class="comment">/* if the method is purely virtual, then it is a good idea to</span>
 <span class="comment">   * check that it has been overridden before calling it, and,</span>
 <span class="comment">   * depending on the intent of the class, either ignore it silently</span>
 <span class="comment">   * or warn the user.</span>
-<span class="comment">   /</span>
-<span class="comment">  if (MAMAN_BAR_GET_CLASS (self)-&gt;do_action_one != NULL)</span>
-<span class="comment">    MAMAN_BAR_GET_CLASS (self)-&gt;do_action_one (self, /* parameters */</span><span class="symbol">);</span>
-<span class="normal">  </span><span class="keyword">else</span>
-<span class="normal">    </span><span class="function"><a href="../glib/glib-Message-Logging.html#g-warning">g_warning</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Class '%s' does not override the mandatory "</span>
-<span class="normal">               </span><span class="string">"MamanBarClass.do_action_one() virtual function."</span><span class="symbol">,</span>
-<span class="normal">               </span><span class="function"><a href="gobject-The-Base-Object-Type.html#G-OBJECT-TYPE-NAME:CAPS">G_OBJECT_TYPE_NAME</a></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_bar_do_action_two</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</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_BAR</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_BAR_GET_CLASS</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">)-&gt;</span><span class="function">do_action_two</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
-<span class="cbracket">}</span></pre></td>
+<span class="comment">   */</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>klass<span class="gtkdoc opt">-&gt;</span>open <span class="gtkdoc opt">!=</span> NULL<span class="gtkdoc opt">);</span>
+  klass<span class="gtkdoc opt">-&gt;</span><span class="function">open</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_file_close</span> <span class="gtkdoc opt">(</span>ViewerFile  <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>
+  ViewerFileClass <span class="gtkdoc opt">*</span>klass<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>error <span class="gtkdoc opt">==</span> NULL <span class="gtkdoc opt">|| *</span>error <span class="gtkdoc opt">==</span> NULL<span class="gtkdoc opt">);</span>
+  klass <span class="gtkdoc opt">=</span> <span class="function">VIEWER_FILE_GET_CLASS</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">);</span>
+  <span class="keyword">if</span> <span class="gtkdoc opt">(</span>klass<span class="gtkdoc opt">-&gt;</span>close <span class="gtkdoc opt">!=</span> NULL<span class="gtkdoc opt">)</span>
+    klass<span class="gtkdoc opt">-&gt;</span><span class="function">close</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">,</span> error<span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -257,11 +339,12 @@
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="id-1.6.3.7.5"></a>Virtual private Methods</h3></div></div></div>
+<a name="virtual-private-methods"></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:
+        These are very similar to <a class="link" href="howto-gobject-methods.html#virtual-public-methods" title="Virtual public methods">virtual
+        public methods</a>. They just don't
+        have a public function to call directly. The header
+        file contains only a declaration of the virtual function:
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -276,24 +359,42 @@
 7
 8
 9
-10</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="comment">/* declaration in maman-bar.h. */</span>
-<span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanBarClass</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="usertype">GObjectClass</span><span class="normal"> parent</span><span class="symbol">;</span>
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="comment">/* declaration in viewer-file.h. */</span>
+<span class="gtkdoc kwb">struct</span> _ViewerFileClass
+<span class="gtkdoc opt">{</span>
+  GObjectClass parent<span class="gtkdoc opt">;</span>
-<span class="normal">  </span><span class="comment">/* stuff */</span>
-<span class="normal">  </span><span class="type">void</span><span class="normal"> </span><span class="symbol">(*</span><span class="normal"> helper_do_specific_action</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
-<span class="cbracket">}</span><span class="symbol">;</span>
+  <span class="comment">/* Public virtual method as before. */</span>
+  <span class="gtkdoc kwb">void</span>     <span class="gtkdoc opt">(*</span>open<span class="gtkdoc opt">)           (</span>ViewerFile  <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="type">void</span><span class="normal"> </span><span class="function">maman_bar_do_any_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span></pre></td>
+  <span class="comment">/* Private helper function to work out whether the file can be loaded via</span>
+<span class="comment">   * memory mapped I/O, or whether it has to be read as a stream. */</span>
+  <span class="function"><a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a></span> <span class="gtkdoc opt">(*</span>can_memory_map<span class="gtkdoc opt">) (</span>ViewerFile <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">);</span>
+  <span class="comment">/* Padding to allow adding up to 12 new virtual functions without</span>
+<span class="comment">   * breaking ABI. */</span>
+  gpointer padding<span class="gtkdoc opt">[</span><span class="number">12</span><span class="gtkdoc opt">];</span>
+<span class="gtkdoc opt">};</span>
+<span class="gtkdoc kwb">void</span> <span class="function">viewer_file_open</span> <span class="gtkdoc opt">(</span>ViewerFile <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">,</span> GError <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span></pre></td>
       </tr>
     </tbody>
   </table>
 </div>
 <p>
-        These class functions are often used to delegate part of the job
+        These virtual functions are often used to delegate part of the job
         to child classes:
 </p>
 <div class="informalexample">
@@ -320,28 +421,40 @@
 18
 19
 20
-21</pre></td>
+21
+22
+23
+24
+25
+26
+27</pre></td>
         <td class="listing_code"><pre class="programlisting"><span class="comment">/* this accessor function is static: it is not exported outside of this file. */</span>
-<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span><span class="normal"> </span>
-<span class="function">maman_bar_do_specific_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="function">MAMAN_BAR_GET_CLASS</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">)-&gt;</span><span class="function">do_specific_action</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
-<span class="cbracket">}</span>
-<span class="type">void</span>
-<span class="function">maman_bar_do_any_action</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="comment">/* random code here */</span>
-<span class="normal">  </span><span class="comment">/* </span>
-<span class="comment">   * Try to execute the requested action. Maybe the requested action</span>
-<span class="comment">   * cannot be implemented here. So, we delegate its implementation</span>
-<span class="comment">   * to the child class:</span>
-<span class="comment">   */</span>
-<span class="normal">  </span><span class="function">maman_bar_do_specific_action</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">self</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* parameters */</span><span class="symbol">);</span>
+<span class="gtkdoc kwb">static</span> gboolean
+<span class="function">viewer_file_can_memory_map</span> <span class="gtkdoc opt">(</span>ViewerFile <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  <span class="keyword">return</span> <span class="function">VIEWER_FILE_GET_CLASS</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">)-&gt;</span><span class="function">can_memory_map</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">);</span>
+<span class="gtkdoc opt">}</span>
-<span class="normal">  </span><span class="comment">/* other random code here */</span>
-<span class="cbracket">}</span></pre></td>
+<span class="gtkdoc kwb">void</span>
+<span class="function">viewer_file_open</span> <span class="gtkdoc opt">(</span>ViewerFile  <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>
+  <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>error <span class="gtkdoc opt">==</span> NULL <span class="gtkdoc opt">|| *</span>error <span class="gtkdoc opt">==</span> NULL<span class="gtkdoc opt">);</span>
+  <span class="comment">/*</span>
+<span class="comment">   * Try to load the file using memory mapped I/O, if the implementation of the</span>
+<span class="comment">   * class determines that is possible using its private virtual method.</span>
+<span class="comment">   */</span>
+  <span class="keyword">if</span> <span class="gtkdoc opt">(</span><span class="function">viewer_file_can_memory_map</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">))</span>
+    <span class="gtkdoc opt">{</span>
+      <span class="comment">/* Load the file using memory mapped I/O. */</span>
+    <span class="gtkdoc opt">}</span>
+  <span class="keyword">else</span>
+    <span class="gtkdoc opt">{</span>
+      <span class="comment">/* Fall back to trying to load the file using streaming I/O… */</span>
+    <span class="gtkdoc opt">}</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -351,7 +464,7 @@
       </p>
 <p>
         Again, it is possible to provide a default implementation for this
-        private virtual class function:
+        private virtual function:
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -365,16 +478,26 @@
 6
 7
 8
-9</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
-<span class="function">maman_bar_class_init</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBarClass</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">klass</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="comment">/* pure virtual method: mandates implementation in children. */</span>
-<span class="normal">  klass</span><span class="symbol">-&gt;</span><span class="normal">do_specific_action_one </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="normal">  </span><span class="comment">/* merely virtual method. */</span>
-<span class="normal">  klass</span><span class="symbol">-&gt;</span><span class="normal">do_specific_action_two </span><span class="symbol">=</span><span class="normal"> maman_bar_real_do_specific_action_two</span><span class="symbol">;</span>
-<span class="cbracket">}</span></pre></td>
+9
+10
+11
+12
+13
+14</pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">static</span> gboolean
+<span class="function">viewer_file_real_can_memory_map</span> <span class="gtkdoc opt">(</span>ViewerFile <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  <span class="comment">/* As an example, always return false. Or, potentially return true if the</span>
+<span class="comment">   * file is local. */</span>
+  <span class="keyword">return</span> FALSE<span class="gtkdoc opt">;</span>
+<span class="gtkdoc opt">}</span>
+<span class="gtkdoc kwb">static void</span>
+<span class="function">viewer_file_class_init</span> <span class="gtkdoc opt">(</span>ViewerFileClass <span class="gtkdoc opt">*</span>klass<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  <span class="comment">/* non-pure virtual method; does not have to be implemented in children. */</span>
+  klass<span class="gtkdoc opt">-&gt;</span>can_memory_map <span class="gtkdoc opt">=</span> viewer_file_real_can_memory_map<span class="gtkdoc opt">;</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -383,7 +506,7 @@
 <p>
       </p>
 <p>
-        Children can then implement the subclass with code such as:
+        Derived classes can then override the method with code such as:
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -397,14 +520,14 @@
 6
 7
 8</pre></td>
-        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
-<span class="function">maman_bar_subtype_class_init</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBarSubTypeClass</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">klass</span><span class="symbol">)</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="usertype">MamanBarClass</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">bar_class </span><span class="symbol">=</span><span class="normal"> </span><span class="function">MAMAN_BAR_CLASS</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">klass</span><span class="symbol">);</span>
-<span class="normal">  </span><span class="comment">/* implement pure virtual class function. */</span>
-<span class="normal">  bar_class</span><span class="symbol">-&gt;</span><span class="normal">do_specific_action_one </span><span class="symbol">=</span><span class="normal"> maman_bar_subtype_do_specific_action_one</span><span class="symbol">;</span>
-<span class="cbracket">}</span></pre></td>
+        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">static void</span>
+<span class="function">viewer_audio_file_class_init</span> <span class="gtkdoc opt">(</span>ViewerAudioFileClass <span class="gtkdoc opt">*</span>klass<span class="gtkdoc opt">)</span>
+<span class="gtkdoc opt">{</span>
+  ViewerFileClass <span class="gtkdoc opt">*</span>file_class <span class="gtkdoc opt">=</span> <span class="function">VIEWER_FILE_CLASS</span> <span class="gtkdoc opt">(</span>klass<span class="gtkdoc opt">);</span>
+  <span class="comment">/* implement pure virtual function. */</span>
+  file_class<span class="gtkdoc opt">-&gt;</span>can_memory_map <span class="gtkdoc opt">=</span> viewer_audio_file_can_memory_map<span class="gtkdoc opt">;</span>
+<span class="gtkdoc opt">}</span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -415,7 +538,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>