1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
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.
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.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 * gparam.h: GParamSpec base class implementation
22 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
23 #error "Only <glib-object.h> can be included directly."
26 #include <gobject/gvalue.h>
30 /* --- standard type macros --- */
35 * Checks whether @type "is a" %G_TYPE_PARAM.
37 #define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
40 * @pspec: a valid #GParamSpec
42 * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
43 * a #GParamSpec object.
45 #define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
48 * @pspec: a #GParamSpec
50 * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
53 #define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
56 * @pclass: a valid #GParamSpecClass
58 * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
60 #define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
62 * G_IS_PARAM_SPEC_CLASS:
63 * @pclass: a #GParamSpecClass
65 * Checks whether @pclass "is a" valid #GParamSpecClass structure of type
66 * %G_TYPE_PARAM or derived.
68 #define G_IS_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
70 * G_PARAM_SPEC_GET_CLASS:
71 * @pspec: a valid #GParamSpec
73 * Retrieves the #GParamSpecClass of a #GParamSpec.
75 #define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
78 /* --- convenience macros --- */
81 * @pspec: a valid #GParamSpec
83 * Retrieves the #GType of this @pspec.
85 #define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec))
87 * G_PARAM_SPEC_TYPE_NAME:
88 * @pspec: a valid #GParamSpec
90 * Retrieves the #GType name of this @pspec.
92 #define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
94 * G_PARAM_SPEC_VALUE_TYPE:
95 * @pspec: a valid #GParamSpec
97 * Retrieves the #GType to initialize a #GValue for this parameter.
99 #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type)
101 * G_VALUE_HOLDS_PARAM:
102 * @value: a valid #GValue structure
104 * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
106 * Returns: %TRUE on success.
108 #define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
114 * @G_PARAM_READABLE: the parameter is readable
115 * @G_PARAM_WRITABLE: the parameter is writable
116 * @G_PARAM_READWRITE: alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE
117 * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
118 * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
119 * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert())
120 * strict validation is not required
121 * @G_PARAM_STATIC_NAME: the string used as name when constructing the
122 * parameter is guaranteed to remain valid and
123 * unmodified for the lifetime of the parameter.
125 * @G_PARAM_STATIC_NICK: the string used as nick when constructing the
126 * parameter is guaranteed to remain valid and
127 * unmmodified for the lifetime of the parameter.
129 * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the
130 * parameter is guaranteed to remain valid and
131 * unmodified for the lifetime of the parameter.
133 * @G_PARAM_PRIVATE: internal
134 * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed
135 * in a future version. A warning will be generated if it is used
136 * while running with G_ENABLE_DIAGNOSTIC=1.
139 * Through the #GParamFlags flag values, certain aspects of parameters
140 * can be configured. See also #G_PARAM_READWRITE and #G_PARAM_STATIC_STRINGS.
144 G_PARAM_READABLE = 1 << 0,
145 G_PARAM_WRITABLE = 1 << 1,
146 G_PARAM_READWRITE = (G_PARAM_READABLE | G_PARAM_WRITABLE),
147 G_PARAM_CONSTRUCT = 1 << 2,
148 G_PARAM_CONSTRUCT_ONLY = 1 << 3,
149 G_PARAM_LAX_VALIDATION = 1 << 4,
150 G_PARAM_STATIC_NAME = 1 << 5,
151 #ifndef G_DISABLE_DEPRECATED
152 G_PARAM_PRIVATE = G_PARAM_STATIC_NAME,
154 G_PARAM_STATIC_NICK = 1 << 6,
155 G_PARAM_STATIC_BLURB = 1 << 7,
156 /* User defined flags go up to 30 */
157 G_PARAM_DEPRECATED = 1 << 31
160 * G_PARAM_STATIC_STRINGS:
162 * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
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 */
171 * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
173 #define G_PARAM_MASK (0x000000ff)
175 * G_PARAM_USER_SHIFT:
177 * Minimum shift count to be used for user defined flags, to be stored in
178 * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT.
180 #define G_PARAM_USER_SHIFT (8)
182 /* --- typedefs & structures --- */
183 typedef struct _GParamSpec GParamSpec;
184 typedef struct _GParamSpecClass GParamSpecClass;
185 typedef struct _GParameter GParameter;
186 typedef struct _GParamSpecPool GParamSpecPool;
189 * @g_type_instance: private #GTypeInstance portion
190 * @name: name of this parameter: always an interned string
191 * @flags: #GParamFlags flags for this parameter
192 * @value_type: the #GValue type for this parameter
193 * @owner_type: #GType type that uses (introduces) this parameter
195 * All other fields of the GParamSpec struct are private and
196 * should not be used directly.
200 GTypeInstance g_type_instance;
202 const gchar *name; /* interned string */
205 GType owner_type; /* class or interface using this property */
212 guint param_id; /* sort-criteria */
216 * @g_type_class: the parent class
217 * @value_type: the #GValue type for this parameter
218 * @finalize: The instance finalization function (optional), should chain
219 * up to the finalize method of the parent class.
220 * @value_set_default: Resets a @value to the default value for this type
221 * (recommended, the default is g_value_reset()), see
222 * g_param_value_set_default().
223 * @value_validate: Ensures that the contents of @value comply with the
224 * specifications set out by this type (optional), see
225 * g_param_value_validate().
226 * @values_cmp: Compares @value1 with @value2 according to this type
227 * (recommended, the default is memcmp()), see g_param_values_cmp().
229 * The class structure for the GParamSpec type.
230 * Normally, GParamSpec classes are filled by
231 * g_param_type_register_static().
233 struct _GParamSpecClass
235 GTypeClass g_type_class;
239 void (*finalize) (GParamSpec *pspec);
242 void (*value_set_default) (GParamSpec *pspec,
244 gboolean (*value_validate) (GParamSpec *pspec,
246 gint (*values_cmp) (GParamSpec *pspec,
247 const GValue *value1,
248 const GValue *value2);
254 * @name: the parameter name
255 * @value: the parameter value
257 * The GParameter struct is an auxiliary structure used
258 * to hand parameter name/value pairs to g_object_newv().
260 struct _GParameter /* auxiliary structure for _setv() variants */
267 /* --- prototypes --- */
268 GLIB_AVAILABLE_IN_ALL
269 GParamSpec* g_param_spec_ref (GParamSpec *pspec);
270 GLIB_AVAILABLE_IN_ALL
271 void g_param_spec_unref (GParamSpec *pspec);
272 GLIB_AVAILABLE_IN_ALL
273 void g_param_spec_sink (GParamSpec *pspec);
274 GLIB_AVAILABLE_IN_ALL
275 GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec);
276 GLIB_AVAILABLE_IN_ALL
277 gpointer g_param_spec_get_qdata (GParamSpec *pspec,
279 GLIB_AVAILABLE_IN_ALL
280 void g_param_spec_set_qdata (GParamSpec *pspec,
283 GLIB_AVAILABLE_IN_ALL
284 void g_param_spec_set_qdata_full (GParamSpec *pspec,
287 GDestroyNotify destroy);
288 GLIB_AVAILABLE_IN_ALL
289 gpointer g_param_spec_steal_qdata (GParamSpec *pspec,
291 GLIB_AVAILABLE_IN_ALL
292 GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec);
294 GLIB_AVAILABLE_IN_ALL
295 void g_param_value_set_default (GParamSpec *pspec,
297 GLIB_AVAILABLE_IN_ALL
298 gboolean g_param_value_defaults (GParamSpec *pspec,
300 GLIB_AVAILABLE_IN_ALL
301 gboolean g_param_value_validate (GParamSpec *pspec,
303 GLIB_AVAILABLE_IN_ALL
304 gboolean g_param_value_convert (GParamSpec *pspec,
305 const GValue *src_value,
307 gboolean strict_validation);
308 GLIB_AVAILABLE_IN_ALL
309 gint g_param_values_cmp (GParamSpec *pspec,
310 const GValue *value1,
311 const GValue *value2);
312 GLIB_AVAILABLE_IN_ALL
313 const gchar * g_param_spec_get_name (GParamSpec *pspec);
314 GLIB_AVAILABLE_IN_ALL
315 const gchar * g_param_spec_get_nick (GParamSpec *pspec);
316 GLIB_AVAILABLE_IN_ALL
317 const gchar * g_param_spec_get_blurb (GParamSpec *pspec);
318 GLIB_AVAILABLE_IN_ALL
319 void g_value_set_param (GValue *value,
321 GLIB_AVAILABLE_IN_ALL
322 GParamSpec* g_value_get_param (const GValue *value);
323 GLIB_AVAILABLE_IN_ALL
324 GParamSpec* g_value_dup_param (const GValue *value);
327 GLIB_AVAILABLE_IN_ALL
328 void g_value_take_param (GValue *value,
330 GLIB_DEPRECATED_FOR(g_value_take_param)
331 void g_value_set_param_take_ownership (GValue *value,
333 GLIB_AVAILABLE_IN_2_36
334 const GValue * g_param_spec_get_default_value (GParamSpec *param);
336 /* --- convenience functions --- */
337 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
339 * GParamSpecTypeInfo:
340 * @instance_size: Size of the instance (object) structure.
341 * @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.
342 * @instance_init: Location of the instance initialization function (optional).
343 * @value_type: The #GType of values conforming to this #GParamSpec
344 * @finalize: The instance finalization function (optional).
345 * @value_set_default: Resets a @value to the default value for @pspec
346 * (recommended, the default is g_value_reset()), see
347 * g_param_value_set_default().
348 * @value_validate: Ensures that the contents of @value comply with the
349 * specifications set out by @pspec (optional), see
350 * g_param_value_validate().
351 * @values_cmp: Compares @value1 with @value2 according to @pspec
352 * (recommended, the default is memcmp()), see g_param_values_cmp().
354 * This structure is used to provide the type system with the information
355 * required to initialize and destruct (finalize) a parameter's class and
357 * The initialized structure is passed to the g_param_type_register_static()
358 * The type system will perform a deep copy of this structure, so its memory
359 * does not need to be persistent across invocation of
360 * g_param_type_register_static().
362 struct _GParamSpecTypeInfo
364 /* type system portion */
365 guint16 instance_size; /* obligatory */
366 guint16 n_preallocs; /* optional */
367 void (*instance_init) (GParamSpec *pspec); /* optional */
370 GType value_type; /* obligatory */
371 void (*finalize) (GParamSpec *pspec); /* optional */
372 void (*value_set_default) (GParamSpec *pspec, /* recommended */
374 gboolean (*value_validate) (GParamSpec *pspec, /* optional */
376 gint (*values_cmp) (GParamSpec *pspec, /* recommended */
377 const GValue *value1,
378 const GValue *value2);
380 GLIB_AVAILABLE_IN_ALL
381 GType g_param_type_register_static (const gchar *name,
382 const GParamSpecTypeInfo *pspec_info);
384 /* For registering builting types */
385 GType _g_param_type_register_static_constant (const gchar *name,
386 const GParamSpecTypeInfo *pspec_info,
390 /* --- protected --- */
391 GLIB_AVAILABLE_IN_ALL
392 gpointer g_param_spec_internal (GType param_type,
397 GLIB_AVAILABLE_IN_ALL
398 GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing);
399 GLIB_AVAILABLE_IN_ALL
400 void g_param_spec_pool_insert (GParamSpecPool *pool,
403 GLIB_AVAILABLE_IN_ALL
404 void g_param_spec_pool_remove (GParamSpecPool *pool,
406 GLIB_AVAILABLE_IN_ALL
407 GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool,
408 const gchar *param_name,
410 gboolean walk_ancestors);
411 GLIB_AVAILABLE_IN_ALL
412 GList* g_param_spec_pool_list_owned (GParamSpecPool *pool,
414 GLIB_AVAILABLE_IN_ALL
415 GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool,
422 * gboolean value_validate (GParamSpec *pspec,
424 * modify value contents in the least destructive way, so
425 * that it complies with pspec's requirements (i.e.
426 * according to minimum/maximum ranges etc...). return
427 * whether modification was necessary.
429 * gint values_cmp (GParamSpec *pspec,
430 * const GValue *value1,
431 * const GValue *value2):
432 * return value1 - value2, i.e. (-1) if value1 < value2,
433 * (+1) if value1 > value2, and (0) otherwise (equality)
438 #endif /* __G_PARAM_H__ */