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 | |