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 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, write to the 16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 17 * Boston, MA 02111-1307, USA. 18 * 19 * gparam.h: GParamSpec base class implementation 20 */ 21 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) 22 #error "Only <glib-object.h> can be included directly." 23 #endif 24 25 #ifndef __G_PARAM_H__ 26 #define __G_PARAM_H__ 27 28 #include <gobject/gvalue.h> 29 30 G_BEGIN_DECLS 31 32 /* --- standard type macros --- */ 33 /** 34 * G_TYPE_IS_PARAM: 35 * @type: a #GType ID 36 * 37 * Checks whether @type "is a" %G_TYPE_PARAM. 38 */ 39 #define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM) 40 /** 41 * G_PARAM_SPEC: 42 * @pspec: a valid #GParamSpec 43 * 44 * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into 45 * a #GParamSpec object. 46 */ 47 #define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec)) 48 /** 49 * G_IS_PARAM_SPEC: 50 * @pspec: a #GParamSpec 51 * 52 * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM 53 * or derived. 54 */ 55 #define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM)) 56 /** 57 * G_PARAM_SPEC_CLASS: 58 * @pclass: a valid #GParamSpecClass 59 * 60 * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. 61 */ 62 #define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass)) 63 /** 64 * G_IS_PARAM_SPEC_CLASS: 65 * @pclass: a #GParamSpecClass 66 * 67 * Checks whether @pclass "is a" valid #GParamSpecClass structure of type 68 * %G_TYPE_PARAM or derived. 69 */ 70 #define G_IS_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM)) 71 /** 72 * G_PARAM_SPEC_GET_CLASS: 73 * @pspec: a valid #GParamSpec 74 * 75 * Retrieves the #GParamSpecClass of a #GParamSpec. 76 */ 77 #define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass)) 78 79 80 /* --- convenience macros --- */ 81 /** 82 * G_PARAM_SPEC_TYPE: 83 * @pspec: a valid #GParamSpec 84 * 85 * Retrieves the #GType of this @pspec. 86 */ 87 #define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec)) 88 /** 89 * G_PARAM_SPEC_TYPE_NAME: 90 * @pspec: a valid #GParamSpec 91 * 92 * Retrieves the #GType name of this @pspec. 93 */ 94 #define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec))) 95 /** 96 * G_PARAM_SPEC_VALUE_TYPE: 97 * @pspec: a valid #GParamSpec 98 * 99 * Retrieves the #GType to initialize a #GValue for this parameter. 100 */ 101 #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type) 102 /** 103 * G_VALUE_HOLDS_PARAM: 104 * @value: a valid #GValue structure 105 * 106 * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. 107 * 108 * Returns: %TRUE on success. 109 */ 110 #define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM)) 111 112 113 /* --- flags --- */ 114 /** 115 * GParamFlags: 116 * @G_PARAM_READABLE: the parameter is readable 117 * @G_PARAM_WRITABLE: the parameter is writable 118 * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction 119 * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction 120 * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) 121 * strict validation is not required 122 * @G_PARAM_STATIC_NAME: the string used as name when constructing the 123 * parameter is guaranteed to remain valid and 124 * unmodified for the lifetime of the parameter. 125 * Since 2.8 126 * @G_PARAM_STATIC_NICK: the string used as nick when constructing the 127 * parameter is guaranteed to remain valid and 128 * unmmodified for the lifetime of the parameter. 129 * Since 2.8 130 * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the 131 * parameter is guaranteed to remain valid and 132 * unmodified for the lifetime of the parameter. 133 * Since 2.8 134 * @G_PARAM_PRIVATE: internal 135 * 136 * Through the #GParamFlags flag values, certain aspects of parameters 137 * can be configured. 138 */ 139 typedef enum 140 { 141 G_PARAM_READABLE = 1 << 0, 142 G_PARAM_WRITABLE = 1 << 1, 143 G_PARAM_CONSTRUCT = 1 << 2, 144 G_PARAM_CONSTRUCT_ONLY = 1 << 3, 145 G_PARAM_LAX_VALIDATION = 1 << 4, 146 G_PARAM_STATIC_NAME = 1 << 5, 147 #ifndef G_DISABLE_DEPRECATED 148 G_PARAM_PRIVATE = G_PARAM_STATIC_NAME, 149 #endif 150 G_PARAM_STATIC_NICK = 1 << 6, 151 G_PARAM_STATIC_BLURB = 1 << 7 152 } GParamFlags; 153 /** 154 * G_PARAM_READWRITE: 155 * 156 * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. 157 */ 158 #define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE) 159 /** 160 * G_PARAM_STATIC_STRINGS: 161 * 162 * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. 163 * 164 * Since 2.13.0 165 */ 166 #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB) 167 /* bits in the range 0xffffff00 are reserved for 3rd party usage */ 168 /** 169 * G_PARAM_MASK: 170 * 171 * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. 172 */ 173 #define G_PARAM_MASK (0x000000ff) 174 /** 175 * G_PARAM_USER_SHIFT: 176 * 177 * Minimum shift count to be used for user defined flags, to be stored in 178 * #GParamSpec.flags. 179 */ 180 #define G_PARAM_USER_SHIFT (8) 181 182 183 /* --- typedefs & structures --- */ 184 typedef struct _GParamSpec GParamSpec; 185 typedef struct _GParamSpecClass GParamSpecClass; 186 typedef struct _GParameter GParameter; 187 typedef struct _GParamSpecPool GParamSpecPool; 188 /** 189 * GParamSpec: 190 * @g_type_instance: private #GTypeInstance portion 191 * @name: name of this parameter 192 * @flags: #GParamFlags flags for this parameter 193 * @value_type: the #GValue type for this parameter 194 * @owner_type: #GType type that uses (introduces) this paremeter 195 * 196 * All other fields of the <structname>GParamSpec</structname> struct are private and 197 * should not be used directly. 198 */ 199 struct _GParamSpec 200 { 201 GTypeInstance g_type_instance; 202 203 gchar *name; 204 GParamFlags flags; 205 GType value_type; 206 GType owner_type; /* class or interface using this property */ 207 208 /*< private >*/ 209 gchar *_nick; 210 gchar *_blurb; 211 GData *qdata; 212 guint ref_count; 213 guint param_id; /* sort-criteria */ 214 }; 215 /** 216 * GParamSpecClass: 217 * @g_type_class: the parent class 218 * @value_type: the #GValue type for this parameter 219 * @finalize: The instance finalization function (optional), should chain 220 * up to the finalize method of the parent class. 221 * @value_set_default: Resets a @value to the default value for this type 222 * (recommended, the default is g_value_reset()), see 223 * g_param_value_set_default(). 224 * @value_validate: Ensures that the contents of @value comply with the 225 * specifications set out by this type (optional), see 226 * g_param_value_set_validate(). 227 * @values_cmp: Compares @value1 with @value2 according to this type 228 * (recommended, the default is memcmp()), see g_param_values_cmp(). 229 * 230 * The class structure for the <structname>GParamSpec</structname> type. 231 * Normally, <structname>GParamSpec</structname> classes are filled by 232 * g_param_type_register_static(). 233 */ 234 struct _GParamSpecClass 235 { 236 GTypeClass g_type_class; 237 238 GType value_type; 239 240 void (*finalize) (GParamSpec *pspec); 241 242 /* GParam methods */ 243 void (*value_set_default) (GParamSpec *pspec, 244 GValue *value); 245 gboolean (*value_validate) (GParamSpec *pspec, 246 GValue *value); 247 gint (*values_cmp) (GParamSpec *pspec, 248 const GValue *value1, 249 const GValue *value2); 250 /*< private >*/ 251 gpointer dummy[4]; 252 }; 253 /** 254 * GParameter: 255 * @name: the parameter name 256 * @value: the parameter value 257 * 258 * The <structname>GParameter</structname> struct is an auxiliary structure used 259 * to hand parameter name/value pairs to g_object_newv(). 260 */ 261 struct _GParameter /* auxillary structure for _setv() variants */ 262 { 263 const gchar *name; 264 GValue value; 265 }; 266 267 268 /* --- prototypes --- */ 269 GParamSpec* g_param_spec_ref (GParamSpec *pspec); 270 void g_param_spec_unref (GParamSpec *pspec); 271 void g_param_spec_sink (GParamSpec *pspec); 272 GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec); 273 gpointer g_param_spec_get_qdata (GParamSpec *pspec, 274 GQuark quark); 275 void g_param_spec_set_qdata (GParamSpec *pspec, 276 GQuark quark, 277 gpointer data); 278 void g_param_spec_set_qdata_full (GParamSpec *pspec, 279 GQuark quark, 280 gpointer data, 281 GDestroyNotify destroy); 282 gpointer g_param_spec_steal_qdata (GParamSpec *pspec, 283 GQuark quark); 284 GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec); 285 286 void g_param_value_set_default (GParamSpec *pspec, 287 GValue *value); 288 gboolean g_param_value_defaults (GParamSpec *pspec, 289 GValue *value); 290 gboolean g_param_value_validate (GParamSpec *pspec, 291 GValue *value); 292 gboolean g_param_value_convert (GParamSpec *pspec, 293 const GValue *src_value, 294 GValue *dest_value, 295 gboolean strict_validation); 296 gint g_param_values_cmp (GParamSpec *pspec, 297 const GValue *value1, 298 const GValue *value2); 299 G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec); 300 G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec); 301 G_CONST_RETURN gchar* g_param_spec_get_blurb (GParamSpec *pspec); 302 void g_value_set_param (GValue *value, 303 GParamSpec *param); 304 GParamSpec* g_value_get_param (const GValue *value); 305 GParamSpec* g_value_dup_param (const GValue *value); 306 307 308 void g_value_take_param (GValue *value, 309 GParamSpec *param); 310 #ifndef G_DISABLE_DEPRECATED 311 void g_value_set_param_take_ownership (GValue *value, 312 GParamSpec *param); 313 #endif 314 315 /* --- convenience functions --- */ 316 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo; 317 /** 318 * GParamSpecTypeInfo: 319 * @instance_size: Size of the instance (object) structure. 320 * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. 321 * @instance_init: Location of the instance initialization function (optional). 322 * @value_type: The #GType of values conforming to this #GParamSpec 323 * @finalize: The instance finalization function (optional). 324 * @value_set_default: Resets a @value to the default value for @pspec 325 * (recommended, the default is g_value_reset()), see 326 * g_param_value_set_default(). 327 * @value_validate: Ensures that the contents of @value comply with the 328 * specifications set out by @pspec (optional), see 329 * g_param_value_set_validate(). 330 * @values_cmp: Compares @value1 with @value2 according to @pspec 331 * (recommended, the default is memcmp()), see g_param_values_cmp(). 332 * 333 * This structure is used to provide the type system with the information 334 * required to initialize and destruct (finalize) a parameter's class and 335 * instances thereof. 336 * The initialized structure is passed to the g_param_type_register_static() 337 * The type system will perform a deep copy of this structure, so its memory 338 * does not need to be persistent across invocation of 339 * g_param_type_register_static(). 340 */ 341 struct _GParamSpecTypeInfo 342 { 343 /* type system portion */ 344 guint16 instance_size; /* obligatory */ 345 guint16 n_preallocs; /* optional */ 346 void (*instance_init) (GParamSpec *pspec); /* optional */ 347 348 /* class portion */ 349 GType value_type; /* obligatory */ 350 void (*finalize) (GParamSpec *pspec); /* optional */ 351 void (*value_set_default) (GParamSpec *pspec, /* recommended */ 352 GValue *value); 353 gboolean (*value_validate) (GParamSpec *pspec, /* optional */ 354 GValue *value); 355 gint (*values_cmp) (GParamSpec *pspec, /* recommended */ 356 const GValue *value1, 357 const GValue *value2); 358 }; 359 GType g_param_type_register_static (const gchar *name, 360 const GParamSpecTypeInfo *pspec_info); 361 362 /* For registering builting types */ 363 GType _g_param_type_register_static_constant (const gchar *name, 364 const GParamSpecTypeInfo *pspec_info, 365 GType opt_type); 366 367 368 /* --- protected --- */ 369 gpointer g_param_spec_internal (GType param_type, 370 const gchar *name, 371 const gchar *nick, 372 const gchar *blurb, 373 GParamFlags flags); 374 GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing); 375 void g_param_spec_pool_insert (GParamSpecPool *pool, 376 GParamSpec *pspec, 377 GType owner_type); 378 void g_param_spec_pool_remove (GParamSpecPool *pool, 379 GParamSpec *pspec); 380 GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool, 381 const gchar *param_name, 382 GType owner_type, 383 gboolean walk_ancestors); 384 GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, 385 GType owner_type); 386 GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, 387 GType owner_type, 388 guint *n_pspecs_p); 389 390 391 392 /* contracts: 393 * 394 * gboolean value_validate (GParamSpec *pspec, 395 * GValue *value): 396 * modify value contents in the least destructive way, so 397 * that it complies with pspec's requirements (i.e. 398 * according to minimum/maximum ranges etc...). return 399 * whether modification was necessary. 400 * 401 * gint values_cmp (GParamSpec *pspec, 402 * const GValue *value1, 403 * const GValue *value2): 404 * return value1 - value2, i.e. (-1) if value1 < value2, 405 * (+1) if value1 > value2, and (0) otherwise (equality) 406 */ 407 408 G_END_DECLS 409 410 #endif /* __G_PARAM_H__ */ 411
