1/* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
3 *
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.1 of the License, or (at your option) any later version.
8 *
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.
13 *
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 */
17
18/*
19 * MT safe
20 */
21
22#include "config.h"
23
24#include <string.h>
25
26#include "gparam.h"
27#include "gparamspecs.h"
28#include "gvaluecollector.h"
29#include "gtype-private.h"
30
31/**
32 * SECTION:gparamspec
33 * @short_description: Metadata for parameter specifications
34 * @see_also: g_object_class_install_property(), g_object_set(),
35 * g_object_get(), g_object_set_property(), g_object_get_property(),
36 * g_value_register_transform_func()
37 * @title: GParamSpec
38 *
39 * #GParamSpec is an object structure that encapsulates the metadata
40 * required to specify parameters, such as e.g. #GObject properties.
41 *
42 * ## Parameter names # {#canonical-parameter-names}
43 *
44 * A property name consists of one or more segments consisting of ASCII letters
45 * and digits, separated by either the `-` or `_` character. The first
46 * character of a property name must be a letter. These are the same rules as
47 * for signal naming (see g_signal_new()).
48 *
49 * When creating and looking up a #GParamSpec, either separator can be
50 * used, but they cannot be mixed. Using `-` is considerably more
51 * efficient, and is the ‘canonical form’. Using `_` is discouraged.
52 */
53
54
55/* --- defines --- */
56#define PARAM_FLOATING_FLAG 0x2
57#define G_PARAM_USER_MASK (~0U << 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
60/* --- prototypes --- */
61static void g_param_spec_class_base_init (GParamSpecClass *class);
62static void g_param_spec_class_base_finalize (GParamSpecClass *class);
63static void g_param_spec_class_init (GParamSpecClass *class,
64 gpointer class_data);
65static void g_param_spec_init (GParamSpec *pspec,
66 GParamSpecClass *class);
67static void g_param_spec_finalize (GParamSpec *pspec);
68static void value_param_init (GValue *value);
69static void value_param_free_value (GValue *value);
70static void value_param_copy_value (const GValue *src_value,
71 GValue *dest_value);
72static void value_param_transform_value (const GValue *src_value,
73 GValue *dest_value);
74static gpointer value_param_peek_pointer (const GValue *value);
75static gchar* value_param_collect_value (GValue *value,
76 guint n_collect_values,
77 GTypeCValue *collect_values,
78 guint collect_flags);
79static gchar* value_param_lcopy_value (const GValue *value,
80 guint n_collect_values,
81 GTypeCValue *collect_values,
82 guint collect_flags);
83
84typedef struct
85{
86 GValue default_value;
87 GQuark name_quark;
88} GParamSpecPrivate;
89
90static gint g_param_private_offset;
91
92/* --- functions --- */
93static inline GParamSpecPrivate *
94g_param_spec_get_private (GParamSpec *pspec)
95{
96 return &G_STRUCT_MEMBER (GParamSpecPrivate, pspec, g_param_private_offset);
97}
98
99void
100_g_param_type_init (void)
101{
102 static const GTypeFundamentalInfo finfo = {
103 (G_TYPE_FLAG_CLASSED |
104 G_TYPE_FLAG_INSTANTIATABLE |
105 G_TYPE_FLAG_DERIVABLE |
106 G_TYPE_FLAG_DEEP_DERIVABLE),
107 };
108 static const GTypeValueTable param_value_table = {
109 value_param_init, /* value_init */
110 value_param_free_value, /* value_free */
111 value_param_copy_value, /* value_copy */
112 value_param_peek_pointer, /* value_peek_pointer */
113 "p", /* collect_format */
114 value_param_collect_value, /* collect_value */
115 "p", /* lcopy_format */
116 value_param_lcopy_value, /* lcopy_value */
117 };
118 const GTypeInfo param_spec_info = {
119 sizeof (GParamSpecClass),
120
121 (GBaseInitFunc) g_param_spec_class_base_init,
122 (GBaseFinalizeFunc) g_param_spec_class_base_finalize,
123 (GClassInitFunc) g_param_spec_class_init,
124 (GClassFinalizeFunc) NULL,
125 NULL, /* class_data */
126
127 sizeof (GParamSpec),
128 0, /* n_preallocs */
129 (GInstanceInitFunc) g_param_spec_init,
130
131 &param_value_table,
132 };
133 GType type;
134
135 /* This should be registered as GParamSpec instead of GParam, for
136 * consistency sake, so that type name can be mapped to struct name,
137 * However, some language bindings, most noticeable the python ones
138 * depends on the "GParam" identifier, see #548689
139 */
140 type = g_type_register_fundamental (G_TYPE_PARAM, type_name: g_intern_static_string (string: "GParam"), info: &param_spec_info, finfo: &finfo, flags: G_TYPE_FLAG_ABSTRACT);
141 g_assert (type == G_TYPE_PARAM);
142 g_param_private_offset = g_type_add_instance_private (class_type: type, private_size: sizeof (GParamSpecPrivate));
143 g_value_register_transform_func (G_TYPE_PARAM, G_TYPE_PARAM, transform_func: value_param_transform_value);
144}
145
146static void
147g_param_spec_class_base_init (GParamSpecClass *class)
148{
149}
150
151static void
152g_param_spec_class_base_finalize (GParamSpecClass *class)
153{
154}
155
156static void
157g_param_spec_class_init (GParamSpecClass *class,
158 gpointer class_data)
159{
160 class->value_type = G_TYPE_NONE;
161 class->finalize = g_param_spec_finalize;
162 class->value_set_default = NULL;
163 class->value_validate = NULL;
164 class->values_cmp = NULL;
165
166 g_type_class_adjust_private_offset (g_class: class, private_size_or_offset: &g_param_private_offset);
167}
168
169static void
170g_param_spec_init (GParamSpec *pspec,
171 GParamSpecClass *class)
172{
173 pspec->name = NULL;
174 pspec->_nick = NULL;
175 pspec->_blurb = NULL;
176 pspec->flags = 0;
177 pspec->value_type = class->value_type;
178 pspec->owner_type = 0;
179 pspec->qdata = NULL;
180 g_datalist_set_flags (datalist: &pspec->qdata, PARAM_FLOATING_FLAG);
181 pspec->ref_count = 1;
182 pspec->param_id = 0;
183}
184
185static void
186g_param_spec_finalize (GParamSpec *pspec)
187{
188 GParamSpecPrivate *priv = g_param_spec_get_private (pspec);
189
190 if (priv->default_value.g_type)
191 g_value_reset (value: &priv->default_value);
192
193 g_datalist_clear (datalist: &pspec->qdata);
194
195 if (!(pspec->flags & G_PARAM_STATIC_NICK))
196 g_free (mem: pspec->_nick);
197
198 if (!(pspec->flags & G_PARAM_STATIC_BLURB))
199 g_free (mem: pspec->_blurb);
200
201 g_type_free_instance (instance: (GTypeInstance*) pspec);
202}
203
204/**
205 * g_param_spec_ref: (skip)
206 * @pspec: (transfer none) (not nullable): a valid #GParamSpec
207 *
208 * Increments the reference count of @pspec.
209 *
210 * Returns: (transfer full) (not nullable): the #GParamSpec that was passed into this function
211 */
212GParamSpec*
213g_param_spec_ref (GParamSpec *pspec)
214{
215 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
216
217 g_atomic_int_inc ((int *)&pspec->ref_count);
218
219 return pspec;
220}
221
222/**
223 * g_param_spec_unref: (skip)
224 * @pspec: a valid #GParamSpec
225 *
226 * Decrements the reference count of a @pspec.
227 */
228void
229g_param_spec_unref (GParamSpec *pspec)
230{
231 gboolean is_zero;
232
233 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
234
235 is_zero = g_atomic_int_dec_and_test ((int *)&pspec->ref_count);
236
237 if (G_UNLIKELY (is_zero))
238 {
239 G_PARAM_SPEC_GET_CLASS (pspec)->finalize (pspec);
240 }
241}
242
243/**
244 * g_param_spec_sink:
245 * @pspec: a valid #GParamSpec
246 *
247 * The initial reference count of a newly created #GParamSpec is 1,
248 * even though no one has explicitly called g_param_spec_ref() on it
249 * yet. So the initial reference count is flagged as "floating", until
250 * someone calls `g_param_spec_ref (pspec); g_param_spec_sink
251 * (pspec);` in sequence on it, taking over the initial
252 * reference count (thus ending up with a @pspec that has a reference
253 * count of 1 still, but is not flagged "floating" anymore).
254 */
255void
256g_param_spec_sink (GParamSpec *pspec)
257{
258 gsize oldvalue;
259 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
260
261 oldvalue = g_atomic_pointer_and (&pspec->qdata, ~(gsize)PARAM_FLOATING_FLAG);
262 if (oldvalue & PARAM_FLOATING_FLAG)
263 g_param_spec_unref (pspec);
264}
265
266/**
267 * g_param_spec_ref_sink: (skip)
268 * @pspec: a valid #GParamSpec
269 *
270 * Convenience function to ref and sink a #GParamSpec.
271 *
272 * Since: 2.10
273 * Returns: (transfer full) (not nullable): the #GParamSpec that was passed into this function
274 */
275GParamSpec*
276g_param_spec_ref_sink (GParamSpec *pspec)
277{
278 gsize oldvalue;
279 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
280
281 oldvalue = g_atomic_pointer_and (&pspec->qdata, ~(gsize)PARAM_FLOATING_FLAG);
282 if (!(oldvalue & PARAM_FLOATING_FLAG))
283 g_param_spec_ref (pspec);
284
285 return pspec;
286}
287
288/**
289 * g_param_spec_get_name:
290 * @pspec: a valid #GParamSpec
291 *
292 * Get the name of a #GParamSpec.
293 *
294 * The name is always an "interned" string (as per g_intern_string()).
295 * This allows for pointer-value comparisons.
296 *
297 * Returns: the name of @pspec.
298 */
299const gchar *
300g_param_spec_get_name (GParamSpec *pspec)
301{
302 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
303
304 return pspec->name;
305}
306
307/**
308 * g_param_spec_get_nick:
309 * @pspec: a valid #GParamSpec
310 *
311 * Get the nickname of a #GParamSpec.
312 *
313 * Returns: the nickname of @pspec.
314 */
315const gchar *
316g_param_spec_get_nick (GParamSpec *pspec)
317{
318 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
319
320 if (pspec->_nick)
321 return pspec->_nick;
322 else
323 {
324 GParamSpec *redirect_target;
325
326 redirect_target = g_param_spec_get_redirect_target (pspec);
327 if (redirect_target && redirect_target->_nick)
328 return redirect_target->_nick;
329 }
330
331 return pspec->name;
332}
333
334/**
335 * g_param_spec_get_blurb:
336 * @pspec: a valid #GParamSpec
337 *
338 * Get the short description of a #GParamSpec.
339 *
340 * Returns: (nullable): the short description of @pspec.
341 */
342const gchar *
343g_param_spec_get_blurb (GParamSpec *pspec)
344{
345 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
346
347 if (pspec->_blurb)
348 return pspec->_blurb;
349 else
350 {
351 GParamSpec *redirect_target;
352
353 redirect_target = g_param_spec_get_redirect_target (pspec);
354 if (redirect_target && redirect_target->_blurb)
355 return redirect_target->_blurb;
356 }
357
358 return NULL;
359}
360
361/* @key must have already been validated with is_valid()
362 * Modifies @key in place. */
363static void
364canonicalize_key (gchar *key)
365{
366 gchar *p;
367
368 for (p = key; *p != 0; p++)
369 {
370 gchar c = *p;
371
372 if (c == '_')
373 *p = '-';
374 }
375}
376
377/* @key must have already been validated with is_valid() */
378static gboolean
379is_canonical (const gchar *key)
380{
381 return (strchr (s: key, c: '_') == NULL);
382}
383
384/**
385 * g_param_spec_is_valid_name:
386 * @name: the canonical name of the property
387 *
388 * Validate a property name for a #GParamSpec. This can be useful for
389 * dynamically-generated properties which need to be validated at run-time
390 * before actually trying to create them.
391 *
392 * See [canonical parameter names][canonical-parameter-names] for details of
393 * the rules for valid names.
394 *
395 * Returns: %TRUE if @name is a valid property name, %FALSE otherwise.
396 * Since: 2.66
397 */
398gboolean
399g_param_spec_is_valid_name (const gchar *name)
400{
401 const gchar *p;
402
403 /* First character must be a letter. */
404 if ((name[0] < 'A' || name[0] > 'Z') &&
405 (name[0] < 'a' || name[0] > 'z'))
406 return FALSE;
407
408 for (p = name; *p != 0; p++)
409 {
410 const gchar c = *p;
411
412 if (c != '-' && c != '_' &&
413 (c < '0' || c > '9') &&
414 (c < 'A' || c > 'Z') &&
415 (c < 'a' || c > 'z'))
416 return FALSE;
417 }
418
419 return TRUE;
420}
421
422/**
423 * g_param_spec_internal: (skip)
424 * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
425 * @name: the canonical name of the property
426 * @nick: the nickname of the property
427 * @blurb: a short description of the property
428 * @flags: a combination of #GParamFlags
429 *
430 * Creates a new #GParamSpec instance.
431 *
432 * See [canonical parameter names][canonical-parameter-names] for details of
433 * the rules for @name. Names which violate these rules lead to undefined
434 * behaviour.
435 *
436 * Beyond the name, #GParamSpecs have two more descriptive
437 * strings associated with them, the @nick, which should be suitable
438 * for use as a label for the property in a property editor, and the
439 * @blurb, which should be a somewhat longer description, suitable for
440 * e.g. a tooltip. The @nick and @blurb should ideally be localized.
441 *
442 * Returns: (type GObject.ParamSpec): (transfer floating): a newly allocated
443 * #GParamSpec instance, which is initially floating
444 */
445gpointer
446g_param_spec_internal (GType param_type,
447 const gchar *name,
448 const gchar *nick,
449 const gchar *blurb,
450 GParamFlags flags)
451{
452 GParamSpec *pspec;
453 GParamSpecPrivate *priv;
454
455 g_return_val_if_fail (G_TYPE_IS_PARAM (param_type) && param_type != G_TYPE_PARAM, NULL);
456 g_return_val_if_fail (name != NULL, NULL);
457 g_return_val_if_fail (g_param_spec_is_valid_name (name), NULL);
458 g_return_val_if_fail (!(flags & G_PARAM_STATIC_NAME) || is_canonical (name), NULL);
459
460 pspec = (gpointer) g_type_create_instance (type: param_type);
461
462 if (flags & G_PARAM_STATIC_NAME)
463 {
464 /* pspec->name is not freed if (flags & G_PARAM_STATIC_NAME) */
465 pspec->name = (gchar *) g_intern_static_string (string: name);
466 if (!is_canonical (key: pspec->name))
467 g_warning ("G_PARAM_STATIC_NAME used with non-canonical pspec name: %s", pspec->name);
468 }
469 else
470 {
471 if (is_canonical (key: name))
472 pspec->name = (gchar *) g_intern_string (string: name);
473 else
474 {
475 gchar *tmp = g_strdup (str: name);
476 canonicalize_key (key: tmp);
477 pspec->name = (gchar *) g_intern_string (string: tmp);
478 g_free (mem: tmp);
479 }
480 }
481
482 priv = g_param_spec_get_private (pspec);
483 priv->name_quark = g_quark_from_string (string: pspec->name);
484
485 if (flags & G_PARAM_STATIC_NICK)
486 pspec->_nick = (gchar*) nick;
487 else
488 pspec->_nick = g_strdup (str: nick);
489
490 if (flags & G_PARAM_STATIC_BLURB)
491 pspec->_blurb = (gchar*) blurb;
492 else
493 pspec->_blurb = g_strdup (str: blurb);
494
495 pspec->flags = (flags & G_PARAM_USER_MASK) | (flags & G_PARAM_MASK);
496
497 return pspec;
498}
499
500/**
501 * g_param_spec_get_qdata:
502 * @pspec: a valid #GParamSpec
503 * @quark: a #GQuark, naming the user data pointer
504 *
505 * Gets back user data pointers stored via g_param_spec_set_qdata().
506 *
507 * Returns: (transfer none) (nullable): the user data pointer set, or %NULL
508 */
509gpointer
510g_param_spec_get_qdata (GParamSpec *pspec,
511 GQuark quark)
512{
513 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
514
515 return quark ? g_datalist_id_get_data (datalist: &pspec->qdata, key_id: quark) : NULL;
516}
517
518/**
519 * g_param_spec_set_qdata:
520 * @pspec: the #GParamSpec to set store a user data pointer
521 * @quark: a #GQuark, naming the user data pointer
522 * @data: (nullable): an opaque user data pointer
523 *
524 * Sets an opaque, named pointer on a #GParamSpec. The name is
525 * specified through a #GQuark (retrieved e.g. via
526 * g_quark_from_static_string()), and the pointer can be gotten back
527 * from the @pspec with g_param_spec_get_qdata(). Setting a
528 * previously set user data pointer, overrides (frees) the old pointer
529 * set, using %NULL as pointer essentially removes the data stored.
530 */
531void
532g_param_spec_set_qdata (GParamSpec *pspec,
533 GQuark quark,
534 gpointer data)
535{
536 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
537 g_return_if_fail (quark > 0);
538
539 g_datalist_id_set_data (&pspec->qdata, quark, data);
540}
541
542/**
543 * g_param_spec_set_qdata_full: (skip)
544 * @pspec: the #GParamSpec to set store a user data pointer
545 * @quark: a #GQuark, naming the user data pointer
546 * @data: (nullable): an opaque user data pointer
547 * @destroy: (nullable): function to invoke with @data as argument, when @data needs to
548 * be freed
549 *
550 * This function works like g_param_spec_set_qdata(), but in addition,
551 * a `void (*destroy) (gpointer)` function may be
552 * specified which is called with @data as argument when the @pspec is
553 * finalized, or the data is being overwritten by a call to
554 * g_param_spec_set_qdata() with the same @quark.
555 */
556void
557g_param_spec_set_qdata_full (GParamSpec *pspec,
558 GQuark quark,
559 gpointer data,
560 GDestroyNotify destroy)
561{
562 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
563 g_return_if_fail (quark > 0);
564
565 g_datalist_id_set_data_full (datalist: &pspec->qdata, key_id: quark, data, destroy_func: data ? destroy : (GDestroyNotify) NULL);
566}
567
568/**
569 * g_param_spec_steal_qdata:
570 * @pspec: the #GParamSpec to get a stored user data pointer from
571 * @quark: a #GQuark, naming the user data pointer
572 *
573 * Gets back user data pointers stored via g_param_spec_set_qdata()
574 * and removes the @data from @pspec without invoking its destroy()
575 * function (if any was set). Usually, calling this function is only
576 * required to update user data pointers with a destroy notifier.
577 *
578 * Returns: (transfer none) (nullable): the user data pointer set, or %NULL
579 */
580gpointer
581g_param_spec_steal_qdata (GParamSpec *pspec,
582 GQuark quark)
583{
584 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
585 g_return_val_if_fail (quark > 0, NULL);
586
587 return g_datalist_id_remove_no_notify (datalist: &pspec->qdata, key_id: quark);
588}
589
590/**
591 * g_param_spec_get_redirect_target:
592 * @pspec: a #GParamSpec
593 *
594 * If the paramspec redirects operations to another paramspec,
595 * returns that paramspec. Redirect is used typically for
596 * providing a new implementation of a property in a derived
597 * type while preserving all the properties from the parent
598 * type. Redirection is established by creating a property
599 * of type #GParamSpecOverride. See g_object_class_override_property()
600 * for an example of the use of this capability.
601 *
602 * Since: 2.4
603 *
604 * Returns: (transfer none) (nullable): paramspec to which requests on this
605 * paramspec should be redirected, or %NULL if none.
606 */
607GParamSpec*
608g_param_spec_get_redirect_target (GParamSpec *pspec)
609{
610 GTypeInstance *inst = (GTypeInstance *)pspec;
611
612 if (inst && inst->g_class && inst->g_class->g_type == G_TYPE_PARAM_OVERRIDE)
613 return ((GParamSpecOverride*)pspec)->overridden;
614 else
615 return NULL;
616}
617
618/**
619 * g_param_value_set_default:
620 * @pspec: a valid #GParamSpec
621 * @value: a #GValue of correct type for @pspec; since 2.64, you
622 * can also pass an empty #GValue, initialized with %G_VALUE_INIT
623 *
624 * Sets @value to its default value as specified in @pspec.
625 */
626void
627g_param_value_set_default (GParamSpec *pspec,
628 GValue *value)
629{
630 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
631
632 if (G_VALUE_TYPE (value) == G_TYPE_INVALID)
633 {
634 g_value_init (value, G_PARAM_SPEC_VALUE_TYPE (pspec));
635 }
636 else
637 {
638 g_return_if_fail (G_IS_VALUE (value));
639 g_return_if_fail (PSPEC_APPLIES_TO_VALUE (pspec, value));
640 g_value_reset (value);
641 }
642
643 G_PARAM_SPEC_GET_CLASS (pspec)->value_set_default (pspec, value);
644}
645
646/**
647 * g_param_value_defaults:
648 * @pspec: a valid #GParamSpec
649 * @value: a #GValue of correct type for @pspec
650 *
651 * Checks whether @value contains the default value as specified in @pspec.
652 *
653 * Returns: whether @value contains the canonical default for this @pspec
654 */
655gboolean
656g_param_value_defaults (GParamSpec *pspec,
657 const GValue *value)
658{
659 GValue dflt_value = G_VALUE_INIT;
660 gboolean defaults;
661
662 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), FALSE);
663 g_return_val_if_fail (G_IS_VALUE (value), FALSE);
664 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec, value), FALSE);
665
666 g_value_init (value: &dflt_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
667 G_PARAM_SPEC_GET_CLASS (pspec)->value_set_default (pspec, &dflt_value);
668 defaults = G_PARAM_SPEC_GET_CLASS (pspec)->values_cmp (pspec, value, &dflt_value) == 0;
669 g_value_unset (value: &dflt_value);
670
671 return defaults;
672}
673
674/**
675 * g_param_value_validate:
676 * @pspec: a valid #GParamSpec
677 * @value: a #GValue of correct type for @pspec
678 *
679 * Ensures that the contents of @value comply with the specifications
680 * set out by @pspec. For example, a #GParamSpecInt might require
681 * that integers stored in @value may not be smaller than -42 and not be
682 * greater than +42. If @value contains an integer outside of this range,
683 * it is modified accordingly, so the resulting value will fit into the
684 * range -42 .. +42.
685 *
686 * Returns: whether modifying @value was necessary to ensure validity
687 */
688gboolean
689g_param_value_validate (GParamSpec *pspec,
690 GValue *value)
691{
692 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), FALSE);
693 g_return_val_if_fail (G_IS_VALUE (value), FALSE);
694 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec, value), FALSE);
695
696 if (G_PARAM_SPEC_GET_CLASS (pspec)->value_validate)
697 {
698 GValue oval = *value;
699
700 if (G_PARAM_SPEC_GET_CLASS (pspec)->value_validate (pspec, value) ||
701 memcmp (s1: &oval.data, s2: &value->data, n: sizeof (oval.data)))
702 return TRUE;
703 }
704
705 return FALSE;
706}
707
708/**
709 * g_param_value_convert:
710 * @pspec: a valid #GParamSpec
711 * @src_value: source #GValue
712 * @dest_value: destination #GValue of correct type for @pspec
713 * @strict_validation: %TRUE requires @dest_value to conform to @pspec
714 * without modifications
715 *
716 * Transforms @src_value into @dest_value if possible, and then
717 * validates @dest_value, in order for it to conform to @pspec. If
718 * @strict_validation is %TRUE this function will only succeed if the
719 * transformed @dest_value complied to @pspec without modifications.
720 *
721 * See also g_value_type_transformable(), g_value_transform() and
722 * g_param_value_validate().
723 *
724 * Returns: %TRUE if transformation and validation were successful,
725 * %FALSE otherwise and @dest_value is left untouched.
726 */
727gboolean
728g_param_value_convert (GParamSpec *pspec,
729 const GValue *src_value,
730 GValue *dest_value,
731 gboolean strict_validation)
732{
733 GValue tmp_value = G_VALUE_INIT;
734
735 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), FALSE);
736 g_return_val_if_fail (G_IS_VALUE (src_value), FALSE);
737 g_return_val_if_fail (G_IS_VALUE (dest_value), FALSE);
738 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec, dest_value), FALSE);
739
740 /* better leave dest_value untouched when returning FALSE */
741
742 g_value_init (value: &tmp_value, G_VALUE_TYPE (dest_value));
743 if (g_value_transform (src_value, dest_value: &tmp_value) &&
744 (!g_param_value_validate (pspec, value: &tmp_value) || !strict_validation))
745 {
746 g_value_unset (value: dest_value);
747
748 /* values are relocatable */
749 memcpy (dest: dest_value, src: &tmp_value, n: sizeof (tmp_value));
750
751 return TRUE;
752 }
753 else
754 {
755 g_value_unset (value: &tmp_value);
756
757 return FALSE;
758 }
759}
760
761/**
762 * g_param_values_cmp:
763 * @pspec: a valid #GParamSpec
764 * @value1: a #GValue of correct type for @pspec
765 * @value2: a #GValue of correct type for @pspec
766 *
767 * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1,
768 * if @value1 is found to be less than, equal to or greater than @value2,
769 * respectively.
770 *
771 * Returns: -1, 0 or +1, for a less than, equal to or greater than result
772 */
773gint
774g_param_values_cmp (GParamSpec *pspec,
775 const GValue *value1,
776 const GValue *value2)
777{
778 gint cmp;
779
780 /* param_values_cmp() effectively does: value1 - value2
781 * so the return values are:
782 * -1) value1 < value2
783 * 0) value1 == value2
784 * 1) value1 > value2
785 */
786 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), 0);
787 g_return_val_if_fail (G_IS_VALUE (value1), 0);
788 g_return_val_if_fail (G_IS_VALUE (value2), 0);
789 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec, value1), 0);
790 g_return_val_if_fail (PSPEC_APPLIES_TO_VALUE (pspec, value2), 0);
791
792 cmp = G_PARAM_SPEC_GET_CLASS (pspec)->values_cmp (pspec, value1, value2);
793
794 return CLAMP (cmp, -1, 1);
795}
796
797static void
798value_param_init (GValue *value)
799{
800 value->data[0].v_pointer = NULL;
801}
802
803static void
804value_param_free_value (GValue *value)
805{
806 if (value->data[0].v_pointer)
807 g_param_spec_unref (pspec: value->data[0].v_pointer);
808}
809
810static void
811value_param_copy_value (const GValue *src_value,
812 GValue *dest_value)
813{
814 if (src_value->data[0].v_pointer)
815 dest_value->data[0].v_pointer = g_param_spec_ref (pspec: src_value->data[0].v_pointer);
816 else
817 dest_value->data[0].v_pointer = NULL;
818}
819
820static void
821value_param_transform_value (const GValue *src_value,
822 GValue *dest_value)
823{
824 if (src_value->data[0].v_pointer &&
825 g_type_is_a (G_PARAM_SPEC_TYPE (dest_value->data[0].v_pointer), G_VALUE_TYPE (dest_value)))
826 dest_value->data[0].v_pointer = g_param_spec_ref (pspec: src_value->data[0].v_pointer);
827 else
828 dest_value->data[0].v_pointer = NULL;
829}
830
831static gpointer
832value_param_peek_pointer (const GValue *value)
833{
834 return value->data[0].v_pointer;
835}
836
837static gchar*
838value_param_collect_value (GValue *value,
839 guint n_collect_values,
840 GTypeCValue *collect_values,
841 guint collect_flags)
842{
843 if (collect_values[0].v_pointer)
844 {
845 GParamSpec *param = collect_values[0].v_pointer;
846
847 if (param->g_type_instance.g_class == NULL)
848 return g_strconcat (string1: "invalid unclassed param spec pointer for value type '",
849 G_VALUE_TYPE_NAME (value),
850 "'",
851 NULL);
852 else if (!g_value_type_compatible (G_PARAM_SPEC_TYPE (param), G_VALUE_TYPE (value)))
853 return g_strconcat (string1: "invalid param spec type '",
854 G_PARAM_SPEC_TYPE_NAME (param),
855 "' for value type '",
856 G_VALUE_TYPE_NAME (value),
857 "'",
858 NULL);
859 value->data[0].v_pointer = g_param_spec_ref (pspec: param);
860 }
861 else
862 value->data[0].v_pointer = NULL;
863
864 return NULL;
865}
866
867static gchar*
868value_param_lcopy_value (const GValue *value,
869 guint n_collect_values,
870 GTypeCValue *collect_values,
871 guint collect_flags)
872{
873 GParamSpec **param_p = collect_values[0].v_pointer;
874
875 g_return_val_if_fail (param_p != NULL, g_strdup_printf ("value location for '%s' passed as NULL", G_VALUE_TYPE_NAME (value)));
876
877 if (!value->data[0].v_pointer)
878 *param_p = NULL;
879 else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
880 *param_p = value->data[0].v_pointer;
881 else
882 *param_p = g_param_spec_ref (pspec: value->data[0].v_pointer);
883
884 return NULL;
885}
886
887
888/* --- param spec pool --- */
889/**
890 * GParamSpecPool:
891 *
892 * A #GParamSpecPool maintains a collection of #GParamSpecs which can be
893 * quickly accessed by owner and name. The implementation of the #GObject property
894 * system uses such a pool to store the #GParamSpecs of the properties all object
895 * types.
896 */
897struct _GParamSpecPool
898{
899 GMutex mutex;
900 gboolean type_prefixing;
901 GHashTable *hash_table;
902};
903
904static guint
905param_spec_pool_hash (gconstpointer key_spec)
906{
907 const GParamSpec *key = key_spec;
908 const gchar *p;
909 guint h = key->owner_type;
910
911 for (p = key->name; *p; p++)
912 h = (h << 5) - h + *p;
913
914 return h;
915}
916
917static gboolean
918param_spec_pool_equals (gconstpointer key_spec_1,
919 gconstpointer key_spec_2)
920{
921 const GParamSpec *key1 = key_spec_1;
922 const GParamSpec *key2 = key_spec_2;
923
924 return (key1->owner_type == key2->owner_type &&
925 strcmp (s1: key1->name, s2: key2->name) == 0);
926}
927
928/**
929 * g_param_spec_pool_new:
930 * @type_prefixing: Whether the pool will support type-prefixed property names.
931 *
932 * Creates a new #GParamSpecPool.
933 *
934 * If @type_prefixing is %TRUE, lookups in the newly created pool will
935 * allow to specify the owner as a colon-separated prefix of the
936 * property name, like "GtkContainer:border-width". This feature is
937 * deprecated, so you should always set @type_prefixing to %FALSE.
938 *
939 * Returns: (transfer full): a newly allocated #GParamSpecPool.
940 */
941GParamSpecPool*
942g_param_spec_pool_new (gboolean type_prefixing)
943{
944 static GMutex init_mutex;
945 GParamSpecPool *pool = g_new (GParamSpecPool, 1);
946
947 memcpy (dest: &pool->mutex, src: &init_mutex, n: sizeof (init_mutex));
948 pool->type_prefixing = type_prefixing != FALSE;
949 pool->hash_table = g_hash_table_new (hash_func: param_spec_pool_hash, key_equal_func: param_spec_pool_equals);
950
951 return pool;
952}
953
954/**
955 * g_param_spec_pool_insert:
956 * @pool: a #GParamSpecPool.
957 * @pspec: (transfer none) (not nullable): the #GParamSpec to insert
958 * @owner_type: a #GType identifying the owner of @pspec
959 *
960 * Inserts a #GParamSpec in the pool.
961 */
962void
963g_param_spec_pool_insert (GParamSpecPool *pool,
964 GParamSpec *pspec,
965 GType owner_type)
966{
967 const gchar *p;
968
969 if (pool && pspec && owner_type > 0 && pspec->owner_type == 0)
970 {
971 for (p = pspec->name; *p; p++)
972 {
973 if (!strchr (G_CSET_A_2_Z G_CSET_a_2_z G_CSET_DIGITS "-_", c: *p))
974 {
975 g_warning (G_STRLOC ": pspec name \"%s\" contains invalid characters", pspec->name);
976 return;
977 }
978 }
979 g_mutex_lock (mutex: &pool->mutex);
980 pspec->owner_type = owner_type;
981 g_param_spec_ref (pspec);
982 g_hash_table_add (hash_table: pool->hash_table, key: pspec);
983 g_mutex_unlock (mutex: &pool->mutex);
984 }
985 else
986 {
987 g_return_if_fail (pool != NULL);
988 g_return_if_fail (pspec);
989 g_return_if_fail (owner_type > 0);
990 g_return_if_fail (pspec->owner_type == 0);
991 }
992}
993
994/**
995 * g_param_spec_pool_remove:
996 * @pool: a #GParamSpecPool
997 * @pspec: (transfer none) (not nullable): the #GParamSpec to remove
998 *
999 * Removes a #GParamSpec from the pool.
1000 */
1001void
1002g_param_spec_pool_remove (GParamSpecPool *pool,
1003 GParamSpec *pspec)
1004{
1005 if (pool && pspec)
1006 {
1007 g_mutex_lock (mutex: &pool->mutex);
1008 if (g_hash_table_remove (hash_table: pool->hash_table, key: pspec))
1009 g_param_spec_unref (pspec);
1010 else
1011 g_warning (G_STRLOC ": attempt to remove unknown pspec '%s' from pool", pspec->name);
1012 g_mutex_unlock (mutex: &pool->mutex);
1013 }
1014 else
1015 {
1016 g_return_if_fail (pool != NULL);
1017 g_return_if_fail (pspec);
1018 }
1019}
1020
1021static inline GParamSpec*
1022param_spec_ht_lookup (GHashTable *hash_table,
1023 const gchar *param_name,
1024 GType owner_type,
1025 gboolean walk_ancestors)
1026{
1027 GParamSpec key, *pspec;
1028
1029 key.owner_type = owner_type;
1030 key.name = (gchar*) param_name;
1031 if (walk_ancestors)
1032 do
1033 {
1034 pspec = g_hash_table_lookup (hash_table, key: &key);
1035 if (pspec)
1036 return pspec;
1037 key.owner_type = g_type_parent (type: key.owner_type);
1038 }
1039 while (key.owner_type);
1040 else
1041 pspec = g_hash_table_lookup (hash_table, key: &key);
1042
1043 if (!pspec && !is_canonical (key: param_name))
1044 {
1045 gchar *canonical;
1046
1047 canonical = g_strdup (str: key.name);
1048 canonicalize_key (key: canonical);
1049
1050 /* try canonicalized form */
1051 key.name = canonical;
1052 key.owner_type = owner_type;
1053
1054 if (walk_ancestors)
1055 do
1056 {
1057 pspec = g_hash_table_lookup (hash_table, key: &key);
1058 if (pspec)
1059 {
1060 g_free (mem: canonical);
1061 return pspec;
1062 }
1063 key.owner_type = g_type_parent (type: key.owner_type);
1064 }
1065 while (key.owner_type);
1066 else
1067 pspec = g_hash_table_lookup (hash_table, key: &key);
1068
1069 g_free (mem: canonical);
1070 }
1071
1072 return pspec;
1073}
1074
1075/**
1076 * g_param_spec_pool_lookup:
1077 * @pool: a #GParamSpecPool
1078 * @param_name: the name to look for
1079 * @owner_type: the owner to look for
1080 * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name
1081 * owned by an ancestor of @owner_type.
1082 *
1083 * Looks up a #GParamSpec in the pool.
1084 *
1085 * Returns: (transfer none) (nullable): The found #GParamSpec, or %NULL if no
1086 * matching #GParamSpec was found.
1087 */
1088GParamSpec*
1089g_param_spec_pool_lookup (GParamSpecPool *pool,
1090 const gchar *param_name,
1091 GType owner_type,
1092 gboolean walk_ancestors)
1093{
1094 GParamSpec *pspec;
1095 gchar *delim;
1096
1097 g_return_val_if_fail (pool != NULL, NULL);
1098 g_return_val_if_fail (param_name != NULL, NULL);
1099
1100 g_mutex_lock (mutex: &pool->mutex);
1101
1102 delim = pool->type_prefixing ? strchr (s: param_name, c: ':') : NULL;
1103
1104 /* try quick and away, i.e. without prefix */
1105 if (!delim)
1106 {
1107 pspec = param_spec_ht_lookup (hash_table: pool->hash_table, param_name, owner_type, walk_ancestors);
1108 g_mutex_unlock (mutex: &pool->mutex);
1109
1110 return pspec;
1111 }
1112
1113 /* strip type prefix */
1114 if (pool->type_prefixing && delim[1] == ':')
1115 {
1116 guint l = delim - param_name;
1117 gchar stack_buffer[32], *buffer = l < 32 ? stack_buffer : g_new (gchar, l + 1);
1118 GType type;
1119
1120 strncpy (dest: buffer, src: param_name, n: delim - param_name);
1121 buffer[l] = 0;
1122 type = g_type_from_name (name: buffer);
1123 if (l >= 32)
1124 g_free (mem: buffer);
1125 if (type) /* type==0 isn't a valid type pefix */
1126 {
1127 /* sanity check, these cases don't make a whole lot of sense */
1128 if ((!walk_ancestors && type != owner_type) || !g_type_is_a (type: owner_type, is_a_type: type))
1129 {
1130 g_mutex_unlock (mutex: &pool->mutex);
1131
1132 return NULL;
1133 }
1134 owner_type = type;
1135 param_name += l + 2;
1136 pspec = param_spec_ht_lookup (hash_table: pool->hash_table, param_name, owner_type, walk_ancestors);
1137 g_mutex_unlock (mutex: &pool->mutex);
1138
1139 return pspec;
1140 }
1141 }
1142 /* malformed param_name */
1143
1144 g_mutex_unlock (mutex: &pool->mutex);
1145
1146 return NULL;
1147}
1148
1149static void
1150pool_list (gpointer key,
1151 gpointer value,
1152 gpointer user_data)
1153{
1154 GParamSpec *pspec = value;
1155 gpointer *data = user_data;
1156 GType owner_type = (GType) data[1];
1157
1158 if (owner_type == pspec->owner_type)
1159 data[0] = g_list_prepend (list: data[0], data: pspec);
1160}
1161
1162/**
1163 * g_param_spec_pool_list_owned:
1164 * @pool: a #GParamSpecPool
1165 * @owner_type: the owner to look for
1166 *
1167 * Gets an #GList of all #GParamSpecs owned by @owner_type in
1168 * the pool.
1169 *
1170 * Returns: (transfer container) (element-type GObject.ParamSpec): a
1171 * #GList of all #GParamSpecs owned by @owner_type in
1172 * the pool#GParamSpecs.
1173 */
1174GList*
1175g_param_spec_pool_list_owned (GParamSpecPool *pool,
1176 GType owner_type)
1177{
1178 gpointer data[2];
1179
1180 g_return_val_if_fail (pool != NULL, NULL);
1181 g_return_val_if_fail (owner_type > 0, NULL);
1182
1183 g_mutex_lock (mutex: &pool->mutex);
1184 data[0] = NULL;
1185 data[1] = (gpointer) owner_type;
1186 g_hash_table_foreach (hash_table: pool->hash_table, func: pool_list, user_data: &data);
1187 g_mutex_unlock (mutex: &pool->mutex);
1188
1189 return data[0];
1190}
1191
1192static gint
1193pspec_compare_id (gconstpointer a,
1194 gconstpointer b)
1195{
1196 const GParamSpec *pspec1 = a, *pspec2 = b;
1197
1198 if (pspec1->param_id < pspec2->param_id)
1199 return -1;
1200
1201 if (pspec1->param_id > pspec2->param_id)
1202 return 1;
1203
1204 return strcmp (s1: pspec1->name, s2: pspec2->name);
1205}
1206
1207static inline gboolean
1208should_list_pspec (GParamSpec *pspec,
1209 GType owner_type,
1210 GHashTable *ht)
1211{
1212 GParamSpec *found;
1213
1214 /* Remove paramspecs that are redirected, and also paramspecs
1215 * that have are overridden by non-redirected properties.
1216 * The idea is to get the single paramspec for each name that
1217 * best corresponds to what the application sees.
1218 */
1219 if (g_param_spec_get_redirect_target (pspec))
1220 return FALSE;
1221
1222 found = param_spec_ht_lookup (hash_table: ht, param_name: pspec->name, owner_type, TRUE);
1223 if (found != pspec)
1224 {
1225 GParamSpec *redirect = g_param_spec_get_redirect_target (pspec: found);
1226 if (redirect != pspec)
1227 return FALSE;
1228 }
1229
1230 return TRUE;
1231}
1232
1233static void
1234pool_depth_list (gpointer key,
1235 gpointer value,
1236 gpointer user_data)
1237{
1238 GParamSpec *pspec = value;
1239 gpointer *data = user_data;
1240 GSList **slists = data[0];
1241 GType owner_type = (GType) data[1];
1242 GHashTable *ht = data[2];
1243 int *count = data[3];
1244
1245 if (g_type_is_a (type: owner_type, is_a_type: pspec->owner_type) &&
1246 should_list_pspec (pspec, owner_type, ht))
1247 {
1248 if (G_TYPE_IS_INTERFACE (pspec->owner_type))
1249 {
1250 slists[0] = g_slist_prepend (list: slists[0], data: pspec);
1251 *count = *count + 1;
1252 }
1253 else
1254 {
1255 guint d = g_type_depth (type: pspec->owner_type);
1256
1257 slists[d - 1] = g_slist_prepend (list: slists[d - 1], data: pspec);
1258 *count = *count + 1;
1259 }
1260 }
1261}
1262
1263/* We handle interfaces specially since we don't want to
1264 * count interface prerequisites like normal inheritance;
1265 * the property comes from the direct inheritance from
1266 * the prerequisite class, not from the interface that
1267 * prerequires it.
1268 *
1269 * also 'depth' isn't a meaningful concept for interface
1270 * prerequites.
1271 */
1272static void
1273pool_depth_list_for_interface (gpointer key,
1274 gpointer value,
1275 gpointer user_data)
1276{
1277 GParamSpec *pspec = value;
1278 gpointer *data = user_data;
1279 GSList **slists = data[0];
1280 GType owner_type = (GType) data[1];
1281 GHashTable *ht = data[2];
1282 int *count = data[3];
1283
1284 if (pspec->owner_type == owner_type &&
1285 should_list_pspec (pspec, owner_type, ht))
1286 {
1287 slists[0] = g_slist_prepend (list: slists[0], data: pspec);
1288 *count = *count + 1;
1289 }
1290}
1291
1292/**
1293 * g_param_spec_pool_list:
1294 * @pool: a #GParamSpecPool
1295 * @owner_type: the owner to look for
1296 * @n_pspecs_p: (out): return location for the length of the returned array
1297 *
1298 * Gets an array of all #GParamSpecs owned by @owner_type in
1299 * the pool.
1300 *
1301 * Returns: (array length=n_pspecs_p) (transfer container): a newly
1302 * allocated array containing pointers to all #GParamSpecs
1303 * owned by @owner_type in the pool
1304 */
1305GParamSpec**
1306g_param_spec_pool_list (GParamSpecPool *pool,
1307 GType owner_type,
1308 guint *n_pspecs_p)
1309{
1310 GParamSpec **pspecs, **p;
1311 GSList **slists, *node;
1312 gpointer data[4];
1313 guint d, i;
1314 int n_pspecs = 0;
1315
1316 g_return_val_if_fail (pool != NULL, NULL);
1317 g_return_val_if_fail (owner_type > 0, NULL);
1318 g_return_val_if_fail (n_pspecs_p != NULL, NULL);
1319
1320 g_mutex_lock (mutex: &pool->mutex);
1321 d = g_type_depth (type: owner_type);
1322 slists = g_new0 (GSList*, d);
1323 data[0] = slists;
1324 data[1] = (gpointer) owner_type;
1325 data[2] = pool->hash_table;
1326 data[3] = &n_pspecs;
1327
1328 g_hash_table_foreach (hash_table: pool->hash_table,
1329 G_TYPE_IS_INTERFACE (owner_type) ?
1330 pool_depth_list_for_interface :
1331 pool_depth_list,
1332 user_data: &data);
1333
1334 pspecs = g_new (GParamSpec*, n_pspecs + 1);
1335 p = pspecs;
1336 for (i = 0; i < d; i++)
1337 {
1338 slists[i] = g_slist_sort (list: slists[i], compare_func: pspec_compare_id);
1339 for (node = slists[i]; node; node = node->next)
1340 *p++ = node->data;
1341 g_slist_free (list: slists[i]);
1342 }
1343 *p++ = NULL;
1344 g_free (mem: slists);
1345 g_mutex_unlock (mutex: &pool->mutex);
1346
1347 *n_pspecs_p = n_pspecs;
1348
1349 return pspecs;
1350}
1351
1352/* --- auxiliary functions --- */
1353typedef struct
1354{
1355 /* class portion */
1356 GType value_type;
1357 void (*finalize) (GParamSpec *pspec);
1358 void (*value_set_default) (GParamSpec *pspec,
1359 GValue *value);
1360 gboolean (*value_validate) (GParamSpec *pspec,
1361 GValue *value);
1362 gint (*values_cmp) (GParamSpec *pspec,
1363 const GValue *value1,
1364 const GValue *value2);
1365} ParamSpecClassInfo;
1366
1367static void
1368param_spec_generic_class_init (gpointer g_class,
1369 gpointer class_data)
1370{
1371 GParamSpecClass *class = g_class;
1372 ParamSpecClassInfo *info = class_data;
1373
1374 class->value_type = info->value_type;
1375 if (info->finalize)
1376 class->finalize = info->finalize; /* optional */
1377 class->value_set_default = info->value_set_default;
1378 if (info->value_validate)
1379 class->value_validate = info->value_validate; /* optional */
1380 class->values_cmp = info->values_cmp;
1381 g_free (mem: class_data);
1382}
1383
1384static void
1385default_value_set_default (GParamSpec *pspec,
1386 GValue *value)
1387{
1388 /* value is already zero initialized */
1389}
1390
1391static gint
1392default_values_cmp (GParamSpec *pspec,
1393 const GValue *value1,
1394 const GValue *value2)
1395{
1396 return memcmp (s1: &value1->data, s2: &value2->data, n: sizeof (value1->data));
1397}
1398
1399/**
1400 * g_param_type_register_static:
1401 * @name: 0-terminated string used as the name of the new #GParamSpec type.
1402 * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
1403 *
1404 * Registers @name as the name of a new static type derived from
1405 * #G_TYPE_PARAM. The type system uses the information contained in
1406 * the #GParamSpecTypeInfo structure pointed to by @info to manage the
1407 * #GParamSpec type and its instances.
1408 *
1409 * Returns: The new type identifier.
1410 */
1411GType
1412g_param_type_register_static (const gchar *name,
1413 const GParamSpecTypeInfo *pspec_info)
1414{
1415 GTypeInfo info = {
1416 sizeof (GParamSpecClass), /* class_size */
1417 NULL, /* base_init */
1418 NULL, /* base_destroy */
1419 param_spec_generic_class_init, /* class_init */
1420 NULL, /* class_destroy */
1421 NULL, /* class_data */
1422 0, /* instance_size */
1423 16, /* n_preallocs */
1424 NULL, /* instance_init */
1425 NULL, /* value_table */
1426 };
1427 ParamSpecClassInfo *cinfo;
1428
1429 g_return_val_if_fail (name != NULL, 0);
1430 g_return_val_if_fail (pspec_info != NULL, 0);
1431 g_return_val_if_fail (g_type_from_name (name) == 0, 0);
1432 g_return_val_if_fail (pspec_info->instance_size >= sizeof (GParamSpec), 0);
1433 g_return_val_if_fail (g_type_name (pspec_info->value_type) != NULL, 0);
1434 /* default: g_return_val_if_fail (pspec_info->value_set_default != NULL, 0); */
1435 /* optional: g_return_val_if_fail (pspec_info->value_validate != NULL, 0); */
1436 /* default: g_return_val_if_fail (pspec_info->values_cmp != NULL, 0); */
1437
1438 info.instance_size = pspec_info->instance_size;
1439 info.n_preallocs = pspec_info->n_preallocs;
1440 info.instance_init = (GInstanceInitFunc) pspec_info->instance_init;
1441 cinfo = g_new (ParamSpecClassInfo, 1);
1442 cinfo->value_type = pspec_info->value_type;
1443 cinfo->finalize = pspec_info->finalize;
1444 cinfo->value_set_default = pspec_info->value_set_default ? pspec_info->value_set_default : default_value_set_default;
1445 cinfo->value_validate = pspec_info->value_validate;
1446 cinfo->values_cmp = pspec_info->values_cmp ? pspec_info->values_cmp : default_values_cmp;
1447 info.class_data = cinfo;
1448
1449 return g_type_register_static (G_TYPE_PARAM, type_name: name, info: &info, flags: 0);
1450}
1451
1452/**
1453 * g_value_set_param:
1454 * @value: a valid #GValue of type %G_TYPE_PARAM
1455 * @param: (nullable): the #GParamSpec to be set
1456 *
1457 * Set the contents of a %G_TYPE_PARAM #GValue to @param.
1458 */
1459void
1460g_value_set_param (GValue *value,
1461 GParamSpec *param)
1462{
1463 g_return_if_fail (G_VALUE_HOLDS_PARAM (value));
1464 if (param)
1465 g_return_if_fail (G_IS_PARAM_SPEC (param));
1466
1467 if (value->data[0].v_pointer)
1468 g_param_spec_unref (pspec: value->data[0].v_pointer);
1469 value->data[0].v_pointer = param;
1470 if (value->data[0].v_pointer)
1471 g_param_spec_ref (pspec: value->data[0].v_pointer);
1472}
1473
1474/**
1475 * g_value_set_param_take_ownership: (skip)
1476 * @value: a valid #GValue of type %G_TYPE_PARAM
1477 * @param: (nullable): the #GParamSpec to be set
1478 *
1479 * This is an internal function introduced mainly for C marshallers.
1480 *
1481 * Deprecated: 2.4: Use g_value_take_param() instead.
1482 */
1483void
1484g_value_set_param_take_ownership (GValue *value,
1485 GParamSpec *param)
1486{
1487 g_value_take_param (value, param);
1488}
1489
1490/**
1491 * g_value_take_param: (skip)
1492 * @value: a valid #GValue of type %G_TYPE_PARAM
1493 * @param: (nullable): the #GParamSpec to be set
1494 *
1495 * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
1496 * over the ownership of the caller’s reference to @param; the caller
1497 * doesn’t have to unref it any more.
1498 *
1499 * Since: 2.4
1500 */
1501void
1502g_value_take_param (GValue *value,
1503 GParamSpec *param)
1504{
1505 g_return_if_fail (G_VALUE_HOLDS_PARAM (value));
1506 if (param)
1507 g_return_if_fail (G_IS_PARAM_SPEC (param));
1508
1509 if (value->data[0].v_pointer)
1510 g_param_spec_unref (pspec: value->data[0].v_pointer);
1511 value->data[0].v_pointer = param; /* we take over the reference count */
1512}
1513
1514/**
1515 * g_value_get_param:
1516 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1517 *
1518 * Get the contents of a %G_TYPE_PARAM #GValue.
1519 *
1520 * Returns: (transfer none): #GParamSpec content of @value
1521 */
1522GParamSpec*
1523g_value_get_param (const GValue *value)
1524{
1525 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value), NULL);
1526
1527 return value->data[0].v_pointer;
1528}
1529
1530/**
1531 * g_value_dup_param: (skip)
1532 * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
1533 *
1534 * Get the contents of a %G_TYPE_PARAM #GValue, increasing its
1535 * reference count.
1536 *
1537 * Returns: (transfer full): #GParamSpec content of @value, should be
1538 * unreferenced when no longer needed.
1539 */
1540GParamSpec*
1541g_value_dup_param (const GValue *value)
1542{
1543 g_return_val_if_fail (G_VALUE_HOLDS_PARAM (value), NULL);
1544
1545 return value->data[0].v_pointer ? g_param_spec_ref (pspec: value->data[0].v_pointer) : NULL;
1546}
1547
1548/**
1549 * g_param_spec_get_default_value:
1550 * @pspec: a #GParamSpec
1551 *
1552 * Gets the default value of @pspec as a pointer to a #GValue.
1553 *
1554 * The #GValue will remain valid for the life of @pspec.
1555 *
1556 * Returns: a pointer to a #GValue which must not be modified
1557 *
1558 * Since: 2.38
1559 **/
1560const GValue *
1561g_param_spec_get_default_value (GParamSpec *pspec)
1562{
1563 GParamSpecPrivate *priv = g_param_spec_get_private (pspec);
1564
1565 /* We use the type field of the GValue as the key for the once because
1566 * it will be zero before it is initialised and non-zero after. We
1567 * have to take care that we don't write a non-zero value to the type
1568 * field before we are completely done, however, because then another
1569 * thread could come along and find the value partially-initialised.
1570 *
1571 * In order to accomplish this we store the default value in a
1572 * stack-allocated GValue. We then set the type field in that value
1573 * to zero and copy the contents into place. We then end by storing
1574 * the type as the last step in order to ensure that we're completely
1575 * done before a g_once_init_enter() could take the fast path in
1576 * another thread.
1577 */
1578 if (g_once_init_enter (&priv->default_value.g_type))
1579 {
1580 GValue default_value = G_VALUE_INIT;
1581
1582 g_value_init (value: &default_value, g_type: pspec->value_type);
1583 g_param_value_set_default (pspec, value: &default_value);
1584
1585 /* store all but the type */
1586 memcpy (dest: priv->default_value.data, src: default_value.data, n: sizeof (default_value.data));
1587
1588 g_once_init_leave (&priv->default_value.g_type, pspec->value_type);
1589 }
1590
1591 return &priv->default_value;
1592}
1593
1594/**
1595 * g_param_spec_get_name_quark:
1596 * @pspec: a #GParamSpec
1597 *
1598 * Gets the GQuark for the name.
1599 *
1600 * Returns: the GQuark for @pspec->name.
1601 *
1602 * Since: 2.46
1603 */
1604GQuark
1605g_param_spec_get_name_quark (GParamSpec *pspec)
1606{
1607 GParamSpecPrivate *priv = g_param_spec_get_private (pspec);
1608
1609 /* Return the quark that we've stashed away at creation time.
1610 * This lets us avoid a lock and a hash table lookup when
1611 * dispatching property change notification.
1612 */
1613
1614 return priv->name_quark;
1615}
1616

source code of gtk/subprojects/glib/gobject/gparam.c