| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Object Construction</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="index.html" title="GObject Reference Manual"> |
| <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject"> |
| <link rel="prev" href="howto-gobject-code.html" title="Boilerplate code"> |
| <link rel="next" href="howto-gobject-destruction.html" title="Object Destruction"> |
| <meta name="generator" content="GTK-Doc V1.14 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> |
| <td><a accesskey="p" href="howto-gobject-code.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> |
| <td><a accesskey="u" href="howto-gobject.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> |
| <th width="100%" align="center">GObject Reference Manual</th> |
| <td><a accesskey="n" href="howto-gobject-destruction.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="sect1" title="Object Construction"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="howto-gobject-construction"></a>Object Construction</h2></div></div></div> |
| <p> |
| People often get confused when trying to construct their GObjects because of the |
| sheer number of different ways to hook into the objects's construction process: it is |
| difficult to figure which is the <span class="emphasis"><em>correct</em></span>, recommended way. |
| </p> |
| <p> |
| <a class="xref" href="chapter-gobject.html#gobject-construction-table" title="Table 4. g_object_new">Table 4, “g_object_new”</a> shows what user-provided functions |
| are invoked during object instantiation and in which order they are invoked. |
| A user looking for the equivalent of the simple C++ constructor function should use |
| the instance_init method. It will be invoked after all the parent's instance_init |
| functions have been invoked. It cannot take arbitrary construction parameters |
| (as in C++) but if your object needs arbitrary parameters to complete initialization, |
| you can use construction properties. |
| </p> |
| <p> |
| Construction properties will be set only after all instance_init functions have run. |
| No object reference will be returned to the client of <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> |
| until all the construction properties have been set. |
| </p> |
| <p> |
| As such, I would recommend writing the following code first: |
| </p> |
| <pre class="programlisting"> |
| static void |
| maman_bar_init (MamanBar *self) |
| { |
| self->priv = MAMAN_BAR_GET_PRIVATE (self); |
| |
| /* initialize all public and private members to reasonable default values. */ |
| |
| /* If you need specific construction properties to complete initialization, |
| * delay initialization completion until the property is set. |
| */ |
| } |
| </pre> |
| <p> |
| </p> |
| <p> |
| Now, if you need special construction properties, install the properties in the class_init function, |
| override the set and get methods and implement the get and set methods as described in |
| <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>. Make sure that these properties use a construct only |
| <span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec" title="GParamSpec">GParamSpec</a></span> by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps |
| GType ensure that these properties are not set again later by malicious user code. |
| </p> |
| <pre class="programlisting"> |
| static void |
| bar_class_init (MamanBarClass *klass) |
| { |
| GObjectClass *gobject_class = G_OBJECT_CLASS (klass); |
| GParamSpec *maman_param_spec; |
| |
| gobject_class->set_property = bar_set_property; |
| gobject_class->get_property = bar_get_property; |
| |
| maman_param_spec = g_param_spec_string ("maman", |
| "Maman construct prop", |
| "Set maman's name", |
| "no-name-set" /* default value */, |
| G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE); |
| g_object_class_install_property (gobject_class, |
| PROP_MAMAN, |
| maman_param_spec); |
| } |
| </pre> |
| <p> |
| If you need this, make sure you can build and run code similar to the code shown above. Make sure |
| your construct properties can set correctly during construction, make sure you cannot set them |
| afterwards and make sure that if your users do not call <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code> |
| with the required construction properties, these will be initialized with the default values. |
| </p> |
| <p> |
| I consider good taste to halt program execution if a construction property is set its |
| default value. This allows you to catch client code which does not give a reasonable |
| value to the construction properties. Of course, you are free to disagree but you |
| should have a good reason to do so. |
| </p> |
| <p> |
| Some people sometimes need to construct their object but only after |
| the construction properties have been set. This is possible through |
| the use of the constructor class method as described in |
| <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or, more simply, using |
| the constructed class method available since GLib 2.12. |
| </p> |
| </div> |
| <div class="footer"> |
| <hr> |
| Generated by GTK-Doc V1.14</div> |
| </body> |
| </html> |
