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