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 _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, ...) \ |
364 | GType \ |
365 | type_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 | |
379 | G_END_DECLS |
380 | |
381 | #endif /* __G_ENUMS_H__ */ |
382 | |