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
28G_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 --- */
140typedef struct _GEnumClass GEnumClass;
141typedef struct _GFlagsClass GFlagsClass;
142typedef struct _GEnumValue GEnumValue;
143typedef 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 */
157struct _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 */
178struct _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 */
196struct _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 */
211struct _GFlagsValue
212{
213 guint value;
214 const gchar *value_name;
215 const gchar *value_nick;
216};
217
218
219/* --- prototypes --- */
220GOBJECT_AVAILABLE_IN_ALL
221GEnumValue* g_enum_get_value (GEnumClass *enum_class,
222 gint value);
223GOBJECT_AVAILABLE_IN_ALL
224GEnumValue* g_enum_get_value_by_name (GEnumClass *enum_class,
225 const gchar *name);
226GOBJECT_AVAILABLE_IN_ALL
227GEnumValue* g_enum_get_value_by_nick (GEnumClass *enum_class,
228 const gchar *nick);
229GOBJECT_AVAILABLE_IN_ALL
230GFlagsValue* g_flags_get_first_value (GFlagsClass *flags_class,
231 guint value);
232GOBJECT_AVAILABLE_IN_ALL
233GFlagsValue* g_flags_get_value_by_name (GFlagsClass *flags_class,
234 const gchar *name);
235GOBJECT_AVAILABLE_IN_ALL
236GFlagsValue* g_flags_get_value_by_nick (GFlagsClass *flags_class,
237 const gchar *nick);
238GOBJECT_AVAILABLE_IN_2_54
239gchar *g_enum_to_string (GType g_enum_type,
240 gint value);
241GOBJECT_AVAILABLE_IN_2_54
242gchar *g_flags_to_string (GType flags_type,
243 guint value);
244GOBJECT_AVAILABLE_IN_ALL
245void g_value_set_enum (GValue *value,
246 gint v_enum);
247GOBJECT_AVAILABLE_IN_ALL
248gint g_value_get_enum (const GValue *value);
249GOBJECT_AVAILABLE_IN_ALL
250void g_value_set_flags (GValue *value,
251 guint v_flags);
252GOBJECT_AVAILABLE_IN_ALL
253guint 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 */
261GOBJECT_AVAILABLE_IN_ALL
262GType g_enum_register_static (const gchar *name,
263 const GEnumValue *const_static_values);
264GOBJECT_AVAILABLE_IN_ALL
265GType 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 */
270GOBJECT_AVAILABLE_IN_ALL
271void g_enum_complete_type_info (GType g_enum_type,
272 GTypeInfo *info,
273 const GEnumValue *const_values);
274GOBJECT_AVAILABLE_IN_ALL
275void 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, ...) \
321GType \
322type_name ## _get_type (void) { \
323 static _g_type_once_init_type g_define_type__static = 0; \
324 if (_g_type_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_type_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, ...) \
364GType \
365type_name ## _get_type (void) { \
366 static _g_type_once_init_type g_define_type__static = 0; \
367 if (_g_type_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_type_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
379G_END_DECLS
380
381#endif /* __G_ENUMS_H__ */
382