1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
3 * Copyright (C) 2010 Christian Persch
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
27 #define GLIB_DISABLE_DEPRECATION_WARNINGS
29 #include "gparamspecs.h"
30 #include "gtype-private.h"
31 #include "gvaluecollector.h"
33 #include "gvaluearray.h"
37 * SECTION:param_value_types
38 * @short_description: Standard Parameter and Value Types
39 * @see_also: #GParamSpec, #GValue, g_object_class_install_property().
40 * @title: Parameters and Values
42 * #GValue provides an abstract container structure which can be
43 * copied, transformed and compared while holding a value of any
44 * (derived) type, which is registered as a #GType with a
45 * #GTypeValueTable in its #GTypeInfo structure. Parameter
46 * specifications for most value types can be created as #GParamSpec
47 * derived instances, to implement e.g. #GObject properties which
48 * operate on #GValue containers.
50 * Parameter names need to start with a letter (a-z or A-Z). Subsequent
51 * characters can be letters, numbers or a '-'.
52 * All other characters are replaced by a '-' during construction.
56 #define G_FLOAT_EPSILON (1e-30)
57 #define G_DOUBLE_EPSILON (1e-90)
60 /* --- param spec functions --- */
62 param_char_init (GParamSpec *pspec)
64 GParamSpecChar *cspec = G_PARAM_SPEC_CHAR (pspec);
66 cspec->minimum = 0x7f;
67 cspec->maximum = 0x80;
68 cspec->default_value = 0;
72 param_char_set_default (GParamSpec *pspec,
75 value->data[0].v_int = G_PARAM_SPEC_CHAR (pspec)->default_value;
79 param_char_validate (GParamSpec *pspec,
82 GParamSpecChar *cspec = G_PARAM_SPEC_CHAR (pspec);
83 gint oval = value->data[0].v_int;
85 value->data[0].v_int = CLAMP (value->data[0].v_int, cspec->minimum, cspec->maximum);
87 return value->data[0].v_int != oval;
91 param_uchar_init (GParamSpec *pspec)
93 GParamSpecUChar *uspec = G_PARAM_SPEC_UCHAR (pspec);
96 uspec->maximum = 0xff;
97 uspec->default_value = 0;
101 param_uchar_set_default (GParamSpec *pspec,
104 value->data[0].v_uint = G_PARAM_SPEC_UCHAR (pspec)->default_value;
108 param_uchar_validate (GParamSpec *pspec,
111 GParamSpecUChar *uspec = G_PARAM_SPEC_UCHAR (pspec);
112 guint oval = value->data[0].v_uint;
114 value->data[0].v_uint = CLAMP (value->data[0].v_uint, uspec->minimum, uspec->maximum);
116 return value->data[0].v_uint != oval;
120 param_boolean_set_default (GParamSpec *pspec,
123 value->data[0].v_int = G_PARAM_SPEC_BOOLEAN (pspec)->default_value;
127 param_boolean_validate (GParamSpec *pspec,
130 gint oval = value->data[0].v_int;
132 value->data[0].v_int = value->data[0].v_int != FALSE;
134 return value->data[0].v_int != oval;
138 param_int_init (GParamSpec *pspec)
140 GParamSpecInt *ispec = G_PARAM_SPEC_INT (pspec);
142 ispec->minimum = 0x7fffffff;
143 ispec->maximum = 0x80000000;
144 ispec->default_value = 0;
148 param_int_set_default (GParamSpec *pspec,
151 value->data[0].v_int = G_PARAM_SPEC_INT (pspec)->default_value;
155 param_int_validate (GParamSpec *pspec,
158 GParamSpecInt *ispec = G_PARAM_SPEC_INT (pspec);
159 gint oval = value->data[0].v_int;
161 value->data[0].v_int = CLAMP (value->data[0].v_int, ispec->minimum, ispec->maximum);
163 return value->data[0].v_int != oval;
167 param_int_values_cmp (GParamSpec *pspec,
168 const GValue *value1,
169 const GValue *value2)
171 if (value1->data[0].v_int < value2->data[0].v_int)
174 return value1->data[0].v_int > value2->data[0].v_int;
178 param_uint_init (GParamSpec *pspec)
180 GParamSpecUInt *uspec = G_PARAM_SPEC_UINT (pspec);
183 uspec->maximum = 0xffffffff;
184 uspec->default_value = 0;
188 param_uint_set_default (GParamSpec *pspec,
191 value->data[0].v_uint = G_PARAM_SPEC_UINT (pspec)->default_value;
195 param_uint_validate (GParamSpec *pspec,
198 GParamSpecUInt *uspec = G_PARAM_SPEC_UINT (pspec);
199 guint oval = value->data[0].v_uint;
201 value->data[0].v_uint = CLAMP (value->data[0].v_uint, uspec->minimum, uspec->maximum);
203 return value->data[0].v_uint != oval;
207 param_uint_values_cmp (GParamSpec *pspec,
208 const GValue *value1,
209 const GValue *value2)
211 if (value1->data[0].v_uint < value2->data[0].v_uint)
214 return value1->data[0].v_uint > value2->data[0].v_uint;
218 param_long_init (GParamSpec *pspec)
220 GParamSpecLong *lspec = G_PARAM_SPEC_LONG (pspec);
223 lspec->minimum = 0x7fffffff;
224 lspec->maximum = 0x80000000;
225 #else /* SIZEOF_LONG != 4 (8) */
226 lspec->minimum = 0x7fffffffffffffff;
227 lspec->maximum = 0x8000000000000000;
229 lspec->default_value = 0;
233 param_long_set_default (GParamSpec *pspec,
236 value->data[0].v_long = G_PARAM_SPEC_LONG (pspec)->default_value;
240 param_long_validate (GParamSpec *pspec,
243 GParamSpecLong *lspec = G_PARAM_SPEC_LONG (pspec);
244 glong oval = value->data[0].v_long;
246 value->data[0].v_long = CLAMP (value->data[0].v_long, lspec->minimum, lspec->maximum);
248 return value->data[0].v_long != oval;
252 param_long_values_cmp (GParamSpec *pspec,
253 const GValue *value1,
254 const GValue *value2)
256 if (value1->data[0].v_long < value2->data[0].v_long)
259 return value1->data[0].v_long > value2->data[0].v_long;
263 param_ulong_init (GParamSpec *pspec)
265 GParamSpecULong *uspec = G_PARAM_SPEC_ULONG (pspec);
269 uspec->maximum = 0xffffffff;
270 #else /* SIZEOF_LONG != 4 (8) */
271 uspec->maximum = 0xffffffffffffffff;
273 uspec->default_value = 0;
277 param_ulong_set_default (GParamSpec *pspec,
280 value->data[0].v_ulong = G_PARAM_SPEC_ULONG (pspec)->default_value;
284 param_ulong_validate (GParamSpec *pspec,
287 GParamSpecULong *uspec = G_PARAM_SPEC_ULONG (pspec);
288 gulong oval = value->data[0].v_ulong;
290 value->data[0].v_ulong = CLAMP (value->data[0].v_ulong, uspec->minimum, uspec->maximum);
292 return value->data[0].v_ulong != oval;
296 param_ulong_values_cmp (GParamSpec *pspec,
297 const GValue *value1,
298 const GValue *value2)
300 if (value1->data[0].v_ulong < value2->data[0].v_ulong)
303 return value1->data[0].v_ulong > value2->data[0].v_ulong;
307 param_int64_init (GParamSpec *pspec)
309 GParamSpecInt64 *lspec = G_PARAM_SPEC_INT64 (pspec);
311 lspec->minimum = G_MININT64;
312 lspec->maximum = G_MAXINT64;
313 lspec->default_value = 0;
317 param_int64_set_default (GParamSpec *pspec,
320 value->data[0].v_int64 = G_PARAM_SPEC_INT64 (pspec)->default_value;
324 param_int64_validate (GParamSpec *pspec,
327 GParamSpecInt64 *lspec = G_PARAM_SPEC_INT64 (pspec);
328 gint64 oval = value->data[0].v_int64;
330 value->data[0].v_int64 = CLAMP (value->data[0].v_int64, lspec->minimum, lspec->maximum);
332 return value->data[0].v_int64 != oval;
336 param_int64_values_cmp (GParamSpec *pspec,
337 const GValue *value1,
338 const GValue *value2)
340 if (value1->data[0].v_int64 < value2->data[0].v_int64)
343 return value1->data[0].v_int64 > value2->data[0].v_int64;
347 param_uint64_init (GParamSpec *pspec)
349 GParamSpecUInt64 *uspec = G_PARAM_SPEC_UINT64 (pspec);
352 uspec->maximum = G_MAXUINT64;
353 uspec->default_value = 0;
357 param_uint64_set_default (GParamSpec *pspec,
360 value->data[0].v_uint64 = G_PARAM_SPEC_UINT64 (pspec)->default_value;
364 param_uint64_validate (GParamSpec *pspec,
367 GParamSpecUInt64 *uspec = G_PARAM_SPEC_UINT64 (pspec);
368 guint64 oval = value->data[0].v_uint64;
370 value->data[0].v_uint64 = CLAMP (value->data[0].v_uint64, uspec->minimum, uspec->maximum);
372 return value->data[0].v_uint64 != oval;
376 param_uint64_values_cmp (GParamSpec *pspec,
377 const GValue *value1,
378 const GValue *value2)
380 if (value1->data[0].v_uint64 < value2->data[0].v_uint64)
383 return value1->data[0].v_uint64 > value2->data[0].v_uint64;
387 param_unichar_init (GParamSpec *pspec)
389 GParamSpecUnichar *uspec = G_PARAM_SPEC_UNICHAR (pspec);
391 uspec->default_value = 0;
395 param_unichar_set_default (GParamSpec *pspec,
398 value->data[0].v_uint = G_PARAM_SPEC_UNICHAR (pspec)->default_value;
402 param_unichar_validate (GParamSpec *pspec,
405 gunichar oval = value->data[0].v_uint;
406 gboolean changed = FALSE;
408 if (!g_unichar_validate (oval))
410 value->data[0].v_uint = 0;
418 param_unichar_values_cmp (GParamSpec *pspec,
419 const GValue *value1,
420 const GValue *value2)
422 if (value1->data[0].v_uint < value2->data[0].v_uint)
425 return value1->data[0].v_uint > value2->data[0].v_uint;
429 param_enum_init (GParamSpec *pspec)
431 GParamSpecEnum *espec = G_PARAM_SPEC_ENUM (pspec);
433 espec->enum_class = NULL;
434 espec->default_value = 0;
438 param_enum_finalize (GParamSpec *pspec)
440 GParamSpecEnum *espec = G_PARAM_SPEC_ENUM (pspec);
441 GParamSpecClass *parent_class = g_type_class_peek (g_type_parent (G_TYPE_PARAM_ENUM));
443 if (espec->enum_class)
445 g_type_class_unref (espec->enum_class);
446 espec->enum_class = NULL;
449 parent_class->finalize (pspec);
453 param_enum_set_default (GParamSpec *pspec,
456 value->data[0].v_long = G_PARAM_SPEC_ENUM (pspec)->default_value;
460 param_enum_validate (GParamSpec *pspec,
463 GParamSpecEnum *espec = G_PARAM_SPEC_ENUM (pspec);
464 glong oval = value->data[0].v_long;
466 if (!espec->enum_class ||
467 !g_enum_get_value (espec->enum_class, value->data[0].v_long))
468 value->data[0].v_long = espec->default_value;
470 return value->data[0].v_long != oval;
474 param_flags_init (GParamSpec *pspec)
476 GParamSpecFlags *fspec = G_PARAM_SPEC_FLAGS (pspec);
478 fspec->flags_class = NULL;
479 fspec->default_value = 0;
483 param_flags_finalize (GParamSpec *pspec)
485 GParamSpecFlags *fspec = G_PARAM_SPEC_FLAGS (pspec);
486 GParamSpecClass *parent_class = g_type_class_peek (g_type_parent (G_TYPE_PARAM_FLAGS));
488 if (fspec->flags_class)
490 g_type_class_unref (fspec->flags_class);
491 fspec->flags_class = NULL;
494 parent_class->finalize (pspec);
498 param_flags_set_default (GParamSpec *pspec,
501 value->data[0].v_ulong = G_PARAM_SPEC_FLAGS (pspec)->default_value;
505 param_flags_validate (GParamSpec *pspec,
508 GParamSpecFlags *fspec = G_PARAM_SPEC_FLAGS (pspec);
509 gulong oval = value->data[0].v_ulong;
511 if (fspec->flags_class)
512 value->data[0].v_ulong &= fspec->flags_class->mask;
514 value->data[0].v_ulong = fspec->default_value;
516 return value->data[0].v_ulong != oval;
520 param_float_init (GParamSpec *pspec)
522 GParamSpecFloat *fspec = G_PARAM_SPEC_FLOAT (pspec);
524 fspec->minimum = -G_MAXFLOAT;
525 fspec->maximum = G_MAXFLOAT;
526 fspec->default_value = 0;
527 fspec->epsilon = G_FLOAT_EPSILON;
531 param_float_set_default (GParamSpec *pspec,
534 value->data[0].v_float = G_PARAM_SPEC_FLOAT (pspec)->default_value;
538 param_float_validate (GParamSpec *pspec,
541 GParamSpecFloat *fspec = G_PARAM_SPEC_FLOAT (pspec);
542 gfloat oval = value->data[0].v_float;
544 value->data[0].v_float = CLAMP (value->data[0].v_float, fspec->minimum, fspec->maximum);
546 return value->data[0].v_float != oval;
550 param_float_values_cmp (GParamSpec *pspec,
551 const GValue *value1,
552 const GValue *value2)
554 gfloat epsilon = G_PARAM_SPEC_FLOAT (pspec)->epsilon;
556 if (value1->data[0].v_float < value2->data[0].v_float)
557 return - (value2->data[0].v_float - value1->data[0].v_float > epsilon);
559 return value1->data[0].v_float - value2->data[0].v_float > epsilon;
563 param_double_init (GParamSpec *pspec)
565 GParamSpecDouble *dspec = G_PARAM_SPEC_DOUBLE (pspec);
567 dspec->minimum = -G_MAXDOUBLE;
568 dspec->maximum = G_MAXDOUBLE;
569 dspec->default_value = 0;
570 dspec->epsilon = G_DOUBLE_EPSILON;
574 param_double_set_default (GParamSpec *pspec,
577 value->data[0].v_double = G_PARAM_SPEC_DOUBLE (pspec)->default_value;
581 param_double_validate (GParamSpec *pspec,
584 GParamSpecDouble *dspec = G_PARAM_SPEC_DOUBLE (pspec);
585 gdouble oval = value->data[0].v_double;
587 value->data[0].v_double = CLAMP (value->data[0].v_double, dspec->minimum, dspec->maximum);
589 return value->data[0].v_double != oval;
593 param_double_values_cmp (GParamSpec *pspec,
594 const GValue *value1,
595 const GValue *value2)
597 gdouble epsilon = G_PARAM_SPEC_DOUBLE (pspec)->epsilon;
599 if (value1->data[0].v_double < value2->data[0].v_double)
600 return - (value2->data[0].v_double - value1->data[0].v_double > epsilon);
602 return value1->data[0].v_double - value2->data[0].v_double > epsilon;
606 param_string_init (GParamSpec *pspec)
608 GParamSpecString *sspec = G_PARAM_SPEC_STRING (pspec);
610 sspec->default_value = NULL;
611 sspec->cset_first = NULL;
612 sspec->cset_nth = NULL;
613 sspec->substitutor = '_';
614 sspec->null_fold_if_empty = FALSE;
615 sspec->ensure_non_null = FALSE;
619 param_string_finalize (GParamSpec *pspec)
621 GParamSpecString *sspec = G_PARAM_SPEC_STRING (pspec);
622 GParamSpecClass *parent_class = g_type_class_peek (g_type_parent (G_TYPE_PARAM_STRING));
624 g_free (sspec->default_value);
625 g_free (sspec->cset_first);
626 g_free (sspec->cset_nth);
627 sspec->default_value = NULL;
628 sspec->cset_first = NULL;
629 sspec->cset_nth = NULL;
631 parent_class->finalize (pspec);
635 param_string_set_default (GParamSpec *pspec,
638 value->data[0].v_pointer = g_strdup (G_PARAM_SPEC_STRING (pspec)->default_value);
642 param_string_validate (GParamSpec *pspec,
645 GParamSpecString *sspec = G_PARAM_SPEC_STRING (pspec);
646 gchar *string = value->data[0].v_pointer;
649 if (string && string[0])
653 if (sspec->cset_first && !strchr (sspec->cset_first, string[0]))
655 if (value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)
657 value->data[0].v_pointer = g_strdup (string);
658 string = value->data[0].v_pointer;
659 value->data[1].v_uint &= ~G_VALUE_NOCOPY_CONTENTS;
661 string[0] = sspec->substitutor;
665 for (s = string + 1; *s; s++)
666 if (!strchr (sspec->cset_nth, *s))
668 if (value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)
670 value->data[0].v_pointer = g_strdup (string);
671 s = (gchar*) value->data[0].v_pointer + (s - string);
672 string = value->data[0].v_pointer;
673 value->data[1].v_uint &= ~G_VALUE_NOCOPY_CONTENTS;
675 *s = sspec->substitutor;
679 if (sspec->null_fold_if_empty && string && string[0] == 0)
681 if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
682 g_free (value->data[0].v_pointer);
684 value->data[1].v_uint &= ~G_VALUE_NOCOPY_CONTENTS;
685 value->data[0].v_pointer = NULL;
687 string = value->data[0].v_pointer;
689 if (sspec->ensure_non_null && !string)
691 value->data[1].v_uint &= ~G_VALUE_NOCOPY_CONTENTS;
692 value->data[0].v_pointer = g_strdup ("");
694 string = value->data[0].v_pointer;
701 param_string_values_cmp (GParamSpec *pspec,
702 const GValue *value1,
703 const GValue *value2)
705 if (!value1->data[0].v_pointer)
706 return value2->data[0].v_pointer != NULL ? -1 : 0;
707 else if (!value2->data[0].v_pointer)
708 return value1->data[0].v_pointer != NULL;
710 return strcmp (value1->data[0].v_pointer, value2->data[0].v_pointer);
714 param_param_init (GParamSpec *pspec)
716 /* GParamSpecParam *spec = G_PARAM_SPEC_PARAM (pspec); */
720 param_param_set_default (GParamSpec *pspec,
723 value->data[0].v_pointer = NULL;
727 param_param_validate (GParamSpec *pspec,
730 /* GParamSpecParam *spec = G_PARAM_SPEC_PARAM (pspec); */
731 GParamSpec *param = value->data[0].v_pointer;
734 if (param && !g_value_type_compatible (G_PARAM_SPEC_TYPE (param), G_PARAM_SPEC_VALUE_TYPE (pspec)))
736 g_param_spec_unref (param);
737 value->data[0].v_pointer = NULL;
745 param_boxed_init (GParamSpec *pspec)
747 /* GParamSpecBoxed *bspec = G_PARAM_SPEC_BOXED (pspec); */
751 param_boxed_set_default (GParamSpec *pspec,
754 value->data[0].v_pointer = NULL;
758 param_boxed_validate (GParamSpec *pspec,
761 /* GParamSpecBoxed *bspec = G_PARAM_SPEC_BOXED (pspec); */
764 /* can't do a whole lot here since we haven't even G_BOXED_TYPE() */
770 param_boxed_values_cmp (GParamSpec *pspec,
771 const GValue *value1,
772 const GValue *value2)
774 guint8 *p1 = value1->data[0].v_pointer;
775 guint8 *p2 = value2->data[0].v_pointer;
777 /* not much to compare here, try to at least provide stable lesser/greater result */
779 return p1 < p2 ? -1 : p1 > p2;
783 param_pointer_init (GParamSpec *pspec)
785 /* GParamSpecPointer *spec = G_PARAM_SPEC_POINTER (pspec); */
789 param_pointer_set_default (GParamSpec *pspec,
792 value->data[0].v_pointer = NULL;
796 param_pointer_validate (GParamSpec *pspec,
799 /* GParamSpecPointer *spec = G_PARAM_SPEC_POINTER (pspec); */
806 param_pointer_values_cmp (GParamSpec *pspec,
807 const GValue *value1,
808 const GValue *value2)
810 guint8 *p1 = value1->data[0].v_pointer;
811 guint8 *p2 = value2->data[0].v_pointer;
813 /* not much to compare here, try to at least provide stable lesser/greater result */
815 return p1 < p2 ? -1 : p1 > p2;
819 param_value_array_init (GParamSpec *pspec)
821 GParamSpecValueArray *aspec = G_PARAM_SPEC_VALUE_ARRAY (pspec);
823 aspec->element_spec = NULL;
824 aspec->fixed_n_elements = 0; /* disable */
828 value_array_ensure_size (GValueArray *value_array,
829 guint fixed_n_elements)
833 if (fixed_n_elements)
835 while (value_array->n_values < fixed_n_elements)
837 g_value_array_append (value_array, NULL);
840 while (value_array->n_values > fixed_n_elements)
842 g_value_array_remove (value_array, value_array->n_values - 1);
850 param_value_array_finalize (GParamSpec *pspec)
852 GParamSpecValueArray *aspec = G_PARAM_SPEC_VALUE_ARRAY (pspec);
853 GParamSpecClass *parent_class = g_type_class_peek (g_type_parent (G_TYPE_PARAM_VALUE_ARRAY));
855 if (aspec->element_spec)
857 g_param_spec_unref (aspec->element_spec);
858 aspec->element_spec = NULL;
861 parent_class->finalize (pspec);
865 param_value_array_set_default (GParamSpec *pspec,
868 GParamSpecValueArray *aspec = G_PARAM_SPEC_VALUE_ARRAY (pspec);
870 if (!value->data[0].v_pointer && aspec->fixed_n_elements)
871 value->data[0].v_pointer = g_value_array_new (aspec->fixed_n_elements);
873 if (value->data[0].v_pointer)
875 /* g_value_reset (value); already done */
876 value_array_ensure_size (value->data[0].v_pointer, aspec->fixed_n_elements);
881 param_value_array_validate (GParamSpec *pspec,
884 GParamSpecValueArray *aspec = G_PARAM_SPEC_VALUE_ARRAY (pspec);
885 GValueArray *value_array = value->data[0].v_pointer;
888 if (!value->data[0].v_pointer && aspec->fixed_n_elements)
889 value->data[0].v_pointer = g_value_array_new (aspec->fixed_n_elements);
891 if (value->data[0].v_pointer)
893 /* ensure array size validity */
894 changed += value_array_ensure_size (value_array, aspec->fixed_n_elements);
896 /* ensure array values validity against a present element spec */
897 if (aspec->element_spec)
899 GParamSpec *element_spec = aspec->element_spec;
902 for (i = 0; i < value_array->n_values; i++)
904 GValue *element = value_array->values + i;
906 /* need to fixup value type, or ensure that the array value is initialized at all */
907 if (!g_value_type_compatible (G_VALUE_TYPE (element), G_PARAM_SPEC_VALUE_TYPE (element_spec)))
909 if (G_VALUE_TYPE (element) != 0)
910 g_value_unset (element);
911 g_value_init (element, G_PARAM_SPEC_VALUE_TYPE (element_spec));
912 g_param_value_set_default (element_spec, element);
915 /* validate array value against element_spec */
916 changed += g_param_value_validate (element_spec, element);
925 param_value_array_values_cmp (GParamSpec *pspec,
926 const GValue *value1,
927 const GValue *value2)
929 GParamSpecValueArray *aspec = G_PARAM_SPEC_VALUE_ARRAY (pspec);
930 GValueArray *value_array1 = value1->data[0].v_pointer;
931 GValueArray *value_array2 = value2->data[0].v_pointer;
933 if (!value_array1 || !value_array2)
934 return value_array2 ? -1 : value_array1 != value_array2;
936 if (value_array1->n_values != value_array2->n_values)
937 return value_array1->n_values < value_array2->n_values ? -1 : 1;
938 else if (!aspec->element_spec)
940 /* we need an element specification for comparisons, so there's not much
941 * to compare here, try to at least provide stable lesser/greater result
943 return value_array1->n_values < value_array2->n_values ? -1 : value_array1->n_values > value_array2->n_values;
945 else /* value_array1->n_values == value_array2->n_values */
949 for (i = 0; i < value_array1->n_values; i++)
951 GValue *element1 = value_array1->values + i;
952 GValue *element2 = value_array2->values + i;
955 /* need corresponding element types, provide stable result otherwise */
956 if (G_VALUE_TYPE (element1) != G_VALUE_TYPE (element2))
957 return G_VALUE_TYPE (element1) < G_VALUE_TYPE (element2) ? -1 : 1;
958 cmp = g_param_values_cmp (aspec->element_spec, element1, element2);
967 param_object_init (GParamSpec *pspec)
969 /* GParamSpecObject *ospec = G_PARAM_SPEC_OBJECT (pspec); */
973 param_object_set_default (GParamSpec *pspec,
976 value->data[0].v_pointer = NULL;
980 param_object_validate (GParamSpec *pspec,
983 GParamSpecObject *ospec = G_PARAM_SPEC_OBJECT (pspec);
984 GObject *object = value->data[0].v_pointer;
987 if (object && !g_value_type_compatible (G_OBJECT_TYPE (object), G_PARAM_SPEC_VALUE_TYPE (ospec)))
989 g_object_unref (object);
990 value->data[0].v_pointer = NULL;
998 param_object_values_cmp (GParamSpec *pspec,
999 const GValue *value1,
1000 const GValue *value2)
1002 guint8 *p1 = value1->data[0].v_pointer;
1003 guint8 *p2 = value2->data[0].v_pointer;
1005 /* not much to compare here, try to at least provide stable lesser/greater result */
1007 return p1 < p2 ? -1 : p1 > p2;
1011 param_override_init (GParamSpec *pspec)
1013 /* GParamSpecOverride *ospec = G_PARAM_SPEC_OVERRIDE (pspec); */
1017 param_override_finalize (GParamSpec *pspec)
1019 GParamSpecOverride *ospec = G_PARAM_SPEC_OVERRIDE (pspec);
1020 GParamSpecClass *parent_class = g_type_class_peek (g_type_parent (G_TYPE_PARAM_OVERRIDE));
1022 if (ospec->overridden)
1024 g_param_spec_unref (ospec->overridden);
1025 ospec->overridden = NULL;
1028 parent_class->finalize (pspec);
1032 param_override_set_default (GParamSpec *pspec,
1035 GParamSpecOverride *ospec = G_PARAM_SPEC_OVERRIDE (pspec);
1037 g_param_value_set_default (ospec->overridden, value);
1041 param_override_validate (GParamSpec *pspec,
1044 GParamSpecOverride *ospec = G_PARAM_SPEC_OVERRIDE (pspec);
1046 return g_param_value_validate (ospec->overridden, value);
1050 param_override_values_cmp (GParamSpec *pspec,
1051 const GValue *value1,
1052 const GValue *value2)
1054 GParamSpecOverride *ospec = G_PARAM_SPEC_OVERRIDE (pspec);
1056 return g_param_values_cmp (ospec->overridden, value1, value2);
1060 param_gtype_init (GParamSpec *pspec)
1065 param_gtype_set_default (GParamSpec *pspec,
1068 GParamSpecGType *tspec = G_PARAM_SPEC_GTYPE (pspec);
1070 value->data[0].v_pointer = GSIZE_TO_POINTER (tspec->is_a_type);
1074 param_gtype_validate (GParamSpec *pspec,
1077 GParamSpecGType *tspec = G_PARAM_SPEC_GTYPE (pspec);
1078 GType gtype = GPOINTER_TO_SIZE (value->data[0].v_pointer);
1081 if (tspec->is_a_type != G_TYPE_NONE && !g_type_is_a (gtype, tspec->is_a_type))
1083 value->data[0].v_pointer = GSIZE_TO_POINTER (tspec->is_a_type);
1091 param_gtype_values_cmp (GParamSpec *pspec,
1092 const GValue *value1,
1093 const GValue *value2)
1095 GType p1 = GPOINTER_TO_SIZE (value1->data[0].v_pointer);
1096 GType p2 = GPOINTER_TO_SIZE (value2->data[0].v_pointer);
1098 /* not much to compare here, try to at least provide stable lesser/greater result */
1100 return p1 < p2 ? -1 : p1 > p2;
1104 param_variant_init (GParamSpec *pspec)
1106 GParamSpecVariant *vspec = G_PARAM_SPEC_VARIANT (pspec);
1109 vspec->default_value = NULL;
1113 param_variant_finalize (GParamSpec *pspec)
1115 GParamSpecVariant *vspec = G_PARAM_SPEC_VARIANT (pspec);
1116 GParamSpecClass *parent_class = g_type_class_peek (g_type_parent (G_TYPE_PARAM_VARIANT));
1118 if (vspec->default_value)
1119 g_variant_unref (vspec->default_value);
1120 g_variant_type_free (vspec->type);
1122 parent_class->finalize (pspec);
1126 param_variant_set_default (GParamSpec *pspec,
1129 value->data[0].v_pointer = G_PARAM_SPEC_VARIANT (pspec)->default_value;
1130 value->data[1].v_uint |= G_VALUE_NOCOPY_CONTENTS;
1134 param_variant_validate (GParamSpec *pspec,
1137 GParamSpecVariant *vspec = G_PARAM_SPEC_VARIANT (pspec);
1138 GVariant *variant = value->data[0].v_pointer;
1140 if ((variant == NULL && vspec->default_value != NULL) ||
1141 (variant != NULL && !g_variant_is_of_type (variant, vspec->type)))
1143 g_param_value_set_default (pspec, value);
1150 /* g_variant_compare() can only be used with scalar types. */
1152 variant_is_incomparable (GVariant *v)
1154 GVariantClass v_class = g_variant_classify (v);
1156 return (v_class == G_VARIANT_CLASS_HANDLE ||
1157 v_class == G_VARIANT_CLASS_VARIANT ||
1158 v_class == G_VARIANT_CLASS_MAYBE||
1159 v_class == G_VARIANT_CLASS_ARRAY ||
1160 v_class == G_VARIANT_CLASS_TUPLE ||
1161 v_class == G_VARIANT_CLASS_DICT_ENTRY);
1165 param_variant_values_cmp (GParamSpec *pspec,
1166 const GValue *value1,
1167 const GValue *value2)
1169 GVariant *v1 = value1->data[0].v_pointer;
1170 GVariant *v2 = value2->data[0].v_pointer;
1172 if (v1 == NULL && v2 == NULL)
1174 else if (v1 == NULL && v2 != NULL)
1176 else if (v1 != NULL && v2 == NULL)
1179 if (!g_variant_type_equal (g_variant_get_type (v1), g_variant_get_type (v2)) ||
1180 variant_is_incomparable (v1) ||
1181 variant_is_incomparable (v2))
1182 return g_variant_equal (v1, v2) ? 0 : (v1 < v2 ? -1 : 1);
1184 return g_variant_compare (v1, v2);
1187 /* --- type initialization --- */
1188 GType *g_param_spec_types = NULL;
1191 _g_param_spec_types_init (void)
1193 const guint n_types = 23;
1194 GType type, *spec_types, *spec_types_bound;
1196 g_param_spec_types = g_new0 (GType, n_types);
1197 spec_types = g_param_spec_types;
1198 spec_types_bound = g_param_spec_types + n_types;
1200 /* G_TYPE_PARAM_CHAR
1203 const GParamSpecTypeInfo pspec_info = {
1204 sizeof (GParamSpecChar), /* instance_size */
1205 16, /* n_preallocs */
1206 param_char_init, /* instance_init */
1207 G_TYPE_CHAR, /* value_type */
1208 NULL, /* finalize */
1209 param_char_set_default, /* value_set_default */
1210 param_char_validate, /* value_validate */
1211 param_int_values_cmp, /* values_cmp */
1213 type = g_param_type_register_static (g_intern_static_string ("GParamChar"), &pspec_info);
1214 *spec_types++ = type;
1215 g_assert (type == G_TYPE_PARAM_CHAR);
1218 /* G_TYPE_PARAM_UCHAR
1221 const GParamSpecTypeInfo pspec_info = {
1222 sizeof (GParamSpecUChar), /* instance_size */
1223 16, /* n_preallocs */
1224 param_uchar_init, /* instance_init */
1225 G_TYPE_UCHAR, /* value_type */
1226 NULL, /* finalize */
1227 param_uchar_set_default, /* value_set_default */
1228 param_uchar_validate, /* value_validate */
1229 param_uint_values_cmp, /* values_cmp */
1231 type = g_param_type_register_static (g_intern_static_string ("GParamUChar"), &pspec_info);
1232 *spec_types++ = type;
1233 g_assert (type == G_TYPE_PARAM_UCHAR);
1236 /* G_TYPE_PARAM_BOOLEAN
1239 const GParamSpecTypeInfo pspec_info = {
1240 sizeof (GParamSpecBoolean), /* instance_size */
1241 16, /* n_preallocs */
1242 NULL, /* instance_init */
1243 G_TYPE_BOOLEAN, /* value_type */
1244 NULL, /* finalize */
1245 param_boolean_set_default, /* value_set_default */
1246 param_boolean_validate, /* value_validate */
1247 param_int_values_cmp, /* values_cmp */
1249 type = g_param_type_register_static (g_intern_static_string ("GParamBoolean"), &pspec_info);
1250 *spec_types++ = type;
1251 g_assert (type == G_TYPE_PARAM_BOOLEAN);
1257 const GParamSpecTypeInfo pspec_info = {
1258 sizeof (GParamSpecInt), /* instance_size */
1259 16, /* n_preallocs */
1260 param_int_init, /* instance_init */
1261 G_TYPE_INT, /* value_type */
1262 NULL, /* finalize */
1263 param_int_set_default, /* value_set_default */
1264 param_int_validate, /* value_validate */
1265 param_int_values_cmp, /* values_cmp */
1267 type = g_param_type_register_static (g_intern_static_string ("GParamInt"), &pspec_info);
1268 *spec_types++ = type;
1269 g_assert (type == G_TYPE_PARAM_INT);
1272 /* G_TYPE_PARAM_UINT
1275 const GParamSpecTypeInfo pspec_info = {
1276 sizeof (GParamSpecUInt), /* instance_size */
1277 16, /* n_preallocs */
1278 param_uint_init, /* instance_init */
1279 G_TYPE_UINT, /* value_type */
1280 NULL, /* finalize */
1281 param_uint_set_default, /* value_set_default */
1282 param_uint_validate, /* value_validate */
1283 param_uint_values_cmp, /* values_cmp */
1285 type = g_param_type_register_static (g_intern_static_string ("GParamUInt"), &pspec_info);
1286 *spec_types++ = type;
1287 g_assert (type == G_TYPE_PARAM_UINT);
1290 /* G_TYPE_PARAM_LONG
1293 const GParamSpecTypeInfo pspec_info = {
1294 sizeof (GParamSpecLong), /* instance_size */
1295 16, /* n_preallocs */
1296 param_long_init, /* instance_init */
1297 G_TYPE_LONG, /* value_type */
1298 NULL, /* finalize */
1299 param_long_set_default, /* value_set_default */
1300 param_long_validate, /* value_validate */
1301 param_long_values_cmp, /* values_cmp */
1303 type = g_param_type_register_static (g_intern_static_string ("GParamLong"), &pspec_info);
1304 *spec_types++ = type;
1305 g_assert (type == G_TYPE_PARAM_LONG);
1308 /* G_TYPE_PARAM_ULONG
1311 const GParamSpecTypeInfo pspec_info = {
1312 sizeof (GParamSpecULong), /* instance_size */
1313 16, /* n_preallocs */
1314 param_ulong_init, /* instance_init */
1315 G_TYPE_ULONG, /* value_type */
1316 NULL, /* finalize */
1317 param_ulong_set_default, /* value_set_default */
1318 param_ulong_validate, /* value_validate */
1319 param_ulong_values_cmp, /* values_cmp */
1321 type = g_param_type_register_static (g_intern_static_string ("GParamULong"), &pspec_info);
1322 *spec_types++ = type;
1323 g_assert (type == G_TYPE_PARAM_ULONG);
1326 /* G_TYPE_PARAM_INT64
1329 const GParamSpecTypeInfo pspec_info = {
1330 sizeof (GParamSpecInt64), /* instance_size */
1331 16, /* n_preallocs */
1332 param_int64_init, /* instance_init */
1333 G_TYPE_INT64, /* value_type */
1334 NULL, /* finalize */
1335 param_int64_set_default, /* value_set_default */
1336 param_int64_validate, /* value_validate */
1337 param_int64_values_cmp, /* values_cmp */
1339 type = g_param_type_register_static (g_intern_static_string ("GParamInt64"), &pspec_info);
1340 *spec_types++ = type;
1341 g_assert (type == G_TYPE_PARAM_INT64);
1344 /* G_TYPE_PARAM_UINT64
1347 const GParamSpecTypeInfo pspec_info = {
1348 sizeof (GParamSpecUInt64), /* instance_size */
1349 16, /* n_preallocs */
1350 param_uint64_init, /* instance_init */
1351 G_TYPE_UINT64, /* value_type */
1352 NULL, /* finalize */
1353 param_uint64_set_default, /* value_set_default */
1354 param_uint64_validate, /* value_validate */
1355 param_uint64_values_cmp, /* values_cmp */
1357 type = g_param_type_register_static (g_intern_static_string ("GParamUInt64"), &pspec_info);
1358 *spec_types++ = type;
1359 g_assert (type == G_TYPE_PARAM_UINT64);
1362 /* G_TYPE_PARAM_UNICHAR
1365 const GParamSpecTypeInfo pspec_info = {
1366 sizeof (GParamSpecUnichar), /* instance_size */
1367 16, /* n_preallocs */
1368 param_unichar_init, /* instance_init */
1369 G_TYPE_UINT, /* value_type */
1370 NULL, /* finalize */
1371 param_unichar_set_default, /* value_set_default */
1372 param_unichar_validate, /* value_validate */
1373 param_unichar_values_cmp, /* values_cmp */
1375 type = g_param_type_register_static (g_intern_static_string ("GParamUnichar"), &pspec_info);
1376 *spec_types++ = type;
1377 g_assert (type == G_TYPE_PARAM_UNICHAR);
1380 /* G_TYPE_PARAM_ENUM
1383 const GParamSpecTypeInfo pspec_info = {
1384 sizeof (GParamSpecEnum), /* instance_size */
1385 16, /* n_preallocs */
1386 param_enum_init, /* instance_init */
1387 G_TYPE_ENUM, /* value_type */
1388 param_enum_finalize, /* finalize */
1389 param_enum_set_default, /* value_set_default */
1390 param_enum_validate, /* value_validate */
1391 param_long_values_cmp, /* values_cmp */
1393 type = g_param_type_register_static (g_intern_static_string ("GParamEnum"), &pspec_info);
1394 *spec_types++ = type;
1395 g_assert (type == G_TYPE_PARAM_ENUM);
1398 /* G_TYPE_PARAM_FLAGS
1401 const GParamSpecTypeInfo pspec_info = {
1402 sizeof (GParamSpecFlags), /* instance_size */
1403 16, /* n_preallocs */
1404 param_flags_init, /* instance_init */
1405 G_TYPE_FLAGS, /* value_type */
1406 param_flags_finalize, /* finalize */
1407 param_flags_set_default, /* value_set_default */
1408 param_flags_validate, /* value_validate */
1409 param_ulong_values_cmp, /* values_cmp */
1411 type = g_param_type_register_static (g_intern_static_string ("GParamFlags"), &pspec_info);
1412 *spec_types++ = type;
1413 g_assert (type == G_TYPE_PARAM_FLAGS);
1416 /* G_TYPE_PARAM_FLOAT
1419 const GParamSpecTypeInfo pspec_info = {
1420 sizeof (GParamSpecFloat), /* instance_size */
1421 16, /* n_preallocs */
1422 param_float_init, /* instance_init */
1423 G_TYPE_FLOAT, /* value_type */
1424 NULL, /* finalize */
1425 param_float_set_default, /* value_set_default */
1426 param_float_validate, /* value_validate */
1427 param_float_values_cmp, /* values_cmp */
1429 type = g_param_type_register_static (g_intern_static_string ("GParamFloat"), &pspec_info);
1430 *spec_types++ = type;
1431 g_assert (type == G_TYPE_PARAM_FLOAT);
1434 /* G_TYPE_PARAM_DOUBLE
1437 const GParamSpecTypeInfo pspec_info = {
1438 sizeof (GParamSpecDouble), /* instance_size */
1439 16, /* n_preallocs */
1440 param_double_init, /* instance_init */
1441 G_TYPE_DOUBLE, /* value_type */
1442 NULL, /* finalize */
1443 param_double_set_default, /* value_set_default */
1444 param_double_validate, /* value_validate */
1445 param_double_values_cmp, /* values_cmp */
1447 type = g_param_type_register_static (g_intern_static_string ("GParamDouble"), &pspec_info);
1448 *spec_types++ = type;
1449 g_assert (type == G_TYPE_PARAM_DOUBLE);
1452 /* G_TYPE_PARAM_STRING
1455 const GParamSpecTypeInfo pspec_info = {
1456 sizeof (GParamSpecString), /* instance_size */
1457 16, /* n_preallocs */
1458 param_string_init, /* instance_init */
1459 G_TYPE_STRING, /* value_type */
1460 param_string_finalize, /* finalize */
1461 param_string_set_default, /* value_set_default */
1462 param_string_validate, /* value_validate */
1463 param_string_values_cmp, /* values_cmp */
1465 type = g_param_type_register_static (g_intern_static_string ("GParamString"), &pspec_info);
1466 *spec_types++ = type;
1467 g_assert (type == G_TYPE_PARAM_STRING);
1470 /* G_TYPE_PARAM_PARAM
1473 const GParamSpecTypeInfo pspec_info = {
1474 sizeof (GParamSpecParam), /* instance_size */
1475 16, /* n_preallocs */
1476 param_param_init, /* instance_init */
1477 G_TYPE_PARAM, /* value_type */
1478 NULL, /* finalize */
1479 param_param_set_default, /* value_set_default */
1480 param_param_validate, /* value_validate */
1481 param_pointer_values_cmp, /* values_cmp */
1483 type = g_param_type_register_static (g_intern_static_string ("GParamParam"), &pspec_info);
1484 *spec_types++ = type;
1485 g_assert (type == G_TYPE_PARAM_PARAM);
1488 /* G_TYPE_PARAM_BOXED
1491 const GParamSpecTypeInfo pspec_info = {
1492 sizeof (GParamSpecBoxed), /* instance_size */
1493 4, /* n_preallocs */
1494 param_boxed_init, /* instance_init */
1495 G_TYPE_BOXED, /* value_type */
1496 NULL, /* finalize */
1497 param_boxed_set_default, /* value_set_default */
1498 param_boxed_validate, /* value_validate */
1499 param_boxed_values_cmp, /* values_cmp */
1501 type = g_param_type_register_static (g_intern_static_string ("GParamBoxed"), &pspec_info);
1502 *spec_types++ = type;
1503 g_assert (type == G_TYPE_PARAM_BOXED);
1506 /* G_TYPE_PARAM_POINTER
1509 const GParamSpecTypeInfo pspec_info = {
1510 sizeof (GParamSpecPointer), /* instance_size */
1511 0, /* n_preallocs */
1512 param_pointer_init, /* instance_init */
1513 G_TYPE_POINTER, /* value_type */
1514 NULL, /* finalize */
1515 param_pointer_set_default, /* value_set_default */
1516 param_pointer_validate, /* value_validate */
1517 param_pointer_values_cmp, /* values_cmp */
1519 type = g_param_type_register_static (g_intern_static_string ("GParamPointer"), &pspec_info);
1520 *spec_types++ = type;
1521 g_assert (type == G_TYPE_PARAM_POINTER);
1524 /* G_TYPE_PARAM_VALUE_ARRAY
1527 /* const */ GParamSpecTypeInfo pspec_info = {
1528 sizeof (GParamSpecValueArray), /* instance_size */
1529 0, /* n_preallocs */
1530 param_value_array_init, /* instance_init */
1531 0xdeadbeef, /* value_type, assigned further down */
1532 param_value_array_finalize, /* finalize */
1533 param_value_array_set_default, /* value_set_default */
1534 param_value_array_validate, /* value_validate */
1535 param_value_array_values_cmp, /* values_cmp */
1537 pspec_info.value_type = G_TYPE_VALUE_ARRAY;
1538 type = g_param_type_register_static (g_intern_static_string ("GParamValueArray"), &pspec_info);
1539 *spec_types++ = type;
1540 g_assert (type == G_TYPE_PARAM_VALUE_ARRAY);
1543 /* G_TYPE_PARAM_OBJECT
1546 const GParamSpecTypeInfo pspec_info = {
1547 sizeof (GParamSpecObject), /* instance_size */
1548 16, /* n_preallocs */
1549 param_object_init, /* instance_init */
1550 G_TYPE_OBJECT, /* value_type */
1551 NULL, /* finalize */
1552 param_object_set_default, /* value_set_default */
1553 param_object_validate, /* value_validate */
1554 param_object_values_cmp, /* values_cmp */
1556 type = g_param_type_register_static (g_intern_static_string ("GParamObject"), &pspec_info);
1557 *spec_types++ = type;
1558 g_assert (type == G_TYPE_PARAM_OBJECT);
1561 /* G_TYPE_PARAM_OVERRIDE
1564 const GParamSpecTypeInfo pspec_info = {
1565 sizeof (GParamSpecOverride), /* instance_size */
1566 16, /* n_preallocs */
1567 param_override_init, /* instance_init */
1568 G_TYPE_NONE, /* value_type */
1569 param_override_finalize, /* finalize */
1570 param_override_set_default, /* value_set_default */
1571 param_override_validate, /* value_validate */
1572 param_override_values_cmp, /* values_cmp */
1574 type = g_param_type_register_static (g_intern_static_string ("GParamOverride"), &pspec_info);
1575 *spec_types++ = type;
1576 g_assert (type == G_TYPE_PARAM_OVERRIDE);
1579 /* G_TYPE_PARAM_GTYPE
1582 GParamSpecTypeInfo pspec_info = {
1583 sizeof (GParamSpecGType), /* instance_size */
1584 0, /* n_preallocs */
1585 param_gtype_init, /* instance_init */
1586 0xdeadbeef, /* value_type, assigned further down */
1587 NULL, /* finalize */
1588 param_gtype_set_default, /* value_set_default */
1589 param_gtype_validate, /* value_validate */
1590 param_gtype_values_cmp, /* values_cmp */
1592 pspec_info.value_type = G_TYPE_GTYPE;
1593 type = g_param_type_register_static (g_intern_static_string ("GParamGType"), &pspec_info);
1594 *spec_types++ = type;
1595 g_assert (type == G_TYPE_PARAM_GTYPE);
1598 /* G_TYPE_PARAM_VARIANT
1601 const GParamSpecTypeInfo pspec_info = {
1602 sizeof (GParamSpecVariant), /* instance_size */
1603 0, /* n_preallocs */
1604 param_variant_init, /* instance_init */
1605 G_TYPE_VARIANT, /* value_type */
1606 param_variant_finalize, /* finalize */
1607 param_variant_set_default, /* value_set_default */
1608 param_variant_validate, /* value_validate */
1609 param_variant_values_cmp, /* values_cmp */
1611 type = g_param_type_register_static (g_intern_static_string ("GParamVariant"), &pspec_info);
1612 *spec_types++ = type;
1613 g_assert (type == G_TYPE_PARAM_VARIANT);
1616 g_assert (spec_types == spec_types_bound);
1619 /* --- GParamSpec initialization --- */
1622 * g_param_spec_char:
1623 * @name: canonical name of the property specified
1624 * @nick: nick name for the property specified
1625 * @blurb: description of the property specified
1626 * @minimum: minimum value for the property specified
1627 * @maximum: maximum value for the property specified
1628 * @default_value: default value for the property specified
1629 * @flags: flags for the property specified
1631 * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.
1633 * Returns: (transfer full): a newly created parameter specification
1636 g_param_spec_char (const gchar *name,
1641 gint8 default_value,
1644 GParamSpecChar *cspec;
1646 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1648 cspec = g_param_spec_internal (G_TYPE_PARAM_CHAR,
1656 cspec->minimum = minimum;
1657 cspec->maximum = maximum;
1658 cspec->default_value = default_value;
1660 return G_PARAM_SPEC (cspec);
1664 * g_param_spec_uchar:
1665 * @name: canonical name of the property specified
1666 * @nick: nick name for the property specified
1667 * @blurb: description of the property specified
1668 * @minimum: minimum value for the property specified
1669 * @maximum: maximum value for the property specified
1670 * @default_value: default value for the property specified
1671 * @flags: flags for the property specified
1673 * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.
1675 * Returns: (transfer full): a newly created parameter specification
1678 g_param_spec_uchar (const gchar *name,
1683 guint8 default_value,
1686 GParamSpecUChar *uspec;
1688 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1690 uspec = g_param_spec_internal (G_TYPE_PARAM_UCHAR,
1698 uspec->minimum = minimum;
1699 uspec->maximum = maximum;
1700 uspec->default_value = default_value;
1702 return G_PARAM_SPEC (uspec);
1706 * g_param_spec_boolean:
1707 * @name: canonical name of the property specified
1708 * @nick: nick name for the property specified
1709 * @blurb: description of the property specified
1710 * @default_value: default value for the property specified
1711 * @flags: flags for the property specified
1713 * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
1714 * property. In many cases, it may be more appropriate to use an enum with
1715 * g_param_spec_enum(), both to improve code clarity by using explicitly named
1716 * values, and to allow for more values to be added in future without breaking
1719 * See g_param_spec_internal() for details on property names.
1721 * Returns: (transfer full): a newly created parameter specification
1724 g_param_spec_boolean (const gchar *name,
1727 gboolean default_value,
1730 GParamSpecBoolean *bspec;
1732 g_return_val_if_fail (default_value == TRUE || default_value == FALSE, NULL);
1734 bspec = g_param_spec_internal (G_TYPE_PARAM_BOOLEAN,
1742 bspec->default_value = default_value;
1744 return G_PARAM_SPEC (bspec);
1749 * @name: canonical name of the property specified
1750 * @nick: nick name for the property specified
1751 * @blurb: description of the property specified
1752 * @minimum: minimum value for the property specified
1753 * @maximum: maximum value for the property specified
1754 * @default_value: default value for the property specified
1755 * @flags: flags for the property specified
1757 * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
1759 * See g_param_spec_internal() for details on property names.
1761 * Returns: (transfer full): a newly created parameter specification
1764 g_param_spec_int (const gchar *name,
1772 GParamSpecInt *ispec;
1774 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1776 ispec = g_param_spec_internal (G_TYPE_PARAM_INT,
1784 ispec->minimum = minimum;
1785 ispec->maximum = maximum;
1786 ispec->default_value = default_value;
1788 return G_PARAM_SPEC (ispec);
1792 * g_param_spec_uint:
1793 * @name: canonical name of the property specified
1794 * @nick: nick name for the property specified
1795 * @blurb: description of the property specified
1796 * @minimum: minimum value for the property specified
1797 * @maximum: maximum value for the property specified
1798 * @default_value: default value for the property specified
1799 * @flags: flags for the property specified
1801 * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
1803 * See g_param_spec_internal() for details on property names.
1805 * Returns: (transfer full): a newly created parameter specification
1808 g_param_spec_uint (const gchar *name,
1813 guint default_value,
1816 GParamSpecUInt *uspec;
1818 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1820 uspec = g_param_spec_internal (G_TYPE_PARAM_UINT,
1828 uspec->minimum = minimum;
1829 uspec->maximum = maximum;
1830 uspec->default_value = default_value;
1832 return G_PARAM_SPEC (uspec);
1836 * g_param_spec_long:
1837 * @name: canonical name of the property specified
1838 * @nick: nick name for the property specified
1839 * @blurb: description of the property specified
1840 * @minimum: minimum value for the property specified
1841 * @maximum: maximum value for the property specified
1842 * @default_value: default value for the property specified
1843 * @flags: flags for the property specified
1845 * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
1847 * See g_param_spec_internal() for details on property names.
1849 * Returns: (transfer full): a newly created parameter specification
1852 g_param_spec_long (const gchar *name,
1857 glong default_value,
1860 GParamSpecLong *lspec;
1862 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1864 lspec = g_param_spec_internal (G_TYPE_PARAM_LONG,
1872 lspec->minimum = minimum;
1873 lspec->maximum = maximum;
1874 lspec->default_value = default_value;
1876 return G_PARAM_SPEC (lspec);
1880 * g_param_spec_ulong:
1881 * @name: canonical name of the property specified
1882 * @nick: nick name for the property specified
1883 * @blurb: description of the property specified
1884 * @minimum: minimum value for the property specified
1885 * @maximum: maximum value for the property specified
1886 * @default_value: default value for the property specified
1887 * @flags: flags for the property specified
1889 * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG
1892 * See g_param_spec_internal() for details on property names.
1894 * Returns: (transfer full): a newly created parameter specification
1897 g_param_spec_ulong (const gchar *name,
1902 gulong default_value,
1905 GParamSpecULong *uspec;
1907 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1909 uspec = g_param_spec_internal (G_TYPE_PARAM_ULONG,
1917 uspec->minimum = minimum;
1918 uspec->maximum = maximum;
1919 uspec->default_value = default_value;
1921 return G_PARAM_SPEC (uspec);
1925 * g_param_spec_int64:
1926 * @name: canonical name of the property specified
1927 * @nick: nick name for the property specified
1928 * @blurb: description of the property specified
1929 * @minimum: minimum value for the property specified
1930 * @maximum: maximum value for the property specified
1931 * @default_value: default value for the property specified
1932 * @flags: flags for the property specified
1934 * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
1936 * See g_param_spec_internal() for details on property names.
1938 * Returns: (transfer full): a newly created parameter specification
1941 g_param_spec_int64 (const gchar *name,
1946 gint64 default_value,
1949 GParamSpecInt64 *lspec;
1951 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1953 lspec = g_param_spec_internal (G_TYPE_PARAM_INT64,
1961 lspec->minimum = minimum;
1962 lspec->maximum = maximum;
1963 lspec->default_value = default_value;
1965 return G_PARAM_SPEC (lspec);
1969 * g_param_spec_uint64:
1970 * @name: canonical name of the property specified
1971 * @nick: nick name for the property specified
1972 * @blurb: description of the property specified
1973 * @minimum: minimum value for the property specified
1974 * @maximum: maximum value for the property specified
1975 * @default_value: default value for the property specified
1976 * @flags: flags for the property specified
1978 * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64
1981 * See g_param_spec_internal() for details on property names.
1983 * Returns: (transfer full): a newly created parameter specification
1986 g_param_spec_uint64 (const gchar *name,
1991 guint64 default_value,
1994 GParamSpecUInt64 *uspec;
1996 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
1998 uspec = g_param_spec_internal (G_TYPE_PARAM_UINT64,
2006 uspec->minimum = minimum;
2007 uspec->maximum = maximum;
2008 uspec->default_value = default_value;
2010 return G_PARAM_SPEC (uspec);
2014 * g_param_spec_unichar:
2015 * @name: canonical name of the property specified
2016 * @nick: nick name for the property specified
2017 * @blurb: description of the property specified
2018 * @default_value: default value for the property specified
2019 * @flags: flags for the property specified
2021 * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT
2022 * property. #GValue structures for this property can be accessed with
2023 * g_value_set_uint() and g_value_get_uint().
2025 * See g_param_spec_internal() for details on property names.
2027 * Returns: (transfer full): a newly created parameter specification
2030 g_param_spec_unichar (const gchar *name,
2033 gunichar default_value,
2036 GParamSpecUnichar *uspec;
2038 uspec = g_param_spec_internal (G_TYPE_PARAM_UNICHAR,
2046 uspec->default_value = default_value;
2048 return G_PARAM_SPEC (uspec);
2052 * g_param_spec_enum:
2053 * @name: canonical name of the property specified
2054 * @nick: nick name for the property specified
2055 * @blurb: description of the property specified
2056 * @enum_type: a #GType derived from %G_TYPE_ENUM
2057 * @default_value: default value for the property specified
2058 * @flags: flags for the property specified
2060 * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM
2063 * See g_param_spec_internal() for details on property names.
2065 * Returns: (transfer full): a newly created parameter specification
2068 g_param_spec_enum (const gchar *name,
2075 GParamSpecEnum *espec;
2076 GEnumClass *enum_class;
2078 g_return_val_if_fail (G_TYPE_IS_ENUM (enum_type), NULL);
2080 enum_class = g_type_class_ref (enum_type);
2082 g_return_val_if_fail (g_enum_get_value (enum_class, default_value) != NULL, NULL);
2084 espec = g_param_spec_internal (G_TYPE_PARAM_ENUM,
2092 espec->enum_class = enum_class;
2093 espec->default_value = default_value;
2094 G_PARAM_SPEC (espec)->value_type = enum_type;
2096 return G_PARAM_SPEC (espec);
2100 * g_param_spec_flags:
2101 * @name: canonical name of the property specified
2102 * @nick: nick name for the property specified
2103 * @blurb: description of the property specified
2104 * @flags_type: a #GType derived from %G_TYPE_FLAGS
2105 * @default_value: default value for the property specified
2106 * @flags: flags for the property specified
2108 * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS
2111 * See g_param_spec_internal() for details on property names.
2113 * Returns: (transfer full): a newly created parameter specification
2116 g_param_spec_flags (const gchar *name,
2120 guint default_value,
2123 GParamSpecFlags *fspec;
2124 GFlagsClass *flags_class;
2126 g_return_val_if_fail (G_TYPE_IS_FLAGS (flags_type), NULL);
2128 flags_class = g_type_class_ref (flags_type);
2130 g_return_val_if_fail ((default_value & flags_class->mask) == default_value, NULL);
2132 fspec = g_param_spec_internal (G_TYPE_PARAM_FLAGS,
2140 fspec->flags_class = flags_class;
2141 fspec->default_value = default_value;
2142 G_PARAM_SPEC (fspec)->value_type = flags_type;
2144 return G_PARAM_SPEC (fspec);
2148 * g_param_spec_float:
2149 * @name: canonical name of the property specified
2150 * @nick: nick name for the property specified
2151 * @blurb: description of the property specified
2152 * @minimum: minimum value for the property specified
2153 * @maximum: maximum value for the property specified
2154 * @default_value: default value for the property specified
2155 * @flags: flags for the property specified
2157 * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
2159 * See g_param_spec_internal() for details on property names.
2161 * Returns: (transfer full): a newly created parameter specification
2164 g_param_spec_float (const gchar *name,
2169 gfloat default_value,
2172 GParamSpecFloat *fspec;
2174 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
2176 fspec = g_param_spec_internal (G_TYPE_PARAM_FLOAT,
2184 fspec->minimum = minimum;
2185 fspec->maximum = maximum;
2186 fspec->default_value = default_value;
2188 return G_PARAM_SPEC (fspec);
2192 * g_param_spec_double:
2193 * @name: canonical name of the property specified
2194 * @nick: nick name for the property specified
2195 * @blurb: description of the property specified
2196 * @minimum: minimum value for the property specified
2197 * @maximum: maximum value for the property specified
2198 * @default_value: default value for the property specified
2199 * @flags: flags for the property specified
2201 * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE
2204 * See g_param_spec_internal() for details on property names.
2206 * Returns: (transfer full): a newly created parameter specification
2209 g_param_spec_double (const gchar *name,
2214 gdouble default_value,
2217 GParamSpecDouble *dspec;
2219 g_return_val_if_fail (default_value >= minimum && default_value <= maximum, NULL);
2221 dspec = g_param_spec_internal (G_TYPE_PARAM_DOUBLE,
2229 dspec->minimum = minimum;
2230 dspec->maximum = maximum;
2231 dspec->default_value = default_value;
2233 return G_PARAM_SPEC (dspec);
2237 * g_param_spec_string:
2238 * @name: canonical name of the property specified
2239 * @nick: nick name for the property specified
2240 * @blurb: description of the property specified
2241 * @default_value: (nullable): default value for the property specified
2242 * @flags: flags for the property specified
2244 * Creates a new #GParamSpecString instance.
2246 * See g_param_spec_internal() for details on property names.
2248 * Returns: (transfer full): a newly created parameter specification
2251 g_param_spec_string (const gchar *name,
2254 const gchar *default_value,
2257 GParamSpecString *sspec = g_param_spec_internal (G_TYPE_PARAM_STRING,
2265 g_free (sspec->default_value);
2266 sspec->default_value = g_strdup (default_value);
2268 return G_PARAM_SPEC (sspec);
2272 * g_param_spec_param:
2273 * @name: canonical name of the property specified
2274 * @nick: nick name for the property specified
2275 * @blurb: description of the property specified
2276 * @param_type: a #GType derived from %G_TYPE_PARAM
2277 * @flags: flags for the property specified
2279 * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM
2282 * See g_param_spec_internal() for details on property names.
2284 * Returns: (transfer full): a newly created parameter specification
2287 g_param_spec_param (const gchar *name,
2293 GParamSpecParam *pspec;
2295 g_return_val_if_fail (G_TYPE_IS_PARAM (param_type), NULL);
2297 pspec = g_param_spec_internal (G_TYPE_PARAM_PARAM,
2305 G_PARAM_SPEC (pspec)->value_type = param_type;
2307 return G_PARAM_SPEC (pspec);
2311 * g_param_spec_boxed:
2312 * @name: canonical name of the property specified
2313 * @nick: nick name for the property specified
2314 * @blurb: description of the property specified
2315 * @boxed_type: %G_TYPE_BOXED derived type of this property
2316 * @flags: flags for the property specified
2318 * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED
2321 * See g_param_spec_internal() for details on property names.
2323 * Returns: (transfer full): a newly created parameter specification
2326 g_param_spec_boxed (const gchar *name,
2332 GParamSpecBoxed *bspec;
2334 g_return_val_if_fail (G_TYPE_IS_BOXED (boxed_type), NULL);
2335 g_return_val_if_fail (G_TYPE_IS_VALUE_TYPE (boxed_type), NULL);
2337 bspec = g_param_spec_internal (G_TYPE_PARAM_BOXED,
2345 G_PARAM_SPEC (bspec)->value_type = boxed_type;
2347 return G_PARAM_SPEC (bspec);
2351 * g_param_spec_pointer:
2352 * @name: canonical name of the property specified
2353 * @nick: nick name for the property specified
2354 * @blurb: description of the property specified
2355 * @flags: flags for the property specified
2357 * Creates a new #GParamSpecPointer instance specifying a pointer property.
2358 * Where possible, it is better to use g_param_spec_object() or
2359 * g_param_spec_boxed() to expose memory management information.
2361 * See g_param_spec_internal() for details on property names.
2363 * Returns: (transfer full): a newly created parameter specification
2366 g_param_spec_pointer (const gchar *name,
2371 GParamSpecPointer *pspec;
2373 pspec = g_param_spec_internal (G_TYPE_PARAM_POINTER,
2381 return G_PARAM_SPEC (pspec);
2385 * g_param_spec_gtype:
2386 * @name: canonical name of the property specified
2387 * @nick: nick name for the property specified
2388 * @blurb: description of the property specified
2389 * @is_a_type: a #GType whose subtypes are allowed as values
2390 * of the property (use %G_TYPE_NONE for any type)
2391 * @flags: flags for the property specified
2393 * Creates a new #GParamSpecGType instance specifying a
2394 * %G_TYPE_GTYPE property.
2396 * See g_param_spec_internal() for details on property names.
2400 * Returns: (transfer full): a newly created parameter specification
2403 g_param_spec_gtype (const gchar *name,
2409 GParamSpecGType *tspec;
2411 tspec = g_param_spec_internal (G_TYPE_PARAM_GTYPE,
2419 tspec->is_a_type = is_a_type;
2421 return G_PARAM_SPEC (tspec);
2425 * g_param_spec_value_array: (skip)
2426 * @name: canonical name of the property specified
2427 * @nick: nick name for the property specified
2428 * @blurb: description of the property specified
2429 * @element_spec: a #GParamSpec describing the elements contained in
2430 * arrays of this property, may be %NULL
2431 * @flags: flags for the property specified
2433 * Creates a new #GParamSpecValueArray instance specifying a
2434 * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a
2435 * %G_TYPE_BOXED type, as such, #GValue structures for this property
2436 * can be accessed with g_value_set_boxed() and g_value_get_boxed().
2438 * See g_param_spec_internal() for details on property names.
2440 * Returns: a newly created parameter specification
2443 g_param_spec_value_array (const gchar *name,
2446 GParamSpec *element_spec,
2449 GParamSpecValueArray *aspec;
2452 g_return_val_if_fail (G_IS_PARAM_SPEC (element_spec), NULL);
2454 aspec = g_param_spec_internal (G_TYPE_PARAM_VALUE_ARRAY,
2464 aspec->element_spec = g_param_spec_ref (element_spec);
2465 g_param_spec_sink (element_spec);
2468 return G_PARAM_SPEC (aspec);
2472 * g_param_spec_object:
2473 * @name: canonical name of the property specified
2474 * @nick: nick name for the property specified
2475 * @blurb: description of the property specified
2476 * @object_type: %G_TYPE_OBJECT derived type of this property
2477 * @flags: flags for the property specified
2479 * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT
2482 * See g_param_spec_internal() for details on property names.
2484 * Returns: (transfer full): a newly created parameter specification
2487 g_param_spec_object (const gchar *name,
2493 GParamSpecObject *ospec;
2495 g_return_val_if_fail (g_type_is_a (object_type, G_TYPE_OBJECT), NULL);
2497 ospec = g_param_spec_internal (G_TYPE_PARAM_OBJECT,
2505 G_PARAM_SPEC (ospec)->value_type = object_type;
2507 return G_PARAM_SPEC (ospec);
2511 * g_param_spec_override: (skip)
2512 * @name: the name of the property.
2513 * @overridden: The property that is being overridden
2515 * Creates a new property of type #GParamSpecOverride. This is used
2516 * to direct operations to another paramspec, and will not be directly
2517 * useful unless you are implementing a new base type similar to GObject.
2521 * Returns: the newly created #GParamSpec
2524 g_param_spec_override (const gchar *name,
2525 GParamSpec *overridden)
2529 g_return_val_if_fail (name != NULL, NULL);
2530 g_return_val_if_fail (G_IS_PARAM_SPEC (overridden), NULL);
2532 /* Dereference further redirections for property that was passed in
2536 GParamSpec *indirect = g_param_spec_get_redirect_target (overridden);
2538 overridden = indirect;
2543 pspec = g_param_spec_internal (G_TYPE_PARAM_OVERRIDE,
2549 pspec->value_type = G_PARAM_SPEC_VALUE_TYPE (overridden);
2550 G_PARAM_SPEC_OVERRIDE (pspec)->overridden = g_param_spec_ref (overridden);
2556 * g_param_spec_variant:
2557 * @name: canonical name of the property specified
2558 * @nick: nick name for the property specified
2559 * @blurb: description of the property specified
2560 * @type: a #GVariantType
2561 * @default_value: (nullable) (transfer full): a #GVariant of type @type to
2562 * use as the default value, or %NULL
2563 * @flags: flags for the property specified
2565 * Creates a new #GParamSpecVariant instance specifying a #GVariant
2568 * If @default_value is floating, it is consumed.
2570 * See g_param_spec_internal() for details on property names.
2572 * Returns: (transfer full): the newly created #GParamSpec
2577 g_param_spec_variant (const gchar *name,
2580 const GVariantType *type,
2581 GVariant *default_value,
2584 GParamSpecVariant *vspec;
2586 g_return_val_if_fail (type != NULL, NULL);
2587 g_return_val_if_fail (default_value == NULL ||
2588 g_variant_is_of_type (default_value, type), NULL);
2590 vspec = g_param_spec_internal (G_TYPE_PARAM_VARIANT,
2598 vspec->type = g_variant_type_copy (type);
2600 vspec->default_value = g_variant_ref_sink (default_value);
2602 return G_PARAM_SPEC (vspec);