docs/reference/gobject/html/howto-gobject-code.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Boilerplate code: GObject Reference Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
   9 <link rel="prev" href="howto-gobject.html" title="How to define and implement a new GObject">
  10 <link rel="next" href="howto-gobject-construction.html" title="Object construction">
  11 <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="howto-gobject.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="howto-gobject.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="howto-gobject-construction.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="sect1">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="howto-gobject-code"></a>Boilerplate code</h2></div></div></div>
  25 <p>
  26       In your code, the first step is to <code class="function">#include</code> the
  27       needed headers:
  28 </p>
  29 <div class="informalexample">
  30   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
  31     <tbody>
  32       <tr>
  33         <td class="listing_lines" align="right"><pre>1
  34 2
  35 3
  36 4
  37 5
  38 6
  39 7
  40 8
  41 9
  42 10
  43 11
  44 12
  45 13
  46 14
  47 15</pre></td>
  48         <td class="listing_code"><pre class="programlisting"><span class="comment">/*</span>
  49 <span class="comment"> * Copyright information</span>
  50 <span class="comment"> */</span>
  51
  52 <span class="gtkdoc ppc">#include</span> <span class="gtkdoc pps">&quot;viewer-file.h&quot;</span><span class="gtkdoc ppc"></span>
  53
  54 <span class="comment">/* Private structure definition. */</span>
  55 <span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> <span class="gtkdoc opt">{</span>
  56   gchar <span class="gtkdoc opt">*</span>filename<span class="gtkdoc opt">;</span>
  57   <span class="comment">/* stuff */</span>
  58 <span class="gtkdoc opt">}</span> ViewerFilePrivate<span class="gtkdoc opt">;</span>
  59
  60 <span class="comment">/* </span>
  61 <span class="comment"> * forward definitions</span>
  62 <span class="comment"> */</span></pre></td>
  63       </tr>
  64     </tbody>
  65   </table>
  66 </div>
  67
  68 <p>
  69     </p>
  70 <p>
  71       If the class is being declared as final using
  72       <code class="function">G_DECLARE_FINAL_TYPE</code>, its instance structure should
  73       be defined in the C file:
  74 </p>
  75 <div class="informalexample">
  76   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
  77     <tbody>
  78       <tr>
  79         <td class="listing_lines" align="right"><pre>1
  80 2
  81 3
  82 4
  83 5
  84 6</pre></td>
  85         <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">struct</span> _ViewerFile
  86 <span class="gtkdoc opt">{</span>
  87   GObject parent_instance<span class="gtkdoc opt">;</span>
  88
  89   <span class="comment">/* Other members, including private data. */</span>
  90 <span class="gtkdoc opt">}</span></pre></td>
  91       </tr>
  92     </tbody>
  93   </table>
  94 </div>
  95
  96 <p>
  97     </p>
  98 <p>
  99       Call the <code class="function">G_DEFINE_TYPE</code> macro (or
 100       <code class="function">G_DEFINE_TYPE_WITH_PRIVATE</code> if your class needs
 101       private data — final types do <span class="emphasis"><em>not</em></span> need private data)
 102       using the name
 103       of the type, the prefix of the functions and the parent GType to
 104       reduce the amount of boilerplate needed. This macro will:
 105
 106       </p>
 107 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 108 <li class="listitem">implement the <code class="function">viewer_file_get_type</code>
 109         function</li>
 110 <li class="listitem">define a parent class pointer accessible from
 111         the whole .c file</li>
 112 <li class="listitem">add private instance data to the type (if using
 113         <code class="function">G_DEFINE_TYPE_WITH_PRIVATE</code>)</li>
 114 </ul></div>
 115 <p>
 116     </p>
 117 <p>
 118       If the class has been declared as final using
 119       <code class="function">G_DECLARE_FINAL_TYPE</code> (see
 120       <a class="xref" href="howto-gobject.html#howto-gobject-header" title="Boilerplate header code">the section called “Boilerplate header code”</a>), private data should be placed in
 121       the instance structure, <span class="type">ViewerFile</span>, and
 122       <code class="function">G_DEFINE_TYPE</code> should be used instead of
 123       <code class="function">G_DEFINE_TYPE_WITH_PRIVATE</code>. The instance structure
 124       for a final class is not exposed publicly, and is not embedded in the
 125       instance structures of any derived classes (because the class is final);
 126       so its size can vary without causing incompatibilities for code which uses
 127       the class. Conversely, private data for derivable classes
 128       <span class="emphasis"><em>must</em></span> be included in a private structure, and
 129       <code class="function">G_DEFINE_TYPE_WITH_PRIVATE</code> must be used.
 130
 131 </p>
 132 <div class="informalexample">
 133   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 134     <tbody>
 135       <tr>
 136         <td class="listing_lines" align="right"><pre>1</pre></td>
 137         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="gobject-Type-Information.html#G-DEFINE-TYPE:CAPS">G_DEFINE_TYPE</a></span> <span class="gtkdoc opt">(</span>ViewerFile<span class="gtkdoc opt">,</span> viewer_file<span class="gtkdoc opt">,</span> G_TYPE_OBJECT<span class="gtkdoc opt">)</span></pre></td>
 138       </tr>
 139     </tbody>
 140   </table>
 141 </div>
 142
 143 <p>
 144 or
 145 </p>
 146 <div class="informalexample">
 147   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 148     <tbody>
 149       <tr>
 150         <td class="listing_lines" align="right"><pre>1</pre></td>
 151         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="gobject-Type-Information.html#G-DEFINE-TYPE-WITH-PRIVATE:CAPS">G_DEFINE_TYPE_WITH_PRIVATE</a></span> <span class="gtkdoc opt">(</span>ViewerFile<span class="gtkdoc opt">,</span> viewer_file<span class="gtkdoc opt">,</span> G_TYPE_OBJECT<span class="gtkdoc opt">)</span></pre></td>
 152       </tr>
 153     </tbody>
 154   </table>
 155 </div>
 156
 157 <p>
 158     </p>
 159 <p>
 160       It is also possible to use the
 161       <code class="function">G_DEFINE_TYPE_WITH_CODE</code> macro to control the
 162       <code class="function">get_type</code> function implementation — for instance, to
 163       add a call to the <code class="function">G_IMPLEMENT_INTERFACE</code> macro to
 164       implement an interface.
 165     </p>
 166 </div>
 167 <div class="footer">
 168 <hr>Generated by GTK-Doc V1.25.1</div>
 169 </body>
 170 </html>