glib-2.0/gobject/genums.h

0001 /* GObject - GLib Type, Object, Parameter and Signal Library
0002  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General
0017  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019 #ifndef __G_ENUMS_H__
0020 #define __G_ENUMS_H__
0021
0022 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
0023 #error "Only <glib-object.h> can be included directly."
0024 #endif
0025
0026 #include <gobject/gtype.h>
0027
0028 G_BEGIN_DECLS
0029
0030 /* --- type macros --- */
0031 /**
0032  * G_TYPE_IS_ENUM:
0033  * @type: a #GType ID.
0034  *
0035  * Checks whether @type "is a" %G_TYPE_ENUM.
0036  *
0037  * Returns: %TRUE if @type "is a" %G_TYPE_ENUM.
0038  */
0039 #define G_TYPE_IS_ENUM(type)           (G_TYPE_FUNDAMENTAL (type) == G_TYPE_ENUM)
0040 /**
0041  * G_ENUM_CLASS:
0042  * @class: a valid #GEnumClass
0043  *
0044  * Casts a derived #GEnumClass structure into a #GEnumClass structure.
0045  */
0046 #define G_ENUM_CLASS(class)        (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_ENUM, GEnumClass))
0047 /**
0048  * G_IS_ENUM_CLASS:
0049  * @class: a #GEnumClass
0050  *
0051  * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
0052  * or derived.
0053  */
0054 #define G_IS_ENUM_CLASS(class)         (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_ENUM))
0055 /**
0056  * G_ENUM_CLASS_TYPE:
0057  * @class: a #GEnumClass
0058  *
0059  * Get the type identifier from a given #GEnumClass structure.
0060  *
0061  * Returns: the #GType
0062  */
0063 #define G_ENUM_CLASS_TYPE(class)       (G_TYPE_FROM_CLASS (class))
0064 /**
0065  * G_ENUM_CLASS_TYPE_NAME:
0066  * @class: a #GEnumClass
0067  *
0068  * Get the static type name from a given #GEnumClass structure.
0069  *
0070  * Returns: the type name.
0071  */
0072 #define G_ENUM_CLASS_TYPE_NAME(class)  (g_type_name (G_ENUM_CLASS_TYPE (class)))
0073
0074
0075 /**
0076  * G_TYPE_IS_FLAGS:
0077  * @type: a #GType ID.
0078  *
0079  * Checks whether @type "is a" %G_TYPE_FLAGS.
0080  *
0081  * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS.
0082  */
0083 #define G_TYPE_IS_FLAGS(type)          (G_TYPE_FUNDAMENTAL (type) == G_TYPE_FLAGS)
0084 /**
0085  * G_FLAGS_CLASS:
0086  * @class: a valid #GFlagsClass
0087  *
0088  * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
0089  */
0090 #define G_FLAGS_CLASS(class)           (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_FLAGS, GFlagsClass))
0091 /**
0092  * G_IS_FLAGS_CLASS:
0093  * @class: a #GFlagsClass
0094  *
0095  * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
0096  * or derived.
0097  */
0098 #define G_IS_FLAGS_CLASS(class)        (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_FLAGS))
0099 /**
0100  * G_FLAGS_CLASS_TYPE:
0101  * @class: a #GFlagsClass
0102  *
0103  * Get the type identifier from a given #GFlagsClass structure.
0104  *
0105  * Returns: the #GType
0106  */
0107 #define G_FLAGS_CLASS_TYPE(class)      (G_TYPE_FROM_CLASS (class))
0108 /**
0109  * G_FLAGS_CLASS_TYPE_NAME:
0110  * @class: a #GFlagsClass
0111  *
0112  * Get the static type name from a given #GFlagsClass structure.
0113  *
0114  * Returns: the type name.
0115  */
0116 #define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class)))
0117
0118
0119 /**
0120  * G_VALUE_HOLDS_ENUM:
0121  * @value: a valid #GValue structure
0122  *
0123  * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
0124  *
0125  * Returns: %TRUE on success.
0126  */
0127 #define G_VALUE_HOLDS_ENUM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM))
0128 /**
0129  * G_VALUE_HOLDS_FLAGS:
0130  * @value: a valid #GValue structure
0131  *
0132  * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
0133  *
0134  * Returns: %TRUE on success.
0135  */
0136 #define G_VALUE_HOLDS_FLAGS(value)     (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS))
0137
0138
0139 /* --- enum/flag values & classes --- */
0140 typedef struct _GEnumClass  GEnumClass;
0141 typedef struct _GFlagsClass GFlagsClass;
0142 typedef struct _GEnumValue  GEnumValue;
0143 typedef struct _GFlagsValue GFlagsValue;
0144
0145 /**
0146  * GEnumClass:
0147  * @g_type_class: the parent class
0148  * @minimum: the smallest possible value.
0149  * @maximum: the largest possible value.
0150  * @n_values: the number of possible values.
0151  * @values: an array of #GEnumValue structs describing the
0152  *  individual values.
0153  *
0154  * The class of an enumeration type holds information about its
0155  * possible values.
0156  */
0157 struct  _GEnumClass
0158 {
0159   GTypeClass  g_type_class;
0160
0161   /*< public >*/
0162   gint        minimum;
0163   gint        maximum;
0164   guint       n_values;
0165   GEnumValue *values;
0166 };
0167 /**
0168  * GFlagsClass:
0169  * @g_type_class: the parent class
0170  * @mask: a mask covering all possible values.
0171  * @n_values: the number of possible values.
0172  * @values: an array of #GFlagsValue structs describing the
0173  *  individual values.
0174  *
0175  * The class of a flags type holds information about its
0176  * possible values.
0177  */
0178 struct  _GFlagsClass
0179 {
0180   GTypeClass   g_type_class;
0181
0182   /*< public >*/
0183   guint        mask;
0184   guint        n_values;
0185   GFlagsValue *values;
0186 };
0187 /**
0188  * GEnumValue:
0189  * @value: the enum value
0190  * @value_name: the name of the value
0191  * @value_nick: the nickname of the value
0192  *
0193  * A structure which contains a single enum value, its name, and its
0194  * nickname.
0195  */
0196 struct _GEnumValue
0197 {
0198   gint   value;
0199   const gchar *value_name;
0200   const gchar *value_nick;
0201 };
0202 /**
0203  * GFlagsValue:
0204  * @value: the flags value
0205  * @value_name: the name of the value
0206  * @value_nick: the nickname of the value
0207  *
0208  * A structure which contains a single flags value, its name, and its
0209  * nickname.
0210  */
0211 struct _GFlagsValue
0212 {
0213   guint  value;
0214   const gchar *value_name;
0215   const gchar *value_nick;
0216 };
0217
0218
0219 /* --- prototypes --- */
0220 GOBJECT_AVAILABLE_IN_ALL
0221 GEnumValue* g_enum_get_value        (GEnumClass *enum_class,
0222                          gint        value);
0223 GOBJECT_AVAILABLE_IN_ALL
0224 GEnumValue* g_enum_get_value_by_name    (GEnumClass *enum_class,
0225                          const gchar    *name);
0226 GOBJECT_AVAILABLE_IN_ALL
0227 GEnumValue* g_enum_get_value_by_nick    (GEnumClass *enum_class,
0228                          const gchar    *nick);
0229 GOBJECT_AVAILABLE_IN_ALL
0230 GFlagsValue*    g_flags_get_first_value     (GFlagsClass    *flags_class,
0231                          guint       value);
0232 GOBJECT_AVAILABLE_IN_ALL
0233 GFlagsValue*    g_flags_get_value_by_name   (GFlagsClass    *flags_class,
0234                          const gchar    *name);
0235 GOBJECT_AVAILABLE_IN_ALL
0236 GFlagsValue*    g_flags_get_value_by_nick   (GFlagsClass    *flags_class,
0237                          const gchar    *nick);
0238 GOBJECT_AVAILABLE_IN_2_54
0239 gchar          *g_enum_to_string                (GType           g_enum_type,
0240                                                  gint            value);
0241 GOBJECT_AVAILABLE_IN_2_54
0242 gchar          *g_flags_to_string               (GType           flags_type,
0243                                                  guint           value);
0244 GOBJECT_AVAILABLE_IN_ALL
0245 void            g_value_set_enum            (GValue         *value,
0246                          gint            v_enum);
0247 GOBJECT_AVAILABLE_IN_ALL
0248 gint            g_value_get_enum            (const GValue   *value);
0249 GOBJECT_AVAILABLE_IN_ALL
0250 void            g_value_set_flags           (GValue         *value,
0251                          guint           v_flags);
0252 GOBJECT_AVAILABLE_IN_ALL
0253 guint           g_value_get_flags           (const GValue   *value);
0254
0255
0256
0257 /* --- registration functions --- */
0258 /* const_static_values is a NULL terminated array of enum/flags
0259  * values that is taken over!
0260  */
0261 GOBJECT_AVAILABLE_IN_ALL
0262 GType   g_enum_register_static     (const gchar       *name,
0263                     const GEnumValue  *const_static_values);
0264 GOBJECT_AVAILABLE_IN_ALL
0265 GType   g_flags_register_static    (const gchar       *name,
0266                     const GFlagsValue *const_static_values);
0267 /* functions to complete the type information
0268  * for enums/flags implemented by plugins
0269  */
0270 GOBJECT_AVAILABLE_IN_ALL
0271 void    g_enum_complete_type_info  (GType          g_enum_type,
0272                     GTypeInfo         *info,
0273                     const GEnumValue  *const_values);
0274 GOBJECT_AVAILABLE_IN_ALL
0275 void    g_flags_complete_type_info (GType          g_flags_type,
0276                     GTypeInfo         *info,
0277                     const GFlagsValue *const_values);
0278
0279 /* {{{ Macros */
0280
0281 /**
0282  * G_DEFINE_ENUM_VALUE:
0283  * @EnumValue: an enumeration value
0284  * @EnumNick: a short string representing the enumeration value
0285  *
0286  * Defines an enumeration value, and maps it to a "nickname".
0287  *
0288  * This macro can only be used with G_DEFINE_ENUM_TYPE() and
0289  * G_DEFINE_FLAGS_TYPE().
0290  *
0291  * Since: 2.74
0292  */
0293 #define G_DEFINE_ENUM_VALUE(EnumValue, EnumNick) \
0294   { EnumValue, #EnumValue, EnumNick } \
0295   GOBJECT_AVAILABLE_MACRO_IN_2_74
0296
0297 /**
0298  * G_DEFINE_ENUM_TYPE:
0299  * @TypeName: the enumeration type, in `CamelCase`
0300  * @type_name: the enumeration type prefixed, in `snake_case`
0301  * @...: a list of enumeration values, defined using G_DEFINE_ENUM_VALUE()
0302  *
0303  * A convenience macro for defining enumeration types.
0304  *
0305  * This macro will generate a `*_get_type()` function for the
0306  * given @TypeName, using @type_name as the function prefix.
0307  *
0308  * |[<!-- language="C" -->
0309  * G_DEFINE_ENUM_TYPE (GtkOrientation, gtk_orientation,
0310  *   G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_HORIZONTAL, "horizontal"),
0311  *   G_DEFINE_ENUM_VALUE (GTK_ORIENTATION_VERTICAL, "vertical"))
0312  * ]|
0313  *
0314  * For projects that have multiple enumeration types, or enumeration
0315  * types with many values, you should consider using glib-mkenums to
0316  * generate the type function.
0317  *
0318  * Since: 2.74
0319  */
0320 #define G_DEFINE_ENUM_TYPE(TypeName, type_name, ...) \
0321 GType \
0322 type_name ## _get_type (void) { \
0323   static _g_type_once_init_type g_define_type__static = 0; \
0324   if (_g_type_once_init_enter (&g_define_type__static)) { \
0325     static const GEnumValue enum_values[] = { \
0326       __VA_ARGS__ , \
0327       { 0, NULL, NULL }, \
0328     }; \
0329     GType g_define_type = g_enum_register_static (g_intern_static_string (#TypeName), enum_values); \
0330     _g_type_once_init_leave (&g_define_type__static, g_define_type); \
0331   } \
0332   return g_define_type__static; \
0333 } \
0334   GOBJECT_AVAILABLE_MACRO_IN_2_74
0335
0336 /**
0337  * G_DEFINE_FLAGS_TYPE:
0338  * @TypeName: the enumeration type, in `CamelCase`
0339  * @type_name: the enumeration type prefixed, in `snake_case`
0340  * @...: a list of enumeration values, defined using G_DEFINE_ENUM_VALUE()
0341  *
0342  * A convenience macro for defining flag types.
0343  *
0344  * This macro will generate a `*_get_type()` function for the
0345  * given @TypeName, using @type_name as the function prefix.
0346  *
0347  * |[<!-- language="C" -->
0348  * G_DEFINE_FLAGS_TYPE (GSettingsBindFlags, g_settings_bind_flags,
0349  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_DEFAULT, "default"),
0350  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET, "get"),
0351  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_SET, "set"),
0352  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_NO_SENSITIVITY, "no-sensitivity"),
0353  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_GET_NO_CHANGES, "get-no-changes"),
0354  *   G_DEFINE_ENUM_VALUE (G_SETTINGS_BIND_INVERT_BOOLEAN, "invert-boolean"))
0355  * ]|
0356  *
0357  * For projects that have multiple enumeration types, or enumeration
0358  * types with many values, you should consider using glib-mkenums to
0359  * generate the type function.
0360  *
0361  * Since: 2.74
0362  */
0363 #define G_DEFINE_FLAGS_TYPE(TypeName, type_name, ...) \
0364 GType \
0365 type_name ## _get_type (void) { \
0366   static _g_type_once_init_type g_define_type__static = 0; \
0367   if (_g_type_once_init_enter (&g_define_type__static)) { \
0368     static const GFlagsValue flags_values[] = { \
0369       __VA_ARGS__ , \
0370       { 0, NULL, NULL }, \
0371     }; \
0372     GType g_define_type = g_flags_register_static (g_intern_static_string (#TypeName), flags_values); \
0373     _g_type_once_init_leave (&g_define_type__static, g_define_type); \
0374   } \
0375   return g_define_type__static; \
0376 } \
0377   GOBJECT_AVAILABLE_MACRO_IN_2_74
0378
0379 G_END_DECLS
0380
0381 #endif /* __G_ENUMS_H__ */