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