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/gvalue.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_PARAM_SPEC_VALUE_TYPE(pspec)  (G_PARAM_SPEC_GET_CLASS (pspec)->value_type)
  41 #define G_IS_VALUE_PARAM(value)         (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
  42
  43
  44 /* --- flags --- */
  45 typedef enum
  46 {
  47   G_PARAM_READABLE            = 1 << 0,
  48   G_PARAM_WRITABLE            = 1 << 1,
  49   G_PARAM_CONSTRUCT           = 1 << 2,
  50   G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
  51 #define G_PARAM_MASK            (0x000f)
  52   /* bits in the range 0xfff0 are reserved for 3rd party usage */
  53 #define G_PARAM_USER_MASK       (0xfff0)
  54 } GParamFlags;
  55
  56
  57 /* --- typedefs & structures --- */
  58 typedef struct _GParamSpec      GParamSpec;
  59 typedef struct _GParamSpecClass GParamSpecClass;
  60 struct _GParamSpec
  61 {
  62   GTypeInstance  g_type_instance;
  63
  64   gchar         *name;
  65   gchar         *nick;
  66   gchar         *blurb;
  67   GParamFlags    flags;
  68
  69   /*< private >*/
  70   GType          owner_type;
  71   GData         *qdata;
  72   guint          ref_count;
  73 };
  74 struct _GParamSpecClass
  75 {
  76   GTypeClass      g_type_class;
  77
  78   GType           value_type;
  79
  80   void          (*finalize)             (GParamSpec   *pspec);
  81
  82   /* GParam methods */
  83   void          (*value_set_default)    (GParamSpec   *pspec,
  84                                          GValue       *value);
  85   gboolean      (*value_validate)       (GParamSpec   *pspec,
  86                                          GValue       *value);
  87   gint          (*values_cmp)           (GParamSpec   *pspec,
  88                                          const GValue *value1,
  89                                          const GValue *value2);
  90 };
  91
  92
  93 /* --- prototypes --- */
  94 GParamSpec*     g_param_spec_ref                (GParamSpec    *pspec);
  95 void            g_param_spec_unref              (GParamSpec    *pspec);
  96 void            g_param_spec_sink               (GParamSpec    *pspec);
  97 gpointer        g_param_spec_get_qdata          (GParamSpec    *pspec,
  98                                                  GQuark         quark);
  99 void            g_param_spec_set_qdata          (GParamSpec    *pspec,
 100                                                  GQuark         quark,
 101                                                  gpointer       data);
 102 void            g_param_spec_set_qdata_full     (GParamSpec    *pspec,
 103                                                  GQuark         quark,
 104                                                  gpointer       data,
 105                                                  GDestroyNotify destroy);
 106 gpointer        g_param_spec_steal_qdata        (GParamSpec    *pspec,
 107                                                  GQuark         quark);
 108 void            g_param_value_set_default       (GParamSpec    *pspec,
 109                                                  GValue        *value);
 110 gboolean        g_param_value_defaults          (GParamSpec    *pspec,
 111                                                  GValue        *value);
 112 gboolean        g_param_value_validate          (GParamSpec    *pspec,
 113                                                  GValue        *value);
 114 gint            g_param_values_cmp              (GParamSpec    *pspec,
 115                                                  const GValue  *value1,
 116                                                  const GValue  *value2);
 117 void            g_value_set_param               (GValue        *value,
 118                                                  GParamSpec    *param);
 119 GParamSpec*     g_value_get_param               (const GValue  *value);
 120 GParamSpec*     g_value_dup_param               (const GValue  *value);
 121
 122
 123 /* --- convenience functions --- */
 124 typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
 125 struct _GParamSpecTypeInfo
 126 {
 127   /* type system portion */
 128   guint16         instance_size;                               /* obligatory */
 129   guint16         n_preallocs;                                 /* optional */
 130   void          (*instance_init)        (GParamSpec   *pspec); /* optional */
 131
 132   /* class portion */
 133   GType           value_type;                                  /* obligatory */
 134   void          (*finalize)             (GParamSpec   *pspec); /* optional */
 135   void          (*value_set_default)    (GParamSpec   *pspec,  /* recommended */
 136                                          GValue       *value);
 137   gboolean      (*value_validate)       (GParamSpec   *pspec,  /* optional */
 138                                          GValue       *value);
 139   gint          (*values_cmp)           (GParamSpec   *pspec,  /* recommended */
 140                                          const GValue *value1,
 141                                          const GValue *value2);
 142 };
 143 GType   g_param_type_register_static    (const gchar              *name,
 144                                          const GParamSpecTypeInfo *pspec_info);
 145
 146
 147 /* --- private --- */
 148 gpointer        g_param_spec_internal           (GType          param_type,
 149                                                  const gchar   *name,
 150                                                  const gchar   *nick,
 151                                                  const gchar   *blurb,
 152                                                  GParamFlags    flags);
 153 GHashTable*     g_param_spec_hash_table_new     (void);
 154 void            g_param_spec_hash_table_insert  (GHashTable    *hash_table,
 155                                                  GParamSpec    *pspec,
 156                                                  GType          owner_type);
 157 void            g_param_spec_hash_table_remove  (GHashTable    *hash_table,
 158                                                  GParamSpec    *pspec);
 159 GParamSpec*     g_param_spec_hash_table_lookup  (GHashTable    *hash_table,
 160                                                  const gchar   *param_name,
 161                                                  GType          owner_type,
 162                                                  gboolean       try_ancestors,
 163                                                  const gchar  **trailer);
 164
 165
 166 /* contracts:
 167  *
 168  * gboolean value_validate (GParamSpec *pspec,
 169  *                          GValue     *value):
 170  *      modify value contents in the least destructive way, so
 171  *      that it complies with pspec's requirements (i.e.
 172  *      according to minimum/maximum ranges etc...). return
 173  *      whether modification was necessary.
 174  *
 175  * gint values_cmp (GParamSpec   *pspec,
 176  *                  const GValue *value1,
 177  *                  const GValue *value2):
 178  *      return value1 - value2, i.e. <0 if value1 < value2,
 179  *      >0 if value1 > value2, and 0 otherwise (they are equal)
 180  */
 181
 182 #ifdef __cplusplus
 183 }
 184 #endif /* __cplusplus */
 185
 186 #endif /* __G_PARAM_H__ */