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, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
29 #include "gparamspecs.h"
30 #include "gvaluecollector.h"
35 * @short_description: Metadata for parameter specifications
36 * @see_also: g_object_class_install_property(), g_object_set(),
37 * g_object_get(), g_object_set_property(), g_object_get_property(),
38 * g_value_register_transform_func()
41 * #GParamSpec is an object structure that encapsulates the metadata
42 * required to specify parameters, such as e.g. #GObject properties.
44 * <para id="canonical-parameter-name">
45 * Parameter names need to start with a letter (a-z or A-Z). Subsequent
46 * characters can be letters, numbers or a '-'.
47 * All other characters are replaced by a '-' during construction.
48 * The result of this replacement is called the canonical name of the
55 #define PARAM_FLOATING_FLAG 0x2
56 #define G_PARAM_USER_MASK (~0 << G_PARAM_USER_SHIFT)
57 #define PSPEC_APPLIES_TO_VALUE(pspec, value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_PARAM_SPEC_VALUE_TYPE (pspec)))
58 #define G_SLOCK(mutex) g_static_mutex_lock (mutex)
59 #define G_SUNLOCK(mutex) g_static_mutex_unlock (mutex)
62 /* --- prototypes --- */
63 static void g_param_spec_class_base_init (GParamSpecClass
*class);
64 static void g_param_spec_class_base_finalize (GParamSpecClass
*class);
65 static void g_param_spec_class_init (GParamSpecClass
*class,
67 static void g_param_spec_init (GParamSpec
*pspec
,
68 GParamSpecClass
*class);
69 static void g_param_spec_finalize (GParamSpec
*pspec
);
70 static void value_param_init (GValue
*value
);
71 static void value_param_free_value (GValue
*value
);
72 static void value_param_copy_value (const GValue
*src_value
,
74 static void value_param_transform_value (const GValue
*src_value
,
76 static gpointer
value_param_peek_pointer (const GValue
*value
);
77 static gchar
* value_param_collect_value (GValue
*value
,
78 guint n_collect_values
,
79 GTypeCValue
*collect_values
,
81 static gchar
* value_param_lcopy_value (const GValue
*value
,
82 guint n_collect_values
,
83 GTypeCValue
*collect_values
,
87 /* --- functions --- */
89 g_param_type_init (void)
91 static const GTypeFundamentalInfo finfo
= {
92 (G_TYPE_FLAG_CLASSED
|
93 G_TYPE_FLAG_INSTANTIATABLE
|
94 G_TYPE_FLAG_DERIVABLE
|
95 G_TYPE_FLAG_DEEP_DERIVABLE
),
97 static const GTypeValueTable param_value_table
= {
98 value_param_init
, /* value_init */
99 value_param_free_value
, /* value_free */
100 value_param_copy_value
, /* value_copy */
101 value_param_peek_pointer
, /* value_peek_pointer */
102 "p", /* collect_format */
103 value_param_collect_value
, /* collect_value */
104 "p", /* lcopy_format */
105 value_param_lcopy_value
, /* lcopy_value */
107 static const GTypeInfo param_spec_info
= {
108 sizeof (GParamSpecClass
),
110 (GBaseInitFunc
) g_param_spec_class_base_init
,
111 (GBaseFinalizeFunc
) g_param_spec_class_base_finalize
,
112 (GClassInitFunc
) g_param_spec_class_init
,
113 (GClassFinalizeFunc
) NULL
,
114 NULL
, /* class_data */
118 (GInstanceInitFunc
) g_param_spec_init
,
124 /* This should be registred as GParamSpec instead of GParam, for
125 * consistency sake, so that type name can be mapped to struct name,
126 * However, some language bindings, most noticable the python ones
127 * depends on the "GParam" identifier, see #548689
129 type
= g_type_register_fundamental (G_TYPE_PARAM
, g_intern_static_string ("GParam"), ¶m_spec_info
, &finfo
, G_TYPE_FLAG_ABSTRACT
);
130 g_assert (type
== G_TYPE_PARAM
);
131 g_value_register_transform_func (G_TYPE_PARAM
, G_TYPE_PARAM
, value_param_transform_value
);
135 g_param_spec_class_base_init (GParamSpecClass
*class)
140 g_param_spec_class_base_finalize (GParamSpecClass
*class)
145 g_param_spec_class_init (GParamSpecClass
*class,
148 class->value_type
= G_TYPE_NONE
;
149 class->finalize
= g_param_spec_finalize
;
150 class->value_set_default
= NULL
;
151 class->value_validate
= NULL
;
152 class->values_cmp
= NULL
;
156 g_param_spec_init (GParamSpec
*pspec
,
157 GParamSpecClass
*class)
161 pspec
->_blurb
= NULL
;
163 pspec
->value_type
= class->value_type
;
164 pspec
->owner_type
= 0;
166 g_datalist_init (&pspec
->qdata
);
167 g_datalist_set_flags (&pspec
->qdata
, PARAM_FLOATING_FLAG
);
168 pspec
->ref_count
= 1;
173 g_param_spec_finalize (GParamSpec
*pspec
)
175 g_datalist_clear (&pspec
->qdata
);
177 if (!(pspec
->flags
& G_PARAM_STATIC_NAME
))
178 g_free (pspec
->name
);
180 if (!(pspec
->flags
& G_PARAM_STATIC_NICK
))
181 g_free (pspec
->_nick
);
183 if (!(pspec
->flags
& G_PARAM_STATIC_BLURB
))
184 g_free (pspec
->_blurb
);
186 g_type_free_instance ((GTypeInstance
*) pspec
);
191 * @pspec: a valid #GParamSpec
193 * Increments the reference count of @pspec.
195 * Returns: the #GParamSpec that was passed into this function
198 g_param_spec_ref (GParamSpec
*pspec
)
200 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
201 g_return_val_if_fail (pspec
->ref_count
> 0, NULL
);
203 g_atomic_int_inc ((int *)&pspec
->ref_count
);
209 * g_param_spec_unref:
210 * @pspec: a valid #GParamSpec
212 * Decrements the reference count of a @pspec.
215 g_param_spec_unref (GParamSpec
*pspec
)
219 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
220 g_return_if_fail (pspec
->ref_count
> 0);
222 is_zero
= g_atomic_int_dec_and_test ((int *)&pspec
->ref_count
);
224 if (G_UNLIKELY (is_zero
))
226 G_PARAM_SPEC_GET_CLASS (pspec
)->finalize (pspec
);
232 * @pspec: a valid #GParamSpec
234 * The initial reference count of a newly created #GParamSpec is 1,
235 * even though no one has explicitly called g_param_spec_ref() on it
236 * yet. So the initial reference count is flagged as "floating", until
237 * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink
238 * (pspec);</literal> in sequence on it, taking over the initial
239 * reference count (thus ending up with a @pspec that has a reference
240 * count of 1 still, but is not flagged "floating" anymore).
243 g_param_spec_sink (GParamSpec
*pspec
)
246 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
247 g_return_if_fail (pspec
->ref_count
> 0);
250 oldvalue
= g_atomic_pointer_get (&pspec
->qdata
);
251 while (!g_atomic_pointer_compare_and_exchange ((void**) &pspec
->qdata
, oldvalue
,
252 (gpointer
) ((gsize
) oldvalue
& ~(gsize
) PARAM_FLOATING_FLAG
)));
253 if ((gsize
) oldvalue
& PARAM_FLOATING_FLAG
)
254 g_param_spec_unref (pspec
);
258 * g_param_spec_ref_sink:
259 * @pspec: a valid #GParamSpec
261 * Convenience function to ref and sink a #GParamSpec.
264 * Returns: the #GParamSpec that was passed into this function
267 g_param_spec_ref_sink (GParamSpec
*pspec
)
269 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
270 g_return_val_if_fail (pspec
->ref_count
> 0, NULL
);
272 g_param_spec_ref (pspec
);
273 g_param_spec_sink (pspec
);
278 * g_param_spec_get_name:
279 * @pspec: a valid #GParamSpec
281 * Get the name of a #GParamSpec.
283 * Returns: the name of @pspec.
285 G_CONST_RETURN gchar
*
286 g_param_spec_get_name (GParamSpec
*pspec
)
288 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
294 * g_param_spec_get_nick:
295 * @pspec: a valid #GParamSpec
297 * Get the nickname of a #GParamSpec.
299 * Returns: the nickname of @pspec.
301 G_CONST_RETURN gchar
*
302 g_param_spec_get_nick (GParamSpec
*pspec
)
304 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
310 GParamSpec
*redirect_target
;
312 redirect_target
= g_param_spec_get_redirect_target (pspec
);
313 if (redirect_target
&& redirect_target
->_nick
)
314 return redirect_target
->_nick
;
321 * g_param_spec_get_blurb:
322 * @pspec: a valid #GParamSpec
324 * Get the short description of a #GParamSpec.
326 * Returns: the short description of @pspec.
328 G_CONST_RETURN gchar
*
329 g_param_spec_get_blurb (GParamSpec
*pspec
)
331 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
334 return pspec
->_blurb
;
337 GParamSpec
*redirect_target
;
339 redirect_target
= g_param_spec_get_redirect_target (pspec
);
340 if (redirect_target
&& redirect_target
->_blurb
)
341 return redirect_target
->_blurb
;
348 canonicalize_key (gchar
*key
)
352 for (p
= key
; *p
!= 0; p
++)
357 (c
< '0' || c
> '9') &&
358 (c
< 'A' || c
> 'Z') &&
359 (c
< 'a' || c
> 'z'))
365 is_canonical (const gchar
*key
)
369 for (p
= key
; *p
!= 0; p
++)
374 (c
< '0' || c
> '9') &&
375 (c
< 'A' || c
> 'Z') &&
376 (c
< 'a' || c
> 'z'))
384 * g_param_spec_internal:
385 * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
386 * @name: the canonical name of the property
387 * @nick: the nickname of the property
388 * @blurb: a short description of the property
389 * @flags: a combination of #GParamFlags
391 * Creates a new #GParamSpec instance.
393 * A property name consists of segments consisting of ASCII letters and
394 * digits, separated by either the '-' or '_' character. The first
395 * character of a property name must be a letter. Names which violate these
396 * rules lead to undefined behaviour.
398 * When creating and looking up a #GParamSpec, either separator can be
399 * used, but they cannot be mixed. Using '-' is considerably more
400 * efficient and in fact required when using property names as detail
401 * strings for signals.
403 * Beyond the name, #GParamSpec<!-- -->s have two more descriptive
404 * strings associated with them, the @nick, which should be suitable
405 * for use as a label for the property in a property editor, and the
406 * @blurb, which should be a somewhat longer description, suitable for
407 * e.g. a tooltip. The @nick and @blurb should ideally be localized.
409 * Returns: a newly allocated #GParamSpec instance
412 g_param_spec_internal (GType param_type
,
420 g_return_val_if_fail (G_TYPE_IS_PARAM (param_type
) && param_type
!= G_TYPE_PARAM
, NULL
);
421 g_return_val_if_fail (name
!= NULL
, NULL
);
422 g_return_val_if_fail ((name
[0] >= 'A' && name
[0] <= 'Z') || (name
[0] >= 'a' && name
[0] <= 'z'), NULL
);
423 g_return_val_if_fail (!(flags
& G_PARAM_STATIC_NAME
) || is_canonical (name
), NULL
);
425 pspec
= (gpointer
) g_type_create_instance (param_type
);
427 if (flags
& G_PARAM_STATIC_NAME
)
429 pspec
->name
= g_intern_static_string (name
);
430 if (!is_canonical (pspec
->name
))
431 g_warning ("G_PARAM_STATIC_NAME used with non-canonical pspec name: %s", pspec
->name
);
435 pspec
->name
= g_strdup (name
);
436 canonicalize_key (pspec
->name
);
437 g_intern_string (pspec
->name
);
440 if (flags
& G_PARAM_STATIC_NICK
)
441 pspec
->_nick
= (gchar
*) nick
;
443 pspec
->_nick
= g_strdup (nick
);
445 if (flags
& G_PARAM_STATIC_BLURB
)
446 pspec
->_blurb
= (gchar
*) blurb
;
448 pspec
->_blurb
= g_strdup (blurb
);
450 pspec
->flags
= (flags
& G_PARAM_USER_MASK
) | (flags
& G_PARAM_MASK
);
456 * g_param_spec_get_qdata:
457 * @pspec: a valid #GParamSpec
458 * @quark: a #GQuark, naming the user data pointer
460 * Gets back user data pointers stored via g_param_spec_set_qdata().
462 * Returns: the user data pointer set, or %NULL
465 g_param_spec_get_qdata (GParamSpec
*pspec
,
468 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
470 return quark
? g_datalist_id_get_data (&pspec
->qdata
, quark
) : NULL
;
474 * g_param_spec_set_qdata:
475 * @pspec: the #GParamSpec to set store a user data pointer
476 * @quark: a #GQuark, naming the user data pointer
477 * @data: an opaque user data pointer
479 * Sets an opaque, named pointer on a #GParamSpec. The name is
480 * specified through a #GQuark (retrieved e.g. via
481 * g_quark_from_static_string()), and the pointer can be gotten back
482 * from the @pspec with g_param_spec_get_qdata(). Setting a
483 * previously set user data pointer, overrides (frees) the old pointer
484 * set, using %NULL as pointer essentially removes the data stored.
487 g_param_spec_set_qdata (GParamSpec
*pspec
,
491 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
492 g_return_if_fail (quark
> 0);
494 g_datalist_id_set_data (&pspec
->qdata
, quark
, data
);
498 * g_param_spec_set_qdata_full:
499 * @pspec: the #GParamSpec to set store a user data pointer
500 * @quark: a #GQuark, naming the user data pointer
501 * @data: an opaque user data pointer
502 * @destroy: function to invoke with @data as argument, when @data needs to
505 * This function works like g_param_spec_set_qdata(), but in addition,
506 * a <literal>void (*destroy) (gpointer)</literal> function may be
507 * specified which is called with @data as argument when the @pspec is
508 * finalized, or the data is being overwritten by a call to
509 * g_param_spec_set_qdata() with the same @quark.
512 g_param_spec_set_qdata_full (GParamSpec
*pspec
,
515 GDestroyNotify destroy
)
517 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
518 g_return_if_fail (quark
> 0);
520 g_datalist_id_set_data_full (&pspec
->qdata
, quark
, data
, data
? destroy
: (GDestroyNotify
) NULL
);
524 * g_param_spec_steal_qdata:
525 * @pspec: the #GParamSpec to get a stored user data pointer from
526 * @quark: a #GQuark, naming the user data pointer
528 * Gets back user data pointers stored via g_param_spec_set_qdata()
529 * and removes the @data from @pspec without invoking its destroy()
530 * function (if any was set). Usually, calling this function is only
531 * required to update user data pointers with a destroy notifier.
533 * Returns: the user data pointer set, or %NULL
536 g_param_spec_steal_qdata (GParamSpec
*pspec
,
539 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
540 g_return_val_if_fail (quark
> 0, NULL
);
542 return g_datalist_id_remove_no_notify (&pspec
->qdata
, quark
);
546 * g_param_spec_get_redirect_target:
547 * @pspec: a #GParamSpec
549 * If the paramspec redirects operations to another paramspec,
550 * returns that paramspec. Redirect is used typically for
551 * providing a new implementation of a property in a derived
552 * type while preserving all the properties from the parent
553 * type. Redirection is established by creating a property
554 * of type #GParamSpecOverride. See g_object_class_override_property()
555 * for an example of the use of this capability.
559 * Returns: paramspec to which requests on this paramspec should
560 * be redirected, or %NULL if none.
563 g_param_spec_get_redirect_target (GParamSpec
*pspec
)
565 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
567 if (G_IS_PARAM_SPEC_OVERRIDE (pspec
))
569 GParamSpecOverride
*ospec
= G_PARAM_SPEC_OVERRIDE (pspec
);
571 return ospec
->overridden
;
578 * g_param_value_set_default:
579 * @pspec: a valid #GParamSpec
580 * @value: a #GValue of correct type for @pspec
582 * Sets @value to its default value as specified in @pspec.
585 g_param_value_set_default (GParamSpec
*pspec
,
588 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
589 g_return_if_fail (G_IS_VALUE (value
));
590 g_return_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
));
592 g_value_reset (value
);
593 G_PARAM_SPEC_GET_CLASS (pspec
)->value_set_default (pspec
, value
);
597 * g_param_value_defaults:
598 * @pspec: a valid #GParamSpec
599 * @value: a #GValue of correct type for @pspec
601 * Checks whether @value contains the default value as specified in @pspec.
603 * Returns: whether @value contains the canonical default for this @pspec
606 g_param_value_defaults (GParamSpec
*pspec
,
609 GValue dflt_value
= { 0, };
612 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
613 g_return_val_if_fail (G_IS_VALUE (value
), FALSE
);
614 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
), FALSE
);
616 g_value_init (&dflt_value
, G_PARAM_SPEC_VALUE_TYPE (pspec
));
617 G_PARAM_SPEC_GET_CLASS (pspec
)->value_set_default (pspec
, &dflt_value
);
618 defaults
= G_PARAM_SPEC_GET_CLASS (pspec
)->values_cmp (pspec
, value
, &dflt_value
) == 0;
619 g_value_unset (&dflt_value
);
625 * g_param_value_validate:
626 * @pspec: a valid #GParamSpec
627 * @value: a #GValue of correct type for @pspec
629 * Ensures that the contents of @value comply with the specifications
630 * set out by @pspec. For example, a #GParamSpecInt might require
631 * that integers stored in @value may not be smaller than -42 and not be
632 * greater than +42. If @value contains an integer outside of this range,
633 * it is modified accordingly, so the resulting value will fit into the
636 * Returns: whether modifying @value was necessary to ensure validity
639 g_param_value_validate (GParamSpec
*pspec
,
642 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
643 g_return_val_if_fail (G_IS_VALUE (value
), FALSE
);
644 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
), FALSE
);
646 if (G_PARAM_SPEC_GET_CLASS (pspec
)->value_validate
)
648 GValue oval
= *value
;
650 if (G_PARAM_SPEC_GET_CLASS (pspec
)->value_validate (pspec
, value
) ||
651 memcmp (&oval
.data
, &value
->data
, sizeof (oval
.data
)))
659 * g_param_value_convert:
660 * @pspec: a valid #GParamSpec
661 * @src_value: souce #GValue
662 * @dest_value: destination #GValue of correct type for @pspec
663 * @strict_validation: %TRUE requires @dest_value to conform to @pspec
664 * without modifications
666 * Transforms @src_value into @dest_value if possible, and then
667 * validates @dest_value, in order for it to conform to @pspec. If
668 * @strict_validation is %TRUE this function will only succeed if the
669 * transformed @dest_value complied to @pspec without modifications.
671 * See also g_value_type_transformable(), g_value_transform() and
672 * g_param_value_validate().
674 * Returns: %TRUE if transformation and validation were successful,
675 * %FALSE otherwise and @dest_value is left untouched.
678 g_param_value_convert (GParamSpec
*pspec
,
679 const GValue
*src_value
,
681 gboolean strict_validation
)
683 GValue tmp_value
= { 0, };
685 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
686 g_return_val_if_fail (G_IS_VALUE (src_value
), FALSE
);
687 g_return_val_if_fail (G_IS_VALUE (dest_value
), FALSE
);
688 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, dest_value
), FALSE
);
690 /* better leave dest_value untouched when returning FALSE */
692 g_value_init (&tmp_value
, G_VALUE_TYPE (dest_value
));
693 if (g_value_transform (src_value
, &tmp_value
) &&
694 (!g_param_value_validate (pspec
, &tmp_value
) || !strict_validation
))
696 g_value_unset (dest_value
);
698 /* values are relocatable */
699 memcpy (dest_value
, &tmp_value
, sizeof (tmp_value
));
705 g_value_unset (&tmp_value
);
712 * g_param_values_cmp:
713 * @pspec: a valid #GParamSpec
714 * @value1: a #GValue of correct type for @pspec
715 * @value2: a #GValue of correct type for @pspec
717 * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1,
718 * if @value1 is found to be less than, equal to or greater than @value2,
721 * Returns: -1, 0 or +1, for a less than, equal to or greater than result
724 g_param_values_cmp (GParamSpec
*pspec
,
725 const GValue
*value1
,
726 const GValue
*value2
)
730 /* param_values_cmp() effectively does: value1 - value2
731 * so the return values are:
732 * -1) value1 < value2
733 * 0) value1 == value2
736 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), 0);
737 g_return_val_if_fail (G_IS_VALUE (value1
), 0);
738 g_return_val_if_fail (G_IS_VALUE (value2
), 0);
739 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value1
), 0);
740 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value2
), 0);
742 cmp
= G_PARAM_SPEC_GET_CLASS (pspec
)->values_cmp (pspec
, value1
, value2
);
744 return CLAMP (cmp
, -1, 1);
748 value_param_init (GValue
*value
)
750 value
->data
[0].v_pointer
= NULL
;
754 value_param_free_value (GValue
*value
)
756 if (value
->data
[0].v_pointer
)
757 g_param_spec_unref (value
->data
[0].v_pointer
);
761 value_param_copy_value (const GValue
*src_value
,
764 if (src_value
->data
[0].v_pointer
)
765 dest_value
->data
[0].v_pointer
= g_param_spec_ref (src_value
->data
[0].v_pointer
);
767 dest_value
->data
[0].v_pointer
= NULL
;
771 value_param_transform_value (const GValue
*src_value
,
774 if (src_value
->data
[0].v_pointer
&&
775 g_type_is_a (G_PARAM_SPEC_TYPE (dest_value
->data
[0].v_pointer
), G_VALUE_TYPE (dest_value
)))
776 dest_value
->data
[0].v_pointer
= g_param_spec_ref (src_value
->data
[0].v_pointer
);
778 dest_value
->data
[0].v_pointer
= NULL
;
782 value_param_peek_pointer (const GValue
*value
)
784 return value
->data
[0].v_pointer
;
788 value_param_collect_value (GValue
*value
,
789 guint n_collect_values
,
790 GTypeCValue
*collect_values
,
793 if (collect_values
[0].v_pointer
)
795 GParamSpec
*param
= collect_values
[0].v_pointer
;
797 if (param
->g_type_instance
.g_class
== NULL
)
798 return g_strconcat ("invalid unclassed param spec pointer for value type `",
799 G_VALUE_TYPE_NAME (value
),
802 else if (!g_value_type_compatible (G_PARAM_SPEC_TYPE (param
), G_VALUE_TYPE (value
)))
803 return g_strconcat ("invalid param spec type `",
804 G_PARAM_SPEC_TYPE_NAME (param
),
805 "' for value type `",
806 G_VALUE_TYPE_NAME (value
),
809 value
->data
[0].v_pointer
= g_param_spec_ref (param
);
812 value
->data
[0].v_pointer
= NULL
;
818 value_param_lcopy_value (const GValue
*value
,
819 guint n_collect_values
,
820 GTypeCValue
*collect_values
,
823 GParamSpec
**param_p
= collect_values
[0].v_pointer
;
826 return g_strdup_printf ("value location for `%s' passed as NULL", G_VALUE_TYPE_NAME (value
));
828 if (!value
->data
[0].v_pointer
)
830 else if (collect_flags
& G_VALUE_NOCOPY_CONTENTS
)
831 *param_p
= value
->data
[0].v_pointer
;
833 *param_p
= g_param_spec_ref (value
->data
[0].v_pointer
);
839 /* --- param spec pool --- */
843 * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be
844 * quickly accessed by owner and name. The implementation of the #GObject property
845 * system uses such a pool to store the #GParamSpecs of the properties all object
848 struct _GParamSpecPool
851 gboolean type_prefixing
;
852 GHashTable
*hash_table
;
856 param_spec_pool_hash (gconstpointer key_spec
)
858 const GParamSpec
*key
= key_spec
;
860 guint h
= key
->owner_type
;
862 for (p
= key
->name
; *p
; p
++)
863 h
= (h
<< 5) - h
+ *p
;
869 param_spec_pool_equals (gconstpointer key_spec_1
,
870 gconstpointer key_spec_2
)
872 const GParamSpec
*key1
= key_spec_1
;
873 const GParamSpec
*key2
= key_spec_2
;
875 return (key1
->owner_type
== key2
->owner_type
&&
876 strcmp (key1
->name
, key2
->name
) == 0);
880 * g_param_spec_pool_new:
881 * @type_prefixing: Whether the pool will support type-prefixed property names.
883 * Creates a new #GParamSpecPool.
885 * If @type_prefixing is %TRUE, lookups in the newly created pool will
886 * allow to specify the owner as a colon-separated prefix of the
887 * property name, like "GtkContainer:border-width". This feature is
888 * deprecated, so you should always set @type_prefixing to %FALSE.
890 * Returns: a newly allocated #GParamSpecPool.
893 g_param_spec_pool_new (gboolean type_prefixing
)
895 static GStaticMutex init_smutex
= G_STATIC_MUTEX_INIT
;
896 GParamSpecPool
*pool
= g_new (GParamSpecPool
, 1);
898 memcpy (&pool
->smutex
, &init_smutex
, sizeof (init_smutex
));
899 pool
->type_prefixing
= type_prefixing
!= FALSE
;
900 pool
->hash_table
= g_hash_table_new (param_spec_pool_hash
, param_spec_pool_equals
);
906 * g_param_spec_pool_insert:
907 * @pool: a #GParamSpecPool.
908 * @pspec: the #GParamSpec to insert
909 * @owner_type: a #GType identifying the owner of @pspec
911 * Inserts a #GParamSpec in the pool.
914 g_param_spec_pool_insert (GParamSpecPool
*pool
,
920 if (pool
&& pspec
&& owner_type
> 0 && pspec
->owner_type
== 0)
922 G_SLOCK (&pool
->smutex
);
923 for (p
= pspec
->name
; *p
; p
++)
925 if (!strchr (G_CSET_A_2_Z G_CSET_a_2_z G_CSET_DIGITS
"-_", *p
))
927 g_warning (G_STRLOC
": pspec name \"%s\" contains invalid characters", pspec
->name
);
928 G_SUNLOCK (&pool
->smutex
);
933 pspec
->owner_type
= owner_type
;
934 g_param_spec_ref (pspec
);
935 g_hash_table_insert (pool
->hash_table
, pspec
, pspec
);
936 G_SUNLOCK (&pool
->smutex
);
940 g_return_if_fail (pool
!= NULL
);
941 g_return_if_fail (pspec
);
942 g_return_if_fail (owner_type
> 0);
943 g_return_if_fail (pspec
->owner_type
== 0);
948 * g_param_spec_pool_remove:
949 * @pool: a #GParamSpecPool
950 * @pspec: the #GParamSpec to remove
952 * Removes a #GParamSpec from the pool.
955 g_param_spec_pool_remove (GParamSpecPool
*pool
,
960 G_SLOCK (&pool
->smutex
);
961 if (g_hash_table_remove (pool
->hash_table
, pspec
))
962 g_param_spec_unref (pspec
);
964 g_warning (G_STRLOC
": attempt to remove unknown pspec `%s' from pool", pspec
->name
);
965 G_SUNLOCK (&pool
->smutex
);
969 g_return_if_fail (pool
!= NULL
);
970 g_return_if_fail (pspec
);
974 static inline GParamSpec
*
975 param_spec_ht_lookup (GHashTable
*hash_table
,
976 const gchar
*param_name
,
978 gboolean walk_ancestors
)
980 GParamSpec key
, *pspec
;
982 key
.owner_type
= owner_type
;
983 key
.name
= (gchar
*) param_name
;
987 pspec
= g_hash_table_lookup (hash_table
, &key
);
990 key
.owner_type
= g_type_parent (key
.owner_type
);
992 while (key
.owner_type
);
994 pspec
= g_hash_table_lookup (hash_table
, &key
);
996 if (!pspec
&& !is_canonical (param_name
))
998 /* try canonicalized form */
999 key
.name
= g_strdup (param_name
);
1000 key
.owner_type
= owner_type
;
1002 canonicalize_key (key
.name
);
1006 pspec
= g_hash_table_lookup (hash_table
, &key
);
1012 key
.owner_type
= g_type_parent (key
.owner_type
);
1014 while (key
.owner_type
);
1016 pspec
= g_hash_table_lookup (hash_table
, &key
);
1024 * g_param_spec_pool_lookup:
1025 * @pool: a #GParamSpecPool
1026 * @param_name: the name to look for
1027 * @owner_type: the owner to look for
1028 * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name
1029 * owned by an ancestor of @owner_type.
1031 * Looks up a #GParamSpec in the pool.
1033 * Returns: The found #GParamSpec, or %NULL if no matching #GParamSpec was found.
1036 g_param_spec_pool_lookup (GParamSpecPool
*pool
,
1037 const gchar
*param_name
,
1039 gboolean walk_ancestors
)
1044 if (!pool
|| !param_name
)
1046 g_return_val_if_fail (pool
!= NULL
, NULL
);
1047 g_return_val_if_fail (param_name
!= NULL
, NULL
);
1050 G_SLOCK (&pool
->smutex
);
1052 delim
= pool
->type_prefixing
? strchr (param_name
, ':') : NULL
;
1054 /* try quick and away, i.e. without prefix */
1057 pspec
= param_spec_ht_lookup (pool
->hash_table
, param_name
, owner_type
, walk_ancestors
);
1058 G_SUNLOCK (&pool
->smutex
);
1063 /* strip type prefix */
1064 if (pool
->type_prefixing
&& delim
[1] == ':')
1066 guint l
= delim
- param_name
;
1067 gchar stack_buffer
[32], *buffer
= l
< 32 ? stack_buffer
: g_new (gchar
, l
+ 1);
1070 strncpy (buffer
, param_name
, delim
- param_name
);
1072 type
= g_type_from_name (buffer
);
1075 if (type
) /* type==0 isn't a valid type pefix */
1077 /* sanity check, these cases don't make a whole lot of sense */
1078 if ((!walk_ancestors
&& type
!= owner_type
) || !g_type_is_a (owner_type
, type
))
1080 G_SUNLOCK (&pool
->smutex
);
1085 param_name
+= l
+ 2;
1086 pspec
= param_spec_ht_lookup (pool
->hash_table
, param_name
, owner_type
, walk_ancestors
);
1087 G_SUNLOCK (&pool
->smutex
);
1092 /* malformed param_name */
1094 G_SUNLOCK (&pool
->smutex
);
1100 pool_list (gpointer key
,
1104 GParamSpec
*pspec
= value
;
1105 gpointer
*data
= user_data
;
1106 GType owner_type
= (GType
) data
[1];
1108 if (owner_type
== pspec
->owner_type
)
1109 data
[0] = g_list_prepend (data
[0], pspec
);
1113 * g_param_spec_pool_list_owned:
1114 * @pool: a #GParamSpecPool
1115 * @owner_type: the owner to look for
1117 * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
1120 * Returns: a #GList of all #GParamSpec<!-- -->s owned by @owner_type
1121 * in the pool#GParamSpec<!-- -->s.
1124 g_param_spec_pool_list_owned (GParamSpecPool
*pool
,
1129 g_return_val_if_fail (pool
!= NULL
, NULL
);
1130 g_return_val_if_fail (owner_type
> 0, NULL
);
1132 G_SLOCK (&pool
->smutex
);
1134 data
[1] = (gpointer
) owner_type
;
1135 g_hash_table_foreach (pool
->hash_table
, pool_list
, &data
);
1136 G_SUNLOCK (&pool
->smutex
);
1142 pspec_compare_id (gconstpointer a
,
1145 const GParamSpec
*pspec1
= a
, *pspec2
= b
;
1147 if (pspec1
->param_id
< pspec2
->param_id
)
1150 if (pspec1
->param_id
> pspec2
->param_id
)
1153 return strcmp (pspec1
->name
, pspec2
->name
);
1156 static inline GSList
*
1157 pspec_list_remove_overridden_and_redirected (GSList
*plist
,
1162 GSList
*rlist
= NULL
;
1166 GSList
*tmp
= plist
->next
;
1167 GParamSpec
*pspec
= plist
->data
;
1169 gboolean remove
= FALSE
;
1171 /* Remove paramspecs that are redirected, and also paramspecs
1172 * that have are overridden by non-redirected properties.
1173 * The idea is to get the single paramspec for each name that
1174 * best corresponds to what the application sees.
1176 if (g_param_spec_get_redirect_target (pspec
))
1180 found
= param_spec_ht_lookup (ht
, pspec
->name
, owner_type
, TRUE
);
1183 GParamSpec
*redirect
= g_param_spec_get_redirect_target (found
);
1184 if (redirect
!= pspec
)
1191 g_slist_free_1 (plist
);
1195 plist
->next
= rlist
;
1205 pool_depth_list (gpointer key
,
1209 GParamSpec
*pspec
= value
;
1210 gpointer
*data
= user_data
;
1211 GSList
**slists
= data
[0];
1212 GType owner_type
= (GType
) data
[1];
1214 if (g_type_is_a (owner_type
, pspec
->owner_type
))
1216 if (G_TYPE_IS_INTERFACE (pspec
->owner_type
))
1218 slists
[0] = g_slist_prepend (slists
[0], pspec
);
1222 guint d
= g_type_depth (pspec
->owner_type
);
1224 slists
[d
- 1] = g_slist_prepend (slists
[d
- 1], pspec
);
1229 /* We handle interfaces specially since we don't want to
1230 * count interface prerequisites like normal inheritance;
1231 * the property comes from the direct inheritance from
1232 * the prerequisite class, not from the interface that
1235 * also 'depth' isn't a meaningful concept for interface
1239 pool_depth_list_for_interface (gpointer key
,
1243 GParamSpec
*pspec
= value
;
1244 gpointer
*data
= user_data
;
1245 GSList
**slists
= data
[0];
1246 GType owner_type
= (GType
) data
[1];
1248 if (pspec
->owner_type
== owner_type
)
1249 slists
[0] = g_slist_prepend (slists
[0], pspec
);
1253 * g_param_spec_pool_list:
1254 * @pool: a #GParamSpecPool
1255 * @owner_type: the owner to look for
1256 * @n_pspecs_p: return location for the length of the returned array
1258 * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
1261 * Returns: a newly allocated array containing pointers to all
1262 * #GParamSpec<!-- -->s owned by @owner_type in the pool
1265 g_param_spec_pool_list (GParamSpecPool
*pool
,
1269 GParamSpec
**pspecs
, **p
;
1270 GSList
**slists
, *node
;
1274 g_return_val_if_fail (pool
!= NULL
, NULL
);
1275 g_return_val_if_fail (owner_type
> 0, NULL
);
1276 g_return_val_if_fail (n_pspecs_p
!= NULL
, NULL
);
1278 G_SLOCK (&pool
->smutex
);
1280 d
= g_type_depth (owner_type
);
1281 slists
= g_new0 (GSList
*, d
);
1283 data
[1] = (gpointer
) owner_type
;
1285 g_hash_table_foreach (pool
->hash_table
,
1286 G_TYPE_IS_INTERFACE (owner_type
) ?
1287 pool_depth_list_for_interface
:
1291 for (i
= 0; i
< d
; i
++)
1292 slists
[i
] = pspec_list_remove_overridden_and_redirected (slists
[i
], pool
->hash_table
, owner_type
, n_pspecs_p
);
1293 pspecs
= g_new (GParamSpec
*, *n_pspecs_p
+ 1);
1295 for (i
= 0; i
< d
; i
++)
1297 slists
[i
] = g_slist_sort (slists
[i
], pspec_compare_id
);
1298 for (node
= slists
[i
]; node
; node
= node
->next
)
1300 g_slist_free (slists
[i
]);
1304 G_SUNLOCK (&pool
->smutex
);
1310 /* --- auxillary functions --- */
1315 void (*finalize
) (GParamSpec
*pspec
);
1316 void (*value_set_default
) (GParamSpec
*pspec
,
1318 gboolean (*value_validate
) (GParamSpec
*pspec
,
1320 gint (*values_cmp
) (GParamSpec
*pspec
,
1321 const GValue
*value1
,
1322 const GValue
*value2
);
1323 } ParamSpecClassInfo
;
1326 param_spec_generic_class_init (gpointer g_class
,
1327 gpointer class_data
)
1329 GParamSpecClass
*class = g_class
;
1330 ParamSpecClassInfo
*info
= class_data
;
1332 class->value_type
= info
->value_type
;
1334 class->finalize
= info
->finalize
; /* optional */
1335 class->value_set_default
= info
->value_set_default
;
1336 if (info
->value_validate
)
1337 class->value_validate
= info
->value_validate
; /* optional */
1338 class->values_cmp
= info
->values_cmp
;
1339 g_free (class_data
);
1343 default_value_set_default (GParamSpec
*pspec
,
1346 /* value is already zero initialized */
1350 default_values_cmp (GParamSpec
*pspec
,
1351 const GValue
*value1
,
1352 const GValue
*value2
)
1354 return memcmp (&value1
->data
, &value2
->data
, sizeof (value1
->data
));
1358 * g_param_type_register_static:
1359 * @name: 0-terminated string used as the name of the new #GParamSpec type.
1360 * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
1362 * Registers @name as the name of a new static type derived from
1363 * #G_TYPE_PARAM. The type system uses the information contained in
1364 * the #GParamSpecTypeInfo structure pointed to by @info to manage the
1365 * #GParamSpec type and its instances.
1367 * Returns: The new type identifier.
1370 g_param_type_register_static (const gchar
*name
,
1371 const GParamSpecTypeInfo
*pspec_info
)
1374 sizeof (GParamSpecClass
), /* class_size */
1375 NULL
, /* base_init */
1376 NULL
, /* base_destroy */
1377 param_spec_generic_class_init
, /* class_init */
1378 NULL
, /* class_destroy */
1379 NULL
, /* class_data */
1380 0, /* instance_size */
1381 16, /* n_preallocs */
1382 NULL
, /* instance_init */
1384 ParamSpecClassInfo
*cinfo
;
1386 g_return_val_if_fail (name
!= NULL
, 0);
1387 g_return_val_if_fail (pspec_info
!= NULL
, 0);
1388 g_return_val_if_fail (g_type_from_name (name
) == 0, 0);
1389 g_return_val_if_fail (pspec_info
->instance_size
>= sizeof (GParamSpec
), 0);
1390 g_return_val_if_fail (g_type_name (pspec_info
->value_type
) != NULL
, 0);
1391 /* default: g_return_val_if_fail (pspec_info->value_set_default != NULL, 0); */
1392 /* optional: g_return_val_if_fail (pspec_info->value_validate != NULL, 0); */
1393 /* default: g_return_val_if_fail (pspec_info->values_cmp != NULL, 0); */
1395 info
.instance_size
= pspec_info
->instance_size
;
1396 info
.n_preallocs
= pspec_info
->n_preallocs
;
1397 info
.instance_init
= (GInstanceInitFunc
) pspec_info
->instance_init
;
1398 cinfo
= g_new (ParamSpecClassInfo
, 1);
1399 cinfo
->value_type
= pspec_info
->value_type
;
1400 cinfo
->finalize
= pspec_info
->finalize
;
1401 cinfo
->value_set_default
= pspec_info
->value_set_default
? pspec_info
->value_set_default
: default_value_set_default
;
1402 cinfo
->value_validate
= pspec_info
->value_validate
;
1403 cinfo
->values_cmp
= pspec_info
->values_cmp
? pspec_info
->values_cmp
: default_values_cmp
;
1404 info
.class_data
= cinfo
;
1406 return g_type_register_static (G_TYPE_PARAM
, name
, &info
, 0);
1410 * g_value_set_param:
1411 * @value: a valid #GValue of type %G_TYPE_PARAM
1412 * @param: the #GParamSpec to be set
1414 * Set the contents of a %G_TYPE_PARAM #GValue to @param.
1417 g_value_set_param (GValue
*value
,
1420 g_return_if_fail (G_VALUE_HOLDS_PARAM (value
));
1422 g_return_if_fail (G_IS_PARAM_SPEC (param
));
1424 if (value
->data
[0].v_pointer
)
1425 g_param_spec_unref (value
->data
[0].v_pointer
);
1426 value
->data
[0].v_pointer
= param
;
1427 if (value
->data
[0].v_pointer
)
1428 g_param_spec_ref (value
->data
[0].v_pointer
);
1432 * g_value_set_param_take_ownership:
1433 * @value: a valid #GValue of type %G_TYPE_PARAM
1434 * @param: the #GParamSpec to be set
1436 * This is an internal function introduced mainly for C marshallers.
1438 * Deprecated: 2.4: Use g_value_take_param() instead.
1441 g_value_set_param_take_ownership (GValue
*value
,
1444 g_value_take_param (value
, param
);
1448 * g_value_take_param:
1449 * @value: a valid #GValue of type %G_TYPE_PARAM
1450 * @param: the #GParamSpec to be set
1452 * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
1453 * over the ownership of the callers reference to @param; the caller
1454 * doesn't have to unref it any more.
1459 g_value_take_param (GValue
*value
,
1462 g_return_if_fail (G_VALUE_HOLDS_PARAM (value
));
1464 g_return_if_fail (G_IS_PARAM_SPEC (param
));
1466 if (value
->data
[0].v_pointer
)
1467 g_param_spec_unref (value
->data
[0].v_pointer
);
1468 value
->data
[0].v_pointer
= param
; /* we take over the reference count */
1472 * g_value_get_param:
1473 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1475 * Get the contents of a %G_TYPE_PARAM #GValue.
1477 * Returns: #GParamSpec content of @value
1480 g_value_get_param (const GValue
*value
)
1482 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value
), NULL
);
1484 return value
->data
[0].v_pointer
;
1488 * g_value_dup_param:
1489 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1491 * Get the contents of a %G_TYPE_PARAM #GValue, increasing its
1494 * Returns: #GParamSpec content of @value, should be unreferenced when
1498 g_value_dup_param (const GValue
*value
)
1500 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value
), NULL
);
1502 return value
->data
[0].v_pointer
? g_param_spec_ref (value
->data
[0].v_pointer
) : NULL
;