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.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 a new GObject: 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="pt02.html" title="Part IV. Tutorial">
 <link rel="next" href="howto-gobject-code.html" title="Boilerplate code">
-<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">
@@ -25,22 +25,27 @@
 <div class="toc"><dl class="toc">
 <dt><span class="sect1"><a href="howto-gobject.html#howto-gobject-header">Boilerplate header code</a></span></dt>
 <dt><span class="sect1"><a href="howto-gobject-code.html">Boilerplate code</a></span></dt>
-<dt><span class="sect1"><a href="howto-gobject-construction.html">Object Construction</a></span></dt>
-<dt><span class="sect1"><a href="howto-gobject-destruction.html">Object Destruction</a></span></dt>
+<dt><span class="sect1"><a href="howto-gobject-construction.html">Object construction</a></span></dt>
+<dt><span class="sect1"><a href="howto-gobject-destruction.html">Object destruction</a></span></dt>
 <dt><span class="sect1"><a href="howto-gobject-methods.html">Object methods</a></span></dt>
 <dd><dl>
-<dt><span class="sect2"><a href="howto-gobject-methods.html#id-1.6.3.7.3">Non-virtual public methods</a></span></dt>
-<dt><span class="sect2"><a href="howto-gobject-methods.html#id-1.6.3.7.4">Virtual public methods</a></span></dt>
-<dt><span class="sect2"><a href="howto-gobject-methods.html#id-1.6.3.7.5">Virtual private Methods</a></span></dt>
+<dt><span class="sect2"><a href="howto-gobject-methods.html#non-virtual-public-methods">Non-virtual public methods</a></span></dt>
+<dt><span class="sect2"><a href="howto-gobject-methods.html#virtual-public-methods">Virtual public methods</a></span></dt>
+<dt><span class="sect2"><a href="howto-gobject-methods.html#virtual-private-methods">Virtual private Methods</a></span></dt>
 </dl></dd>
 <dt><span class="sect1"><a href="howto-gobject-chainup.html">Chaining up</a></span></dt>
 </dl></div>
 <p>
-    Clearly, this is one of the most common questions people ask: they just
-    want to crank code and implement a subclass of a GObject. Sometimes because
-    they want to create their own class hierarchy, sometimes because they want
-    to subclass one of GTK+'s widget. This chapter will focus on the
-    implementation of a subtype of GObject.
+    This chapter focuses on the implementation of a subtype of GObject, for
+    example to create a custom class hierarchy, or to subclass a GTK+ widget.
+  </p>
+<p>
+    Throughout the chapter, a running example of a file viewer program is used,
+    which has a <span class="type">ViewerFile</span> class to represent a single file being
+    viewed, and various derived classes for different types of files with
+    special functionality, such as audio files. The example application also
+    supports editing files (for example, to tweak a photo being viewed), using
+    a <span class="type">ViewerEditable</span> interface.
   </p>
 <div class="sect1">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -49,64 +54,126 @@
       The first step before writing the code for your GObject is to write the
       type's header which contains the needed type, function and macro
       definitions. Each of these elements is nothing but a convention which
-      is followed not only by GTK+'s code but also by most users of GObject.
-      If you feel the need not to obey the rules stated below, think about it
-      twice:
-      </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>If your users are a bit accustomed to GTK+ code or any
-        GLib code, they will be a bit surprised and getting used to the
-        conventions you decided upon will take time (money) and will make them
-        grumpy (not a good thing)</p></li>
-<li class="listitem"><p>You must assess the fact that these conventions might
-        have been designed by both smart and experienced people: maybe they
-        were at least partly right. Try to put your ego aside.</p></li>
-</ul></div>
-<p>
-      It is, nevertheless, important to note that these rules generally apply
-      to code that is meant to be called by third parties; it is perfectly
-      possible to write a valid, self-contained GObject types without most of
-      the boilerplate used in this tutorial; most of the boilerplate is also
-      not strictly required if you plan to use the GObject types only through
-      language bindings based on introspection.
+      is followed by almost all users of GObject, and has been refined over
+      multiple years of experience developing GObject-based code. If you are
+      writing a library, it is particularly important for you to adhere closely
+      to these conventions; users of your library will assume that you have.
+      Even if not writing a library, it will help other people who want to work
+      on your project.
     </p>
 <p>
       Pick a name convention for your headers and source code and stick to it:
       </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem"><p>use a dash to separate the prefix from the typename:
-        <code class="filename">maman-bar.h</code> and <code class="filename">maman-bar.c</code>
+        <code class="filename">viewer-file.h</code> and <code class="filename">viewer-file.c</code>
         (this is the convention used by Nautilus and most GNOME libraries).</p></li>
 <li class="listitem"><p>use an underscore to separate the prefix from the
-        typename: <code class="filename">maman_bar.h</code> and
-        <code class="filename">maman_bar.c</code>.</p></li>
+        typename: <code class="filename">viewer_file.h</code> and
+        <code class="filename">viewer_file.c</code>.</p></li>
 <li class="listitem"><p>Do not separate the prefix from the typename:
