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"
31 #include "gtype-private.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)))
59 /* --- prototypes --- */
60 static void g_param_spec_class_base_init (GParamSpecClass
*class);
61 static void g_param_spec_class_base_finalize (GParamSpecClass
*class);
62 static void g_param_spec_class_init (GParamSpecClass
*class,
64 static void g_param_spec_init (GParamSpec
*pspec
,
65 GParamSpecClass
*class);
66 static void g_param_spec_finalize (GParamSpec
*pspec
);
67 static void value_param_init (GValue
*value
);
68 static void value_param_free_value (GValue
*value
);
69 static void value_param_copy_value (const GValue
*src_value
,
71 static void value_param_transform_value (const GValue
*src_value
,
73 static gpointer
value_param_peek_pointer (const GValue
*value
);
74 static gchar
* value_param_collect_value (GValue
*value
,
75 guint n_collect_values
,
76 GTypeCValue
*collect_values
,
78 static gchar
* value_param_lcopy_value (const GValue
*value
,
79 guint n_collect_values
,
80 GTypeCValue
*collect_values
,
88 static gint g_param_private_offset
;
90 /* --- functions --- */
91 static inline GParamSpecPrivate
*
92 g_param_spec_get_private (GParamSpec
*pspec
)
94 return &G_STRUCT_MEMBER (GParamSpecPrivate
, pspec
, g_param_private_offset
);
98 _g_param_type_init (void)
100 static const GTypeFundamentalInfo finfo
= {
101 (G_TYPE_FLAG_CLASSED
|
102 G_TYPE_FLAG_INSTANTIATABLE
|
103 G_TYPE_FLAG_DERIVABLE
|
104 G_TYPE_FLAG_DEEP_DERIVABLE
),
106 static const GTypeValueTable param_value_table
= {
107 value_param_init
, /* value_init */
108 value_param_free_value
, /* value_free */
109 value_param_copy_value
, /* value_copy */
110 value_param_peek_pointer
, /* value_peek_pointer */
111 "p", /* collect_format */
112 value_param_collect_value
, /* collect_value */
113 "p", /* lcopy_format */
114 value_param_lcopy_value
, /* lcopy_value */
116 const GTypeInfo param_spec_info
= {
117 sizeof (GParamSpecClass
),
119 (GBaseInitFunc
) g_param_spec_class_base_init
,
120 (GBaseFinalizeFunc
) g_param_spec_class_base_finalize
,
121 (GClassInitFunc
) g_param_spec_class_init
,
122 (GClassFinalizeFunc
) NULL
,
123 NULL
, /* class_data */
127 (GInstanceInitFunc
) g_param_spec_init
,
133 /* This should be registered as GParamSpec instead of GParam, for
134 * consistency sake, so that type name can be mapped to struct name,
135 * However, some language bindings, most noticeable the python ones
136 * depends on the "GParam" identifier, see #548689
138 type
= g_type_register_fundamental (G_TYPE_PARAM
, g_intern_static_string ("GParam"), ¶m_spec_info
, &finfo
, G_TYPE_FLAG_ABSTRACT
);
139 g_assert (type
== G_TYPE_PARAM
);
140 g_param_private_offset
= g_type_add_instance_private (type
, sizeof (GParamSpecPrivate
));
141 g_value_register_transform_func (G_TYPE_PARAM
, G_TYPE_PARAM
, value_param_transform_value
);
145 g_param_spec_class_base_init (GParamSpecClass
*class)
150 g_param_spec_class_base_finalize (GParamSpecClass
*class)
155 g_param_spec_class_init (GParamSpecClass
*class,
158 class->value_type
= G_TYPE_NONE
;
159 class->finalize
= g_param_spec_finalize
;
160 class->value_set_default
= NULL
;
161 class->value_validate
= NULL
;
162 class->values_cmp
= NULL
;
164 g_type_class_adjust_private_offset (class, &g_param_private_offset
);
168 g_param_spec_init (GParamSpec
*pspec
,
169 GParamSpecClass
*class)
173 pspec
->_blurb
= NULL
;
175 pspec
->value_type
= class->value_type
;
176 pspec
->owner_type
= 0;
178 g_datalist_set_flags (&pspec
->qdata
, PARAM_FLOATING_FLAG
);
179 pspec
->ref_count
= 1;
184 g_param_spec_finalize (GParamSpec
*pspec
)
186 GParamSpecPrivate
*priv
= g_param_spec_get_private (pspec
);
188 if (priv
->default_value
.g_type
)
189 g_value_reset (&priv
->default_value
);
191 g_datalist_clear (&pspec
->qdata
);
193 if (!(pspec
->flags
& G_PARAM_STATIC_NICK
))
194 g_free (pspec
->_nick
);
196 if (!(pspec
->flags
& G_PARAM_STATIC_BLURB
))
197 g_free (pspec
->_blurb
);
199 g_type_free_instance ((GTypeInstance
*) pspec
);
203 * g_param_spec_ref: (skip)
204 * @pspec: a valid #GParamSpec
206 * Increments the reference count of @pspec.
208 * Returns: the #GParamSpec that was passed into this function
211 g_param_spec_ref (GParamSpec
*pspec
)
213 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
215 g_atomic_int_inc ((int *)&pspec
->ref_count
);
221 * g_param_spec_unref: (skip)
222 * @pspec: a valid #GParamSpec
224 * Decrements the reference count of a @pspec.
227 g_param_spec_unref (GParamSpec
*pspec
)
231 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
233 is_zero
= g_atomic_int_dec_and_test ((int *)&pspec
->ref_count
);
235 if (G_UNLIKELY (is_zero
))
237 G_PARAM_SPEC_GET_CLASS (pspec
)->finalize (pspec
);
243 * @pspec: a valid #GParamSpec
245 * The initial reference count of a newly created #GParamSpec is 1,
246 * even though no one has explicitly called g_param_spec_ref() on it
247 * yet. So the initial reference count is flagged as "floating", until
248 * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink
249 * (pspec);</literal> in sequence on it, taking over the initial
250 * reference count (thus ending up with a @pspec that has a reference
251 * count of 1 still, but is not flagged "floating" anymore).
254 g_param_spec_sink (GParamSpec
*pspec
)
257 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
259 oldvalue
= g_atomic_pointer_and (&pspec
->qdata
, ~(gsize
)PARAM_FLOATING_FLAG
);
260 if (oldvalue
& PARAM_FLOATING_FLAG
)
261 g_param_spec_unref (pspec
);
265 * g_param_spec_ref_sink: (skip)
266 * @pspec: a valid #GParamSpec
268 * Convenience function to ref and sink a #GParamSpec.
271 * Returns: the #GParamSpec that was passed into this function
274 g_param_spec_ref_sink (GParamSpec
*pspec
)
277 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
279 oldvalue
= g_atomic_pointer_and (&pspec
->qdata
, ~(gsize
)PARAM_FLOATING_FLAG
);
280 if (!(oldvalue
& PARAM_FLOATING_FLAG
))
281 g_param_spec_ref (pspec
);
287 * g_param_spec_get_name:
288 * @pspec: a valid #GParamSpec
290 * Get the name of a #GParamSpec.
292 * The name is always an "interned" string (as per g_intern_string()).
293 * This allows for pointer-value comparisons.
295 * Returns: the name of @pspec.
298 g_param_spec_get_name (GParamSpec
*pspec
)
300 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
306 * g_param_spec_get_nick:
307 * @pspec: a valid #GParamSpec
309 * Get the nickname of a #GParamSpec.
311 * Returns: the nickname of @pspec.
314 g_param_spec_get_nick (GParamSpec
*pspec
)
316 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
322 GParamSpec
*redirect_target
;
324 redirect_target
= g_param_spec_get_redirect_target (pspec
);
325 if (redirect_target
&& redirect_target
->_nick
)
326 return redirect_target
->_nick
;
333 * g_param_spec_get_blurb:
334 * @pspec: a valid #GParamSpec
336 * Get the short description of a #GParamSpec.
338 * Returns: the short description of @pspec.
341 g_param_spec_get_blurb (GParamSpec
*pspec
)
343 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
346 return pspec
->_blurb
;
349 GParamSpec
*redirect_target
;
351 redirect_target
= g_param_spec_get_redirect_target (pspec
);
352 if (redirect_target
&& redirect_target
->_blurb
)
353 return redirect_target
->_blurb
;
360 canonicalize_key (gchar
*key
)
364 for (p
= key
; *p
!= 0; p
++)
369 (c
< '0' || c
> '9') &&
370 (c
< 'A' || c
> 'Z') &&
371 (c
< 'a' || c
> 'z'))
377 is_canonical (const gchar
*key
)
381 for (p
= key
; *p
!= 0; p
++)
386 (c
< '0' || c
> '9') &&
387 (c
< 'A' || c
> 'Z') &&
388 (c
< 'a' || c
> 'z'))
396 * g_param_spec_internal: (skip)
397 * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
398 * @name: the canonical name of the property
399 * @nick: the nickname of the property
400 * @blurb: a short description of the property
401 * @flags: a combination of #GParamFlags
403 * Creates a new #GParamSpec instance.
405 * A property name consists of segments consisting of ASCII letters and
406 * digits, separated by either the '-' or '_' character. The first
407 * character of a property name must be a letter. Names which violate these
408 * rules lead to undefined behaviour.
410 * When creating and looking up a #GParamSpec, either separator can be
411 * used, but they cannot be mixed. Using '-' is considerably more
412 * efficient and in fact required when using property names as detail
413 * strings for signals.
415 * Beyond the name, #GParamSpec<!-- -->s have two more descriptive
416 * strings associated with them, the @nick, which should be suitable
417 * for use as a label for the property in a property editor, and the
418 * @blurb, which should be a somewhat longer description, suitable for
419 * e.g. a tooltip. The @nick and @blurb should ideally be localized.
421 * Returns: a newly allocated #GParamSpec instance
424 g_param_spec_internal (GType param_type
,
432 g_return_val_if_fail (G_TYPE_IS_PARAM (param_type
) && param_type
!= G_TYPE_PARAM
, NULL
);
433 g_return_val_if_fail (name
!= NULL
, NULL
);
434 g_return_val_if_fail ((name
[0] >= 'A' && name
[0] <= 'Z') || (name
[0] >= 'a' && name
[0] <= 'z'), NULL
);
435 g_return_val_if_fail (!(flags
& G_PARAM_STATIC_NAME
) || is_canonical (name
), NULL
);
437 pspec
= (gpointer
) g_type_create_instance (param_type
);
439 if (flags
& G_PARAM_STATIC_NAME
)
441 /* pspec->name is not freed if (flags & G_PARAM_STATIC_NAME) */
442 pspec
->name
= (gchar
*) g_intern_static_string (name
);
443 if (!is_canonical (pspec
->name
))
444 g_warning ("G_PARAM_STATIC_NAME used with non-canonical pspec name: %s", pspec
->name
);
448 if (is_canonical (name
))
449 pspec
->name
= (gchar
*) g_intern_string (name
);
452 gchar
*tmp
= g_strdup (name
);
453 canonicalize_key (tmp
);
454 pspec
->name
= (gchar
*) g_intern_string (tmp
);
459 if (flags
& G_PARAM_STATIC_NICK
)
460 pspec
->_nick
= (gchar
*) nick
;
462 pspec
->_nick
= g_strdup (nick
);
464 if (flags
& G_PARAM_STATIC_BLURB
)
465 pspec
->_blurb
= (gchar
*) blurb
;
467 pspec
->_blurb
= g_strdup (blurb
);
469 pspec
->flags
= (flags
& G_PARAM_USER_MASK
) | (flags
& G_PARAM_MASK
);
475 * g_param_spec_get_qdata:
476 * @pspec: a valid #GParamSpec
477 * @quark: a #GQuark, naming the user data pointer
479 * Gets back user data pointers stored via g_param_spec_set_qdata().
481 * Returns: (transfer none): the user data pointer set, or %NULL
484 g_param_spec_get_qdata (GParamSpec
*pspec
,
487 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
489 return quark
? g_datalist_id_get_data (&pspec
->qdata
, quark
) : NULL
;
493 * g_param_spec_set_qdata:
494 * @pspec: the #GParamSpec to set store a user data pointer
495 * @quark: a #GQuark, naming the user data pointer
496 * @data: an opaque user data pointer
498 * Sets an opaque, named pointer on a #GParamSpec. The name is
499 * specified through a #GQuark (retrieved e.g. via
500 * g_quark_from_static_string()), and the pointer can be gotten back
501 * from the @pspec with g_param_spec_get_qdata(). Setting a
502 * previously set user data pointer, overrides (frees) the old pointer
503 * set, using %NULL as pointer essentially removes the data stored.
506 g_param_spec_set_qdata (GParamSpec
*pspec
,
510 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
511 g_return_if_fail (quark
> 0);
513 g_datalist_id_set_data (&pspec
->qdata
, quark
, data
);
517 * g_param_spec_set_qdata_full: (skip)
518 * @pspec: the #GParamSpec to set store a user data pointer
519 * @quark: a #GQuark, naming the user data pointer
520 * @data: an opaque user data pointer
521 * @destroy: function to invoke with @data as argument, when @data needs to
524 * This function works like g_param_spec_set_qdata(), but in addition,
525 * a <literal>void (*destroy) (gpointer)</literal> function may be
526 * specified which is called with @data as argument when the @pspec is
527 * finalized, or the data is being overwritten by a call to
528 * g_param_spec_set_qdata() with the same @quark.
531 g_param_spec_set_qdata_full (GParamSpec
*pspec
,
534 GDestroyNotify destroy
)
536 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
537 g_return_if_fail (quark
> 0);
539 g_datalist_id_set_data_full (&pspec
->qdata
, quark
, data
, data
? destroy
: (GDestroyNotify
) NULL
);
543 * g_param_spec_steal_qdata:
544 * @pspec: the #GParamSpec to get a stored user data pointer from
545 * @quark: a #GQuark, naming the user data pointer
547 * Gets back user data pointers stored via g_param_spec_set_qdata()
548 * and removes the @data from @pspec without invoking its destroy()
549 * function (if any was set). Usually, calling this function is only
550 * required to update user data pointers with a destroy notifier.
552 * Returns: (transfer none): the user data pointer set, or %NULL
555 g_param_spec_steal_qdata (GParamSpec
*pspec
,
558 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
559 g_return_val_if_fail (quark
> 0, NULL
);
561 return g_datalist_id_remove_no_notify (&pspec
->qdata
, quark
);
565 * g_param_spec_get_redirect_target:
566 * @pspec: a #GParamSpec
568 * If the paramspec redirects operations to another paramspec,
569 * returns that paramspec. Redirect is used typically for
570 * providing a new implementation of a property in a derived
571 * type while preserving all the properties from the parent
572 * type. Redirection is established by creating a property
573 * of type #GParamSpecOverride. See g_object_class_override_property()
574 * for an example of the use of this capability.
578 * Returns: (transfer none): paramspec to which requests on this
579 * paramspec should be redirected, or %NULL if none.
582 g_param_spec_get_redirect_target (GParamSpec
*pspec
)
584 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
586 if (G_IS_PARAM_SPEC_OVERRIDE (pspec
))
588 GParamSpecOverride
*ospec
= G_PARAM_SPEC_OVERRIDE (pspec
);
590 return ospec
->overridden
;
597 * g_param_value_set_default:
598 * @pspec: a valid #GParamSpec
599 * @value: a #GValue of correct type for @pspec
601 * Sets @value to its default value as specified in @pspec.
604 g_param_value_set_default (GParamSpec
*pspec
,
607 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
608 g_return_if_fail (G_IS_VALUE (value
));
609 g_return_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
));
611 g_value_reset (value
);
612 G_PARAM_SPEC_GET_CLASS (pspec
)->value_set_default (pspec
, value
);
616 * g_param_value_defaults:
617 * @pspec: a valid #GParamSpec
618 * @value: a #GValue of correct type for @pspec
620 * Checks whether @value contains the default value as specified in @pspec.
622 * Returns: whether @value contains the canonical default for this @pspec
625 g_param_value_defaults (GParamSpec
*pspec
,
628 GValue dflt_value
= G_VALUE_INIT
;
631 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
632 g_return_val_if_fail (G_IS_VALUE (value
), FALSE
);
633 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
), FALSE
);
635 g_value_init (&dflt_value
, G_PARAM_SPEC_VALUE_TYPE (pspec
));
636 G_PARAM_SPEC_GET_CLASS (pspec
)->value_set_default (pspec
, &dflt_value
);
637 defaults
= G_PARAM_SPEC_GET_CLASS (pspec
)->values_cmp (pspec
, value
, &dflt_value
) == 0;
638 g_value_unset (&dflt_value
);
644 * g_param_value_validate:
645 * @pspec: a valid #GParamSpec
646 * @value: a #GValue of correct type for @pspec
648 * Ensures that the contents of @value comply with the specifications
649 * set out by @pspec. For example, a #GParamSpecInt might require
650 * that integers stored in @value may not be smaller than -42 and not be
651 * greater than +42. If @value contains an integer outside of this range,
652 * it is modified accordingly, so the resulting value will fit into the
655 * Returns: whether modifying @value was necessary to ensure validity
658 g_param_value_validate (GParamSpec
*pspec
,
661 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
662 g_return_val_if_fail (G_IS_VALUE (value
), FALSE
);
663 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
), FALSE
);
665 if (G_PARAM_SPEC_GET_CLASS (pspec
)->value_validate
)
667 GValue oval
= *value
;
669 if (G_PARAM_SPEC_GET_CLASS (pspec
)->value_validate (pspec
, value
) ||
670 memcmp (&oval
.data
, &value
->data
, sizeof (oval
.data
)))
678 * g_param_value_convert:
679 * @pspec: a valid #GParamSpec
680 * @src_value: souce #GValue
681 * @dest_value: destination #GValue of correct type for @pspec
682 * @strict_validation: %TRUE requires @dest_value to conform to @pspec
683 * without modifications
685 * Transforms @src_value into @dest_value if possible, and then
686 * validates @dest_value, in order for it to conform to @pspec. If
687 * @strict_validation is %TRUE this function will only succeed if the
688 * transformed @dest_value complied to @pspec without modifications.
690 * See also g_value_type_transformable(), g_value_transform() and
691 * g_param_value_validate().
693 * Returns: %TRUE if transformation and validation were successful,
694 * %FALSE otherwise and @dest_value is left untouched.
697 g_param_value_convert (GParamSpec
*pspec
,
698 const GValue
*src_value
,
700 gboolean strict_validation
)
702 GValue tmp_value
= G_VALUE_INIT
;
704 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
705 g_return_val_if_fail (G_IS_VALUE (src_value
), FALSE
);
706 g_return_val_if_fail (G_IS_VALUE (dest_value
), FALSE
);
707 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, dest_value
), FALSE
);
709 /* better leave dest_value untouched when returning FALSE */
711 g_value_init (&tmp_value
, G_VALUE_TYPE (dest_value
));
712 if (g_value_transform (src_value
, &tmp_value
) &&
713 (!g_param_value_validate (pspec
, &tmp_value
) || !strict_validation
))
715 g_value_unset (dest_value
);
717 /* values are relocatable */
718 memcpy (dest_value
, &tmp_value
, sizeof (tmp_value
));
724 g_value_unset (&tmp_value
);
731 * g_param_values_cmp:
732 * @pspec: a valid #GParamSpec
733 * @value1: a #GValue of correct type for @pspec
734 * @value2: a #GValue of correct type for @pspec
736 * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1,
737 * if @value1 is found to be less than, equal to or greater than @value2,
740 * Returns: -1, 0 or +1, for a less than, equal to or greater than result
743 g_param_values_cmp (GParamSpec
*pspec
,
744 const GValue
*value1
,
745 const GValue
*value2
)
749 /* param_values_cmp() effectively does: value1 - value2
750 * so the return values are:
751 * -1) value1 < value2
752 * 0) value1 == value2
755 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), 0);
756 g_return_val_if_fail (G_IS_VALUE (value1
), 0);
757 g_return_val_if_fail (G_IS_VALUE (value2
), 0);
758 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value1
), 0);
759 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value2
), 0);
761 cmp
= G_PARAM_SPEC_GET_CLASS (pspec
)->values_cmp (pspec
, value1
, value2
);
763 return CLAMP (cmp
, -1, 1);
767 value_param_init (GValue
*value
)
769 value
->data
[0].v_pointer
= NULL
;
773 value_param_free_value (GValue
*value
)
775 if (value
->data
[0].v_pointer
)
776 g_param_spec_unref (value
->data
[0].v_pointer
);
780 value_param_copy_value (const GValue
*src_value
,
783 if (src_value
->data
[0].v_pointer
)
784 dest_value
->data
[0].v_pointer
= g_param_spec_ref (src_value
->data
[0].v_pointer
);
786 dest_value
->data
[0].v_pointer
= NULL
;
790 value_param_transform_value (const GValue
*src_value
,
793 if (src_value
->data
[0].v_pointer
&&
794 g_type_is_a (G_PARAM_SPEC_TYPE (dest_value
->data
[0].v_pointer
), G_VALUE_TYPE (dest_value
)))
795 dest_value
->data
[0].v_pointer
= g_param_spec_ref (src_value
->data
[0].v_pointer
);
797 dest_value
->data
[0].v_pointer
= NULL
;
801 value_param_peek_pointer (const GValue
*value
)
803 return value
->data
[0].v_pointer
;
807 value_param_collect_value (GValue
*value
,
808 guint n_collect_values
,
809 GTypeCValue
*collect_values
,
812 if (collect_values
[0].v_pointer
)
814 GParamSpec
*param
= collect_values
[0].v_pointer
;
816 if (param
->g_type_instance
.g_class
== NULL
)
817 return g_strconcat ("invalid unclassed param spec pointer for value type '",
818 G_VALUE_TYPE_NAME (value
),
821 else if (!g_value_type_compatible (G_PARAM_SPEC_TYPE (param
), G_VALUE_TYPE (value
)))
822 return g_strconcat ("invalid param spec type '",
823 G_PARAM_SPEC_TYPE_NAME (param
),
824 "' for value type '",
825 G_VALUE_TYPE_NAME (value
),
828 value
->data
[0].v_pointer
= g_param_spec_ref (param
);
831 value
->data
[0].v_pointer
= NULL
;
837 value_param_lcopy_value (const GValue
*value
,
838 guint n_collect_values
,
839 GTypeCValue
*collect_values
,
842 GParamSpec
**param_p
= collect_values
[0].v_pointer
;
845 return g_strdup_printf ("value location for '%s' passed as NULL", G_VALUE_TYPE_NAME (value
));
847 if (!value
->data
[0].v_pointer
)
849 else if (collect_flags
& G_VALUE_NOCOPY_CONTENTS
)
850 *param_p
= value
->data
[0].v_pointer
;
852 *param_p
= g_param_spec_ref (value
->data
[0].v_pointer
);
858 /* --- param spec pool --- */
862 * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be
863 * quickly accessed by owner and name. The implementation of the #GObject property
864 * system uses such a pool to store the #GParamSpecs of the properties all object
867 struct _GParamSpecPool
870 gboolean type_prefixing
;
871 GHashTable
*hash_table
;
875 param_spec_pool_hash (gconstpointer key_spec
)
877 const GParamSpec
*key
= key_spec
;
879 guint h
= key
->owner_type
;
881 for (p
= key
->name
; *p
; p
++)
882 h
= (h
<< 5) - h
+ *p
;
888 param_spec_pool_equals (gconstpointer key_spec_1
,
889 gconstpointer key_spec_2
)
891 const GParamSpec
*key1
= key_spec_1
;
892 const GParamSpec
*key2
= key_spec_2
;
894 return (key1
->owner_type
== key2
->owner_type
&&
895 strcmp (key1
->name
, key2
->name
) == 0);
899 * g_param_spec_pool_new:
900 * @type_prefixing: Whether the pool will support type-prefixed property names.
902 * Creates a new #GParamSpecPool.
904 * If @type_prefixing is %TRUE, lookups in the newly created pool will
905 * allow to specify the owner as a colon-separated prefix of the
906 * property name, like "GtkContainer:border-width". This feature is
907 * deprecated, so you should always set @type_prefixing to %FALSE.
909 * Returns: (transfer none): a newly allocated #GParamSpecPool.
912 g_param_spec_pool_new (gboolean type_prefixing
)
914 static GMutex init_mutex
;
915 GParamSpecPool
*pool
= g_new (GParamSpecPool
, 1);
917 memcpy (&pool
->mutex
, &init_mutex
, sizeof (init_mutex
));
918 pool
->type_prefixing
= type_prefixing
!= FALSE
;
919 pool
->hash_table
= g_hash_table_new (param_spec_pool_hash
, param_spec_pool_equals
);
925 * g_param_spec_pool_insert:
926 * @pool: a #GParamSpecPool.
927 * @pspec: the #GParamSpec to insert
928 * @owner_type: a #GType identifying the owner of @pspec
930 * Inserts a #GParamSpec in the pool.
933 g_param_spec_pool_insert (GParamSpecPool
*pool
,
939 if (pool
&& pspec
&& owner_type
> 0 && pspec
->owner_type
== 0)
941 for (p
= pspec
->name
; *p
; p
++)
943 if (!strchr (G_CSET_A_2_Z G_CSET_a_2_z G_CSET_DIGITS
"-_", *p
))
945 g_warning (G_STRLOC
": pspec name \"%s\" contains invalid characters", pspec
->name
);
949 g_mutex_lock (&pool
->mutex
);
950 pspec
->owner_type
= owner_type
;
951 g_param_spec_ref (pspec
);
952 g_hash_table_insert (pool
->hash_table
, pspec
, pspec
);
953 g_mutex_unlock (&pool
->mutex
);
957 g_return_if_fail (pool
!= NULL
);
958 g_return_if_fail (pspec
);
959 g_return_if_fail (owner_type
> 0);
960 g_return_if_fail (pspec
->owner_type
== 0);
965 * g_param_spec_pool_remove:
966 * @pool: a #GParamSpecPool
967 * @pspec: the #GParamSpec to remove
969 * Removes a #GParamSpec from the pool.
972 g_param_spec_pool_remove (GParamSpecPool
*pool
,
977 g_mutex_lock (&pool
->mutex
);
978 if (g_hash_table_remove (pool
->hash_table
, pspec
))
979 g_param_spec_unref (pspec
);
981 g_warning (G_STRLOC
": attempt to remove unknown pspec '%s' from pool", pspec
->name
);
982 g_mutex_unlock (&pool
->mutex
);
986 g_return_if_fail (pool
!= NULL
);
987 g_return_if_fail (pspec
);
991 static inline GParamSpec
*
992 param_spec_ht_lookup (GHashTable
*hash_table
,
993 const gchar
*param_name
,
995 gboolean walk_ancestors
)
997 GParamSpec key
, *pspec
;
999 key
.owner_type
= owner_type
;
1000 key
.name
= (gchar
*) param_name
;
1004 pspec
= g_hash_table_lookup (hash_table
, &key
);
1007 key
.owner_type
= g_type_parent (key
.owner_type
);
1009 while (key
.owner_type
);
1011 pspec
= g_hash_table_lookup (hash_table
, &key
);
1013 if (!pspec
&& !is_canonical (param_name
))
1017 canonical
= g_strdup (key
.name
);
1018 canonicalize_key (canonical
);
1020 /* try canonicalized form */
1021 key
.name
= canonical
;
1022 key
.owner_type
= owner_type
;
1027 pspec
= g_hash_table_lookup (hash_table
, &key
);
1033 key
.owner_type
= g_type_parent (key
.owner_type
);
1035 while (key
.owner_type
);
1037 pspec
= g_hash_table_lookup (hash_table
, &key
);
1046 * g_param_spec_pool_lookup:
1047 * @pool: a #GParamSpecPool
1048 * @param_name: the name to look for
1049 * @owner_type: the owner to look for
1050 * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name
1051 * owned by an ancestor of @owner_type.
1053 * Looks up a #GParamSpec in the pool.
1055 * Returns: (transfer none): The found #GParamSpec, or %NULL if no
1056 * matching #GParamSpec was found.
1059 g_param_spec_pool_lookup (GParamSpecPool
*pool
,
1060 const gchar
*param_name
,
1062 gboolean walk_ancestors
)
1067 if (!pool
|| !param_name
)
1069 g_return_val_if_fail (pool
!= NULL
, NULL
);
1070 g_return_val_if_fail (param_name
!= NULL
, NULL
);
1073 g_mutex_lock (&pool
->mutex
);
1075 delim
= pool
->type_prefixing
? strchr (param_name
, ':') : NULL
;
1077 /* try quick and away, i.e. without prefix */
1080 pspec
= param_spec_ht_lookup (pool
->hash_table
, param_name
, owner_type
, walk_ancestors
);
1081 g_mutex_unlock (&pool
->mutex
);
1086 /* strip type prefix */
1087 if (pool
->type_prefixing
&& delim
[1] == ':')
1089 guint l
= delim
- param_name
;
1090 gchar stack_buffer
[32], *buffer
= l
< 32 ? stack_buffer
: g_new (gchar
, l
+ 1);
1093 strncpy (buffer
, param_name
, delim
- param_name
);
1095 type
= g_type_from_name (buffer
);
1098 if (type
) /* type==0 isn't a valid type pefix */
1100 /* sanity check, these cases don't make a whole lot of sense */
1101 if ((!walk_ancestors
&& type
!= owner_type
) || !g_type_is_a (owner_type
, type
))
1103 g_mutex_unlock (&pool
->mutex
);
1108 param_name
+= l
+ 2;
1109 pspec
= param_spec_ht_lookup (pool
->hash_table
, param_name
, owner_type
, walk_ancestors
);
1110 g_mutex_unlock (&pool
->mutex
);
1115 /* malformed param_name */
1117 g_mutex_unlock (&pool
->mutex
);
1123 pool_list (gpointer key
,
1127 GParamSpec
*pspec
= value
;
1128 gpointer
*data
= user_data
;
1129 GType owner_type
= (GType
) data
[1];
1131 if (owner_type
== pspec
->owner_type
)
1132 data
[0] = g_list_prepend (data
[0], pspec
);
1136 * g_param_spec_pool_list_owned:
1137 * @pool: a #GParamSpecPool
1138 * @owner_type: the owner to look for
1140 * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
1143 * Returns: (transfer container) (element-type GObject.ParamSpec): a
1144 * #GList of all #GParamSpec<!-- -->s owned by @owner_type in
1145 * the pool#GParamSpec<!-- -->s.
1148 g_param_spec_pool_list_owned (GParamSpecPool
*pool
,
1153 g_return_val_if_fail (pool
!= NULL
, NULL
);
1154 g_return_val_if_fail (owner_type
> 0, NULL
);
1156 g_mutex_lock (&pool
->mutex
);
1158 data
[1] = (gpointer
) owner_type
;
1159 g_hash_table_foreach (pool
->hash_table
, pool_list
, &data
);
1160 g_mutex_unlock (&pool
->mutex
);
1166 pspec_compare_id (gconstpointer a
,
1169 const GParamSpec
*pspec1
= a
, *pspec2
= b
;
1171 if (pspec1
->param_id
< pspec2
->param_id
)
1174 if (pspec1
->param_id
> pspec2
->param_id
)
1177 return strcmp (pspec1
->name
, pspec2
->name
);
1180 static inline GSList
*
1181 pspec_list_remove_overridden_and_redirected (GSList
*plist
,
1186 GSList
*rlist
= NULL
;
1190 GSList
*tmp
= plist
->next
;
1191 GParamSpec
*pspec
= plist
->data
;
1193 gboolean remove
= FALSE
;
1195 /* Remove paramspecs that are redirected, and also paramspecs
1196 * that have are overridden by non-redirected properties.
1197 * The idea is to get the single paramspec for each name that
1198 * best corresponds to what the application sees.
1200 if (g_param_spec_get_redirect_target (pspec
))
1204 found
= param_spec_ht_lookup (ht
, pspec
->name
, owner_type
, TRUE
);
1207 GParamSpec
*redirect
= g_param_spec_get_redirect_target (found
);
1208 if (redirect
!= pspec
)
1215 g_slist_free_1 (plist
);
1219 plist
->next
= rlist
;
1229 pool_depth_list (gpointer key
,
1233 GParamSpec
*pspec
= value
;
1234 gpointer
*data
= user_data
;
1235 GSList
**slists
= data
[0];
1236 GType owner_type
= (GType
) data
[1];
1238 if (g_type_is_a (owner_type
, pspec
->owner_type
))
1240 if (G_TYPE_IS_INTERFACE (pspec
->owner_type
))
1242 slists
[0] = g_slist_prepend (slists
[0], pspec
);
1246 guint d
= g_type_depth (pspec
->owner_type
);
1248 slists
[d
- 1] = g_slist_prepend (slists
[d
- 1], pspec
);
1253 /* We handle interfaces specially since we don't want to
1254 * count interface prerequisites like normal inheritance;
1255 * the property comes from the direct inheritance from
1256 * the prerequisite class, not from the interface that
1259 * also 'depth' isn't a meaningful concept for interface
1263 pool_depth_list_for_interface (gpointer key
,
1267 GParamSpec
*pspec
= value
;
1268 gpointer
*data
= user_data
;
1269 GSList
**slists
= data
[0];
1270 GType owner_type
= (GType
) data
[1];
1272 if (pspec
->owner_type
== owner_type
)
1273 slists
[0] = g_slist_prepend (slists
[0], pspec
);
1277 * g_param_spec_pool_list:
1278 * @pool: a #GParamSpecPool
1279 * @owner_type: the owner to look for
1280 * @n_pspecs_p: (out): return location for the length of the returned array
1282 * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
1285 * Returns: (array length=n_pspecs_p) (transfer container): a newly
1286 * allocated array containing pointers to all #GParamSpecs
1287 * owned by @owner_type in the pool
1290 g_param_spec_pool_list (GParamSpecPool
*pool
,
1294 GParamSpec
**pspecs
, **p
;
1295 GSList
**slists
, *node
;
1299 g_return_val_if_fail (pool
!= NULL
, NULL
);
1300 g_return_val_if_fail (owner_type
> 0, NULL
);
1301 g_return_val_if_fail (n_pspecs_p
!= NULL
, NULL
);
1303 g_mutex_lock (&pool
->mutex
);
1305 d
= g_type_depth (owner_type
);
1306 slists
= g_new0 (GSList
*, d
);
1308 data
[1] = (gpointer
) owner_type
;
1310 g_hash_table_foreach (pool
->hash_table
,
1311 G_TYPE_IS_INTERFACE (owner_type
) ?
1312 pool_depth_list_for_interface
:
1316 for (i
= 0; i
< d
; i
++)
1317 slists
[i
] = pspec_list_remove_overridden_and_redirected (slists
[i
], pool
->hash_table
, owner_type
, n_pspecs_p
);
1318 pspecs
= g_new (GParamSpec
*, *n_pspecs_p
+ 1);
1320 for (i
= 0; i
< d
; i
++)
1322 slists
[i
] = g_slist_sort (slists
[i
], pspec_compare_id
);
1323 for (node
= slists
[i
]; node
; node
= node
->next
)
1325 g_slist_free (slists
[i
]);
1329 g_mutex_unlock (&pool
->mutex
);
1335 /* --- auxiliary functions --- */
1340 void (*finalize
) (GParamSpec
*pspec
);
1341 void (*value_set_default
) (GParamSpec
*pspec
,
1343 gboolean (*value_validate
) (GParamSpec
*pspec
,
1345 gint (*values_cmp
) (GParamSpec
*pspec
,
1346 const GValue
*value1
,
1347 const GValue
*value2
);
1348 } ParamSpecClassInfo
;
1351 param_spec_generic_class_init (gpointer g_class
,
1352 gpointer class_data
)
1354 GParamSpecClass
*class = g_class
;
1355 ParamSpecClassInfo
*info
= class_data
;
1357 class->value_type
= info
->value_type
;
1359 class->finalize
= info
->finalize
; /* optional */
1360 class->value_set_default
= info
->value_set_default
;
1361 if (info
->value_validate
)
1362 class->value_validate
= info
->value_validate
; /* optional */
1363 class->values_cmp
= info
->values_cmp
;
1364 g_free (class_data
);
1368 default_value_set_default (GParamSpec
*pspec
,
1371 /* value is already zero initialized */
1375 default_values_cmp (GParamSpec
*pspec
,
1376 const GValue
*value1
,
1377 const GValue
*value2
)
1379 return memcmp (&value1
->data
, &value2
->data
, sizeof (value1
->data
));
1383 * g_param_type_register_static:
1384 * @name: 0-terminated string used as the name of the new #GParamSpec type.
1385 * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
1387 * Registers @name as the name of a new static type derived from
1388 * #G_TYPE_PARAM. The type system uses the information contained in
1389 * the #GParamSpecTypeInfo structure pointed to by @info to manage the
1390 * #GParamSpec type and its instances.
1392 * Returns: The new type identifier.
1395 g_param_type_register_static (const gchar
*name
,
1396 const GParamSpecTypeInfo
*pspec_info
)
1399 sizeof (GParamSpecClass
), /* class_size */
1400 NULL
, /* base_init */
1401 NULL
, /* base_destroy */
1402 param_spec_generic_class_init
, /* class_init */
1403 NULL
, /* class_destroy */
1404 NULL
, /* class_data */
1405 0, /* instance_size */
1406 16, /* n_preallocs */
1407 NULL
, /* instance_init */
1409 ParamSpecClassInfo
*cinfo
;
1411 g_return_val_if_fail (name
!= NULL
, 0);
1412 g_return_val_if_fail (pspec_info
!= NULL
, 0);
1413 g_return_val_if_fail (g_type_from_name (name
) == 0, 0);
1414 g_return_val_if_fail (pspec_info
->instance_size
>= sizeof (GParamSpec
), 0);
1415 g_return_val_if_fail (g_type_name (pspec_info
->value_type
) != NULL
, 0);
1416 /* default: g_return_val_if_fail (pspec_info->value_set_default != NULL, 0); */
1417 /* optional: g_return_val_if_fail (pspec_info->value_validate != NULL, 0); */
1418 /* default: g_return_val_if_fail (pspec_info->values_cmp != NULL, 0); */
1420 info
.instance_size
= pspec_info
->instance_size
;
1421 info
.n_preallocs
= pspec_info
->n_preallocs
;
1422 info
.instance_init
= (GInstanceInitFunc
) pspec_info
->instance_init
;
1423 cinfo
= g_new (ParamSpecClassInfo
, 1);
1424 cinfo
->value_type
= pspec_info
->value_type
;
1425 cinfo
->finalize
= pspec_info
->finalize
;
1426 cinfo
->value_set_default
= pspec_info
->value_set_default
? pspec_info
->value_set_default
: default_value_set_default
;
1427 cinfo
->value_validate
= pspec_info
->value_validate
;
1428 cinfo
->values_cmp
= pspec_info
->values_cmp
? pspec_info
->values_cmp
: default_values_cmp
;
1429 info
.class_data
= cinfo
;
1431 return g_type_register_static (G_TYPE_PARAM
, name
, &info
, 0);
1435 * g_value_set_param:
1436 * @value: a valid #GValue of type %G_TYPE_PARAM
1437 * @param: (allow-none): the #GParamSpec to be set
1439 * Set the contents of a %G_TYPE_PARAM #GValue to @param.
1442 g_value_set_param (GValue
*value
,
1445 g_return_if_fail (G_VALUE_HOLDS_PARAM (value
));
1447 g_return_if_fail (G_IS_PARAM_SPEC (param
));
1449 if (value
->data
[0].v_pointer
)
1450 g_param_spec_unref (value
->data
[0].v_pointer
);
1451 value
->data
[0].v_pointer
= param
;
1452 if (value
->data
[0].v_pointer
)
1453 g_param_spec_ref (value
->data
[0].v_pointer
);
1457 * g_value_set_param_take_ownership: (skip)
1458 * @value: a valid #GValue of type %G_TYPE_PARAM
1459 * @param: (allow-none): the #GParamSpec to be set
1461 * This is an internal function introduced mainly for C marshallers.
1463 * Deprecated: 2.4: Use g_value_take_param() instead.
1466 g_value_set_param_take_ownership (GValue
*value
,
1469 g_value_take_param (value
, param
);
1473 * g_value_take_param: (skip)
1474 * @value: a valid #GValue of type %G_TYPE_PARAM
1475 * @param: (allow-none): the #GParamSpec to be set
1477 * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
1478 * over the ownership of the callers reference to @param; the caller
1479 * doesn't have to unref it any more.
1484 g_value_take_param (GValue
*value
,
1487 g_return_if_fail (G_VALUE_HOLDS_PARAM (value
));
1489 g_return_if_fail (G_IS_PARAM_SPEC (param
));
1491 if (value
->data
[0].v_pointer
)
1492 g_param_spec_unref (value
->data
[0].v_pointer
);
1493 value
->data
[0].v_pointer
= param
; /* we take over the reference count */
1497 * g_value_get_param:
1498 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1500 * Get the contents of a %G_TYPE_PARAM #GValue.
1502 * Returns: (transfer none): #GParamSpec content of @value
1505 g_value_get_param (const GValue
*value
)
1507 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value
), NULL
);
1509 return value
->data
[0].v_pointer
;
1513 * g_value_dup_param: (skip)
1514 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1516 * Get the contents of a %G_TYPE_PARAM #GValue, increasing its
1519 * Returns: #GParamSpec content of @value, should be unreferenced when
1523 g_value_dup_param (const GValue
*value
)
1525 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value
), NULL
);
1527 return value
->data
[0].v_pointer
? g_param_spec_ref (value
->data
[0].v_pointer
) : NULL
;
1531 * g_param_get_default_value:
1532 * @param: a #GParamSpec
1534 * Gets the default value of @param as a pointer to a #GValue.
1536 * The #GValue will remain value for the life of @param.
1538 * Returns: a pointer to a #GValue which must not be modified
1543 g_param_spec_get_default_value (GParamSpec
*pspec
)
1545 GParamSpecPrivate
*priv
= g_param_spec_get_private (pspec
);
1547 /* We use the type field of the GValue as the key for the once because
1548 * it will be zero before it is initialised and non-zero after. We
1549 * have to take care that we don't write a non-zero value to the type
1550 * field before we are completely done, however, because then another
1551 * thread could come along and find the value partially-initialised.
1553 * In order to accomplish this we store the default value in a
1554 * stack-allocated GValue. We then set the type field in that value
1555 * to zero and copy the contents into place. We then end by storing
1556 * the type as the last step in order to ensure that we're completely
1557 * done before a g_once_init_enter() could take the fast path in
1560 if (g_once_init_enter (&priv
->default_value
.g_type
))
1562 GValue default_value
= G_VALUE_INIT
;
1564 g_value_init (&default_value
, pspec
->value_type
);
1565 g_param_value_set_default (pspec
, &default_value
);
1567 /* store all but the type */
1568 default_value
.g_type
= 0;
1569 priv
->default_value
= default_value
;
1571 g_once_init_leave (&priv
->default_value
.g_type
, pspec
->value_type
);
1574 return &priv
->default_value
;