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.76.1">
   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.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="ch06s03.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="howto-interface.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="howto-signals.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="howto-interface-properties"></a>Interface Properties</h2></div></div></div>
  25 <p>
  26       Starting from version 2.4 of GLib, GObject interfaces can also have
  27       properties. Declaration of the interface properties is similar to
  28       declaring the properties of ordinary GObject types as explained in
  29       <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>,
  30       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
  31       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>.
  32     </p>
  33 <p>
  34       To include a property named 'name' of type <span class="type">string</span> in the
  35       <span class="type">maman_ibaz</span> interface example code above, we only need to
  36       add one
  37       <sup>[<a name="id675000" href="#ftn.id675000" class="footnote">12</a>]</sup>
  38       line in the <code class="function">maman_ibaz_base_init</code>
  39       <sup>[<a name="id675013" href="#ftn.id675013" class="footnote">13</a>]</sup>
  40       as shown below:
  41 </p>
  42 <pre class="programlisting">
  43 static void
  44 maman_ibaz_base_init (gpointer g_iface)
  45 {
  46   static gboolean is_initialized = FALSE;
  47
  48   if (!is_initialized)
  49     {
  50       g_object_interface_install_property (g_iface,
  51                                            g_param_spec_string ("name",
  52                                                                 "Name",
  53                                                                 "Name of the MamanIbaz",
  54                                                                 "maman",
  55                                                                 G_PARAM_READWRITE));
  56       is_initialized = TRUE;
  57     }
  58 }
  59 </pre>
  60 <p>
  61     </p>
  62 <p>
  63       One point worth noting is that the declared property wasn't assigned an
  64       integer ID. The reason being that integer IDs of properties are used
  65       only inside the get and set methods and since interfaces do not
  66       implement properties, there is no need to assign integer IDs to
  67       interface properties.
  68     </p>
  69 <p>
  70       An implementation shall declare and define it's properties in the usual
  71       way as explained in <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>, except for one
  72       small change: it must declare the properties of the interface it
  73       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>
  74       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>.
  75       The following code snippet shows the modifications needed in the
  76       <span class="type">MamanBaz</span> declaration and implementation above:
  77 </p>
  78 <pre class="programlisting">
  79
  80 struct _MamanBaz
  81 {
  82   GObject parent_instance;
  83
  84   gint instance_member;
  85   gchar *name;
  86 };
  87
  88 enum
  89 {
  90   PROP_0,
  91
  92   PROP_NAME
  93 };
  94
  95 static void
  96 maman_baz_set_property (GObject      *object,
  97                         guint         property_id,
  98                         const GValue *value,
  99                         GParamSpec   *pspec)
 100 {
 101   MamanBaz *baz = MAMAN_BAZ (object);
 102   GObject *obj;
 103
 104   switch (prop_id)
 105     {
 106     case ARG_NAME:
 107       g_free (baz-&gt;name);
 108       baz-&gt;name = g_value_dup_string (value);
 109       break;
 110
 111     default:
 112       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 113       break;
 114     }
 115 }
 116
 117 static void
 118 maman_baz_get_property (GObject    *object,
 119                         guint       prop_id,
 120                         GValue     *value,
 121                         GParamSpec *pspec)
 122 {
 123   MamanBaz *baz = MAMAN_BAZ (object);
 124
 125   switch (prop_id)
 126     {
 127     case ARG_NAME:
 128       g_value_set_string (value, baz-&gt;name);
 129       break;
 130
 131     default:
 132       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 133       break;
 134     }
 135 }
 136
 137 static void
 138 maman_baz_class_init (MamanBazClass *klass)
 139 {
 140   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 141
 142   gobject_class-&gt;set_property = maman_baz_set_property;
 143   gobject_class-&gt;get_property = maman_baz_get_property;
 144
 145   g_object_class_override_property (gobject_class, PROP_NAME, "name");
 146 }
 147
 148 </pre>
 149 <p>
 150     </p>
 151 <div class="footnotes">
 152 <br><hr width="100" align="left">
 153 <div class="footnote"><p><sup>[<a id="ftn.id675000" href="#id675000" class="para">12</a>] </sup>
 154           That really is one line extended to six for the sake of clarity
 155         </p></div>
 156 <div class="footnote"><p><sup>[<a id="ftn.id675013" href="#id675013" class="para">13</a>] </sup>
 157           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>
 158           can also be called from <code class="function">class_init</code> but it must
 159           not be called after that point.
 160         </p></div>
 161 </div>
 162 </div>
 163 <div class="footer">
 164 <hr>
 165           Generated by GTK-Doc V1.18</div>
 166 </body>
 167 </html>