|
1 /* GObject - GLib Type, Object, Parameter and Signal Library |
|
2 * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc. |
|
3 * Portions copyright (c) 2006-2009 Nokia Corporation. All rights reserved. |
|
4 * This library is free software; you can redistribute it and/or |
|
5 * modify it under the terms of the GNU Lesser General Public |
|
6 * License as published by the Free Software Foundation; either |
|
7 * version 2 of the License, or (at your option) any later version. |
|
8 * |
|
9 * This library is distributed in the hope that it will be useful, |
|
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of |
|
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
|
12 * Lesser General Public License for more details. |
|
13 * |
|
14 * You should have received a copy of the GNU Lesser General |
|
15 * Public License along with this library; if not, write to the |
|
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, |
|
17 * Boston, MA 02111-1307, USA. |
|
18 * |
|
19 * gparam.h: GParamSpec base class implementation |
|
20 */ |
|
21 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) |
|
22 #error "Only <glib-object.h> can be included directly." |
|
23 #endif |
|
24 |
|
25 #ifndef __G_PARAM_H__ |
|
26 #define __G_PARAM_H__ |
|
27 |
|
28 #include <gobject/gvalue.h> |
|
29 |
|
30 G_BEGIN_DECLS |
|
31 |
|
32 /* --- standard type macros --- */ |
|
33 /** |
|
34 * G_TYPE_IS_PARAM: |
|
35 * @type: a #GType ID |
|
36 * |
|
37 * Checks whether @type "is a" %G_TYPE_PARAM. |
|
38 */ |
|
39 #define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM) |
|
40 /** |
|
41 * G_PARAM_SPEC: |
|
42 * @pspec: a valid #GParamSpec |
|
43 * |
|
44 * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into |
|
45 * a #GParamSpec object. |
|
46 */ |
|
47 #define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec)) |
|
48 /** |
|
49 * G_IS_PARAM_SPEC: |
|
50 * @pspec: a #GParamSpec |
|
51 * |
|
52 * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM |
|
53 * or derived. |
|
54 */ |
|
55 #define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM)) |
|
56 /** |
|
57 * G_PARAM_SPEC_CLASS: |
|
58 * @pclass: a valid #GParamSpecClass |
|
59 * |
|
60 * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. |
|
61 */ |
|
62 #define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass)) |
|
63 /** |
|
64 * G_IS_PARAM_SPEC_CLASS: |
|
65 * @pclass: a #GParamSpecClass |
|
66 * |
|
67 * Checks whether @pclass "is a" valid #GParamSpecClass structure of type |
|
68 * %G_TYPE_PARAM or derived. |
|
69 */ |
|
70 #define G_IS_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM)) |
|
71 /** |
|
72 * G_PARAM_SPEC_GET_CLASS: |
|
73 * @pspec: a valid #GParamSpec |
|
74 * |
|
75 * Retrieves the #GParamSpecClass of a #GParamSpec. |
|
76 */ |
|
77 #define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass)) |
|
78 |
|
79 |
|
80 /* --- convenience macros --- */ |
|
81 /** |
|
82 * G_PARAM_SPEC_TYPE: |
|
83 * @pspec: a valid #GParamSpec |
|
84 * |
|
85 * Retrieves the #GType of this @pspec. |
|
86 */ |
|
87 #define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec)) |
|
88 /** |
|
89 * G_PARAM_SPEC_TYPE_NAME: |
|
90 * @pspec: a valid #GParamSpec |
|
91 * |
|
92 * Retrieves the #GType name of this @pspec. |
|
93 */ |
|
94 #define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec))) |
|
95 /** |
|
96 * G_PARAM_SPEC_VALUE_TYPE: |
|
97 * @pspec: a valid #GParamSpec |
|
98 * |
|
99 * Retrieves the #GType to initialize a #GValue for this parameter. |
|
100 */ |
|
101 #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type) |
|
102 /** |
|
103 * G_VALUE_HOLDS_PARAM: |
|
104 * @value: a valid #GValue structure |
|
105 * |
|
106 * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. |
|
107 * |
|
108 * Returns: %TRUE on success. |
|
109 */ |
|
110 #define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM)) |
|
111 |
|
112 |
|
113 /* --- flags --- */ |
|
114 /** |
|
115 * GParamFlags: |
|
116 * @G_PARAM_READABLE: the parameter is readable |
|
117 * @G_PARAM_WRITABLE: the parameter is writable |
|
118 * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction |
|
119 * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction |
|
120 * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) |
|
121 * strict validation is not required |
|
122 * @G_PARAM_STATIC_NAME: the string used as name when constructing the |
|
123 * parameter is guaranteed to remain valid and |
|
124 * unmodified for the lifetime of the parameter. |
|
125 * Since 2.8 |
|
126 * @G_PARAM_STATIC_NICK: the string used as nick when constructing the |
|
127 * parameter is guaranteed to remain valid and |
|
128 * unmmodified for the lifetime of the parameter. |
|
129 * Since 2.8 |
|
130 * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the |
|
131 * parameter is guaranteed to remain valid and |
|
132 * unmodified for the lifetime of the parameter. |
|
133 * Since 2.8 |
|
134 * @G_PARAM_PRIVATE: internal |
|
135 * |
|
136 * Through the #GParamFlags flag values, certain aspects of parameters |
|
137 * can be configured. |
|
138 */ |
|
139 typedef enum |
|
140 { |
|
141 G_PARAM_READABLE = 1 << 0, |
|
142 G_PARAM_WRITABLE = 1 << 1, |
|
143 G_PARAM_CONSTRUCT = 1 << 2, |
|
144 G_PARAM_CONSTRUCT_ONLY = 1 << 3, |
|
145 G_PARAM_LAX_VALIDATION = 1 << 4, |
|
146 G_PARAM_STATIC_NAME = 1 << 5, |
|
147 #ifndef G_DISABLE_DEPRECATED |
|
148 G_PARAM_PRIVATE = G_PARAM_STATIC_NAME, |
|
149 #endif |
|
150 G_PARAM_STATIC_NICK = 1 << 6, |
|
151 G_PARAM_STATIC_BLURB = 1 << 7 |
|
152 } GParamFlags; |
|
153 /** |
|
154 * G_PARAM_READWRITE: |
|
155 * |
|
156 * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. |
|
157 */ |
|
158 #define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE) |
|
159 /** |
|
160 * G_PARAM_STATIC_STRINGS: |
|
161 * |
|
162 * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. |
|
163 * |
|
164 * Since 2.13.0 |
|
165 */ |
|
166 #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB) |
|
167 /* bits in the range 0xffffff00 are reserved for 3rd party usage */ |
|
168 /** |
|
169 * G_PARAM_MASK: |
|
170 * |
|
171 * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. |
|
172 */ |
|
173 #define G_PARAM_MASK (0x000000ff) |
|
174 /** |
|
175 * G_PARAM_USER_SHIFT: |
|
176 * |
|
177 * Minimum shift count to be used for user defined flags, to be stored in |
|
178 * #GParamSpec.flags. |
|
179 */ |
|
180 #define G_PARAM_USER_SHIFT (8) |
|
181 |
|
182 |
|
183 /* --- typedefs & structures --- */ |
|
184 typedef struct _GParamSpec GParamSpec; |
|
185 typedef struct _GParamSpecClass GParamSpecClass; |
|
186 typedef struct _GParameter GParameter; |
|
187 typedef struct _GParamSpecPool GParamSpecPool; |
|
188 /** |
|
189 * GParamSpec: |
|
190 * @g_type_instance: private #GTypeInstance portion |
|
191 * @name: name of this parameter |
|
192 * @flags: #GParamFlags flags for this parameter |
|
193 * @value_type: the #GValue type for this parameter |
|
194 * @owner_type: #GType type that uses (introduces) this paremeter |
|
195 * |
|
196 * All other fields of the <structname>GParamSpec</structname> struct are private and |
|
197 * should not be used directly. |
|
198 */ |
|
199 struct _GParamSpec |
|
200 { |
|
201 GTypeInstance g_type_instance; |
|
202 |
|
203 gchar *name; |
|
204 GParamFlags flags; |
|
205 GType value_type; |
|
206 GType owner_type; /* class or interface using this property */ |
|
207 |
|
208 /*< private >*/ |
|
209 gchar *_nick; |
|
210 gchar *_blurb; |
|
211 GData *qdata; |
|
212 guint ref_count; |
|
213 guint param_id; /* sort-criteria */ |
|
214 }; |
|
215 /** |
|
216 * GParamSpecClass: |
|
217 * @g_type_class: the parent class |
|
218 * @value_type: the #GValue type for this parameter |
|
219 * @finalize: The instance finalization function (optional), should chain |
|
220 * up to the finalize method of the parent class. |
|
221 * @value_set_default: Resets a @value to the default value for this type |
|
222 * (recommended, the default is g_value_reset()), see |
|
223 * g_param_value_set_default(). |
|
224 * @value_validate: Ensures that the contents of @value comply with the |
|
225 * specifications set out by this type (optional), see |
|
226 * g_param_value_set_validate(). |
|
227 * @values_cmp: Compares @value1 with @value2 according to this type |
|
228 * (recommended, the default is memcmp()), see g_param_values_cmp(). |
|
229 * |
|
230 * The class structure for the <structname>GParamSpec</structname> type. |
|
231 * Normally, <structname>GParamSpec</structname> classes are filled by |
|
232 * g_param_type_register_static(). |
|
233 */ |
|
234 struct _GParamSpecClass |
|
235 { |
|
236 GTypeClass g_type_class; |
|
237 |
|
238 GType value_type; |
|
239 |
|
240 void (*finalize) (GParamSpec *pspec); |
|
241 |
|
242 /* GParam methods */ |
|
243 void (*value_set_default) (GParamSpec *pspec, |
|
244 GValue *value); |
|
245 gboolean (*value_validate) (GParamSpec *pspec, |
|
246 GValue *value); |
|
247 gint (*values_cmp) (GParamSpec *pspec, |
|
248 const GValue *value1, |
|
249 const GValue *value2); |
|
250 /*< private >*/ |
|
251 gpointer dummy[4]; |
|
252 }; |
|
253 /** |
|
254 * GParameter: |
|
255 * @name: the parameter name |
|
256 * @value: the parameter value |
|
257 * |
|
258 * The <structname>GParameter</structname> struct is an auxiliary structure used |
|
259 * to hand parameter name/value pairs to g_object_newv(). |
|
260 */ |
|
261 struct _GParameter /* auxillary structure for _setv() variants */ |
|
262 { |
|
263 const gchar *name; |
|
264 GValue value; |
|
265 }; |
|
266 |
|
267 |
|
268 /* --- prototypes --- */ |
|
269 IMPORT_C GParamSpec* g_param_spec_ref (GParamSpec *pspec); |
|
270 IMPORT_C void g_param_spec_unref (GParamSpec *pspec); |
|
271 IMPORT_C void g_param_spec_sink (GParamSpec *pspec); |
|
272 IMPORT_C GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec); |
|
273 IMPORT_C gpointer g_param_spec_get_qdata (GParamSpec *pspec, |
|
274 GQuark quark); |
|
275 IMPORT_C void g_param_spec_set_qdata (GParamSpec *pspec, |
|
276 GQuark quark, |
|
277 gpointer data); |
|
278 IMPORT_C void g_param_spec_set_qdata_full (GParamSpec *pspec, |
|
279 GQuark quark, |
|
280 gpointer data, |
|
281 GDestroyNotify destroy); |
|
282 IMPORT_C gpointer g_param_spec_steal_qdata (GParamSpec *pspec, |
|
283 GQuark quark); |
|
284 IMPORT_C GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec); |
|
285 |
|
286 IMPORT_C void g_param_value_set_default (GParamSpec *pspec, |
|
287 GValue *value); |
|
288 IMPORT_C gboolean g_param_value_defaults (GParamSpec *pspec, |
|
289 GValue *value); |
|
290 IMPORT_C gboolean g_param_value_validate (GParamSpec *pspec, |
|
291 GValue *value); |
|
292 IMPORT_C gboolean g_param_value_convert (GParamSpec *pspec, |
|
293 const GValue *src_value, |
|
294 GValue *dest_value, |
|
295 gboolean strict_validation); |
|
296 IMPORT_C gint g_param_values_cmp (GParamSpec *pspec, |
|
297 const GValue *value1, |
|
298 const GValue *value2); |
|
299 IMPORT_C G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec); |
|
300 IMPORT_C G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec); |
|
301 IMPORT_C G_CONST_RETURN gchar* g_param_spec_get_blurb (GParamSpec *pspec); |
|
302 IMPORT_C void g_value_set_param (GValue *value, |
|
303 GParamSpec *param); |
|
304 IMPORT_C GParamSpec* g_value_get_param (const GValue *value); |
|
305 IMPORT_C GParamSpec* g_value_dup_param (const GValue *value); |
|
306 |
|
307 |
|
308 IMPORT_C void g_value_take_param (GValue *value, |
|
309 GParamSpec *param); |
|
310 #ifndef G_DISABLE_DEPRECATED |
|
311 IMPORT_C void g_value_set_param_take_ownership (GValue *value, |
|
312 GParamSpec *param); |
|
313 #endif |
|
314 |
|
315 /* --- convenience functions --- */ |
|
316 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo; |
|
317 /** |
|
318 * GParamSpecTypeInfo: |
|
319 * @instance_size: Size of the instance (object) structure. |
|
320 * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. |
|
321 * @instance_init: Location of the instance initialization function (optional). |
|
322 * @value_type: The #GType of values conforming to this #GParamSpec |
|
323 * @finalize: The instance finalization function (optional). |
|
324 * @value_set_default: Resets a @value to the default value for @pspec |
|
325 * (recommended, the default is g_value_reset()), see |
|
326 * g_param_value_set_default(). |
|
327 * @value_validate: Ensures that the contents of @value comply with the |
|
328 * specifications set out by @pspec (optional), see |
|
329 * g_param_value_set_validate(). |
|
330 * @values_cmp: Compares @value1 with @value2 according to @pspec |
|
331 * (recommended, the default is memcmp()), see g_param_values_cmp(). |
|
332 * |
|
333 * This structure is used to provide the type system with the information |
|
334 * required to initialize and destruct (finalize) a parameter's class and |
|
335 * instances thereof. |
|
336 * The initialized structure is passed to the g_param_type_register_static() |
|
337 * The type system will perform a deep copy of this structure, so its memory |
|
338 * does not need to be persistent across invocation of |
|
339 * g_param_type_register_static(). |
|
340 */ |
|
341 struct _GParamSpecTypeInfo |
|
342 { |
|
343 /* type system portion */ |
|
344 guint16 instance_size; /* obligatory */ |
|
345 guint16 n_preallocs; /* optional */ |
|
346 void (*instance_init) (GParamSpec *pspec); /* optional */ |
|
347 |
|
348 /* class portion */ |
|
349 GType value_type; /* obligatory */ |
|
350 void (*finalize) (GParamSpec *pspec); /* optional */ |
|
351 void (*value_set_default) (GParamSpec *pspec, /* recommended */ |
|
352 GValue *value); |
|
353 gboolean (*value_validate) (GParamSpec *pspec, /* optional */ |
|
354 GValue *value); |
|
355 gint (*values_cmp) (GParamSpec *pspec, /* recommended */ |
|
356 const GValue *value1, |
|
357 const GValue *value2); |
|
358 }; |
|
359 IMPORT_C GType g_param_type_register_static (const gchar *name, |
|
360 const GParamSpecTypeInfo *pspec_info); |
|
361 |
|
362 /* For registering builting types */ |
|
363 GType _g_param_type_register_static_constant (const gchar *name, |
|
364 const GParamSpecTypeInfo *pspec_info, |
|
365 GType opt_type); |
|
366 |
|
367 |
|
368 /* --- protected --- */ |
|
369 IMPORT_C gpointer g_param_spec_internal (GType param_type, |
|
370 const gchar *name, |
|
371 const gchar *nick, |
|
372 const gchar *blurb, |
|
373 GParamFlags flags); |
|
374 IMPORT_C GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing); |
|
375 IMPORT_C void g_param_spec_pool_insert (GParamSpecPool *pool, |
|
376 GParamSpec *pspec, |
|
377 GType owner_type); |
|
378 IMPORT_C void g_param_spec_pool_remove (GParamSpecPool *pool, |
|
379 GParamSpec *pspec); |
|
380 IMPORT_C GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool, |
|
381 const gchar *param_name, |
|
382 GType owner_type, |
|
383 gboolean walk_ancestors); |
|
384 IMPORT_C GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, |
|
385 GType owner_type); |
|
386 IMPORT_C GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, |
|
387 GType owner_type, |
|
388 guint *n_pspecs_p); |
|
389 |
|
390 |
|
391 |
|
392 /* contracts: |
|
393 * |
|
394 * gboolean value_validate (GParamSpec *pspec, |
|
395 * GValue *value): |
|
396 * modify value contents in the least destructive way, so |
|
397 * that it complies with pspec's requirements (i.e. |
|
398 * according to minimum/maximum ranges etc...). return |
|
399 * whether modification was necessary. |
|
400 * |
|
401 * gint values_cmp (GParamSpec *pspec, |
|
402 * const GValue *value1, |
|
403 * const GValue *value2): |
|
404 * return value1 - value2, i.e. (-1) if value1 < value2, |
|
405 * (+1) if value1 > value2, and (0) otherwise (equality) |
|
406 */ |
|
407 |
|
408 G_END_DECLS |
|
409 |
|
410 #endif /* __G_PARAM_H__ */ |