gobject/genums.h

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 1998-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 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
  20 #error "Only <glib-object.h> can be included directly."
  21 #endif
  22
  23 #ifndef __G_ENUMS_H__
  24 #define __G_ENUMS_H__
  25
  26 #include <gobject/gtype.h>
  27
  28 G_BEGIN_DECLS
  29
  30 /* --- type macros --- */
  31 /**
  32  * G_TYPE_IS_ENUM:
  33  * @type: a #GType ID.
  34  *
  35  * Checks whether @type "is a" %G_TYPE_ENUM.
  36  *
  37  * Returns: %TRUE if @type "is a" %G_TYPE_ENUM.
  38  */
  39 #define G_TYPE_IS_ENUM(type)           (G_TYPE_FUNDAMENTAL (type) == G_TYPE_ENUM)
  40 /**
  41  * G_ENUM_CLASS:
  42  * @class: a valid #GEnumClass
  43  *
  44  * Casts a derived #GEnumClass structure into a #GEnumClass structure.
  45  */
  46 #define G_ENUM_CLASS(class)            (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_ENUM, GEnumClass))
  47 /**
  48  * G_IS_ENUM_CLASS:
  49  * @class: a #GEnumClass
  50  *
  51  * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
  52  * or derived.
  53  */
  54 #define G_IS_ENUM_CLASS(class)         (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_ENUM))
  55 /**
  56  * G_ENUM_CLASS_TYPE:
  57  * @class: a #GEnumClass
  58  *
  59  * Get the type identifier from a given #GEnumClass structure.
  60  *
  61  * Returns: the #GType
  62  */
  63 #define G_ENUM_CLASS_TYPE(class)       (G_TYPE_FROM_CLASS (class))
  64 /**
  65  * G_ENUM_CLASS_TYPE_NAME:
  66  * @class: a #GEnumClass
  67  *
  68  * Get the static type name from a given #GEnumClass structure.
  69  *
  70  * Returns: the type name.
  71  */
  72 #define G_ENUM_CLASS_TYPE_NAME(class)  (g_type_name (G_ENUM_CLASS_TYPE (class)))
  73
  74
  75 /**
  76  * G_TYPE_IS_FLAGS:
  77  * @type: a #GType ID.
  78  *
  79  * Checks whether @type "is a" %G_TYPE_FLAGS.
  80  *
  81  * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS.
  82  */
  83 #define G_TYPE_IS_FLAGS(type)          (G_TYPE_FUNDAMENTAL (type) == G_TYPE_FLAGS)
  84 /**
  85  * G_FLAGS_CLASS:
  86  * @class: a valid #GFlagsClass
  87  *
  88  * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
  89  */
  90 #define G_FLAGS_CLASS(class)           (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_FLAGS, GFlagsClass))
  91 /**
  92  * G_IS_FLAGS_CLASS:
  93  * @class: a #GFlagsClass
  94  *
  95  * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
  96  * or derived.
  97  */
  98 #define G_IS_FLAGS_CLASS(class)        (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_FLAGS))
  99 /**
 100  * G_FLAGS_CLASS_TYPE:
 101  * @class: a #GFlagsClass
 102  *
 103  * Get the type identifier from a given #GFlagsClass structure.
 104  *
 105  * Returns: the #GType
 106  */
 107 #define G_FLAGS_CLASS_TYPE(class)      (G_TYPE_FROM_CLASS (class))
 108 /**
 109  * G_FLAGS_CLASS_TYPE_NAME:
 110  * @class: a #GFlagsClass
 111  *
 112  * Get the static type name from a given #GFlagsClass structure.
 113  *
 114  * Returns: the type name.
 115  */
 116 #define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class)))
 117
 118
 119 /**
 120  * G_VALUE_HOLDS_ENUM:
 121  * @value: a valid #GValue structure
 122  *
 123  * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
 124  *
 125  * Returns: %TRUE on success.
 126  */
 127 #define G_VALUE_HOLDS_ENUM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM))
 128 /**
 129  * G_VALUE_HOLDS_FLAGS:
 130  * @value: a valid #GValue structure
 131  *
 132  * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
 133  *
 134  * Returns: %TRUE on success.
 135  */
 136 #define G_VALUE_HOLDS_FLAGS(value)     (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS))
 137
 138
 139 /* --- enum/flag values & classes --- */
 140 typedef struct _GEnumClass  GEnumClass;
 141 typedef struct _GFlagsClass GFlagsClass;
 142 typedef struct _GEnumValue  GEnumValue;
 143 typedef struct _GFlagsValue GFlagsValue;
 144
 145 /**
 146  * GEnumClass:
 147  * @g_type_class: the parent class
 148  * @minimum: the smallest possible value.
 149  * @maximum: the largest possible value.
 150  * @n_values: the number of possible values.
 151  * @values: an array of #GEnumValue structs describing the
 152  *  individual values.
 153  *
 154  * The class of an enumeration type holds information about its
 155  * possible values.
 156  */
 157 struct  _GEnumClass
 158 {
 159   GTypeClass  g_type_class;
 160
 161   /*< public >*/
 162   gint        minimum;
 163   gint        maximum;
 164   guint       n_values;
 165   GEnumValue *values;
 166 };
 167 /**
 168  * GFlagsClass:
 169  * @g_type_class: the parent class
 170  * @mask: a mask covering all possible values.
 171  * @n_values: the number of possible values.
 172  * @values: an array of #GFlagsValue structs describing the
 173  *  individual values.
 174  *
 175  * The class of a flags type holds information about its
 176  * possible values.
 177  */
 178 struct  _GFlagsClass
 179 {
 180   GTypeClass   g_type_class;
 181
 182   /*< public >*/
 183   guint        mask;
 184   guint        n_values;
 185   GFlagsValue *values;
 186 };
 187 /**
 188  * GEnumValue:
 189  * @value: the enum value
 190  * @value_name: the name of the value
 191  * @value_nick: the nickname of the value
 192  *
 193  * A structure which contains a single enum value, its name, and its
 194  * nickname.
 195  */
 196 struct _GEnumValue
 197 {
 198   gint   value;
 199   const gchar *value_name;
 200   const gchar *value_nick;
 201 };
 202 /**
 203  * GFlagsValue:
 204  * @value: the flags value
 205  * @value_name: the name of the value
 206  * @value_nick: the nickname of the value
 207  *
 208  * A structure which contains a single flags value, its name, and its
 209  * nickname.
 210  */
 211 struct _GFlagsValue
 212 {
 213   guint  value;
 214   const gchar *value_name;
 215   const gchar *value_nick;
 216 };
 217
 218
 219 /* --- prototypes --- */
 220 GEnumValue*     g_enum_get_value                (GEnumClass     *enum_class,
 221                                                  gint            value);
 222 GEnumValue*     g_enum_get_value_by_name        (GEnumClass     *enum_class,
 223                                                  const gchar    *name);
 224 GEnumValue*     g_enum_get_value_by_nick        (GEnumClass     *enum_class,
 225                                                  const gchar    *nick);
 226 GFlagsValue*    g_flags_get_first_value         (GFlagsClass    *flags_class,
 227                                                  guint           value);
 228 GFlagsValue*    g_flags_get_value_by_name       (GFlagsClass    *flags_class,
 229                                                  const gchar    *name);
 230 GFlagsValue*    g_flags_get_value_by_nick       (GFlagsClass    *flags_class,
 231                                                  const gchar    *nick);
 232 void            g_value_set_enum                (GValue         *value,
 233                                                  gint            v_enum);
 234 gint            g_value_get_enum                (const GValue   *value);
 235 void            g_value_set_flags               (GValue         *value,
 236                                                  guint           v_flags);
 237 guint           g_value_get_flags               (const GValue   *value);
 238
 239
 240
 241 /* --- registration functions --- */
 242 /* const_static_values is a NULL terminated array of enum/flags
 243  * values that is taken over!
 244  */
 245 GType   g_enum_register_static     (const gchar       *name,
 246                                     const GEnumValue  *const_static_values);
 247 GType   g_flags_register_static    (const gchar       *name,
 248                                     const GFlagsValue *const_static_values);
 249 /* functions to complete the type information
 250  * for enums/flags implemented by plugins
 251  */
 252 void    g_enum_complete_type_info  (GType              g_enum_type,
 253                                     GTypeInfo         *info,
 254                                     const GEnumValue  *const_values);
 255 void    g_flags_complete_type_info (GType              g_flags_type,
 256                                     GTypeInfo         *info,
 257                                     const GFlagsValue *const_values);
 258
 259 G_END_DECLS
 260
 261 #endif /* __G_ENUMS_H__ */