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