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 #define G_TYPE_IS_PARAM(type)           (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
  34 #define G_PARAM_SPEC(pspec)             (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
  35 #define G_IS_PARAM_SPEC(pspec)          (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
  36 #define G_PARAM_SPEC_CLASS(pclass)      (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
  37 #define G_IS_PARAM_SPEC_CLASS(pclass)   (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
  38 #define G_PARAM_SPEC_GET_CLASS(pspec)   (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
  39
  40
  41 /* --- convenience macros --- */
  42 #define G_PARAM_SPEC_TYPE(pspec)        (G_TYPE_FROM_INSTANCE (pspec))
  43 #define G_PARAM_SPEC_TYPE_NAME(pspec)   (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
  44 #define G_PARAM_SPEC_VALUE_TYPE(pspec)  (G_PARAM_SPEC (pspec)->value_type)
  45 #define G_VALUE_HOLDS_PARAM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
  46
  47
  48 /* --- flags --- */
  49 typedef enum
  50 {
  51   G_PARAM_READABLE            = 1 << 0,
  52   G_PARAM_WRITABLE            = 1 << 1,
  53   G_PARAM_CONSTRUCT           = 1 << 2,
  54   G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
  55   G_PARAM_LAX_VALIDATION      = 1 << 4,
  56   G_PARAM_STATIC_NAME         = 1 << 5,
  57 #ifndef G_DISABLE_DEPRECATED
  58   G_PARAM_PRIVATE             = G_PARAM_STATIC_NAME,
  59 #endif
  60   G_PARAM_STATIC_NICK         = 1 << 6,
  61   G_PARAM_STATIC_BLURB        = 1 << 7
  62 } GParamFlags;
  63 #define G_PARAM_READWRITE       (G_PARAM_READABLE | G_PARAM_WRITABLE)
  64 #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)
  65 #define G_PARAM_MASK            (0x000000ff)
  66 /* bits in the range 0xffffff00 are reserved for 3rd party usage */
  67 #define G_PARAM_USER_SHIFT      (8)
  68
  69
  70 /* --- typedefs & structures --- */
  71 typedef struct _GParamSpec      GParamSpec;
  72 typedef struct _GParamSpecClass GParamSpecClass;
  73 typedef struct _GParameter      GParameter;
  74 typedef struct _GParamSpecPool  GParamSpecPool;
  75 struct _GParamSpec
  76 {
  77   GTypeInstance  g_type_instance;
  78
  79   gchar         *name;
  80   GParamFlags    flags;
  81   GType          value_type;
  82   GType          owner_type;    /* class or interface using this property */
  83
  84   /*< private >*/
  85   gchar         *_nick;
  86   gchar         *_blurb;
  87   GData         *qdata;
  88   guint          ref_count;
  89   guint          param_id;      /* sort-criteria */
  90 };
  91 struct _GParamSpecClass
  92 {
  93   GTypeClass      g_type_class;
  94
  95   GType           value_type;
  96
  97   void          (*finalize)             (GParamSpec   *pspec);
  98
  99   /* GParam methods */
 100   void          (*value_set_default)    (GParamSpec   *pspec,
 101                                          GValue       *value);
 102   gboolean      (*value_validate)       (GParamSpec   *pspec,
 103                                          GValue       *value);
 104   gint          (*values_cmp)           (GParamSpec   *pspec,
 105                                          const GValue *value1,
 106                                          const GValue *value2);
 107   /*< private >*/
 108   gpointer        dummy[4];
 109 };
 110 struct _GParameter /* auxillary structure for _setv() variants */
 111 {
 112   const gchar *name;
 113   GValue       value;
 114 };
 115
 116
 117 /* --- prototypes --- */
 118 GParamSpec*     g_param_spec_ref                (GParamSpec    *pspec);
 119 void            g_param_spec_unref              (GParamSpec    *pspec);
 120 void            g_param_spec_sink               (GParamSpec    *pspec);
 121 GParamSpec*     g_param_spec_ref_sink           (GParamSpec    *pspec);
 122 gpointer        g_param_spec_get_qdata          (GParamSpec    *pspec,
 123                                                  GQuark         quark);
 124 void            g_param_spec_set_qdata          (GParamSpec    *pspec,
 125                                                  GQuark         quark,
 126                                                  gpointer       data);
 127 void            g_param_spec_set_qdata_full     (GParamSpec    *pspec,
 128                                                  GQuark         quark,
 129                                                  gpointer       data,
 130                                                  GDestroyNotify destroy);
 131 gpointer        g_param_spec_steal_qdata        (GParamSpec    *pspec,
 132                                                  GQuark         quark);
 133 GParamSpec*     g_param_spec_get_redirect_target (GParamSpec   *pspec);
 134
 135 void            g_param_value_set_default       (GParamSpec    *pspec,
 136                                                  GValue        *value);
 137 gboolean        g_param_value_defaults          (GParamSpec    *pspec,
 138                                                  GValue        *value);
 139 gboolean        g_param_value_validate          (GParamSpec    *pspec,
 140                                                  GValue        *value);
 141 gboolean        g_param_value_convert           (GParamSpec    *pspec,
 142                                                  const GValue  *src_value,
 143                                                  GValue        *dest_value,
 144                                                  gboolean       strict_validation);
 145 gint            g_param_values_cmp              (GParamSpec    *pspec,
 146                                                  const GValue  *value1,
 147                                                  const GValue  *value2);
 148 G_CONST_RETURN gchar*   g_param_spec_get_name   (GParamSpec    *pspec);
 149 G_CONST_RETURN gchar*   g_param_spec_get_nick   (GParamSpec    *pspec);
 150 G_CONST_RETURN gchar*   g_param_spec_get_blurb  (GParamSpec    *pspec);
 151 void            g_value_set_param               (GValue        *value,
 152                                                  GParamSpec    *param);
 153 GParamSpec*     g_value_get_param               (const GValue  *value);
 154 GParamSpec*     g_value_dup_param               (const GValue  *value);
 155
 156
 157 void           g_value_take_param               (GValue        *value,
 158                                                  GParamSpec    *param);
 159 #ifndef G_DISABLE_DEPRECATED
 160 void           g_value_set_param_take_ownership (GValue        *value,
 161                                                  GParamSpec    *param);
 162 #endif
 163
 164 /* --- convenience functions --- */
 165 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
 166 struct _GParamSpecTypeInfo
 167 {
 168   /* type system portion */
 169   guint16         instance_size;                               /* obligatory */
 170   guint16         n_preallocs;                                 /* optional */
 171   void          (*instance_init)        (GParamSpec   *pspec); /* optional */
 172
 173   /* class portion */
 174   GType           value_type;                                  /* obligatory */
 175   void          (*finalize)             (GParamSpec   *pspec); /* optional */
 176   void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
 177                                          GValue       *value);
 178   gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
 179                                          GValue       *value);
 180   gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
 181                                          const GValue *value1,
 182                                          const GValue *value2);
 183 };
 184 GType   g_param_type_register_static    (const gchar              *name,
 185                                          const GParamSpecTypeInfo *pspec_info);
 186
 187 /* For registering builting types */
 188 GType  _g_param_type_register_static_constant (const gchar              *name,
 189                                                const GParamSpecTypeInfo *pspec_info,
 190                                                GType                     opt_type);
 191
 192
 193 /* --- protected --- */
 194 gpointer        g_param_spec_internal           (GType          param_type,
 195                                                  const gchar   *name,
 196                                                  const gchar   *nick,
 197                                                  const gchar   *blurb,
 198                                                  GParamFlags    flags);
 199 GParamSpecPool* g_param_spec_pool_new           (gboolean       type_prefixing);
 200 void            g_param_spec_pool_insert        (GParamSpecPool *pool,
 201                                                  GParamSpec     *pspec,
 202                                                  GType           owner_type);
 203 void            g_param_spec_pool_remove        (GParamSpecPool *pool,
 204                                                  GParamSpec     *pspec);
 205 GParamSpec*     g_param_spec_pool_lookup        (GParamSpecPool *pool,
 206                                                  const gchar    *param_name,
 207                                                  GType           owner_type,
 208                                                  gboolean        walk_ancestors);
 209 GList*          g_param_spec_pool_list_owned    (GParamSpecPool *pool,
 210                                                  GType           owner_type);
 211 GParamSpec**    g_param_spec_pool_list          (GParamSpecPool *pool,
 212                                                  GType           owner_type,
 213                                                  guint          *n_pspecs_p);
 214
 215
 216
 217 /* contracts:
 218  *
 219  * gboolean value_validate (GParamSpec *pspec,
 220  *                          GValue     *value):
 221  *      modify value contents in the least destructive way, so
 222  *      that it complies with pspec's requirements (i.e.
 223  *      according to minimum/maximum ranges etc...). return
 224  *      whether modification was necessary.
 225  *
 226  * gint values_cmp (GParamSpec   *pspec,
 227  *                  const GValue *value1,
 228  *                  const GValue *value2):
 229  *      return value1 - value2, i.e. (-1) if value1 < value2,
 230  *      (+1) if value1 > value2, and (0) otherwise (equality)
 231  */
 232
 233 G_END_DECLS
 234
 235 #endif /* __G_PARAM_H__ */