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

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>