-        <code class="filename">mamanbar.h</code> and <code class="filename">mamanbar.c</code>.
+        <code class="filename">viewerfile.h</code> and <code class="filename">viewerfile.c</code>.
         (this is the convention used by GTK+)</p></li>
 </ul></div>
 <p>
       Some people like the first two solutions better: it makes reading file
       names easier for those with poor eyesight.
     </p>
-<p>
-      When you need some private (internal) declarations in several
-      (sub)classes, you can define them in a private header file which
-      is often named by appending the <span class="emphasis"><em>private</em></span> keyword
-      to the public header name. For example, one could use
-      <code class="filename">maman-bar-private.h</code>,
-      <code class="filename">maman_bar_private.h</code> or
-      <code class="filename">mamanbarprivate.h</code>. Typically, such private header
-      files are not installed.
-    </p>
 <p>
       The basic conventions for any header which exposes a GType are described
       in <a class="xref" href="gtype-conventions.html" title="Conventions">the section called “Conventions”</a>.
     </p>
 <p>
-            If you want to declare a type named bar with prefix maman, name the type instance
-            <code class="function">MamanBar</code> and its class <code class="function">MamanBarClass</code>
-            (name is case-sensitive). It is customary to declare them with code similar to the
-            following:
+      If you want to declare a type named ‘file’ in namespace ‘viewer’, name the
+      type instance <code class="function">ViewerFile</code> and its class
+      <code class="function">ViewerFileClass</code> (names are case sensitive). The
+      recommended method of declaring a type differs based on whether the type
+      is final or derivable.
+    </p>
+<p>
+      Final types cannot be subclassed further, and should be the default choice
+      for new types — changing a final type to be derivable is always a change
+      that will be compatible with existing uses of the code, but the converse
+      will often cause problems. Final types are declared using
+      <a class="link" href="gobject-Type-Information.html#G-DECLARE-FINAL-TYPE:CAPS" title="G_DECLARE_FINAL_TYPE()"><code class="function">G_DECLARE_FINAL_TYPE</code></a>,
+      and require a structure to hold the instance data to be declared in the
+      source code (not the header file).
+</p>
+<div class="informalexample">
+  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+    <tbody>
+      <tr>
+        <td class="listing_lines" align="right"><pre>1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29</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="comment">/* inclusion guard */</span>
+<span class="gtkdoc ppc">#ifndef __VIEWER_FILE_H__</span>
+<span class="gtkdoc ppc">#define __VIEWER_FILE_H__</span>
+<span class="gtkdoc ppc">#include &lt;glib-object.h&gt;</span>
+<span class="comment">/*</span>
+<span class="comment"> * Potentially, include other headers on which this header depends.</span>
+<span class="comment"> */</span>
+G_BEGIN_DECLS
+<span class="comment">/*</span>
+<span class="comment"> * Type declaration.</span>
+<span class="comment"> */</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-FINAL-TYPE:CAPS">G_DECLARE_FINAL_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="comment">/*</span>
+<span class="comment"> * Method definitions.</span>
+<span class="comment"> */</span>
+ViewerFile <span class="gtkdoc opt">*</span><span class="function">viewer_file_new</span> <span class="gtkdoc opt">(</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>
+G_END_DECLS
+<span class="gtkdoc ppc">#endif</span> <span class="comment">/* __VIEWER_FILE_H__ */</span><span class="gtkdoc ppc"></span></pre></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+<p>
+    </p>
+<p>
+      Derivable types <span class="emphasis"><em>can</em></span> be subclassed further, and their class and
+      instance structures form part of the public API which must not be changed
+      if API stability is cared about. They are 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>:
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -153,65 +220,49 @@
 39
 40
 41
-42
-43
-44
-45
-46
-47
-48
-49
-50</pre></td>
+42</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="comment">/* inclusion guard */</span>
-<span class="preproc">#ifndef</span><span class="normal"> __MAMAN_BAR_H__</span>
-<span class="preproc">#define</span><span class="normal"> __MAMAN_BAR_H__</span>
+<span class="gtkdoc ppc">#ifndef __VIEWER_FILE_H__</span>
+<span class="gtkdoc ppc">#define __VIEWER_FILE_H__</span>
-<span class="preproc">#include</span><span class="normal"> </span><span class="string">&lt;glib-object.h&gt;</span>
+<span class="gtkdoc ppc">#include &lt;glib-object.h&gt;</span>
 <span class="comment">/*</span>
 <span class="comment"> * Potentially, include other headers on which this header depends.</span>
 <span class="comment"> */</span>
+G_BEGIN_DECLS
 <span class="comment">/*</span>
-<span class="comment"> * Type macros.</span>
+<span class="comment"> * Type declaration.</span>
 <span class="comment"> */</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_TYPE_BAR</span><span class="normal">                  </span><span class="symbol">(</span><span class="function">maman_bar_get_type</span><span class="normal"> </span><span class="symbol">())</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_BAR</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_BAR</span><span class="symbol">,</span><span class="normal"> MamanBar</span><span class="symbol">))</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_IS_BAR</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_BAR</span><span class="symbol">))</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_BAR_CLASS</span><span class="symbol">(</span><span class="normal">klass</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-CLASS-CAST:CAPS">G_TYPE_CHECK_CLASS_CAST</a></span><span class="normal"> </span><span class="symbol">((</span><span class="normal">klass</span><span class="symbol">),</span><span class="normal"> MAMAN_TYPE_BAR</span><span class="symbol">,</span><span class="normal"> MamanBarClass</span><span class="symbol">))</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_IS_BAR_CLASS</span><span class="symbol">(</span><span class="normal">klass</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-CLASS-TYPE:CAPS">G_TYPE_CHECK_CLASS_TYPE</a></span><span class="normal"> </span><span class="symbol">((</span><span class="normal">klass</span><span class="symbol">),</span><span class="normal"> MAMAN_TYPE_BAR</span><span class="symbol">))</span>
