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 "gobjectalias.h"
36 * @short_description: Metadata for parameter specifications
37 * @see_also: g_object_class_install_property(), g_object_set(),
38 * g_object_get(), g_object_set_property(), g_object_get_property(),
39 * g_value_register_transform_func()
42 * #GParamSpec is an object structure that encapsulates the metadata
43 * required to specify parameters, such as e.g. #GObject properties.
45 * <para id="canonical-parameter-name">
46 * Parameter names need to start with a letter (a-z or A-Z). Subsequent
47 * characters can be letters, numbers or a '-'.
48 * All other characters are replaced by a '-' during construction.
49 * The result of this replacement is called the canonical name of the
56 #define PARAM_FLOATING_FLAG 0x2
57 #define G_PARAM_USER_MASK (~0 << G_PARAM_USER_SHIFT)
58 #define PSPEC_APPLIES_TO_VALUE(pspec, value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_PARAM_SPEC_VALUE_TYPE (pspec)))
59 #define G_SLOCK(mutex) g_static_mutex_lock (mutex)
60 #define G_SUNLOCK(mutex) g_static_mutex_unlock (mutex)
63 /* --- prototypes --- */
64 static void g_param_spec_class_base_init (GParamSpecClass
*class);
65 static void g_param_spec_class_base_finalize (GParamSpecClass
*class);
66 static void g_param_spec_class_init (GParamSpecClass
*class,
68 static void g_param_spec_init (GParamSpec
*pspec
,
69 GParamSpecClass
*class);
70 static void g_param_spec_finalize (GParamSpec
*pspec
);
71 static void value_param_init (GValue
*value
);
72 static void value_param_free_value (GValue
*value
);
73 static void value_param_copy_value (const GValue
*src_value
,
75 static void value_param_transform_value (const GValue
*src_value
,
77 static gpointer
value_param_peek_pointer (const GValue
*value
);
78 static gchar
* value_param_collect_value (GValue
*value
,
79 guint n_collect_values
,
80 GTypeCValue
*collect_values
,
82 static gchar
* value_param_lcopy_value (const GValue
*value
,
83 guint n_collect_values
,
84 GTypeCValue
*collect_values
,
88 /* --- functions --- */
90 g_param_type_init (void)
92 static const GTypeFundamentalInfo finfo
= {
93 (G_TYPE_FLAG_CLASSED
|
94 G_TYPE_FLAG_INSTANTIATABLE
|
95 G_TYPE_FLAG_DERIVABLE
|
96 G_TYPE_FLAG_DEEP_DERIVABLE
),
98 static const GTypeValueTable param_value_table
= {
99 value_param_init
, /* value_init */
100 value_param_free_value
, /* value_free */
101 value_param_copy_value
, /* value_copy */
102 value_param_peek_pointer
, /* value_peek_pointer */
103 "p", /* collect_format */
104 value_param_collect_value
, /* collect_value */
105 "p", /* lcopy_format */
106 value_param_lcopy_value
, /* lcopy_value */
108 static const GTypeInfo param_spec_info
= {
109 sizeof (GParamSpecClass
),
111 (GBaseInitFunc
) g_param_spec_class_base_init
,
112 (GBaseFinalizeFunc
) g_param_spec_class_base_finalize
,
113 (GClassInitFunc
) g_param_spec_class_init
,
114 (GClassFinalizeFunc
) NULL
,
115 NULL
, /* class_data */
119 (GInstanceInitFunc
) g_param_spec_init
,
125 /* This should be registred as GParamSpec instead of GParam, for
126 * consistency sake, so that type name can be mapped to struct name,
127 * However, some language bindings, most noticable the python ones
128 * depends on the "GParam" identifier, see #548689
130 type
= g_type_register_fundamental (G_TYPE_PARAM
, g_intern_static_string ("GParam"), ¶m_spec_info
, &finfo
, G_TYPE_FLAG_ABSTRACT
);
131 g_assert (type
== G_TYPE_PARAM
);
132 g_value_register_transform_func (G_TYPE_PARAM
, G_TYPE_PARAM
, value_param_transform_value
);
136 g_param_spec_class_base_init (GParamSpecClass
*class)
141 g_param_spec_class_base_finalize (GParamSpecClass
*class)
146 g_param_spec_class_init (GParamSpecClass
*class,
149 class->value_type
= G_TYPE_NONE
;
150 class->finalize
= g_param_spec_finalize
;
151 class->value_set_default
= NULL
;
152 class->value_validate
= NULL
;
153 class->values_cmp
= NULL
;
157 g_param_spec_init (GParamSpec
*pspec
,
158 GParamSpecClass
*class)
162 pspec
->_blurb
= NULL
;
164 pspec
->value_type
= class->value_type
;
165 pspec
->owner_type
= 0;
167 g_datalist_init (&pspec
->qdata
);
168 g_datalist_set_flags (&pspec
->qdata
, PARAM_FLOATING_FLAG
);
169 pspec
->ref_count
= 1;
174 g_param_spec_finalize (GParamSpec
*pspec
)
176 g_datalist_clear (&pspec
->qdata
);
178 if (!(pspec
->flags
& G_PARAM_STATIC_NAME
))
179 g_free (pspec
->name
);
181 if (!(pspec
->flags
& G_PARAM_STATIC_NICK
))
182 g_free (pspec
->_nick
);
184 if (!(pspec
->flags
& G_PARAM_STATIC_BLURB
))
185 g_free (pspec
->_blurb
);
187 g_type_free_instance ((GTypeInstance
*) pspec
);
192 * @pspec: a valid #GParamSpec
194 * Increments the reference count of @pspec.
196 * Returns: the #GParamSpec that was passed into this function
199 g_param_spec_ref (GParamSpec
*pspec
)
201 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
202 g_return_val_if_fail (pspec
->ref_count
> 0, NULL
);
204 g_atomic_int_inc ((int *)&pspec
->ref_count
);
210 * g_param_spec_unref:
211 * @pspec: a valid #GParamSpec
213 * Decrements the reference count of a @pspec.
216 g_param_spec_unref (GParamSpec
*pspec
)
220 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
221 g_return_if_fail (pspec
->ref_count
> 0);
223 is_zero
= g_atomic_int_dec_and_test ((int *)&pspec
->ref_count
);
225 if (G_UNLIKELY (is_zero
))
227 G_PARAM_SPEC_GET_CLASS (pspec
)->finalize (pspec
);
233 * @pspec: a valid #GParamSpec
235 * The initial reference count of a newly created #GParamSpec is 1,
236 * even though no one has explicitly called g_param_spec_ref() on it
237 * yet. So the initial reference count is flagged as "floating", until
238 * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink
239 * (pspec);</literal> in sequence on it, taking over the initial
240 * reference count (thus ending up with a @pspec that has a reference
241 * count of 1 still, but is not flagged "floating" anymore).
244 g_param_spec_sink (GParamSpec
*pspec
)
247 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
248 g_return_if_fail (pspec
->ref_count
> 0);
251 oldvalue
= g_atomic_pointer_get (&pspec
->qdata
);
252 while (!g_atomic_pointer_compare_and_exchange ((void**) &pspec
->qdata
, oldvalue
,
253 (gpointer
) ((gsize
) oldvalue
& ~(gsize
) PARAM_FLOATING_FLAG
)));
254 if ((gsize
) oldvalue
& PARAM_FLOATING_FLAG
)
255 g_param_spec_unref (pspec
);
259 * g_param_spec_ref_sink:
260 * @pspec: a valid #GParamSpec
262 * Convenience function to ref and sink a #GParamSpec.
265 * Returns: the #GParamSpec that was passed into this function
268 g_param_spec_ref_sink (GParamSpec
*pspec
)
270 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
271 g_return_val_if_fail (pspec
->ref_count
> 0, NULL
);
273 g_param_spec_ref (pspec
);
274 g_param_spec_sink (pspec
);
279 * g_param_spec_get_name:
280 * @pspec: a valid #GParamSpec
282 * Get the name of a #GParamSpec.
284 * Returns: the name of @pspec.
286 G_CONST_RETURN gchar
*
287 g_param_spec_get_name (GParamSpec
*pspec
)
289 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
295 * g_param_spec_get_nick:
296 * @pspec: a valid #GParamSpec
298 * Get the nickname of a #GParamSpec.
300 * Returns: the nickname of @pspec.
302 G_CONST_RETURN gchar
*
303 g_param_spec_get_nick (GParamSpec
*pspec
)
305 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
311 GParamSpec
*redirect_target
;
313 redirect_target
= g_param_spec_get_redirect_target (pspec
);
314 if (redirect_target
&& redirect_target
->_nick
)
315 return redirect_target
->_nick
;
322 * g_param_spec_get_blurb:
323 * @pspec: a valid #GParamSpec
325 * Get the short description of a #GParamSpec.
327 * Returns: the short description of @pspec.
329 G_CONST_RETURN gchar
*
330 g_param_spec_get_blurb (GParamSpec
*pspec
)
332 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
335 return pspec
->_blurb
;
338 GParamSpec
*redirect_target
;
340 redirect_target
= g_param_spec_get_redirect_target (pspec
);
341 if (redirect_target
&& redirect_target
->_blurb
)
342 return redirect_target
->_blurb
;
349 canonicalize_key (gchar
*key
)
353 for (p
= key
; *p
!= 0; p
++)
358 (c
< '0' || c
> '9') &&
359 (c
< 'A' || c
> 'Z') &&
360 (c
< 'a' || c
> 'z'))
366 is_canonical (const gchar
*key
)
370 for (p
= key
; *p
!= 0; p
++)
375 (c
< '0' || c
> '9') &&
376 (c
< 'A' || c
> 'Z') &&
377 (c
< 'a' || c
> 'z'))
385 * g_param_spec_internal:
386 * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
387 * @name: the canonical name of the property
388 * @nick: the nickname of the property
389 * @blurb: a short description of the property
390 * @flags: a combination of #GParamFlags
392 * Creates a new #GParamSpec instance.
394 * A property name consists of segments consisting of ASCII letters and
395 * digits, separated by either the '-' or '_' character. The first
396 * character of a property name must be a letter. Names which violate these
397 * rules lead to undefined behaviour.
399 * When creating and looking up a #GParamSpec, either separator can be
400 * used, but they cannot be mixed. Using '-' is considerably more
401 * efficient and in fact required when using property names as detail
402 * strings for signals.
404 * Beyond the name, #GParamSpec<!-- -->s have two more descriptive
405 * strings associated with them, the @nick, which should be suitable
406 * for use as a label for the property in a property editor, and the
407 * @blurb, which should be a somewhat longer description, suitable for
408 * e.g. a tooltip. The @nick and @blurb should ideally be localized.
410 * Returns: a newly allocated #GParamSpec instance
413 g_param_spec_internal (GType param_type
,
421 g_return_val_if_fail (G_TYPE_IS_PARAM (param_type
) && param_type
!= G_TYPE_PARAM
, NULL
);
422 g_return_val_if_fail (name
!= NULL
, NULL
);
423 g_return_val_if_fail ((name
[0] >= 'A' && name
[0] <= 'Z') || (name
[0] >= 'a' && name
[0] <= 'z'), NULL
);
424 g_return_val_if_fail (!(flags
& G_PARAM_STATIC_NAME
) || is_canonical (name
), NULL
);
426 pspec
= (gpointer
) g_type_create_instance (param_type
);
428 if (flags
& G_PARAM_STATIC_NAME
)
430 pspec
->name
= g_intern_static_string (name
);
431 if (!is_canonical (pspec
->name
))
432 g_warning ("G_PARAM_STATIC_NAME used with non-canonical pspec name: %s", pspec
->name
);
436 pspec
->name
= g_strdup (name
);
437 canonicalize_key (pspec
->name
);
438 g_intern_string (pspec
->name
);
441 if (flags
& G_PARAM_STATIC_NICK
)
442 pspec
->_nick
= (gchar
*) nick
;
444 pspec
->_nick
= g_strdup (nick
);
446 if (flags
& G_PARAM_STATIC_BLURB
)
447 pspec
->_blurb
= (gchar
*) blurb
;
449 pspec
->_blurb
= g_strdup (blurb
);
451 pspec
->flags
= (flags
& G_PARAM_USER_MASK
) | (flags
& G_PARAM_MASK
);
457 * g_param_spec_get_qdata:
458 * @pspec: a valid #GParamSpec
459 * @quark: a #GQuark, naming the user data pointer
461 * Gets back user data pointers stored via g_param_spec_set_qdata().
463 * Returns: the user data pointer set, or %NULL
466 g_param_spec_get_qdata (GParamSpec
*pspec
,
469 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
471 return quark
? g_datalist_id_get_data (&pspec
->qdata
, quark
) : NULL
;
475 * g_param_spec_set_qdata:
476 * @pspec: the #GParamSpec to set store a user data pointer
477 * @quark: a #GQuark, naming the user data pointer
478 * @data: an opaque user data pointer
480 * Sets an opaque, named pointer on a #GParamSpec. The name is
481 * specified through a #GQuark (retrieved e.g. via
482 * g_quark_from_static_string()), and the pointer can be gotten back
483 * from the @pspec with g_param_spec_get_qdata(). Setting a
484 * previously set user data pointer, overrides (frees) the old pointer
485 * set, using %NULL as pointer essentially removes the data stored.
488 g_param_spec_set_qdata (GParamSpec
*pspec
,
492 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
493 g_return_if_fail (quark
> 0);
495 g_datalist_id_set_data (&pspec
->qdata
, quark
, data
);
499 * g_param_spec_set_qdata_full:
500 * @pspec: the #GParamSpec to set store a user data pointer
501 * @quark: a #GQuark, naming the user data pointer
502 * @data: an opaque user data pointer
503 * @destroy: function to invoke with @data as argument, when @data needs to
506 * This function works like g_param_spec_set_qdata(), but in addition,
507 * a <literal>void (*destroy) (gpointer)</literal> function may be
508 * specified which is called with @data as argument when the @pspec is
509 * finalized, or the data is being overwritten by a call to
510 * g_param_spec_set_qdata() with the same @quark.
513 g_param_spec_set_qdata_full (GParamSpec
*pspec
,
516 GDestroyNotify destroy
)
518 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
519 g_return_if_fail (quark
> 0);
521 g_datalist_id_set_data_full (&pspec
->qdata
, quark
, data
, data
? destroy
: (GDestroyNotify
) NULL
);
525 * g_param_spec_steal_qdata:
526 * @pspec: the #GParamSpec to get a stored user data pointer from
527 * @quark: a #GQuark, naming the user data pointer
529 * Gets back user data pointers stored via g_param_spec_set_qdata()
530 * and removes the @data from @pspec without invoking its destroy()
531 * function (if any was set). Usually, calling this function is only
532 * required to update user data pointers with a destroy notifier.
534 * Returns: the user data pointer set, or %NULL
537 g_param_spec_steal_qdata (GParamSpec
*pspec
,
540 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
541 g_return_val_if_fail (quark
> 0, NULL
);
543 return g_datalist_id_remove_no_notify (&pspec
->qdata
, quark
);
547 * g_param_spec_get_redirect_target:
548 * @pspec: a #GParamSpec
550 * If the paramspec redirects operations to another paramspec,
551 * returns that paramspec. Redirect is used typically for
552 * providing a new implementation of a property in a derived
553 * type while preserving all the properties from the parent
554 * type. Redirection is established by creating a property
555 * of type #GParamSpecOverride. See g_object_class_override_property()
556 * for an example of the use of this capability.
560 * Returns: paramspec to which requests on this paramspec should
561 * be redirected, or %NULL if none.
564 g_param_spec_get_redirect_target (GParamSpec
*pspec
)
566 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), NULL
);
568 if (G_IS_PARAM_SPEC_OVERRIDE (pspec
))
570 GParamSpecOverride
*ospec
= G_PARAM_SPEC_OVERRIDE (pspec
);
572 return ospec
->overridden
;
579 * g_param_value_set_default:
580 * @pspec: a valid #GParamSpec
581 * @value: a #GValue of correct type for @pspec
583 * Sets @value to its default value as specified in @pspec.
586 g_param_value_set_default (GParamSpec
*pspec
,
589 g_return_if_fail (G_IS_PARAM_SPEC (pspec
));
590 g_return_if_fail (G_IS_VALUE (value
));
591 g_return_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
));
593 g_value_reset (value
);
594 G_PARAM_SPEC_GET_CLASS (pspec
)->value_set_default (pspec
, value
);
598 * g_param_value_defaults:
599 * @pspec: a valid #GParamSpec
600 * @value: a #GValue of correct type for @pspec
602 * Checks whether @value contains the default value as specified in @pspec.
604 * Returns: whether @value contains the canonical default for this @pspec
607 g_param_value_defaults (GParamSpec
*pspec
,
610 GValue dflt_value
= { 0, };
613 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
614 g_return_val_if_fail (G_IS_VALUE (value
), FALSE
);
615 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
), FALSE
);
617 g_value_init (&dflt_value
, G_PARAM_SPEC_VALUE_TYPE (pspec
));
618 G_PARAM_SPEC_GET_CLASS (pspec
)->value_set_default (pspec
, &dflt_value
);
619 defaults
= G_PARAM_SPEC_GET_CLASS (pspec
)->values_cmp (pspec
, value
, &dflt_value
) == 0;
620 g_value_unset (&dflt_value
);
626 * g_param_value_validate:
627 * @pspec: a valid #GParamSpec
628 * @value: a #GValue of correct type for @pspec
630 * Ensures that the contents of @value comply with the specifications
631 * set out by @pspec. For example, a #GParamSpecInt might require
632 * that integers stored in @value may not be smaller than -42 and not be
633 * greater than +42. If @value contains an integer outside of this range,
634 * it is modified accordingly, so the resulting value will fit into the
637 * Returns: whether modifying @value was necessary to ensure validity
640 g_param_value_validate (GParamSpec
*pspec
,
643 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
644 g_return_val_if_fail (G_IS_VALUE (value
), FALSE
);
645 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value
), FALSE
);
647 if (G_PARAM_SPEC_GET_CLASS (pspec
)->value_validate
)
649 GValue oval
= *value
;
651 if (G_PARAM_SPEC_GET_CLASS (pspec
)->value_validate (pspec
, value
) ||
652 memcmp (&oval
.data
, &value
->data
, sizeof (oval
.data
)))
660 * g_param_value_convert:
661 * @pspec: a valid #GParamSpec
662 * @src_value: souce #GValue
663 * @dest_value: destination #GValue of correct type for @pspec
664 * @strict_validation: %TRUE requires @dest_value to conform to @pspec
665 * without modifications
667 * Transforms @src_value into @dest_value if possible, and then
668 * validates @dest_value, in order for it to conform to @pspec. If
669 * @strict_validation is %TRUE this function will only succeed if the
670 * transformed @dest_value complied to @pspec without modifications.
672 * See also g_value_type_transformable(), g_value_transform() and
673 * g_param_value_validate().
675 * Returns: %TRUE if transformation and validation were successful,
676 * %FALSE otherwise and @dest_value is left untouched.
679 g_param_value_convert (GParamSpec
*pspec
,
680 const GValue
*src_value
,
682 gboolean strict_validation
)
684 GValue tmp_value
= { 0, };
686 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), FALSE
);
687 g_return_val_if_fail (G_IS_VALUE (src_value
), FALSE
);
688 g_return_val_if_fail (G_IS_VALUE (dest_value
), FALSE
);
689 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, dest_value
), FALSE
);
691 /* better leave dest_value untouched when returning FALSE */
693 g_value_init (&tmp_value
, G_VALUE_TYPE (dest_value
));
694 if (g_value_transform (src_value
, &tmp_value
) &&
695 (!g_param_value_validate (pspec
, &tmp_value
) || !strict_validation
))
697 g_value_unset (dest_value
);
699 /* values are relocatable */
700 memcpy (dest_value
, &tmp_value
, sizeof (tmp_value
));
706 g_value_unset (&tmp_value
);
713 * g_param_values_cmp:
714 * @pspec: a valid #GParamSpec
715 * @value1: a #GValue of correct type for @pspec
716 * @value2: a #GValue of correct type for @pspec
718 * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1,
719 * if @value1 is found to be less than, equal to or greater than @value2,
722 * Returns: -1, 0 or +1, for a less than, equal to or greater than result
725 g_param_values_cmp (GParamSpec
*pspec
,
726 const GValue
*value1
,
727 const GValue
*value2
)
731 /* param_values_cmp() effectively does: value1 - value2
732 * so the return values are:
733 * -1) value1 < value2
734 * 0) value1 == value2
737 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec
), 0);
738 g_return_val_if_fail (G_IS_VALUE (value1
), 0);
739 g_return_val_if_fail (G_IS_VALUE (value2
), 0);
740 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value1
), 0);
741 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec
, value2
), 0);
743 cmp
= G_PARAM_SPEC_GET_CLASS (pspec
)->values_cmp (pspec
, value1
, value2
);
745 return CLAMP (cmp
, -1, 1);
749 value_param_init (GValue
*value
)
751 value
->data
[0].v_pointer
= NULL
;
755 value_param_free_value (GValue
*value
)
757 if (value
->data
[0].v_pointer
)
758 g_param_spec_unref (value
->data
[0].v_pointer
);
762 value_param_copy_value (const GValue
*src_value
,
765 if (src_value
->data
[0].v_pointer
)
766 dest_value
->data
[0].v_pointer
= g_param_spec_ref (src_value
->data
[0].v_pointer
);
768 dest_value
->data
[0].v_pointer
= NULL
;
772 value_param_transform_value (const GValue
*src_value
,
775 if (src_value
->data
[0].v_pointer
&&
776 g_type_is_a (G_PARAM_SPEC_TYPE (dest_value
->data
[0].v_pointer
), G_VALUE_TYPE (dest_value
)))
777 dest_value
->data
[0].v_pointer
= g_param_spec_ref (src_value
->data
[0].v_pointer
);
779 dest_value
->data
[0].v_pointer
= NULL
;
783 value_param_peek_pointer (const GValue
*value
)
785 return value
->data
[0].v_pointer
;
789 value_param_collect_value (GValue
*value
,
790 guint n_collect_values
,
791 GTypeCValue
*collect_values
,
794 if (collect_values
[0].v_pointer
)
796 GParamSpec
*param
= collect_values
[0].v_pointer
;
798 if (param
->g_type_instance
.g_class
== NULL
)
799 return g_strconcat ("invalid unclassed param spec pointer for value type `",
800 G_VALUE_TYPE_NAME (value
),
803 else if (!g_value_type_compatible (G_PARAM_SPEC_TYPE (param
), G_VALUE_TYPE (value
)))
804 return g_strconcat ("invalid param spec type `",
805 G_PARAM_SPEC_TYPE_NAME (param
),
806 "' for value type `",
807 G_VALUE_TYPE_NAME (value
),
810 value
->data
[0].v_pointer
= g_param_spec_ref (param
);
813 value
->data
[0].v_pointer
= NULL
;
819 value_param_lcopy_value (const GValue
*value
,
820 guint n_collect_values
,
821 GTypeCValue
*collect_values
,
824 GParamSpec
**param_p
= collect_values
[0].v_pointer
;
827 return g_strdup_printf ("value location for `%s' passed as NULL", G_VALUE_TYPE_NAME (value
));
829 if (!value
->data
[0].v_pointer
)
831 else if (collect_flags
& G_VALUE_NOCOPY_CONTENTS
)
832 *param_p
= value
->data
[0].v_pointer
;
834 *param_p
= g_param_spec_ref (value
->data
[0].v_pointer
);
840 /* --- param spec pool --- */
844 * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be
845 * quickly accessed by owner and name. The implementation of the #GObject property
846 * system uses such a pool to store the #GParamSpecs of the properties all object
849 struct _GParamSpecPool
852 gboolean type_prefixing
;
853 GHashTable
*hash_table
;
857 param_spec_pool_hash (gconstpointer key_spec
)
859 const GParamSpec
*key
= key_spec
;
861 guint h
= key
->owner_type
;
863 for (p
= key
->name
; *p
; p
++)
864 h
= (h
<< 5) - h
+ *p
;
870 param_spec_pool_equals (gconstpointer key_spec_1
,
871 gconstpointer key_spec_2
)
873 const GParamSpec
*key1
= key_spec_1
;
874 const GParamSpec
*key2
= key_spec_2
;
876 return (key1
->owner_type
== key2
->owner_type
&&
877 strcmp (key1
->name
, key2
->name
) == 0);
881 * g_param_spec_pool_new:
882 * @type_prefixing: Whether the pool will support type-prefixed property names.
884 * Creates a new #GParamSpecPool.
886 * If @type_prefixing is %TRUE, lookups in the newly created pool will
887 * allow to specify the owner as a colon-separated prefix of the
888 * property name, like "GtkContainer:border-width". This feature is
889 * deprecated, so you should always set @type_prefixing to %FALSE.
891 * Returns: a newly allocated #GParamSpecPool.
894 g_param_spec_pool_new (gboolean type_prefixing
)
896 static GStaticMutex init_smutex
= G_STATIC_MUTEX_INIT
;
897 GParamSpecPool
*pool
= g_new (GParamSpecPool
, 1);
899 memcpy (&pool
->smutex
, &init_smutex
, sizeof (init_smutex
));
900 pool
->type_prefixing
= type_prefixing
!= FALSE
;
901 pool
->hash_table
= g_hash_table_new (param_spec_pool_hash
, param_spec_pool_equals
);
907 * g_param_spec_pool_insert:
908 * @pool: a #GParamSpecPool.
909 * @pspec: the #GParamSpec to insert
910 * @owner_type: a #GType identifying the owner of @pspec
912 * Inserts a #GParamSpec in the pool.
915 g_param_spec_pool_insert (GParamSpecPool
*pool
,
921 if (pool
&& pspec
&& owner_type
> 0 && pspec
->owner_type
== 0)
923 G_SLOCK (&pool
->smutex
);
924 for (p
= pspec
->name
; *p
; p
++)
926 if (!strchr (G_CSET_A_2_Z G_CSET_a_2_z G_CSET_DIGITS
"-_", *p
))
928 g_warning (G_STRLOC
": pspec name \"%s\" contains invalid characters", pspec
->name
);
929 G_SUNLOCK (&pool
->smutex
);
934 pspec
->owner_type
= owner_type
;
935 g_param_spec_ref (pspec
);
936 g_hash_table_insert (pool
->hash_table
, pspec
, pspec
);
937 G_SUNLOCK (&pool
->smutex
);
941 g_return_if_fail (pool
!= NULL
);
942 g_return_if_fail (pspec
);
943 g_return_if_fail (owner_type
> 0);
944 g_return_if_fail (pspec
->owner_type
== 0);
949 * g_param_spec_pool_remove:
950 * @pool: a #GParamSpecPool
951 * @pspec: the #GParamSpec to remove
953 * Removes a #GParamSpec from the pool.
956 g_param_spec_pool_remove (GParamSpecPool
*pool
,
961 G_SLOCK (&pool
->smutex
);
962 if (g_hash_table_remove (pool
->hash_table
, pspec
))
963 g_param_spec_unref (pspec
);
965 g_warning (G_STRLOC
": attempt to remove unknown pspec `%s' from pool", pspec
->name
);
966 G_SUNLOCK (&pool
->smutex
);
970 g_return_if_fail (pool
!= NULL
);
971 g_return_if_fail (pspec
);
975 static inline GParamSpec
*
976 param_spec_ht_lookup (GHashTable
*hash_table
,
977 const gchar
*param_name
,
979 gboolean walk_ancestors
)
981 GParamSpec key
, *pspec
;
983 key
.owner_type
= owner_type
;
984 key
.name
= (gchar
*) param_name
;
988 pspec
= g_hash_table_lookup (hash_table
, &key
);
991 key
.owner_type
= g_type_parent (key
.owner_type
);
993 while (key
.owner_type
);
995 pspec
= g_hash_table_lookup (hash_table
, &key
);
997 if (!pspec
&& !is_canonical (param_name
))
999 /* try canonicalized form */
1000 key
.name
= g_strdup (param_name
);
1001 key
.owner_type
= owner_type
;
1003 canonicalize_key (key
.name
);
1007 pspec
= g_hash_table_lookup (hash_table
, &key
);
1013 key
.owner_type
= g_type_parent (key
.owner_type
);
1015 while (key
.owner_type
);
1017 pspec
= g_hash_table_lookup (hash_table
, &key
);
1025 * g_param_spec_pool_lookup:
1026 * @pool: a #GParamSpecPool
1027 * @param_name: the name to look for
1028 * @owner_type: the owner to look for
1029 * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name
1030 * owned by an ancestor of @owner_type.
1032 * Looks up a #GParamSpec in the pool.
1034 * Returns: The found #GParamSpec, or %NULL if no matching #GParamSpec was found.
1037 g_param_spec_pool_lookup (GParamSpecPool
*pool
,
1038 const gchar
*param_name
,
1040 gboolean walk_ancestors
)
1045 if (!pool
|| !param_name
)
1047 g_return_val_if_fail (pool
!= NULL
, NULL
);
1048 g_return_val_if_fail (param_name
!= NULL
, NULL
);
1051 G_SLOCK (&pool
->smutex
);
1053 delim
= pool
->type_prefixing
? strchr (param_name
, ':') : NULL
;
1055 /* try quick and away, i.e. without prefix */
1058 pspec
= param_spec_ht_lookup (pool
->hash_table
, param_name
, owner_type
, walk_ancestors
);
1059 G_SUNLOCK (&pool
->smutex
);
1064 /* strip type prefix */
1065 if (pool
->type_prefixing
&& delim
[1] == ':')
1067 guint l
= delim
- param_name
;
1068 gchar stack_buffer
[32], *buffer
= l
< 32 ? stack_buffer
: g_new (gchar
, l
+ 1);
1071 strncpy (buffer
, param_name
, delim
- param_name
);
1073 type
= g_type_from_name (buffer
);
1076 if (type
) /* type==0 isn't a valid type pefix */
1078 /* sanity check, these cases don't make a whole lot of sense */
1079 if ((!walk_ancestors
&& type
!= owner_type
) || !g_type_is_a (owner_type
, type
))
1081 G_SUNLOCK (&pool
->smutex
);
1086 param_name
+= l
+ 2;
1087 pspec
= param_spec_ht_lookup (pool
->hash_table
, param_name
, owner_type
, walk_ancestors
);
1088 G_SUNLOCK (&pool
->smutex
);
1093 /* malformed param_name */
1095 G_SUNLOCK (&pool
->smutex
);
1101 pool_list (gpointer key
,
1105 GParamSpec
*pspec
= value
;
1106 gpointer
*data
= user_data
;
1107 GType owner_type
= (GType
) data
[1];
1109 if (owner_type
== pspec
->owner_type
)
1110 data
[0] = g_list_prepend (data
[0], pspec
);
1114 * g_param_spec_pool_list_owned:
1115 * @pool: a #GParamSpecPool
1116 * @owner_type: the owner to look for
1118 * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
1121 * Returns: a #GList of all #GParamSpec<!-- -->s owned by @owner_type
1122 * in the pool#GParamSpec<!-- -->s.
1125 g_param_spec_pool_list_owned (GParamSpecPool
*pool
,
1130 g_return_val_if_fail (pool
!= NULL
, NULL
);
1131 g_return_val_if_fail (owner_type
> 0, NULL
);
1133 G_SLOCK (&pool
->smutex
);
1135 data
[1] = (gpointer
) owner_type
;
1136 g_hash_table_foreach (pool
->hash_table
, pool_list
, &data
);
1137 G_SUNLOCK (&pool
->smutex
);
1143 pspec_compare_id (gconstpointer a
,
1146 const GParamSpec
*pspec1
= a
, *pspec2
= b
;
1148 return pspec1
->param_id
< pspec2
->param_id
? -1 : pspec1
->param_id
> pspec2
->param_id
;
1151 static inline GSList
*
1152 pspec_list_remove_overridden_and_redirected (GSList
*plist
,
1157 GSList
*rlist
= NULL
;
1161 GSList
*tmp
= plist
->next
;
1162 GParamSpec
*pspec
= plist
->data
;
1164 gboolean remove
= FALSE
;
1166 /* Remove paramspecs that are redirected, and also paramspecs
1167 * that have are overridden by non-redirected properties.
1168 * The idea is to get the single paramspec for each name that
1169 * best corresponds to what the application sees.
1171 if (g_param_spec_get_redirect_target (pspec
))
1175 found
= param_spec_ht_lookup (ht
, pspec
->name
, owner_type
, TRUE
);
1178 GParamSpec
*redirect
= g_param_spec_get_redirect_target (found
);
1179 if (redirect
!= pspec
)
1186 g_slist_free_1 (plist
);
1190 plist
->next
= rlist
;
1200 pool_depth_list (gpointer key
,
1204 GParamSpec
*pspec
= value
;
1205 gpointer
*data
= user_data
;
1206 GSList
**slists
= data
[0];
1207 GType owner_type
= (GType
) data
[1];
1209 if (g_type_is_a (owner_type
, pspec
->owner_type
))
1211 if (G_TYPE_IS_INTERFACE (pspec
->owner_type
))
1213 slists
[0] = g_slist_prepend (slists
[0], pspec
);
1217 guint d
= g_type_depth (pspec
->owner_type
);
1219 slists
[d
- 1] = g_slist_prepend (slists
[d
- 1], pspec
);
1224 /* We handle interfaces specially since we don't want to
1225 * count interface prerequisites like normal inheritance;
1226 * the property comes from the direct inheritance from
1227 * the prerequisite class, not from the interface that
1230 * also 'depth' isn't a meaningful concept for interface
1234 pool_depth_list_for_interface (gpointer key
,
1238 GParamSpec
*pspec
= value
;
1239 gpointer
*data
= user_data
;
1240 GSList
**slists
= data
[0];
1241 GType owner_type
= (GType
) data
[1];
1243 if (pspec
->owner_type
== owner_type
)
1244 slists
[0] = g_slist_prepend (slists
[0], pspec
);
1248 * g_param_spec_pool_list:
1249 * @pool: a #GParamSpecPool
1250 * @owner_type: the owner to look for
1251 * @n_pspecs_p: return location for the length of the returned array
1253 * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
1256 * Returns: a newly allocated array containing pointers to all
1257 * #GParamSpec<!-- -->s owned by @owner_type in the pool
1260 g_param_spec_pool_list (GParamSpecPool
*pool
,
1264 GParamSpec
**pspecs
, **p
;
1265 GSList
**slists
, *node
;
1269 g_return_val_if_fail (pool
!= NULL
, NULL
);
1270 g_return_val_if_fail (owner_type
> 0, NULL
);
1271 g_return_val_if_fail (n_pspecs_p
!= NULL
, NULL
);
1273 G_SLOCK (&pool
->smutex
);
1275 d
= g_type_depth (owner_type
);
1276 slists
= g_new0 (GSList
*, d
);
1278 data
[1] = (gpointer
) owner_type
;
1280 g_hash_table_foreach (pool
->hash_table
,
1281 G_TYPE_IS_INTERFACE (owner_type
) ?
1282 pool_depth_list_for_interface
:
1286 for (i
= 0; i
< d
; i
++)
1287 slists
[i
] = pspec_list_remove_overridden_and_redirected (slists
[i
], pool
->hash_table
, owner_type
, n_pspecs_p
);
1288 pspecs
= g_new (GParamSpec
*, *n_pspecs_p
+ 1);
1290 for (i
= 0; i
< d
; i
++)
1292 slists
[i
] = g_slist_sort (slists
[i
], pspec_compare_id
);
1293 for (node
= slists
[i
]; node
; node
= node
->next
)
1295 g_slist_free (slists
[i
]);
1299 G_SUNLOCK (&pool
->smutex
);
1305 /* --- auxillary functions --- */
1310 void (*finalize
) (GParamSpec
*pspec
);
1311 void (*value_set_default
) (GParamSpec
*pspec
,
1313 gboolean (*value_validate
) (GParamSpec
*pspec
,
1315 gint (*values_cmp
) (GParamSpec
*pspec
,
1316 const GValue
*value1
,
1317 const GValue
*value2
);
1318 } ParamSpecClassInfo
;
1321 param_spec_generic_class_init (gpointer g_class
,
1322 gpointer class_data
)
1324 GParamSpecClass
*class = g_class
;
1325 ParamSpecClassInfo
*info
= class_data
;
1327 class->value_type
= info
->value_type
;
1329 class->finalize
= info
->finalize
; /* optional */
1330 class->value_set_default
= info
->value_set_default
;
1331 if (info
->value_validate
)
1332 class->value_validate
= info
->value_validate
; /* optional */
1333 class->values_cmp
= info
->values_cmp
;
1334 g_free (class_data
);
1338 default_value_set_default (GParamSpec
*pspec
,
1341 /* value is already zero initialized */
1345 default_values_cmp (GParamSpec
*pspec
,
1346 const GValue
*value1
,
1347 const GValue
*value2
)
1349 return memcmp (&value1
->data
, &value2
->data
, sizeof (value1
->data
));
1353 * g_param_type_register_static:
1354 * @name: 0-terminated string used as the name of the new #GParamSpec type.
1355 * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
1357 * Registers @name as the name of a new static type derived from
1358 * #G_TYPE_PARAM. The type system uses the information contained in
1359 * the #GParamSpecTypeInfo structure pointed to by @info to manage the
1360 * #GParamSpec type and its instances.
1362 * Returns: The new type identifier.
1365 g_param_type_register_static (const gchar
*name
,
1366 const GParamSpecTypeInfo
*pspec_info
)
1369 sizeof (GParamSpecClass
), /* class_size */
1370 NULL
, /* base_init */
1371 NULL
, /* base_destroy */
1372 param_spec_generic_class_init
, /* class_init */
1373 NULL
, /* class_destroy */
1374 NULL
, /* class_data */
1375 0, /* instance_size */
1376 16, /* n_preallocs */
1377 NULL
, /* instance_init */
1379 ParamSpecClassInfo
*cinfo
;
1381 g_return_val_if_fail (name
!= NULL
, 0);
1382 g_return_val_if_fail (pspec_info
!= NULL
, 0);
1383 g_return_val_if_fail (g_type_from_name (name
) == 0, 0);
1384 g_return_val_if_fail (pspec_info
->instance_size
>= sizeof (GParamSpec
), 0);
1385 g_return_val_if_fail (g_type_name (pspec_info
->value_type
) != NULL
, 0);
1386 /* default: g_return_val_if_fail (pspec_info->value_set_default != NULL, 0); */
1387 /* optional: g_return_val_if_fail (pspec_info->value_validate != NULL, 0); */
1388 /* default: g_return_val_if_fail (pspec_info->values_cmp != NULL, 0); */
1390 info
.instance_size
= pspec_info
->instance_size
;
1391 info
.n_preallocs
= pspec_info
->n_preallocs
;
1392 info
.instance_init
= (GInstanceInitFunc
) pspec_info
->instance_init
;
1393 cinfo
= g_new (ParamSpecClassInfo
, 1);
1394 cinfo
->value_type
= pspec_info
->value_type
;
1395 cinfo
->finalize
= pspec_info
->finalize
;
1396 cinfo
->value_set_default
= pspec_info
->value_set_default
? pspec_info
->value_set_default
: default_value_set_default
;
1397 cinfo
->value_validate
= pspec_info
->value_validate
;
1398 cinfo
->values_cmp
= pspec_info
->values_cmp
? pspec_info
->values_cmp
: default_values_cmp
;
1399 info
.class_data
= cinfo
;
1401 return g_type_register_static (G_TYPE_PARAM
, name
, &info
, 0);
1405 * g_value_set_param:
1406 * @value: a valid #GValue of type %G_TYPE_PARAM
1407 * @param: the #GParamSpec to be set
1409 * Set the contents of a %G_TYPE_PARAM #GValue to @param.
1412 g_value_set_param (GValue
*value
,
1415 g_return_if_fail (G_VALUE_HOLDS_PARAM (value
));
1417 g_return_if_fail (G_IS_PARAM_SPEC (param
));
1419 if (value
->data
[0].v_pointer
)
1420 g_param_spec_unref (value
->data
[0].v_pointer
);
1421 value
->data
[0].v_pointer
= param
;
1422 if (value
->data
[0].v_pointer
)
1423 g_param_spec_ref (value
->data
[0].v_pointer
);
1427 * g_value_set_param_take_ownership:
1428 * @value: a valid #GValue of type %G_TYPE_PARAM
1429 * @param: the #GParamSpec to be set
1431 * This is an internal function introduced mainly for C marshallers.
1433 * Deprecated: 2.4: Use g_value_take_param() instead.
1436 g_value_set_param_take_ownership (GValue
*value
,
1439 g_value_take_param (value
, param
);
1443 * g_value_take_param:
1444 * @value: a valid #GValue of type %G_TYPE_PARAM
1445 * @param: the #GParamSpec to be set
1447 * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
1448 * over the ownership of the callers reference to @param; the caller
1449 * doesn't have to unref it any more.
1454 g_value_take_param (GValue
*value
,
1457 g_return_if_fail (G_VALUE_HOLDS_PARAM (value
));
1459 g_return_if_fail (G_IS_PARAM_SPEC (param
));
1461 if (value
->data
[0].v_pointer
)
1462 g_param_spec_unref (value
->data
[0].v_pointer
);
1463 value
->data
[0].v_pointer
= param
; /* we take over the reference count */
1467 * g_value_get_param:
1468 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1470 * Get the contents of a %G_TYPE_PARAM #GValue.
1472 * Returns: #GParamSpec content of @value
1475 g_value_get_param (const GValue
*value
)
1477 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value
), NULL
);
1479 return value
->data
[0].v_pointer
;
1483 * g_value_dup_param:
1484 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1486 * Get the contents of a %G_TYPE_PARAM #GValue, increasing its
1489 * Returns: #GParamSpec content of @value, should be unreferenced when
1493 g_value_dup_param (const GValue
*value
)
1495 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value
), NULL
);
1497 return value
->data
[0].v_pointer
? g_param_spec_ref (value
->data
[0].v_pointer
) : NULL
;
1500 #define __G_PARAM_C__
1501 #include "gobjectaliasdef.c"