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__ */ 280