glib-2.0/gobject/gparam.h

0001 /* GObject - GLib Type, Object, Parameter and Signal Library
0002  * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General
0017  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  *
0019  * gparam.h: GParamSpec base class implementation
0020  */
0021 #ifndef __G_PARAM_H__
0022 #define __G_PARAM_H__
0023
0024 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
0025 #error "Only <glib-object.h> can be included directly."
0026 #endif
0027
0028 #include    <gobject/gvalue.h>
0029
0030 G_BEGIN_DECLS
0031
0032 /* --- standard type macros --- */
0033 /**
0034  * G_TYPE_IS_PARAM:
0035  * @type: a #GType ID
0036  *
0037  * Checks whether @type "is a" %G_TYPE_PARAM.
0038  */
0039 #define G_TYPE_IS_PARAM(type)       (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
0040 /**
0041  * G_PARAM_SPEC:
0042  * @pspec: a valid #GParamSpec
0043  *
0044  * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
0045  * a #GParamSpec object.
0046  */
0047 #define G_PARAM_SPEC(pspec)     (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
0048 /**
0049  * G_IS_PARAM_SPEC:
0050  * @pspec: a #GParamSpec
0051  *
0052  * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
0053  * or derived.
0054  */
0055 #if GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_42
0056 #define G_IS_PARAM_SPEC(pspec)      (G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE ((pspec), G_TYPE_PARAM))
0057 #else
0058 #define G_IS_PARAM_SPEC(pspec)      (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
0059 #endif
0060 /**
0061  * G_PARAM_SPEC_CLASS:
0062  * @pclass: a valid #GParamSpecClass
0063  *
0064  * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
0065  */
0066 #define G_PARAM_SPEC_CLASS(pclass)      (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
0067 /**
0068  * G_IS_PARAM_SPEC_CLASS:
0069  * @pclass: a #GParamSpecClass
0070  *
0071  * Checks whether @pclass "is a" valid #GParamSpecClass structure of type
0072  * %G_TYPE_PARAM or derived.
0073  */
0074 #define G_IS_PARAM_SPEC_CLASS(pclass)   (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
0075 /**
0076  * G_PARAM_SPEC_GET_CLASS:
0077  * @pspec: a valid #GParamSpec
0078  *
0079  * Retrieves the #GParamSpecClass of a #GParamSpec.
0080  */
0081 #define G_PARAM_SPEC_GET_CLASS(pspec)   (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
0082
0083
0084 /* --- convenience macros --- */
0085 /**
0086  * G_PARAM_SPEC_TYPE:
0087  * @pspec: a valid #GParamSpec
0088  *
0089  * Retrieves the #GType of this @pspec.
0090  */
0091 #define G_PARAM_SPEC_TYPE(pspec)    (G_TYPE_FROM_INSTANCE (pspec))
0092 /**
0093  * G_PARAM_SPEC_TYPE_NAME:
0094  * @pspec: a valid #GParamSpec
0095  *
0096  * Retrieves the #GType name of this @pspec.
0097  */
0098 #define G_PARAM_SPEC_TYPE_NAME(pspec)   (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
0099 /**
0100  * G_PARAM_SPEC_VALUE_TYPE:
0101  * @pspec: a valid #GParamSpec
0102  *
0103  * Retrieves the #GType to initialize a #GValue for this parameter.
0104  */
0105 #define G_PARAM_SPEC_VALUE_TYPE(pspec)  (G_PARAM_SPEC (pspec)->value_type)
0106 /**
0107  * G_VALUE_HOLDS_PARAM:
0108  * @value: a valid #GValue structure
0109  *
0110  * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
0111  *
0112  * Returns: %TRUE on success.
0113  */
0114 #define G_VALUE_HOLDS_PARAM(value)  (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
0115
0116
0117 /* --- flags --- */
0118 /**
0119  * GParamFlags:
0120  * @G_PARAM_READABLE: the parameter is readable
0121  * @G_PARAM_WRITABLE: the parameter is writable
0122  * @G_PARAM_READWRITE: alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE
0123  * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
0124  * @G_PARAM_CONSTRUCT_ONLY: the parameter can only be set upon object construction
0125  * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert())
0126  *  strict validation is not required
0127  * @G_PARAM_STATIC_NAME: the string used as name when constructing the
0128  *  parameter is guaranteed to remain valid and
0129  *  unmodified for the lifetime of the parameter.
0130  *  Since 2.8
0131  * @G_PARAM_STATIC_NICK: the string used as nick when constructing the
0132  *  parameter is guaranteed to remain valid and
0133  *  unmmodified for the lifetime of the parameter.
0134  *  Since 2.8
0135  * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the
0136  *  parameter is guaranteed to remain valid and
0137  *  unmodified for the lifetime of the parameter.
0138  *  Since 2.8
0139  * @G_PARAM_EXPLICIT_NOTIFY: calls to g_object_set_property() for this
0140  *   property will not automatically result in a "notify" signal being
0141  *   emitted: the implementation must call g_object_notify() themselves
0142  *   in case the property actually changes.  Since: 2.42.
0143  * @G_PARAM_PRIVATE: internal
0144  * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed
0145  *  in a future version. A warning will be generated if it is used
0146  *  while running with G_ENABLE_DIAGNOSTIC=1.
0147  *  Since 2.26
0148  *
0149  * Through the #GParamFlags flag values, certain aspects of parameters
0150  * can be configured.
0151  *
0152  * See also: %G_PARAM_STATIC_STRINGS
0153  */
0154 typedef enum
0155 {
0156   G_PARAM_READABLE            = 1 << 0,
0157   G_PARAM_WRITABLE            = 1 << 1,
0158   G_PARAM_READWRITE           = (G_PARAM_READABLE | G_PARAM_WRITABLE),
0159   G_PARAM_CONSTRUCT       = 1 << 2,
0160   G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
0161   G_PARAM_LAX_VALIDATION      = 1 << 4,
0162   G_PARAM_STATIC_NAME         = 1 << 5,
0163   G_PARAM_PRIVATE GOBJECT_DEPRECATED_ENUMERATOR_IN_2_26 = G_PARAM_STATIC_NAME,
0164   G_PARAM_STATIC_NICK         = 1 << 6,
0165   G_PARAM_STATIC_BLURB        = 1 << 7,
0166   /* User defined flags go here */
0167   G_PARAM_EXPLICIT_NOTIFY     = 1 << 30,
0168   /* Avoid warning with -Wpedantic for gcc6 */
0169   G_PARAM_DEPRECATED          = (gint)(1u << 31)
0170 } GParamFlags;
0171
0172 /**
0173  * G_PARAM_STATIC_STRINGS:
0174  *
0175  * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
0176  *
0177  * It is recommended to use this for all properties by default, as it allows for
0178  * internal performance improvements in GObject.
0179  *
0180  * It is very rare that a property would have a dynamically constructed name,
0181  * nickname or blurb.
0182  *
0183  * Since 2.13.0
0184  */
0185 #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)
0186 /* bits in the range 0xffffff00 are reserved for 3rd party usage */
0187 /**
0188  * G_PARAM_MASK:
0189  *
0190  * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
0191  */
0192 #define G_PARAM_MASK        (0x000000ff)
0193 /**
0194  * G_PARAM_USER_SHIFT:
0195  *
0196  * Minimum shift count to be used for user defined flags, to be stored in
0197  * #GParamSpec.flags. The maximum allowed is 10.
0198  */
0199 #define G_PARAM_USER_SHIFT  (8)
0200
0201 /* --- typedefs & structures --- */
0202 typedef struct _GParamSpec      GParamSpec;
0203 typedef struct _GParamSpecClass GParamSpecClass;
0204 typedef struct _GParameter  GParameter GOBJECT_DEPRECATED_TYPE_IN_2_54;
0205 typedef struct _GParamSpecPool  GParamSpecPool;
0206
0207 struct _GParamSpec
0208 {
0209   GTypeInstance  g_type_instance;
0210
0211   const gchar   *name;          /* interned string */
0212   GParamFlags    flags;
0213   GType      value_type;
0214   GType      owner_type;    /* class or interface using this property */
0215
0216   /*< private >*/
0217   gchar         *_nick;
0218   gchar         *_blurb;
0219   GData     *qdata;
0220   guint          ref_count;
0221   guint      param_id;  /* sort-criteria */
0222 };
0223 /**
0224  * GParamSpecClass:
0225  * @g_type_class: the parent class
0226  * @value_type: the #GValue type for this parameter
0227  * @finalize: The instance finalization function (optional), should chain
0228  *  up to the finalize method of the parent class.
0229  * @value_set_default: Resets a @value to the default value for this type
0230  *  (recommended, the default is g_value_reset()), see
0231  *  g_param_value_set_default().
0232  * @value_validate: Ensures that the contents of @value comply with the
0233  *  specifications set out by this type (optional), see
0234  *  g_param_value_validate().
0235  * @values_cmp: Compares @value1 with @value2 according to this type
0236  *  (recommended, the default is memcmp()), see g_param_values_cmp().
0237  * @value_is_valid: Checks if contents of @value comply with the specifications
0238  *   set out by this type, without modifying the value. This vfunc is optional.
0239  *   If it isn't set, GObject will use @value_validate. Since 2.74
0240  *
0241  * The class structure for the GParamSpec type.
0242  * Normally, GParamSpec classes are filled by
0243  * g_param_type_register_static().
0244  */
0245 struct _GParamSpecClass
0246 {
0247   GTypeClass      g_type_class;
0248
0249   GType       value_type;
0250
0251   void          (*finalize)     (GParamSpec   *pspec);
0252
0253   /* GParam methods */
0254   void          (*value_set_default)    (GParamSpec   *pspec,
0255                      GValue       *value);
0256   gboolean      (*value_validate)       (GParamSpec   *pspec,
0257                      GValue       *value);
0258   gint          (*values_cmp)           (GParamSpec   *pspec,
0259                      const GValue *value1,
0260                      const GValue *value2);
0261
0262   gboolean      (*value_is_valid)       (GParamSpec   *pspec,
0263                                          const GValue *value);
0264
0265   /*< private >*/
0266   gpointer    dummy[3];
0267 };
0268 /**
0269  * GParameter:
0270  * @name: the parameter name
0271  * @value: the parameter value
0272  *
0273  * The GParameter struct is an auxiliary structure used
0274  * to hand parameter name/value pairs to g_object_newv().
0275  *
0276  * Deprecated: 2.54: This type is not introspectable.
0277  */
0278 struct _GParameter /* auxiliary structure for _setv() variants */
0279 {
0280   const gchar *name;
0281   GValue       value;
0282 } GOBJECT_DEPRECATED_TYPE_IN_2_54;
0283
0284
0285 /* --- prototypes --- */
0286 GOBJECT_AVAILABLE_IN_ALL
0287 GParamSpec* g_param_spec_ref        (GParamSpec    *pspec);
0288 GOBJECT_AVAILABLE_IN_ALL
0289 void        g_param_spec_unref      (GParamSpec    *pspec);
0290 GOBJECT_AVAILABLE_IN_ALL
0291 void        g_param_spec_sink       (GParamSpec    *pspec);
0292 GOBJECT_AVAILABLE_IN_ALL
0293 GParamSpec* g_param_spec_ref_sink       (GParamSpec    *pspec);
0294 GOBJECT_AVAILABLE_IN_ALL
0295 gpointer        g_param_spec_get_qdata      (GParamSpec    *pspec,
0296                          GQuark         quark);
0297 GOBJECT_AVAILABLE_IN_ALL
0298 void            g_param_spec_set_qdata      (GParamSpec    *pspec,
0299                          GQuark         quark,
0300                          gpointer       data);
0301 GOBJECT_AVAILABLE_IN_ALL
0302 void            g_param_spec_set_qdata_full (GParamSpec    *pspec,
0303                          GQuark         quark,
0304                          gpointer       data,
0305                          GDestroyNotify destroy);
0306 GOBJECT_AVAILABLE_IN_ALL
0307 gpointer        g_param_spec_steal_qdata    (GParamSpec    *pspec,
0308                          GQuark         quark);
0309 GOBJECT_AVAILABLE_IN_ALL
0310 GParamSpec*     g_param_spec_get_redirect_target (GParamSpec   *pspec);
0311
0312 GOBJECT_AVAILABLE_IN_ALL
0313 void        g_param_value_set_default   (GParamSpec    *pspec,
0314                          GValue        *value);
0315 GOBJECT_AVAILABLE_IN_ALL
0316 gboolean    g_param_value_defaults      (GParamSpec    *pspec,
0317                          const GValue  *value);
0318 GOBJECT_AVAILABLE_IN_ALL
0319 gboolean    g_param_value_validate      (GParamSpec    *pspec,
0320                          GValue        *value);
0321 GOBJECT_AVAILABLE_IN_2_74
0322 gboolean        g_param_value_is_valid          (GParamSpec    *pspec,
0323                                                  const GValue  *value);
0324 GOBJECT_AVAILABLE_IN_ALL
0325 gboolean    g_param_value_convert       (GParamSpec    *pspec,
0326                          const GValue  *src_value,
0327                          GValue        *dest_value,
0328                          gboolean   strict_validation);
0329 GOBJECT_AVAILABLE_IN_ALL
0330 gint        g_param_values_cmp      (GParamSpec    *pspec,
0331                          const GValue  *value1,
0332                          const GValue  *value2);
0333 GOBJECT_AVAILABLE_IN_ALL
0334 const gchar *   g_param_spec_get_name           (GParamSpec    *pspec);
0335 GOBJECT_AVAILABLE_IN_ALL
0336 const gchar *   g_param_spec_get_nick           (GParamSpec    *pspec);
0337 GOBJECT_AVAILABLE_IN_ALL
0338 const gchar *   g_param_spec_get_blurb          (GParamSpec    *pspec);
0339 GOBJECT_AVAILABLE_IN_ALL
0340 void            g_value_set_param               (GValue        *value,
0341                          GParamSpec    *param);
0342 GOBJECT_AVAILABLE_IN_ALL
0343 GParamSpec*     g_value_get_param               (const GValue  *value);
0344 GOBJECT_AVAILABLE_IN_ALL
0345 GParamSpec*     g_value_dup_param               (const GValue  *value);
0346
0347
0348 GOBJECT_AVAILABLE_IN_ALL
0349 void           g_value_take_param               (GValue        *value,
0350                              GParamSpec    *param);
0351 GOBJECT_DEPRECATED_FOR(g_value_take_param)
0352 void           g_value_set_param_take_ownership (GValue        *value,
0353                                                  GParamSpec    *param);
0354 GOBJECT_AVAILABLE_IN_2_36
0355 const GValue *  g_param_spec_get_default_value  (GParamSpec    *pspec);
0356
0357 GOBJECT_AVAILABLE_IN_2_46
0358 GQuark          g_param_spec_get_name_quark     (GParamSpec    *pspec);
0359
0360 /* --- convenience functions --- */
0361 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
0362 /**
0363  * GParamSpecTypeInfo:
0364  * @instance_size: Size of the instance (object) structure.
0365  * @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.
0366  * @instance_init: Location of the instance initialization function (optional).
0367  * @value_type: The #GType of values conforming to this #GParamSpec
0368  * @finalize: The instance finalization function (optional).
0369  * @value_set_default: Resets a @value to the default value for @pspec
0370  *  (recommended, the default is g_value_reset()), see
0371  *  g_param_value_set_default().
0372  * @value_validate: Ensures that the contents of @value comply with the
0373  *  specifications set out by @pspec (optional), see
0374  *  g_param_value_validate().
0375  * @values_cmp: Compares @value1 with @value2 according to @pspec
0376  *  (recommended, the default is memcmp()), see g_param_values_cmp().
0377  *
0378  * This structure is used to provide the type system with the information
0379  * required to initialize and destruct (finalize) a parameter's class and
0380  * instances thereof.
0381  *
0382  * The initialized structure is passed to the g_param_type_register_static()
0383  * The type system will perform a deep copy of this structure, so its memory
0384  * does not need to be persistent across invocation of
0385  * g_param_type_register_static().
0386  */
0387 struct _GParamSpecTypeInfo
0388 {
0389   /* type system portion */
0390   guint16         instance_size;                               /* obligatory */
0391   guint16         n_preallocs;                                 /* optional */
0392   void      (*instance_init)    (GParamSpec   *pspec); /* optional */
0393
0394   /* class portion */
0395   GType           value_type;                      /* obligatory */
0396   void          (*finalize)             (GParamSpec   *pspec); /* optional */
0397   void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
0398                      GValue       *value);
0399   gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
0400                      GValue       *value);
0401   gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
0402                      const GValue *value1,
0403                      const GValue *value2);
0404 };
0405 GOBJECT_AVAILABLE_IN_ALL
0406 GType   g_param_type_register_static    (const gchar          *name,
0407                      const GParamSpecTypeInfo *pspec_info);
0408
0409 GOBJECT_AVAILABLE_IN_2_66
0410 gboolean g_param_spec_is_valid_name    (const gchar              *name);
0411
0412 /* For registering builting types */
0413 GType  _g_param_type_register_static_constant (const gchar              *name,
0414                            const GParamSpecTypeInfo *pspec_info,
0415                            GType                     opt_type);
0416
0417
0418 /* --- protected --- */
0419 GOBJECT_AVAILABLE_IN_ALL
0420 gpointer    g_param_spec_internal       (GType          param_type,
0421                          const gchar   *name,
0422                          const gchar   *nick,
0423                          const gchar   *blurb,
0424                          GParamFlags    flags);
0425 GOBJECT_AVAILABLE_IN_ALL
0426 GParamSpecPool* g_param_spec_pool_new       (gboolean   type_prefixing);
0427 GOBJECT_AVAILABLE_IN_ALL
0428 void        g_param_spec_pool_insert    (GParamSpecPool *pool,
0429                          GParamSpec *pspec,
0430                          GType       owner_type);
0431 GOBJECT_AVAILABLE_IN_ALL
0432 void        g_param_spec_pool_remove    (GParamSpecPool *pool,
0433                          GParamSpec *pspec);
0434 GOBJECT_AVAILABLE_IN_ALL
0435 GParamSpec* g_param_spec_pool_lookup    (GParamSpecPool *pool,
0436                          const gchar    *param_name,
0437                          GType       owner_type,
0438                          gboolean    walk_ancestors);
0439 GOBJECT_AVAILABLE_IN_ALL
0440 GList*      g_param_spec_pool_list_owned    (GParamSpecPool *pool,
0441                          GType       owner_type);
0442 GOBJECT_AVAILABLE_IN_ALL
0443 GParamSpec**    g_param_spec_pool_list      (GParamSpecPool *pool,
0444                          GType       owner_type,
0445                          guint      *n_pspecs_p);
0446 GOBJECT_AVAILABLE_IN_2_80
0447 void            g_param_spec_pool_free          (GParamSpecPool *pool);
0448
0449 /* contracts:
0450  *
0451  * gboolean value_validate (GParamSpec *pspec,
0452  *                          GValue     *value):
0453  *  modify value contents in the least destructive way, so
0454  *  that it complies with pspec's requirements (i.e.
0455  *  according to minimum/maximum ranges etc...). return
0456  *  whether modification was necessary.
0457  *
0458  * gint values_cmp (GParamSpec   *pspec,
0459  *                  const GValue *value1,
0460  *                  const GValue *value2):
0461  *  return value1 - value2, i.e. (-1) if value1 < value2,
0462  *  (+1) if value1 > value2, and (0) otherwise (equality)
0463  */
0464
0465 G_END_DECLS
0466
0467 #endif /* __G_PARAM_H__ */