gobject/gparam.h

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 1997, 1998, 1999, 2000 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 #ifndef __G_PARAM_H__
  22 #define __G_PARAM_H__
  23
  24
  25 #include        <gobject/gtype.h>
  26
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif /* __cplusplus */
  31
  32
  33 /* --- type macros --- */
  34 #define G_TYPE_IS_PARAM(type)           (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
  35 #define G_PARAM_SPEC_TYPE(pspec)        (G_TYPE_FROM_INSTANCE (pspec))
  36 #define G_PARAM_SPEC_TYPE_NAME(pspec)   (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
  37 #define G_PARAM_SPEC(pspec)             (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
  38 #define G_IS_PARAM_SPEC(pspec)          (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
  39 #define G_PARAM_SPEC_GET_CLASS(pspec)   (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
  40 #define G_IS_VALUE(value)               (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_PARAM))
  41
  42
  43 /* --- flags --- */
  44 typedef enum
  45 {
  46   G_PARAM_READABLE            = 1 << 0,
  47   G_PARAM_WRITABLE            = 1 << 1,
  48   G_PARAM_MASK                = 0x000f,
  49   /* bits in the range 0xfff0 are reserved for 3rd party usage */
  50   G_PARAM_USER_MASK           = 0xfff0
  51 } GParamFlags;
  52
  53
  54 /* --- typedefs & structures --- */
  55 typedef struct _GParamSpecClass GParamSpecClass;
  56 typedef struct _GParamSpec      GParamSpec;
  57 typedef struct _GValue          GValue;
  58 typedef union  _GParamCValue    GParamCValue;
  59 typedef void  (*GValueExchange) (GValue*, GValue*);
  60 struct _GParamSpecClass
  61 {
  62   GTypeClass      g_type_class;
  63
  64   void          (*finalize)             (GParamSpec   *pspec);
  65
  66   /* GParam methods */
  67   void          (*param_init)           (GValue       *value,
  68                                          GParamSpec   *pspec);
  69   void          (*param_free_value)     (GValue       *value);
  70   gboolean      (*param_validate)       (GValue       *value,
  71                                          GParamSpec   *pspec);
  72   gint          (*param_values_cmp)     (const GValue *value1,
  73                                          const GValue *value2,
  74                                          GParamSpec   *pspec);
  75   void          (*param_copy_value)     (const GValue *src_value,
  76                                          GValue       *dest_value);
  77   /* varargs functionality (optional) */
  78   guint           collect_type;
  79   gchar*        (*param_collect_value)  (GValue       *value,
  80                                          GParamSpec   *pspec,
  81                                          guint         nth_value,
  82                                          GType        *collect_type,
  83                                          GParamCValue *collect_value);
  84   guint           lcopy_type;
  85   gchar*        (*param_lcopy_value)    (const GValue *value,
  86                                          GParamSpec   *pspec,
  87                                          guint         nth_value,
  88                                          GType        *collect_type,
  89                                          GParamCValue *collect_value);
  90 };
  91 struct _GParamSpec
  92 {
  93   GTypeInstance  g_instance;
  94
  95   gchar         *name;
  96   gchar         *nick;
  97   gchar         *blurb;
  98   GParamFlags    flags;
  99
 100   /*< private >*/
 101   GType          owner_type;
 102   GData         *qdata;
 103   guint          ref_count;
 104 };
 105
 106
 107 /* --- prototypes --- */
 108 GParamSpec*     g_param_spec_ref                (GParamSpec    *pspec);
 109 void            g_param_spec_unref              (GParamSpec    *pspec);
 110 gpointer        g_param_spec_get_qdata          (GParamSpec    *pspec,
 111                                                  GQuark         quark);
 112 void            g_param_spec_set_qdata          (GParamSpec    *pspec,
 113                                                  GQuark         quark,
 114                                                  gpointer       data);
 115 void            g_param_spec_set_qdata_full     (GParamSpec    *pspec,
 116                                                  GQuark         quark,
 117                                                  gpointer       data,
 118                                                  GDestroyNotify destroy);
 119 gpointer        g_param_spec_steal_qdata        (GParamSpec    *pspec,
 120                                                  GQuark         quark);
 121
 122
 123 /* --- private --- */
 124 gpointer        g_param_spec_internal           (GType          param_type,
 125                                                  const gchar   *name,
 126                                                  const gchar   *nick,
 127                                                  const gchar   *blurb,
 128                                                  GParamFlags    flags);
 129 GHashTable*     g_param_spec_hash_table_new     (void);
 130 void            g_param_spec_hash_table_insert  (GHashTable    *hash_table,
 131                                                  GParamSpec    *pspec,
 132                                                  GType          owner_type);
 133 void            g_param_spec_hash_table_remove  (GHashTable    *hash_table,
 134                                                  GParamSpec    *pspec);
 135 GParamSpec*     g_param_spec_hash_table_lookup  (GHashTable    *hash_table,
 136                                                  const gchar   *param_name,
 137                                                  GType          owner_type,
 138                                                  gboolean       try_ancestors,
 139                                                  const gchar  **trailer);
 140
 141
 142 /* contracts:
 143  *
 144  * class functions may not evaluate param->pspec directly,
 145  * instead, pspec will be passed as argument if required.
 146  *
 147  * void param_init (GParam *param, GParamSpec *pspec):
 148  *      initialize param's value to default if pspec is given,
 149  *      and to zero-equivalent (a value that doesn't need to be
 150  *      free()ed later on) otherwise.
 151  *
 152  * void param_free_value (GParam *param):
 153  *      free param's value if required, zero-reinitialization
 154  *      of the value is not required. (this class function
 155  *      may be NULL for param types that don't need to free
 156  *      values, such as ints or floats).
 157  *
 158  * gboolean param_validate (GParam *param, GParamSpec *pspec):
 159  *      modify param's value in the least destructive way, so
 160  *      that it complies with pspec's requirements (i.e.
 161  *      according to minimum/maximum ranges etc...). return
 162  *      whether modification was necessary.
 163  *
 164  * gint param_values_cmp (GParam *param1, GParam *param2, GParamSpec*):
 165  *      return param1 - param2, i.e. <0 if param1 < param2,
 166  *      >0 if param1 > param2, and 0 if they are equal
 167  *      (passing pspec is optional, but recommended)
 168  *
 169  * void param_copy_value (GParam *param_src, GParam *param_dest):
 170  *      copy value from param_src to param_dest, param_dest is
 171  *      already free()d and zero-initialized, so its value can
 172  *      simply be overwritten. (may be NULL for memcpy)
 173  *
 174  * gchar* param_collect_value ():
 175  *      class function may be NULL.
 176  *
 177  * gchar* param_lcopy_value ():
 178  *      class function may be NULL.
 179  *
 180  */
 181
 182 #ifdef __cplusplus
 183 }
 184 #endif /* __cplusplus */
 185
 186 #endif /* __G_PARAM_H__ */