gobject/gparam.h

   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 #define G_VALUE_HOLDS_PARAM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
 103
 104
 105 /* --- flags --- */
 106 /**
 107  * GParamFlags:
 108  * @G_PARAM_READABLE: the parameter is readable
 109  * @G_PARAM_WRITABLE: the parameter is writable
 110  * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
 111  * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
 112  * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert())
 113  *  strict validation is not required
 114  * @G_PARAM_STATIC_NAME: the string used as name when constructing the
 115  *  parameter is guaranteed to remain valid and
 116  *  unmodified for the lifetime of the parameter.
 117  *  Since 2.8
 118  * @G_PARAM_STATIC_NICK: the string used as nick when constructing the
 119  *  parameter is guaranteed to remain valid and
 120  *  unmmodified for the lifetime of the parameter.
 121  *  Since 2.8
 122  * @G_PARAM_STATIC_BLURB: the string used as blurb 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_PRIVATE: internal
 127  *
 128  * Through the #GParamFlags flag values, certain aspects of parameters
 129  * can be configured.
 130  */
 131 typedef enum
 132 {
 133   G_PARAM_READABLE            = 1 << 0,
 134   G_PARAM_WRITABLE            = 1 << 1,
 135   G_PARAM_CONSTRUCT           = 1 << 2,
 136   G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
 137   G_PARAM_LAX_VALIDATION      = 1 << 4,
 138   G_PARAM_STATIC_NAME         = 1 << 5,
 139 #ifndef G_DISABLE_DEPRECATED
 140   G_PARAM_PRIVATE             = G_PARAM_STATIC_NAME,
 141 #endif
 142   G_PARAM_STATIC_NICK         = 1 << 6,
 143   G_PARAM_STATIC_BLURB        = 1 << 7
 144 } GParamFlags;
 145 /**
 146  * G_PARAM_READWRITE:
 147  *
 148  * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
 149  */
 150 #define G_PARAM_READWRITE       (G_PARAM_READABLE | G_PARAM_WRITABLE)
 151 /**
 152  * G_PARAM_STATIC_STRINGS:
 153  *
 154  * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
 155  *
 156  * Since 2.13.0
 157  */
 158 #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)
 159 /* bits in the range 0xffffff00 are reserved for 3rd party usage */
 160 /**
 161  * G_PARAM_MASK:
 162  *
 163  * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
 164  */
 165 #define G_PARAM_MASK            (0x000000ff)
 166 /**
 167  * G_PARAM_USER_SHIFT:
 168  *
 169  * Minimum shift count to be used for user defined flags, to be stored in
 170  * #GParamSpec.flags.
 171  */
 172 #define G_PARAM_USER_SHIFT      (8)
 173
 174
 175 /* --- typedefs & structures --- */
 176 typedef struct _GParamSpec      GParamSpec;
 177 typedef struct _GParamSpecClass GParamSpecClass;
 178 typedef struct _GParameter      GParameter;
 179 typedef struct _GParamSpecPool  GParamSpecPool;
 180 /**
 181  * GParamSpec:
 182  * @g_type_instance: private #GTypeInstance portion
 183  * @name: name of this parameter
 184  * @flags: #GParamFlags flags for this parameter
 185  * @value_type: the #GValue type for this parameter
 186  * @owner_type: #GType type that uses (introduces) this paremeter
 187  *
 188  * All other fields of the <structname>GParamSpec</structname> struct are private and
 189  * should not be used directly.
 190  */
 191 struct _GParamSpec
 192 {
 193   GTypeInstance  g_type_instance;
 194
 195   gchar         *name;
 196   GParamFlags    flags;
 197   GType          value_type;
 198   GType          owner_type;    /* class or interface using this property */
 199
 200   /*< private >*/
 201   gchar         *_nick;
 202   gchar         *_blurb;
 203   GData         *qdata;
 204   guint          ref_count;
 205   guint          param_id;      /* sort-criteria */
 206 };
 207 /**
 208  * GParamSpecClass:
 209  * @g_type_class: the parent class
 210  * @value_type: the #GValue type for this parameter
 211  * @finalize: The instance finalization function (optional), should chain
 212  *  up to the finalize method of the parent class.
 213  * @value_set_default: Resets a @value to the default value for this type
 214  *  (recommended, the default is g_value_reset()), see
 215  *  g_param_value_set_default().
 216  * @value_validate: Ensures that the contents of @value comply with the
 217  *  specifications set out by this type (optional), see
 218  *  g_param_value_set_validate().
 219  * @values_cmp: Compares @value1 with @value2 according to this type
 220  *  (recommended, the default is memcmp()), see g_param_values_cmp().
 221  *
 222  * The class structure for the <structname>GParamSpec</structname> type.
 223  * Normally, <structname>GParamSpec</structname> classes are filled by
 224  * g_param_type_register_static().
 225  */
 226 struct _GParamSpecClass
 227 {
 228   GTypeClass      g_type_class;
 229
 230   GType           value_type;
 231
 232   void          (*finalize)             (GParamSpec   *pspec);
 233
 234   /* GParam methods */
 235   void          (*value_set_default)    (GParamSpec   *pspec,
 236                                          GValue       *value);
 237   gboolean      (*value_validate)       (GParamSpec   *pspec,
 238                                          GValue       *value);
 239   gint          (*values_cmp)           (GParamSpec   *pspec,
 240                                          const GValue *value1,
 241                                          const GValue *value2);
 242   /*< private >*/
 243   gpointer        dummy[4];
 244 };
 245 /**
 246  * GParameter:
 247  * @name: the parameter name
 248  * @value: the parameter value
 249  *
 250  * The <structname>GParameter</structname> struct is an auxiliary structure used
 251  * to hand parameter name/value pairs to g_object_newv().
 252  */
 253 struct _GParameter /* auxillary structure for _setv() variants */
 254 {
 255   const gchar *name;
 256   GValue       value;
 257 };
 258
 259
 260 /* --- prototypes --- */
 261 GParamSpec*     g_param_spec_ref                (GParamSpec    *pspec);
 262 void            g_param_spec_unref              (GParamSpec    *pspec);
 263 void            g_param_spec_sink               (GParamSpec    *pspec);
 264 GParamSpec*     g_param_spec_ref_sink           (GParamSpec    *pspec);
 265 gpointer        g_param_spec_get_qdata          (GParamSpec    *pspec,
 266                                                  GQuark         quark);
 267 void            g_param_spec_set_qdata          (GParamSpec    *pspec,
 268                                                  GQuark         quark,
 269                                                  gpointer       data);
 270 void            g_param_spec_set_qdata_full     (GParamSpec    *pspec,
 271                                                  GQuark         quark,
 272                                                  gpointer       data,
 273                                                  GDestroyNotify destroy);
 274 gpointer        g_param_spec_steal_qdata        (GParamSpec    *pspec,
 275                                                  GQuark         quark);
 276 GParamSpec*     g_param_spec_get_redirect_target (GParamSpec   *pspec);
 277
 278 void            g_param_value_set_default       (GParamSpec    *pspec,
 279                                                  GValue        *value);
 280 gboolean        g_param_value_defaults          (GParamSpec    *pspec,
 281                                                  GValue        *value);
 282 gboolean        g_param_value_validate          (GParamSpec    *pspec,
 283                                                  GValue        *value);
 284 gboolean        g_param_value_convert           (GParamSpec    *pspec,
 285                                                  const GValue  *src_value,
 286                                                  GValue        *dest_value,
 287                                                  gboolean       strict_validation);
 288 gint            g_param_values_cmp              (GParamSpec    *pspec,
 289                                                  const GValue  *value1,
 290                                                  const GValue  *value2);
 291 G_CONST_RETURN gchar*   g_param_spec_get_name   (GParamSpec    *pspec);
 292 G_CONST_RETURN gchar*   g_param_spec_get_nick   (GParamSpec    *pspec);
 293 G_CONST_RETURN gchar*   g_param_spec_get_blurb  (GParamSpec    *pspec);
 294 void            g_value_set_param               (GValue        *value,
 295                                                  GParamSpec    *param);
 296 GParamSpec*     g_value_get_param               (const GValue  *value);
 297 GParamSpec*     g_value_dup_param               (const GValue  *value);
 298
 299
 300 void           g_value_take_param               (GValue        *value,
 301                                                  GParamSpec    *param);
 302 #ifndef G_DISABLE_DEPRECATED
 303 void           g_value_set_param_take_ownership (GValue        *value,
 304                                                  GParamSpec    *param);
 305 #endif
 306
 307 /* --- convenience functions --- */
 308 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
 309 /**
 310  * GParamSpecTypeInfo:
 311  * @instance_size: Size of the instance (object) structure.
 312  * @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.
 313  * @instance_init: Location of the instance initialization function (optional).
 314  * @value_type: The #GType of values conforming to this #GParamSpec
 315  * @finalize: The instance finalization function (optional).
 316  * @value_set_default: Resets a @value to the default value for @pspec
 317  *  (recommended, the default is g_value_reset()), see
 318  *  g_param_value_set_default().
 319  * @value_validate: Ensures that the contents of @value comply with the
 320  *  specifications set out by @pspec (optional), see
 321  *  g_param_value_set_validate().
 322  * @values_cmp: Compares @value1 with @value2 according to @pspec
 323  *  (recommended, the default is memcmp()), see g_param_values_cmp().
 324  *
 325  * This structure is used to provide the type system with the information
 326  * required to initialize and destruct (finalize) a parameter's class and
 327  * instances thereof.
 328  * The initialized structure is passed to the g_param_type_register_static()
 329  * The type system will perform a deep copy of this structure, so it's memory
 330  * does not need to be persistent across invocation of
 331  * g_param_type_register_static().
 332  */
 333 struct _GParamSpecTypeInfo
 334 {
 335   /* type system portion */
 336   guint16         instance_size;                               /* obligatory */
 337   guint16         n_preallocs;                                 /* optional */
 338   void          (*instance_init)        (GParamSpec   *pspec); /* optional */
 339
 340   /* class portion */
 341   GType           value_type;                                  /* obligatory */
 342   void          (*finalize)             (GParamSpec   *pspec); /* optional */
 343   void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
 344                                          GValue       *value);
 345   gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
 346                                          GValue       *value);
 347   gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
 348                                          const GValue *value1,
 349                                          const GValue *value2);
 350 };
 351 GType   g_param_type_register_static    (const gchar              *name,
 352                                          const GParamSpecTypeInfo *pspec_info);
 353
 354 /* For registering builting types */
 355 GType  _g_param_type_register_static_constant (const gchar              *name,
 356                                                const GParamSpecTypeInfo *pspec_info,
 357                                                GType                     opt_type);
 358
 359
 360 /* --- protected --- */
 361 gpointer        g_param_spec_internal           (GType          param_type,
 362                                                  const gchar   *name,
 363                                                  const gchar   *nick,
 364                                                  const gchar   *blurb,
 365                                                  GParamFlags    flags);
 366 GParamSpecPool* g_param_spec_pool_new           (gboolean       type_prefixing);
 367 void            g_param_spec_pool_insert        (GParamSpecPool *pool,
 368                                                  GParamSpec     *pspec,
 369                                                  GType           owner_type);
 370 void            g_param_spec_pool_remove        (GParamSpecPool *pool,
 371                                                  GParamSpec     *pspec);
 372 GParamSpec*     g_param_spec_pool_lookup        (GParamSpecPool *pool,
 373                                                  const gchar    *param_name,
 374                                                  GType           owner_type,
 375                                                  gboolean        walk_ancestors);
 376 GList*          g_param_spec_pool_list_owned    (GParamSpecPool *pool,
 377                                                  GType           owner_type);
 378 GParamSpec**    g_param_spec_pool_list          (GParamSpecPool *pool,
 379                                                  GType           owner_type,
 380                                                  guint          *n_pspecs_p);
 381
 382
 383
 384 /* contracts:
 385  *
 386  * gboolean value_validate (GParamSpec *pspec,
 387  *                          GValue     *value):
 388  *      modify value contents in the least destructive way, so
 389  *      that it complies with pspec's requirements (i.e.
 390  *      according to minimum/maximum ranges etc...). return
 391  *      whether modification was necessary.
 392  *
 393  * gint values_cmp (GParamSpec   *pspec,
 394  *                  const GValue *value1,
 395  *                  const GValue *value2):
 396  *      return value1 - value2, i.e. (-1) if value1 < value2,
 397  *      (+1) if value1 > value2, and (0) otherwise (equality)
 398  */
 399
 400 G_END_DECLS
 401
 402 #endif /* __G_PARAM_H__ */