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_FUNDAMENTAL_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_EXPLICIT_NOTIFY: calls to g_object_set_property() for this
134 * property will not automatically result in a "notify" signal being
135 * emitted: the implementation must call g_object_notify() themselves
136 * in case the property actually changes. Since: 2.42.
137 * @G_PARAM_PRIVATE: internal
138 * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed
139 * in a future version. A warning will be generated if it is used
140 * while running with G_ENABLE_DIAGNOSTIC=1.
143 * Through the #GParamFlags flag values, certain aspects of parameters
144 * can be configured. See also #G_PARAM_READWRITE and #G_PARAM_STATIC_STRINGS.
148 G_PARAM_READABLE = 1 << 0,
149 G_PARAM_WRITABLE = 1 << 1,
150 G_PARAM_READWRITE = (G_PARAM_READABLE | G_PARAM_WRITABLE),
151 G_PARAM_CONSTRUCT = 1 << 2,
152 G_PARAM_CONSTRUCT_ONLY = 1 << 3,
153 G_PARAM_LAX_VALIDATION = 1 << 4,
154 G_PARAM_STATIC_NAME = 1 << 5,
155 #ifndef G_DISABLE_DEPRECATED
156 G_PARAM_PRIVATE = G_PARAM_STATIC_NAME,
158 G_PARAM_STATIC_NICK = 1 << 6,
159 G_PARAM_STATIC_BLURB = 1 << 7,
160 G_PARAM_EXPLICIT_NOTIFY = 1 << 8,
161 /* User defined flags go up to 30 */
162 G_PARAM_DEPRECATED = 1 << 31
165 * G_PARAM_STATIC_STRINGS:
167 * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
171 #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)
172 /* bits in the range 0xffffff00 are reserved for 3rd party usage */
176 * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
178 #define G_PARAM_MASK (0x000000ff)
180 * G_PARAM_USER_SHIFT:
182 * Minimum shift count to be used for user defined flags, to be stored in
183 * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT.
185 #define G_PARAM_USER_SHIFT (8)
187 /* --- typedefs & structures --- */
188 typedef struct _GParamSpec GParamSpec;
189 typedef struct _GParamSpecClass GParamSpecClass;
190 typedef struct _GParameter GParameter;
191 typedef struct _GParamSpecPool GParamSpecPool;
194 * @g_type_instance: private #GTypeInstance portion
195 * @name: name of this parameter: always an interned string
196 * @flags: #GParamFlags flags for this parameter
197 * @value_type: the #GValue type for this parameter
198 * @owner_type: #GType type that uses (introduces) this parameter
200 * All other fields of the GParamSpec struct are private and
201 * should not be used directly.
205 GTypeInstance g_type_instance;
207 const gchar *name; /* interned string */
210 GType owner_type; /* class or interface using this property */
217 guint param_id; /* sort-criteria */
221 * @g_type_class: the parent class
222 * @value_type: the #GValue type for this parameter
223 * @finalize: The instance finalization function (optional), should chain
224 * up to the finalize method of the parent class.
225 * @value_set_default: Resets a @value to the default value for this type
226 * (recommended, the default is g_value_reset()), see
227 * g_param_value_set_default().
228 * @value_validate: Ensures that the contents of @value comply with the
229 * specifications set out by this type (optional), see
230 * g_param_value_validate().
231 * @values_cmp: Compares @value1 with @value2 according to this type
232 * (recommended, the default is memcmp()), see g_param_values_cmp().
234 * The class structure for the GParamSpec type.
235 * Normally, GParamSpec classes are filled by
236 * g_param_type_register_static().
238 struct _GParamSpecClass
240 GTypeClass g_type_class;
244 void (*finalize) (GParamSpec *pspec);
247 void (*value_set_default) (GParamSpec *pspec,
249 gboolean (*value_validate) (GParamSpec *pspec,
251 gint (*values_cmp) (GParamSpec *pspec,
252 const GValue *value1,
253 const GValue *value2);
259 * @name: the parameter name
260 * @value: the parameter value
262 * The GParameter struct is an auxiliary structure used
263 * to hand parameter name/value pairs to g_object_newv().
265 struct _GParameter /* auxiliary structure for _setv() variants */
272 /* --- prototypes --- */
273 GLIB_AVAILABLE_IN_ALL
274 GParamSpec* g_param_spec_ref (GParamSpec *pspec);
275 GLIB_AVAILABLE_IN_ALL
276 void g_param_spec_unref (GParamSpec *pspec);
277 GLIB_AVAILABLE_IN_ALL
278 void g_param_spec_sink (GParamSpec *pspec);
279 GLIB_AVAILABLE_IN_ALL
280 GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec);
281 GLIB_AVAILABLE_IN_ALL
282 gpointer g_param_spec_get_qdata (GParamSpec *pspec,
284 GLIB_AVAILABLE_IN_ALL
285 void g_param_spec_set_qdata (GParamSpec *pspec,
288 GLIB_AVAILABLE_IN_ALL
289 void g_param_spec_set_qdata_full (GParamSpec *pspec,
292 GDestroyNotify destroy);
293 GLIB_AVAILABLE_IN_ALL
294 gpointer g_param_spec_steal_qdata (GParamSpec *pspec,
296 GLIB_AVAILABLE_IN_ALL
297 GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec);
299 GLIB_AVAILABLE_IN_ALL
300 void g_param_value_set_default (GParamSpec *pspec,
302 GLIB_AVAILABLE_IN_ALL
303 gboolean g_param_value_defaults (GParamSpec *pspec,
305 GLIB_AVAILABLE_IN_ALL
306 gboolean g_param_value_validate (GParamSpec *pspec,
308 GLIB_AVAILABLE_IN_ALL
309 gboolean g_param_value_convert (GParamSpec *pspec,
310 const GValue *src_value,
312 gboolean strict_validation);
313 GLIB_AVAILABLE_IN_ALL
314 gint g_param_values_cmp (GParamSpec *pspec,
315 const GValue *value1,
316 const GValue *value2);
317 GLIB_AVAILABLE_IN_ALL
318 const gchar * g_param_spec_get_name (GParamSpec *pspec);
319 GLIB_AVAILABLE_IN_ALL
320 const gchar * g_param_spec_get_nick (GParamSpec *pspec);
321 GLIB_AVAILABLE_IN_ALL
322 const gchar * g_param_spec_get_blurb (GParamSpec *pspec);
323 GLIB_AVAILABLE_IN_ALL
324 void g_value_set_param (GValue *value,
326 GLIB_AVAILABLE_IN_ALL
327 GParamSpec* g_value_get_param (const GValue *value);
328 GLIB_AVAILABLE_IN_ALL
329 GParamSpec* g_value_dup_param (const GValue *value);
332 GLIB_AVAILABLE_IN_ALL
333 void g_value_take_param (GValue *value,
335 GLIB_DEPRECATED_FOR(g_value_take_param)
336 void g_value_set_param_take_ownership (GValue *value,
338 GLIB_AVAILABLE_IN_2_36
339 const GValue * g_param_spec_get_default_value (GParamSpec *param);
341 /* --- convenience functions --- */
342 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
344 * GParamSpecTypeInfo:
345 * @instance_size: Size of the instance (object) structure.
346 * @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 [slice allocator][glib-Memory-Slices] now.
347 * @instance_init: Location of the instance initialization function (optional).
348 * @value_type: The #GType of values conforming to this #GParamSpec
349 * @finalize: The instance finalization function (optional).
350 * @value_set_default: Resets a @value to the default value for @pspec
351 * (recommended, the default is g_value_reset()), see
352 * g_param_value_set_default().
353 * @value_validate: Ensures that the contents of @value comply with the
354 * specifications set out by @pspec (optional), see
355 * g_param_value_validate().
356 * @values_cmp: Compares @value1 with @value2 according to @pspec
357 * (recommended, the default is memcmp()), see g_param_values_cmp().
359 * This structure is used to provide the type system with the information
360 * required to initialize and destruct (finalize) a parameter's class and
362 * The initialized structure is passed to the g_param_type_register_static()
363 * The type system will perform a deep copy of this structure, so its memory
364 * does not need to be persistent across invocation of
365 * g_param_type_register_static().
367 struct _GParamSpecTypeInfo
369 /* type system portion */
370 guint16 instance_size; /* obligatory */
371 guint16 n_preallocs; /* optional */
372 void (*instance_init) (GParamSpec *pspec); /* optional */
375 GType value_type; /* obligatory */
376 void (*finalize) (GParamSpec *pspec); /* optional */
377 void (*value_set_default) (GParamSpec *pspec, /* recommended */
379 gboolean (*value_validate) (GParamSpec *pspec, /* optional */
381 gint (*values_cmp) (GParamSpec *pspec, /* recommended */
382 const GValue *value1,
383 const GValue *value2);
385 GLIB_AVAILABLE_IN_ALL
386 GType g_param_type_register_static (const gchar *name,
387 const GParamSpecTypeInfo *pspec_info);
389 /* For registering builting types */
390 GType _g_param_type_register_static_constant (const gchar *name,
391 const GParamSpecTypeInfo *pspec_info,
395 /* --- protected --- */
396 GLIB_AVAILABLE_IN_ALL
397 gpointer g_param_spec_internal (GType param_type,
402 GLIB_AVAILABLE_IN_ALL
403 GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing);
404 GLIB_AVAILABLE_IN_ALL
405 void g_param_spec_pool_insert (GParamSpecPool *pool,
408 GLIB_AVAILABLE_IN_ALL
409 void g_param_spec_pool_remove (GParamSpecPool *pool,
411 GLIB_AVAILABLE_IN_ALL
412 GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool,
413 const gchar *param_name,
415 gboolean walk_ancestors);
416 GLIB_AVAILABLE_IN_ALL
417 GList* g_param_spec_pool_list_owned (GParamSpecPool *pool,
419 GLIB_AVAILABLE_IN_ALL
420 GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool,
427 * gboolean value_validate (GParamSpec *pspec,
429 * modify value contents in the least destructive way, so
430 * that it complies with pspec's requirements (i.e.
431 * according to minimum/maximum ranges etc...). return
432 * whether modification was necessary.
434 * gint values_cmp (GParamSpec *pspec,
435 * const GValue *value1,
436 * const GValue *value2):
437 * return value1 - value2, i.e. (-1) if value1 < value2,
438 * (+1) if value1 > value2, and (0) otherwise (equality)
443 #endif /* __G_PARAM_H__ */