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  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General
  17  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19 #ifndef __G_ENUMS_H__
  20 #define __G_ENUMS_H__
  21
  22 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
  23 #error "Only <glib-object.h> can be included directly."
  24 #endif
  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 GOBJECT_AVAILABLE_IN_ALL
 221 GEnumValue*     g_enum_get_value                (GEnumClass     *enum_class,
 222                                                  gint            value);
 223 GOBJECT_AVAILABLE_IN_ALL
 224 GEnumValue*     g_enum_get_value_by_name        (GEnumClass     *enum_class,
 225                                                  const gchar    *name);
 226 GOBJECT_AVAILABLE_IN_ALL
 227 GEnumValue*     g_enum_get_value_by_nick        (GEnumClass     *enum_class,
 228                                                  const gchar    *nick);
 229 GOBJECT_AVAILABLE_IN_ALL
 230 GFlagsValue*    g_flags_get_first_value         (GFlagsClass    *flags_class,
 231                                                  guint           value);
 232 GOBJECT_AVAILABLE_IN_ALL
 233 GFlagsValue*    g_flags_get_value_by_name       (GFlagsClass    *flags_class,
 234                                                  const gchar    *name);
 235 GOBJECT_AVAILABLE_IN_ALL
 236 GFlagsValue*    g_flags_get_value_by_nick       (GFlagsClass    *flags_class,
 237                                                  const gchar    *nick);
 238 GOBJECT_AVAILABLE_IN_2_54
 239 gchar          *g_enum_to_string                (GType           g_enum_type,
 240                                                  gint            value);
 241 GOBJECT_AVAILABLE_IN_2_54
 242 gchar          *g_flags_to_string               (GType           flags_type,
 243                                                  guint           value);
 244 GOBJECT_AVAILABLE_IN_ALL
 245 void            g_value_set_enum                (GValue         *value,
 246                                                  gint            v_enum);
 247 GOBJECT_AVAILABLE_IN_ALL
 248 gint            g_value_get_enum                (const GValue   *value);
 249 GOBJECT_AVAILABLE_IN_ALL
 250 void            g_value_set_flags               (GValue         *value,
 251                                                  guint           v_flags);
 252 GOBJECT_AVAILABLE_IN_ALL
 253 guint           g_value_get_flags               (const GValue   *value);
 254
 255
 256
 257 /* --- registration functions --- */
 258 /* const_static_values is a NULL terminated array of enum/flags
 259  * values that is taken over!
 260  */
 261 GOBJECT_AVAILABLE_IN_ALL
 262 GType   g_enum_register_static     (const gchar       *name,
 263                                     const GEnumValue  *const_static_values);
 264 GOBJECT_AVAILABLE_IN_ALL
 265 GType   g_flags_register_static    (const gchar       *name,
 266                                     const GFlagsValue *const_static_values);
 267 /* functions to complete the type information
 268  * for enums/flags implemented by plugins
 269  */
 270 GOBJECT_AVAILABLE_IN_ALL
 271 void    g_enum_complete_type_info  (GType              g_enum_type,
 272                                     GTypeInfo         *info,
 273                                     const GEnumValue  *const_values);
 274 GOBJECT_AVAILABLE_IN_ALL
 275 void    g_flags_complete_type_info (GType              g_flags_type,
 276                                     GTypeInfo         *info,
 277                                     const GFlagsValue *const_values);
 278
 279 /* {{{ Macros */
 280
 281 /**
 282  * G_DEFINE_ENUM_VALUE:
 283  * @EnumValue: an enumeration value
 284  * @EnumNick: a short string representing the enumeration value
 285  *
 286  * Defines an enumeration value, and maps it to a "nickname".
 287  *
 288  * This macro can only be used with G_DEFINE_ENUM_TYPE() and
 289  * G_DEFINE_FLAGS_TYPE().
 290  *
 291  * Since: 2.74
 292  */
 293 #define G_DEFINE_ENUM_VALUE(EnumValue, EnumNick) \
 294   { EnumValue, #EnumValue, EnumNick } \
 295   GOBJECT_AVAILABLE_MACRO_IN_2_74
 296
 297 /**
 298  * G_DEFINE_ENUM_TYPE:
 299  * @TypeName: the enumeration type, in `CamelCase`
 300  * @type_name: the enumeration type prefixed, in `snake_case`
 301  * @...: a list of enumeration values, defined using G_DEFINE_ENUM_VALUE()
 302  *
 303  * A convenience macro for defining enumeration types.
 304  *
 305  * This macro will generate a `*_get_type()` function for the
 306  * given @TypeName, using @type_name as the function prefix.
 307  *
 308  * |[<!-- language="C" -->
 309  * G_DEFINE_ENUM_TYPE (GtkOrientation, gtk_orientation,
 310  *   G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_HORIZONTAL, "horizontal"),
 311  *   G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_VERTICAL, "vertical"))
 312  * ]|
 313  *
 314  * For projects that have multiple enumeration types, or enumeration
 315  * types with many values, you should consider using glib-mkenums to
 316  * generate the type function.
 317  *
 318  * Since: 2.74
 319  */
 320 #define G_DEFINE_ENUM_TYPE(TypeName, type_name, ...) \
 321 GType \
 322 type_name ## _get_type (void) { \
 323   static gsize g_define_type__static = 0; \
 324   if (g_once_init_enter (&g_define_type__static)) { \
 325     static const GEnumValue enum_values[] = { \
 326       __VA_ARGS__ , \
 327       { 0, NULL, NULL }, \
 328     }; \
 329     GType g_define_type = g_enum_register_static (g_intern_static_string (#TypeName), enum_values); \
 330     g_once_init_leave (&g_define_type__static, g_define_type); \
 331   } \
 332   return g_define_type__static; \
 333 } \
 334   GOBJECT_AVAILABLE_MACRO_IN_2_74
 335
 336 /**
 337  * G_DEFINE_FLAGS_TYPE:
 338  * @TypeName: the enumeration type, in `CamelCase`
 339  * @type_name: the enumeration type prefixed, in `snake_case`
 340  * @...: a list of enumeration values, defined using G_DEFINE_ENUM_VALUE()
 341  *
 342  * A convenience macro for defining flag types.
 343  *
 344  * This macro will generate a `*_get_type()` function for the
 345  * given @TypeName, using @type_name as the function prefix.
 346  *
 347  * |[<!-- language="C" -->
 348  * G_DEFINE_FLAGS_TYPE (GSettingsBindFlags, g_settings_bind_flags,
 349  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_DEFAULT, "default"),
 350  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET, "get"),
 351  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_SET, "set"),
 352  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_NO_SENSITIVITY, "no-sensitivity"),
 353  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET_NO_CHANGES, "get-no-changes"),
 354  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_INVERT_BOOLEAN, "invert-boolean"))
 355  * ]|
 356  *
 357  * For projects that have multiple enumeration types, or enumeration
 358  * types with many values, you should consider using glib-mkenums to
 359  * generate the type function.
 360  *
 361  * Since: 2.74
 362  */
 363 #define G_DEFINE_FLAGS_TYPE(TypeName, type_name, ...) \
 364 GType \
 365 type_name ## _get_type (void) { \
 366   static gsize g_define_type__static = 0; \
 367   if (g_once_init_enter (&g_define_type__static)) { \
 368     static const GFlagsValue flags_values[] = { \
 369       __VA_ARGS__ , \
 370       { 0, NULL, NULL }, \
 371     }; \
 372     GType g_define_type = g_flags_register_static (g_intern_static_string (#TypeName), flags_values); \
 373     g_once_init_leave (&g_define_type__static, g_define_type); \
 374   } \
 375   return g_define_type__static; \
 376 } \
 377   GOBJECT_AVAILABLE_MACRO_IN_2_74
 378
 379 G_END_DECLS
 380
 381 #endif /* __G_ENUMS_H__ */