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
26G_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 --- */
138typedef struct _GEnumClass GEnumClass;
139typedef struct _GFlagsClass GFlagsClass;
140typedef struct _GEnumValue GEnumValue;
141typedef 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 */
155struct _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 */
176struct _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 */
194struct _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 */
209struct _GFlagsValue
210{
211 guint value;
212 const gchar *value_name;
213 const gchar *value_nick;
214};
215
216
217/* --- prototypes --- */
218GLIB_AVAILABLE_IN_ALL
219GEnumValue* g_enum_get_value (GEnumClass *enum_class,
220 gint value);
221GLIB_AVAILABLE_IN_ALL
222GEnumValue* g_enum_get_value_by_name (GEnumClass *enum_class,
223 const gchar *name);
224GLIB_AVAILABLE_IN_ALL
225GEnumValue* g_enum_get_value_by_nick (GEnumClass *enum_class,
226 const gchar *nick);
227GLIB_AVAILABLE_IN_ALL
228GFlagsValue* g_flags_get_first_value (GFlagsClass *flags_class,
229 guint value);
230GLIB_AVAILABLE_IN_ALL
231GFlagsValue* g_flags_get_value_by_name (GFlagsClass *flags_class,
232 const gchar *name);
233GLIB_AVAILABLE_IN_ALL
234GFlagsValue* g_flags_get_value_by_nick (GFlagsClass *flags_class,
235 const gchar *nick);
236GLIB_AVAILABLE_IN_2_54
237gchar *g_enum_to_string (GType g_enum_type,
238 gint value);
239GLIB_AVAILABLE_IN_2_54
240gchar *g_flags_to_string (GType flags_type,
241 guint value);
242GLIB_AVAILABLE_IN_ALL
243void g_value_set_enum (GValue *value,
244 gint v_enum);
245GLIB_AVAILABLE_IN_ALL
246gint g_value_get_enum (const GValue *value);
247GLIB_AVAILABLE_IN_ALL
248void g_value_set_flags (GValue *value,
249 guint v_flags);
250GLIB_AVAILABLE_IN_ALL
251guint 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 */
259GLIB_AVAILABLE_IN_ALL
260GType g_enum_register_static (const gchar *name,
261 const GEnumValue *const_static_values);
262GLIB_AVAILABLE_IN_ALL
263GType 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 */
268GLIB_AVAILABLE_IN_ALL
269void g_enum_complete_type_info (GType g_enum_type,
270 GTypeInfo *info,
271 const GEnumValue *const_values);
272GLIB_AVAILABLE_IN_ALL
273void g_flags_complete_type_info (GType g_flags_type,
274 GTypeInfo *info,
275 const GFlagsValue *const_values);
276
277G_END_DECLS
278
279#endif /* __G_ENUMS_H__ */
280