|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /proc/21572/root/usr/share/gtk-doc/html/gobject/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Object Construction</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" 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.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="preface" href="pr01.html" title="Introduction">
<link rel="part" href="pt01.html" title="Part I. Concepts">
<link rel="chapter" href="ch01.html" title="Background">
<link rel="chapter" href="ch02.html" title="The Glib Dynamic Type System">
<link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
<link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
<link rel="reference" href="rn01.html" title="API Reference">
<link rel="reference" href="rn02.html" title="Tools Reference">
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
<link rel="chapter" href="howto-gobject.html" title="How To define and implement a new GObject?">
<link rel="chapter" href="howto-interface.html" title="How To define and implement Interfaces?">
<link rel="chapter" href="howto-signals.html" title="Howto create and use signals">
<link rel="part" href="pt03.html" title="Part V. Related Tools">
<link rel="chapter" href="tools-gob.html" title="GObject builder">
<link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of Gobjects">
<link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
<link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
</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" lang="en">
<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 href="chapter-gobject.html#gobject-construction-table" title="Table 1. g_object_new">Table 1, “g_object_new”</a> shows what user-provided functions
are invoked during object instanciation 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">g_object_new></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 (GTypeInstance *instance,
gpointer g_class)
{
MamanBar *self = (MamanBar *)instance;
self->private = g_new0 (MamanBarPrivate, 1);
/* initialize all public and private members to reasonable default values. */
/* If you need specific consruction properties to complete initialization,
* delay initialization completion until the property is set.
*/
}
</pre>
<p>
And make sure that you set <code class="function">maman_bar_init</code> as the type's instance_init function
in <code class="function">maman_bar_get_type</code>. Make sure the code builds and runs: create an instance
of the object and make sure <code class="function">maman_bar_init</code> is called (add a
<code class="function"><a
href="../glib/glib-Warnings-and-Assertions.html#g-print"
>g_print</a></code> call in it).
</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 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 href="gobject-GParamSpec.html#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 href="gobject-The-Base-Object-Type.html#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 href="chapter-gobject.html#gobject-instanciation" title="Object instanciation">the section called “Object instanciation”</a>. However, I have yet to see <span class="emphasis"><em>any</em></span> reasonable
use of this feature. As such, to initialize your object instances, use by default the base_init function
and construction properties.
</p>
</div>
</body>
</html>