← Back to branch summary

~ubuntu-branches/ubuntu/saucy/glib2.0/saucy-proposed

« back to all changes in this revision

Viewing changes to docs/reference/gobject/html/howto-gobject-construction.html

  • Committer: Package Import Robot
  • Author(s): Iain Lane
  • Date: 2013-06-25 12:43:56 UTC
  • mfrom: (1.63.22)
  • Revision ID: package-import@ubuntu.com-20130625124356-597xf4lpikauchiy
Tags: 2.37.3-1ubuntu1
* Resynchronise on unrelease Debian SVN (glib is in NEW there). Remaining
  change:
  - Build-Depend on python:any for cross building.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gobject/html/howto-gobject-construction.html
8
8
<link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
9
9
<link rel="prev" href="howto-gobject-code.html" title="Boilerplate code">
10
10
<link rel="next" href="howto-gobject-destruction.html" title="Object Destruction">
11
 
<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
 
11
<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
12
12
<link rel="stylesheet" href="style.css" type="text/css">
13
13
</head>
14
14
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
42
42
      until all the construction properties have been set.
43
43
    </p>
44
44
<p>
 
45
      It is important to note that object construction cannot <span class="emphasis"><em>ever</em></span>
 
46
      fail. If you require a fallible GObject construction, you can use the
 
47
      GInitable and GAsyncInitable interfaces provided by the GIO library
 
48
    </p>
 
49
<p>
45
50
      As such, I would recommend writing the following code first:
46
51
</p>
47
52
<pre class="programlisting">
 
53
G_DEFINE_TYPE_WITH_PRIVATE (MamanBar, maman_bar, G_TYPE_OBJECT)
 
54
 
 
55
static void
 
56
maman_bar_class_init (MamanBarClass *klass)
 
57
{
 
58
}
 
59
 
48
60
static void
49
61
maman_bar_init (MamanBar *self)
50
62
{
51
 
  self-&gt;priv = MAMAN_BAR_GET_PRIVATE (self); 
 
63
  self-&gt;priv = maman_bar_get_instance_private (self);
52
64
 
53
65
  /* initialize all public and private members to reasonable default values. */
54
 
 
55
 
  /* If you need specific construction properties to complete initialization,
56
 
   * delay initialization completion until the property is set. 
57
 
   */
58
66
}
59
67
</pre>
60
68
<p>
61
69
    </p>
62
70
<p>
63
 
      Now, if you need special construction properties, install the properties in the class_init function,
64
 
      override the set and get methods and implement the get and set methods as described in 
65
 
      <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 
66
 
      <a class="link" href="gobject-GParamSpec.html#GParamSpec" title="struct GParamSpec"><span class="type">GParamSpec</span></a> by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps
67
 
      GType ensure that these properties are not set again later by malicious user code.
 
71
      If you need special construction properties, install the properties in
 
72
      the <code class="function">class_init()</code> function, override the <code class="function">set_property()</code>
 
73
      and <code class="function">get_property()</code> methods of the GObject class,
 
74
      and implement them as described by <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>.
68
75
</p>
69
76
<div class="informalexample">
70
77
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
98
105
26
99
106
27
100
107
28
101
 
29</pre></td>
 
108
29
 
109
30
 
110
31
 
111
32</pre></td>
102
112
        <td class="listing_code"><pre class="programlisting"><span class="keyword">enum</span><span class="normal"> </span><span class="cbracket">{</span>
103
113
<span class="normal">  PROP_0</span><span class="symbol">,</span>
104
114
 
107
117
<span class="normal">  N_PROPERTIES</span>
108
118
<span class="cbracket">}</span><span class="symbol">;</span>
109
119
 
 
120
<span class="comment">/* Keep a pointer to the properties definition */</span>
110
121
<span class="keyword">static</span><span class="normal"> </span><span class="usertype">GParamSpec</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">obj_properties</span><span class="symbol">[</span><span class="normal">N_PROPERTIES</span><span class="symbol">]</span><span class="normal"> </span><span class="symbol">=</span><span class="normal"> </span><span class="cbracket">{</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> </span><span class="cbracket">}</span><span class="symbol">;</span>
111
122
 
112
123
<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
122
133
<span class="normal">                         </span><span class="string">"Maman construct prop"</span><span class="symbol">,</span>
123
134
<span class="normal">                         </span><span class="string">"Set maman's name"</span><span class="symbol">,</span>
124
135
<span class="normal">                         </span><span class="string">"no-name-set"</span><span class="normal"> </span><span class="comment">/* default value */</span><span class="symbol">,</span>
125
 
<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-CONSTRUCT-ONLY:CAPS">G_PARAM_CONSTRUCT_ONLY</a> </span><span class="symbol">|</span><span class="normal"> <a href="gobject-GParamSpec.html#G-PARAM-READWRITE:CAPS">G_PARAM_READWRITE</a></span><span class="symbol">);</span>
 
136
<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-CONSTRUCT-ONLY:CAPS">G_PARAM_CONSTRUCT_ONLY</a> </span><span class="symbol">|</span>
 
137
<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-READWRITE:CAPS">G_PARAM_READWRITE</a> </span><span class="symbol">|</span>
 
138
<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-STATIC-STRINGS:CAPS">G_PARAM_STATIC_STRINGS</a></span><span class="symbol">);</span>
126
139
 
127
140
<span class="normal">  </span><span class="function"><a href="gobject-The-Base-Object-Type.html#g-object-class-install-properties">g_object_class_install_properties</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gobject_class</span><span class="symbol">,</span>
128
141
<span class="normal">                                     N_PROPERTIES</span><span class="symbol">,</span>
134
147
</div>
135
148
 
136
149
<p>
137
 
      If you need this, make sure you can build and run code similar to the code shown above. Make sure
138
 
      your construct properties can set correctly during construction, make sure you cannot set them 
139
 
      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>
140
 
      with the required construction properties, these will be initialized with the default values.
141
 
    </p>
142
 
<p>
143
 
      I consider good taste to halt program execution if a construction property is set its
144
 
      default value. This allows you to catch client code which does not give a reasonable
145
 
      value to the construction properties. Of course, you are free to disagree but you
146
 
      should have a good reason to do so.
147
 
    </p>
148
 
<p>
149
 
      Some people sometimes need to construct their object but only after
150
 
      the construction properties have been set. This is possible through
151
 
      the use of the constructor class method as described in
152
 
      <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or, more simply, using
153
 
      the constructed class method available since GLib 2.12.
 
150
      If you need this, make sure you can build and run code similar to the
 
151
      code shown above. Also, make sure your construct properties can be set
 
152
      without side effects during construction.
 
153
    </p>
 
154
<p>
 
155
      Some people sometimes need to complete the initialization of a instance
 
156
      of a type only after the properties passed to the constructors have been
 
157
      set. This is possible through the use of the <code class="function">constructor()</code>
 
158
      class method as described in <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or,
 
159
      more simply, using the <code class="function">constructed()</code> class method
 
160
      available since GLib 2.12. Note that the <code class="function">constructed()</code>
 
161
      virtual function will only be invoked after the properties marked as
 
162
      G_PARAM_CONSTRUCT_ONLY or G_PARAM_CONSTRUCT have been consumed, but
 
163
      before the regular properties passed to <code class="function">g_object_new()</code>
 
164
      have been set.
154
165
    </p>
155
166
</div>
156
167
<div class="footer">
157
168
<hr>
158
 
          Generated by GTK-Doc V1.18.1</div>
 
169
          Generated by GTK-Doc V1.19</div>
159
170
</body>
160
171
</html>
 
 
b'\\ No newline at end of file'