-<span class="preproc">#define</span><span class="normal"> </span><span class="function">MAMAN_BAR_GET_CLASS</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-INSTANCE-GET-CLASS:CAPS">G_TYPE_INSTANCE_GET_CLASS</a></span><span class="normal"> </span><span class="symbol">((</span><span class="normal">obj</span><span class="symbol">),</span><span class="normal"> MAMAN_TYPE_BAR</span><span class="symbol">,</span><span class="normal"> MamanBarClass</span><span class="symbol">))</span>
-<span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanBar</span><span class="normal">        MamanBar</span><span class="symbol">;</span>
-<span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanBarClass</span><span class="normal">   MamanBarClass</span><span class="symbol">;</span>
-<span class="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanBar</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="comment">/* Parent instance structure */</span>
-<span class="normal">  </span><span class="usertype">GObject</span><span class="normal"> parent_instance</span><span class="symbol">;</span>
-<span class="normal">  </span><span class="comment">/* instance members */</span>
-<span class="cbracket">}</span><span class="symbol">;</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="keyword">struct</span><span class="normal"> </span><span class="classname">_MamanBarClass</span>
-<span class="cbracket">{</span>
-<span class="normal">  </span><span class="comment">/* Parent class structure */</span>
-<span class="normal">  </span><span class="usertype">GObjectClass</span><span class="normal"> parent_class</span><span class="symbol">;</span>
+<span class="gtkdoc kwb">struct</span> _ViewerFileClass
+<span class="gtkdoc opt">{</span>
+  GObjectClass parent_class<span class="gtkdoc opt">;</span>
-<span class="normal">  </span><span class="comment">/* class members */</span>
-<span class="cbracket">}</span><span class="symbol">;</span>
+  <span class="comment">/* Class virtual function fields. */</span>
+  <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span> open<span class="gtkdoc opt">) (</span>ViewerFile  <span class="gtkdoc opt">*</span>file<span class="gtkdoc opt">,</span>
+                 GError     <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>
-<span class="comment">/* used by MAMAN_TYPE_BAR */</span>
-<span class="usertype">GType</span><span class="normal"> </span><span class="function">maman_bar_get_type</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">);</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="comment">/*</span>
 <span class="comment"> * Method definitions.</span>
 <span class="comment"> */</span>
+ViewerFile <span class="gtkdoc opt">*</span><span class="function">viewer_file_new</span> <span class="gtkdoc opt">(</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>
-<span class="preproc">#endif</span><span class="normal"> </span><span class="comment">/* __MAMAN_BAR_H__ */</span></pre></td>
+G_END_DECLS
+<span class="gtkdoc ppc">#endif</span> <span class="comment">/* __VIEWER_FILE_H__ */</span><span class="gtkdoc ppc"></span></pre></td>
       </tr>
     </tbody>
   </table>
@@ -220,31 +271,16 @@
 <p>
     </p>
 <p>
-      Finally, there are different header include conventions. Again, pick one
-      and stick to it. I personally use indifferently any of the two, depending
-      on the codebase I work on: the rule, as always, is consistency.
-      </p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>
-            Some people add at the top of their headers a number of #include
-            directives to pull in all the headers needed to compile client
-            code. This allows client code to simply #include "maman-bar.h".
-          </p></li>
-<li class="listitem"><p>
-            Other do not #include anything and expect the client to #include
-            themselves the headers they need before including your header. This
-            speeds up compilation because it minimizes the amount of
-            pre-processor work. This can be used in conjunction with the
-            re-declaration of certain unused types in the client code to
-            minimize compile-time dependencies and thus speed up compilation.
-          </p></li>
-</ul></div>
-<p>
+      The convention for header includes is to add the minimum number of
+      <code class="function">#include</code> directives to the top of your headers needed
+      to compile that header. This
+      allows client code to simply <code class="function">#include "viewer-file.h"</code>,
+      without needing to know the prerequisites for
+      <code class="filename">viewer-file.h</code>.
     </p>
 </div>
 </div>
 <div class="footer">
-<hr>
-          Generated by GTK-Doc V1.21.1</div>
+<hr>Generated by GTK-Doc V1.24</div>
 </body>
 </html>