docs/reference/gobject/html/gtype-non-instantiable-classed.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>Non-instantiable classed types: interfaces</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System">
   9 <link rel="prev" href="gtype-instantiable-classed.html" title="Instantiable classed types: objects">
  10 <link rel="next" href="chapter-gobject.html" title="The GObject base class">
  11 <meta name="generator" content="GTK-Doc V1.18 (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="2"><tr valign="middle">
  16 <td><a accesskey="p" href="gtype-instantiable-classed.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="chapter-gtype.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GObject Reference Manual</th>
  20 <td><a accesskey="n" href="chapter-gobject.html"><img src="right.png" width="24" height="24" 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="gtype-non-instantiable-classed"></a>Non-instantiable classed types: interfaces</h2></div></div></div>
  25 <p>
  26           GType's interfaces are very similar to Java's interfaces. They allow
  27           to describe a common API that several classes will adhere to.
  28           Imagine the play, pause and stop buttons on hi-fi equipment - those can
  29           be seen as a playback interface. Once you know what they do, you can
  30           control your CD player, MP3 player or anything that uses these symbols.
  31           To declare an interface you have to register a non-instantiable
  32           classed type which derives from
  33           <a class="link" href="gobject-Type-Information.html#GTypeInterface" title="struct GTypeInterface"><span class="type">GTypeInterface</span></a>. The following piece of code declares such an interface.
  34 </p>
  35 <pre class="programlisting">
  36 #define MAMAN_TYPE_IBAZ                (maman_ibaz_get_type ())
  37 #define MAMAN_IBAZ(obj)                (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_IBAZ, MamanIbaz))
  38 #define MAMAN_IS_IBAZ(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_IBAZ))
  39 #define MAMAN_IBAZ_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), MAMAN_TYPE_IBAZ, MamanIbazInterface))
  40
  41 typedef struct _MamanIbaz MamanIbaz; /* dummy object */
  42 typedef struct _MamanIbazInterface MamanIbazInterface;
  43
  44 struct _MamanIbazInterface {
  45   GTypeInterface parent;
  46
  47   void (*do_action) (MamanIbaz *self);
  48 };
  49
  50 GType maman_ibaz_get_type (void);
  51
  52 void maman_ibaz_do_action (MamanIbaz *self);
  53 </pre>
  54 <p>
  55           The interface function, <code class="function">maman_ibaz_do_action</code> is implemented
  56           in a pretty simple way:
  57 </p>
  58 <pre class="programlisting">
  59 void maman_ibaz_do_action (MamanIbaz *self)
  60 {
  61   MAMAN_IBAZ_GET_INTERFACE (self)-&gt;do_action (self);
  62 }
  63 </pre>
  64 <p>
  65          <code class="function">maman_ibaz_get_type</code> registers a type named <span class="emphasis"><em>MamanIBaz</em></span>
  66          which inherits from G_TYPE_INTERFACE. All interfaces must be children of G_TYPE_INTERFACE in the
  67          inheritance tree.
  68         </p>
  69 <p>
  70           An interface is defined by only one structure which must contain as first member
  71           a <a class="link" href="gobject-Type-Information.html#GTypeInterface" title="struct GTypeInterface"><span class="type">GTypeInterface</span></a> structure. The interface structure is expected to
  72           contain the function pointers of the interface methods. It is good style to
  73           define helper functions for each of the interface methods which simply call
  74           the interface' method directly: <code class="function">maman_ibaz_do_action</code>
  75           is one of these.
  76         </p>
  77 <p>
  78           Once an interface type is registered, you must register implementations for these
  79           interfaces. The function named <code class="function">maman_baz_get_type</code> registers
  80           a new GType named MamanBaz which inherits from <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> and which
  81           implements the interface <span class="type">MamanIBaz</span>.
  82 </p>
  83 <pre class="programlisting">
  84 static void maman_baz_do_action (MamanIbaz *self)
  85 {
  86   g_print ("Baz implementation of IBaz interface Action.\n");
  87 }
  88
  89
  90 static void
  91 baz_interface_init (gpointer         g_iface,
  92                     gpointer         iface_data)
  93 {
  94   MamanIbazInterface *iface = (MamanIbazInterface *)g_iface;
  95   iface-&gt;do_action = maman_baz_do_action;
  96 }
  97
  98 GType
  99 maman_baz_get_type (void)
 100 {
 101   static GType type = 0;
 102   if (type == 0) {
 103     const GTypeInfo info = {
 104       sizeof (MamanBazInterface),
 105       NULL,   /* base_init */
 106       NULL,   /* base_finalize */
 107       NULL,   /* class_init */
 108       NULL,   /* class_finalize */
 109       NULL,   /* class_data */
 110       sizeof (MamanBaz),
 111       0,      /* n_preallocs */
 112       NULL    /* instance_init */
 113     };
 114     const GInterfaceInfo ibaz_info = {
 115       (GInterfaceInitFunc) baz_interface_init,    /* interface_init */
 116       NULL,               /* interface_finalize */
 117       NULL          /* interface_data */
 118     };
 119     type = g_type_register_static (G_TYPE_OBJECT,
 120                                    "MamanBazType",
 121                                    &amp;info, 0);
 122     g_type_add_interface_static (type,
 123                                  MAMAN_TYPE_IBAZ,
 124                                  &amp;ibaz_info);
 125   }
 126   return type;
 127 }
 128 </pre>
 129 <p>
 130         </p>
 131 <p>
 132           <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-add-interface-static" title="g_type_add_interface_static ()">g_type_add_interface_static</a></code> records in the type system that
 133           a given type implements also <span class="type">FooInterface</span>
 134           (<code class="function">foo_interface_get_type</code> returns the type of
 135           <span class="type">FooInterface</span>).
 136                 The <a class="link" href="gobject-Type-Information.html#GInterfaceInfo" title="struct GInterfaceInfo"><span class="type">GInterfaceInfo</span></a> structure holds
 137           information about the implementation of the interface:
 138 </p>
 139 <pre class="programlisting">
 140 struct _GInterfaceInfo
 141 {
 142   GInterfaceInitFunc     interface_init;
 143   GInterfaceFinalizeFunc interface_finalize;
 144   gpointer               interface_data;
 145 };
 146 </pre>
 147 <p>
 148         </p>
 149 <p>
 150         When having no special requirements you also can use the <code class="function">G_DEFINE_INTERFACE</code> macro:
 151 </p>
 152 <pre class="programlisting">
 153 G_DEFINE_INTERFACE (MamanBaz, maman_baz, G_TYPE_OBJECT)
 154 </pre>
 155 <p>
 156         </p>
 157 <div class="sect2">
 158 <div class="titlepage"><div><div><h3 class="title">
 159 <a name="gtype-non-instantiable-classed-init"></a>Interface Initialization</h3></div></div></div>
 160 <p>
 161             When an instantiable classed type which registered an interface
 162             implementation is created for the first time, its class structure
 163             is initialized following the process
 164             described in <a class="xref" href="gtype-instantiable-classed.html" title="Instantiable classed types: objects">the section called “Instantiable classed types: objects”</a>.
 165             After that, the interface implementations associated with
 166             the type are initialized.
 167           </p>
 168 <p>
 169             First a memory buffer is allocated to hold the interface structure. The parent's
 170             interface structure is then copied over to the new interface structure (the parent
 171             interface is already initialized at that point). If there is no parent interface,
 172             the interface structure is initialized with zeros. The g_type and the g_instance_type
 173             fields are then initialized: g_type is set to the type of the most-derived interface
 174             and g_instance_type is set to the type of the most derived type which implements
 175             this interface.
 176           </p>
 177 <p>
 178             Finally, the interface' most-derived <code class="function">base_init</code> function and then
 179             the implementation's <code class="function">interface_init</code>
 180             function are invoked. It is important to understand that if there are multiple
 181             implementations of an interface the <code class="function">base_init</code> and
 182             <code class="function">interface_init</code> functions will be
 183             invoked once for each implementation initialized.
 184           </p>
 185 <p>
 186             It is thus common for base_init functions to hold a local static boolean variable
 187             which makes sure that the interface type is initialized only once even if there are
 188             multiple implementations of the interface:
 189 </p>
 190 <pre class="programlisting">
 191 static void
 192 maman_ibaz_base_init (gpointer g_iface)
 193 {
 194   static gboolean initialized = FALSE;
 195
 196   if (!initialized) {
 197     /* create interface signals here. */
 198     initialized = TRUE;
 199   }
 200 }
 201 </pre>
 202 <p>
 203           </p>
 204 <p>
 205           If you have found the stuff about interface hairy, you are right: it is hairy but
 206           there is not much I can do about it. What I can do is summarize what you need to know
 207           about interfaces:
 208         </p>
 209 <p>
 210             The above process can be summarized as follows:
 211           </p>
 212 <div class="table">
 213 <a name="ginterface-init-table"></a><p class="title"><b>Table 2. Interface Initialization</b></p>
 214 <div class="table-contents"><table summary="Interface Initialization" border="1">
 215 <colgroup>
 216 <col align="left">
 217 <col align="left">
 218 <col align="left">
 219 </colgroup>
 220 <thead><tr>
 221 <th align="left">Invocation time</th>
 222 <th align="left">Function Invoked</th>
 223 <th align="left">Function's parameters</th>
 224 <th>Remark</th>
 225 </tr></thead>
 226 <tbody>
 227 <tr>
 228 <td rowspan="2" align="left">First call to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> for type
 229                     implementing interface
 230                    </td>
 231 <td align="left">interface' base_init function</td>
 232 <td align="left">On interface' vtable</td>
 233 <td>Register interface' signals here (use a local static
 234                     boolean variable as described above to make sure not to register them
 235                     twice.).</td>
 236 </tr>
 237 <tr>
 238 <td align="left">interface' interface_init function</td>
 239 <td align="left">On interface' vtable</td>
 240 <td>
 241                     Initialize interface' implementation. That is, initialize the interface
 242                     method pointers in the interface structure to the function's implementation.
 243                   </td>
 244 </tr>
 245 </tbody>
 246 </table></div>
 247 </div>
 248 <p><br class="table-break">
 249           It is highly unlikely (i.e. I do not know of <span class="emphasis"><em>anyone</em></span> who actually
 250           used it) you will ever need other more fancy things such as the ones described in the
 251           following section (<a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-dest" title="Interface Destruction">the section called “Interface Destruction”</a>).
 252         </p>
 253 </div>
 254 <div class="sect2">
 255 <div class="titlepage"><div><div><h3 class="title">
 256 <a name="gtype-non-instantiable-classed-dest"></a>Interface Destruction</h3></div></div></div>
 257 <p>
 258             When the last instance of an instantiable type which registered
 259             an interface implementation is destroyed, the interface's
 260             implementations associated to the type are destroyed.
 261           </p>
 262 <p>
 263             To destroy an interface implementation, GType first calls the
 264             implementation's <code class="function">interface_finalize</code> function
 265             and then the interface's most-derived
 266             <code class="function">base_finalize</code> function.
 267           </p>
 268 <p>
 269             Again, it is important to understand, as in
 270             <a class="xref" href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-init" title="Interface Initialization">the section called “Interface Initialization”</a>,
 271               that both <code class="function">interface_finalize</code> and <code class="function">base_finalize</code>
 272               are invoked exactly once for the destruction of each implementation of an interface. Thus,
 273               if you were to use one of these functions, you would need to use a static integer variable
 274               which would hold the number of instances of implementations of an interface such that
 275               the interface's class is destroyed only once (when the integer variable reaches zero).
 276           </p>
 277 <p>
 278           The above process can be summarized as follows:
 279           </p>
 280 <div class="table">
 281 <a name="ginterface-fini-table"></a><p class="title"><b>Table 3. Interface Finalization</b></p>
 282 <div class="table-contents"><table summary="Interface Finalization" border="1">
 283 <colgroup>
 284 <col align="left">
 285 <col align="left">
 286 <col align="left">
 287 </colgroup>
 288 <thead><tr>
 289 <th align="left">Invocation time</th>
 290 <th align="left">Function Invoked</th>
 291 <th align="left">Function's parameters</th>
 292 </tr></thead>
 293 <tbody>
 294 <tr>
 295 <td rowspan="2" align="left">Last call to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-free-instance" title="g_type_free_instance ()">g_type_free_instance</a></code> for type
 296                     implementing interface
 297                    </td>
 298 <td align="left">interface' interface_finalize function</td>
 299 <td align="left">On interface' vtable</td>
 300 </tr>
 301 <tr>
 302 <td align="left">interface' base_finalize function</td>
 303 <td align="left">On interface' vtable</td>
 304 </tr>
 305 </tbody>
 306 </table></div>
 307 </div>
 308 <p><br class="table-break">
 309         </p>
 310 </div>
 311 </div>
 312 <div class="footer">
 313 <hr>
 314           Generated by GTK-Doc V1.18</div>
 315 </body>
 316 </html>