1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 1997, 1998, 1999, 2000 Tim Janik and Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
27 #define G_PARAM_SPEC_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_PARAM, GParamSpecClass))
30 /* --- prototypes --- */
31 static void g_param_spec_class_base_init (GParamSpecClass *class);
32 static void g_param_spec_class_base_finalize (GParamSpecClass *class);
33 static void g_param_spec_class_init (GParamSpecClass *class,
35 static void g_param_spec_init (GParamSpec *pspec);
36 static void g_param_spec_finalize (GParamSpec *pspec);
39 /* --- functions --- */
41 g_param_type_init (void) /* sync with gtype.c */
43 static const GTypeFundamentalInfo finfo = {
44 (G_TYPE_FLAG_CLASSED |
45 G_TYPE_FLAG_INSTANTIATABLE |
46 G_TYPE_FLAG_DERIVABLE |
47 G_TYPE_FLAG_DEEP_DERIVABLE),
49 static const GTypeInfo param_spec_info = {
50 sizeof (GParamSpecClass),
52 (GBaseInitFunc) g_param_spec_class_base_init,
53 (GBaseFinalizeFunc) g_param_spec_class_base_finalize,
54 (GClassInitFunc) g_param_spec_class_init,
55 (GClassFinalizeFunc) NULL,
56 NULL, /* class_data */
60 (GInstanceInitFunc) g_param_spec_init,
62 NULL, /* value_table */
66 type = g_type_register_fundamental (G_TYPE_PARAM, "GParam", ¶m_spec_info, &finfo, G_TYPE_FLAG_ABSTRACT);
67 g_assert (type == G_TYPE_PARAM);
71 g_param_spec_class_base_init (GParamSpecClass *class)
76 g_param_spec_class_base_finalize (GParamSpecClass *class)
81 g_param_spec_class_init (GParamSpecClass *class,
84 class->value_type = G_TYPE_NONE;
85 class->finalize = g_param_spec_finalize;
86 class->value_set_default = NULL;
87 class->value_validate = NULL;
88 class->values_cmp = NULL;
92 g_param_spec_init (GParamSpec *pspec)
98 pspec->owner_type = 0;
100 pspec->ref_count = 1;
104 g_param_spec_finalize (GParamSpec *pspec)
106 g_datalist_clear (&pspec->qdata);
108 g_free (pspec->name);
109 g_free (pspec->nick);
110 g_free (pspec->blurb);
112 g_type_free_instance ((GTypeInstance*) pspec);
116 g_param_spec_ref (GParamSpec *pspec)
118 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
119 g_return_val_if_fail (pspec->ref_count > 0, NULL);
121 pspec->ref_count += 1;
127 g_param_spec_unref (GParamSpec *pspec)
129 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
130 g_return_if_fail (pspec->ref_count > 0);
132 pspec->ref_count -= 1;
133 if (pspec->ref_count == 0)
134 G_PARAM_SPEC_GET_CLASS (pspec)->finalize (pspec);
138 g_param_spec_internal (GType param_type,
146 g_return_val_if_fail (G_TYPE_IS_PARAM (param_type) && param_type != G_TYPE_PARAM, NULL);
147 g_return_val_if_fail (name != NULL, NULL);
149 pspec = (gpointer) g_type_create_instance (param_type);
150 pspec->name = g_strdup (name);
151 g_strcanon (pspec->name, G_CSET_A_2_Z G_CSET_a_2_z G_CSET_DIGITS "-", '-');
152 pspec->nick = g_strdup (nick ? nick : pspec->name);
153 pspec->blurb = g_strdup (blurb);
154 pspec->flags = (flags & G_PARAM_USER_MASK) | (flags & G_PARAM_MASK);
160 g_param_spec_get_qdata (GParamSpec *pspec,
163 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
165 return quark ? g_datalist_id_get_data (&pspec->qdata, quark) : NULL;
169 g_param_spec_set_qdata (GParamSpec *pspec,
173 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
174 g_return_if_fail (quark > 0);
176 g_datalist_id_set_data (&pspec->qdata, quark, data);
180 g_param_spec_set_qdata_full (GParamSpec *pspec,
183 GDestroyNotify destroy)
185 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
186 g_return_if_fail (quark > 0);
188 g_datalist_id_set_data_full (&pspec->qdata, quark, data, data ? destroy : (GDestroyNotify) NULL);
192 g_param_spec_steal_qdata (GParamSpec *pspec,
195 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), NULL);
196 g_return_val_if_fail (quark > 0, NULL);
198 return g_datalist_id_remove_no_notify (&pspec->qdata, quark);
202 g_param_value_set_default (GParamSpec *pspec,
205 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
206 g_return_if_fail (G_IS_VALUE (value));
207 g_return_if_fail (G_IS_PARAM_VALUE (pspec, value));
209 g_value_reset (value);
210 G_PARAM_SPEC_GET_CLASS (pspec)->value_set_default (pspec, value);
214 g_param_value_defaults (GParamSpec *pspec,
217 GValue dflt_value = { 0, };
220 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), FALSE);
221 g_return_val_if_fail (G_IS_VALUE (value), FALSE);
222 g_return_val_if_fail (G_IS_PARAM_VALUE (pspec, value), FALSE);
224 g_value_init (&dflt_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
225 G_PARAM_SPEC_GET_CLASS (pspec)->value_set_default (pspec, &dflt_value);
226 defaults = G_PARAM_SPEC_GET_CLASS (pspec)->values_cmp (pspec, value, &dflt_value) == 0;
227 g_value_unset (&dflt_value);
233 g_param_value_validate (GParamSpec *pspec,
236 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), FALSE);
237 g_return_val_if_fail (G_IS_VALUE (value), FALSE);
238 g_return_val_if_fail (G_IS_PARAM_VALUE (pspec, value), FALSE);
240 if (G_PARAM_SPEC_GET_CLASS (pspec)->value_validate)
242 GValue oval = *value;
244 if (G_PARAM_SPEC_GET_CLASS (pspec)->value_validate (pspec, value) ||
245 memcmp (&oval.data, &value->data, sizeof (oval.data)))
253 g_param_values_cmp (GParamSpec *pspec,
254 const GValue *value1,
255 const GValue *value2)
259 /* param_values_cmp() effectively does: value1 - value2
260 * so the return values are:
261 * -1) value1 < value2
262 * 0) value1 == value2
265 g_return_val_if_fail (G_IS_PARAM_SPEC (pspec), 0);
266 g_return_val_if_fail (G_IS_VALUE (value1), 0);
267 g_return_val_if_fail (G_IS_VALUE (value2), 0);
268 g_return_val_if_fail (G_IS_PARAM_VALUE (pspec, value1), 0);
269 g_return_val_if_fail (G_IS_PARAM_VALUE (pspec, value2), 0);
271 cmp = G_PARAM_SPEC_GET_CLASS (pspec)->values_cmp (pspec, value1, value2);
273 return CLAMP (cmp, -1, 1);
277 param_spec_hash (gconstpointer key_spec)
279 const GParamSpec *key = key_spec;
281 guint h = key->owner_type;
283 for (p = key->name; *p; p++)
284 h = (h << 5) - h + *p;
290 param_spec_equals (gconstpointer key_spec_1,
291 gconstpointer key_spec_2)
293 const GParamSpec *key1 = key_spec_1;
294 const GParamSpec *key2 = key_spec_2;
296 return (key1->owner_type == key2->owner_type &&
297 strcmp (key1->name, key2->name) == 0);
301 g_param_spec_hash_table_new (void)
303 return g_hash_table_new (param_spec_hash, param_spec_equals);
307 g_param_spec_hash_table_insert (GHashTable *hash_table,
311 g_return_if_fail (hash_table != NULL);
312 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
313 g_return_if_fail (pspec->name != NULL);
314 if (pspec->owner_type != owner_type)
315 g_return_if_fail (pspec->owner_type == 0);
317 if (strchr (pspec->name, ':'))
318 g_warning (G_STRLOC ": parameter name `%s' contains field-delimeter",
322 pspec->owner_type = owner_type;
323 g_hash_table_insert (hash_table, pspec, pspec);
328 g_param_spec_hash_table_remove (GHashTable *hash_table,
331 g_return_if_fail (hash_table != NULL);
332 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
334 g_assert (g_param_spec_hash_table_lookup (hash_table, pspec->name, pspec->owner_type, FALSE, NULL) != NULL); /* FIXME: paranoid */
336 g_hash_table_remove (hash_table, pspec);
337 g_assert (g_param_spec_hash_table_lookup (hash_table, pspec->name, pspec->owner_type, FALSE, NULL) == NULL); /* FIXME: paranoid */
338 pspec->owner_type = 0;
342 g_param_spec_hash_table_lookup (GHashTable *hash_table,
343 const gchar *param_name,
345 gboolean try_ancestors,
346 const gchar **trailer)
352 g_return_val_if_fail (hash_table != NULL, NULL);
353 g_return_val_if_fail (param_name != NULL, NULL);
355 key.owner_type = owner_type;
356 delim = strchr (param_name, ':');
358 key.name = g_strndup (param_name, delim - param_name);
360 key.name = g_strdup (param_name);
361 g_strcanon (key.name, G_CSET_A_2_Z G_CSET_a_2_z G_CSET_DIGITS "-", '-');
366 pspec = g_hash_table_lookup (hash_table, &key);
367 if (!pspec && try_ancestors)
369 key.owner_type = g_type_parent (key.owner_type);
370 while (key.owner_type)
372 pspec = g_hash_table_lookup (hash_table, &key);
375 key.owner_type = g_type_parent (key.owner_type);
385 /* --- auxillary functions --- */
390 void (*finalize) (GParamSpec *pspec);
391 void (*value_set_default) (GParamSpec *pspec,
393 gboolean (*value_validate) (GParamSpec *pspec,
395 gint (*values_cmp) (GParamSpec *pspec,
396 const GValue *value1,
397 const GValue *value2);
398 } ParamSpecClassInfo;
401 param_spec_generic_class_init (gpointer g_class,
404 GParamSpecClass *class = g_class;
405 ParamSpecClassInfo *info = class_data;
407 class->value_type = info->value_type;
409 class->finalize = info->finalize; /* optional */
410 class->value_set_default = info->value_set_default;
411 if (info->value_validate)
412 class->value_validate = info->value_validate; /* optional */
413 class->values_cmp = info->values_cmp;
418 default_value_set_default (GParamSpec *pspec,
421 /* value is already zero initialized */
425 default_values_cmp (GParamSpec *pspec,
426 const GValue *value1,
427 const GValue *value2)
429 return memcmp (&value1->data, &value2->data, sizeof (value1->data));
433 g_param_type_register_static (const gchar *name,
434 const GParamSpecTypeInfo *pspec_info)
437 sizeof (GParamSpecClass), /* class_size */
438 NULL, /* base_init */
439 NULL, /* base_destroy */
440 param_spec_generic_class_init, /* class_init */
441 NULL, /* class_destroy */
442 NULL, /* class_data */
443 0, /* instance_size */
444 16, /* n_preallocs */
445 NULL, /* instance_init */
447 ParamSpecClassInfo *cinfo;
449 g_return_val_if_fail (name != NULL, 0);
450 g_return_val_if_fail (pspec_info != NULL, 0);
451 g_return_val_if_fail (g_type_from_name (name) == 0, 0);
452 g_return_val_if_fail (pspec_info->instance_size >= sizeof (GParamSpec), 0);
453 g_return_val_if_fail (g_type_name (pspec_info->value_type) != NULL, 0);
454 /* default: g_return_val_if_fail (pspec_info->value_set_default != NULL, 0); */
455 /* optional: g_return_val_if_fail (pspec_info->value_validate != NULL, 0); */
456 /* default: g_return_val_if_fail (pspec_info->values_cmp != NULL, 0); */
458 info.instance_size = pspec_info->instance_size;
459 info.n_preallocs = pspec_info->n_preallocs;
460 info.instance_init = (GInstanceInitFunc) pspec_info->instance_init;
461 cinfo = g_new (ParamSpecClassInfo, 1);
462 cinfo->value_type = pspec_info->value_type;
463 cinfo->finalize = pspec_info->finalize;
464 cinfo->value_set_default = pspec_info->value_set_default ? pspec_info->value_set_default : default_value_set_default;
465 cinfo->value_validate = pspec_info->value_validate;
466 cinfo->values_cmp = pspec_info->values_cmp ? pspec_info->values_cmp : default_values_cmp;
467 info.class_data = cinfo;
469 return g_type_register_static (G_TYPE_PARAM, name, &info, 0);