docs/reference/gobject/html/howto-interface-properties.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>Interface Properties</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="howto-interface.html" title="How to define and implement interfaces">
   9 <link rel="prev" href="ch06s03.html" title="Interface definition prerequisites">
  10 <link rel="next" href="howto-signals.html" title="How to create and use signals">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="preface" href="pr01.html" title="Introduction">
  14 <link rel="part" href="pt01.html" title="Part I. Concepts">
  15 <link rel="chapter" href="chapter-intro.html" title="Background">
  16 <link rel="chapter" href="chapter-gtype.html" title="The GLib Dynamic Type System">
  17 <link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
  18 <link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
  19 <link rel="reference" href="rn01.html" title="API Reference">
  20 <link rel="reference" href="rn02.html" title="Tools Reference">
  21 <link rel="part" href="pt02.html" title="Part IV. Tutorial">
  22 <link rel="chapter" href="howto-gobject.html" title="How to define and implement a new GObject">
  23 <link rel="chapter" href="howto-interface.html" title="How to define and implement interfaces">
  24 <link rel="chapter" href="howto-signals.html" title="How to create and use signals">
  25 <link rel="part" href="pt03.html" title="Part V. Related Tools">
  26 <link rel="chapter" href="tools-vala.html" title="Vala">
  27 <link rel="chapter" href="tools-gob.html" title="GObject builder">
  28 <link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of GObjects">
  29 <link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
  30 <link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
  31 <link rel="index" href="api-index-full.html" title="Index">
  32 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  33 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  34 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  35 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  36 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  37 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  38 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  39 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  40 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  41 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  42 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  43 </head>
  44 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  45 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  46 <td><a accesskey="p" href="ch06s03.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  47 <td><a accesskey="u" href="howto-interface.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  48 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  49 <th width="100%" align="center">GObject Reference Manual</th>
  50 <td><a accesskey="n" href="howto-signals.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  51 </tr></table>
  52 <div class="sect1" title="Interface Properties">
  53 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  54 <a name="howto-interface-properties"></a>Interface Properties</h2></div></div></div>
  55 <p>
  56       Starting from version 2.4 of GLib, GObject interfaces can also have
  57       properties. Declaration of the interface properties is similar to
  58       declaring the properties of ordinary GObject types as explained in
  59       <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>,
  60       except that <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-interface-install-property" title="g_object_interface_install_property ()">g_object_interface_install_property</a></code> is used to
  61       declare the properties instead of <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-class-install-property" title="g_object_class_install_property ()">g_object_class_install_property</a></code>.
  62     </p>
  63 <p>
  64       To include a property named 'name' of type <span class="type">string</span> in the
  65       <span class="type">maman_ibaz</span> interface example code above, we only need to
  66       add one
  67       <sup>[<a name="id650412" href="#ftn.id650412" class="footnote">12</a>]</sup>
  68       line in the <code class="function">maman_ibaz_base_init</code>
  69       <sup>[<a name="id650426" href="#ftn.id650426" class="footnote">13</a>]</sup>
  70       as shown below:
  71 </p>
  72 <pre class="programlisting">
  73 static void
  74 maman_ibaz_base_init (gpointer g_iface)
  75 {
  76   static gboolean is_initialized = FALSE;
  77
  78   if (!is_initialized)
  79     {
  80       g_object_interface_install_property (g_iface,
  81                                            g_param_spec_string ("name",
  82                                                                 "Name",
  83                                                                 "Name of the MamanIbaz",
  84                                                                 "maman",
  85                                                                 G_PARAM_READWRITE));
  86       is_initialized = TRUE;
  87     }
  88 }
  89 </pre>
  90 <p>
  91     </p>
  92 <p>
  93       One point worth noting is that the declared property wasn't assigned an
  94       integer ID. The reason being that integer IDs of properties are used
  95       only inside the get and set methods and since interfaces do not
  96       implement properties, there is no need to assign integer IDs to
  97       interface properties.
  98     </p>
  99 <p>
 100       An implementation shall declare and define it's properties in the usual
 101       way as explained in <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>, except for one
 102       small change: it must declare the properties of the interface it
 103       implements using <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-class-override-property" title="g_object_class_override_property ()">g_object_class_override_property</a></code>
 104       instead of <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-class-install-property" title="g_object_class_install_property ()">g_object_class_install_property</a></code>.
 105       The following code snippet shows the modifications needed in the
 106       <span class="type">MamanBaz</span> declaration and implementation above:
 107 </p>
 108 <pre class="programlisting">
 109
 110 struct _MamanBaz
 111 {
 112   GObject parent_instance;
 113
 114   gint instance_member;
 115   gchar *name;
 116 };
 117
 118 enum
 119 {
 120   PROP_0,
 121
 122   PROP_NAME
 123 };
 124
 125 static void
 126 maman_baz_set_property (GObject      *object,
 127                         guint         property_id,
 128                         const GValue *value,
 129                         GParamSpec   *pspec)
 130 {
 131   MamanBaz *baz = MAMAN_BAZ (object);
 132   GObject *obj;
 133
 134   switch (prop_id)
 135     {
 136     case ARG_NAME:
 137       g_free (baz-&gt;name);
 138       baz-&gt;name = g_value_dup_string (value);
 139       break;
 140
 141     default:
 142       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 143       break;
 144     }
 145 }
 146
 147 static void
 148 maman_baz_get_property (GObject    *object,
 149                         guint       prop_id,
 150                         GValue     *value,
 151                         GParamSpec *pspec)
 152 {
 153   MamanBaz *baz = MAMAN_BAZ (object);
 154
 155   switch (prop_id)
 156     {
 157     case ARG_NAME:
 158       g_value_set_string (value, baz-&gt;name);
 159       break;
 160
 161     default:
 162       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 163       break;
 164     }
 165 }
 166
 167 static void
 168 maman_baz_class_init (MamanBazClass *klass)
 169 {
 170   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 171
 172   gobject_class-&gt;set_property = maman_baz_set_property;
 173   gobject_class-&gt;get_property = maman_baz_get_property;
 174
 175   g_object_class_override_property (gobject_class, PROP_NAME, "name");
 176 }
 177
 178 </pre>
 179 <p>
 180     </p>
 181 <div class="footnotes">
 182 <br><hr width="100" align="left">
 183 <div class="footnote"><p><sup>[<a name="ftn.id650412" href="#id650412" class="para">12</a>] </sup>
 184           That really is one line extended to six for the sake of clarity
 185         </p></div>
 186 <div class="footnote"><p><sup>[<a name="ftn.id650426" href="#id650426" class="para">13</a>] </sup>
 187           The <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-interface-install-property" title="g_object_interface_install_property ()">g_object_interface_install_property</a></code>
 188           can also be called from <code class="function">class_init</code> but it must
 189           not be called after that point.
 190         </p></div>
 191 </div>
 192 </div>
 193 <div class="footer">
 194 <hr>
 195           Generated by GTK-Doc V1.13</div>
 196 </body>
 197 </html>