glib2.0_2.20.1
[mer:glib2_0.git] / gobject / genums.h
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 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, write to the
16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17  * Boston, MA 02111-1307, USA.
18  */
19 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
20 #error "Only <glib-object.h> can be included directly."
21 #endif
22
23 #ifndef __G_ENUMS_H__
24 #define __G_ENUMS_H__
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 GEnumValue*     g_enum_get_value                (GEnumClass     *enum_class,
221                                                  gint            value);
222 GEnumValue*     g_enum_get_value_by_name        (GEnumClass     *enum_class,
223                                                  const gchar    *name);
224 GEnumValue*     g_enum_get_value_by_nick        (GEnumClass     *enum_class,
225                                                  const gchar    *nick);
226 GFlagsValue*    g_flags_get_first_value         (GFlagsClass    *flags_class,
227                                                  guint           value);
228 GFlagsValue*    g_flags_get_value_by_name       (GFlagsClass    *flags_class,
229                                                  const gchar    *name);
230 GFlagsValue*    g_flags_get_value_by_nick       (GFlagsClass    *flags_class,
231                                                  const gchar    *nick);
232 void            g_value_set_enum                (GValue         *value,
233                                                  gint            v_enum);
234 gint            g_value_get_enum                (const GValue   *value);
235 void            g_value_set_flags               (GValue         *value,
236                                                  guint           v_flags);
237 guint           g_value_get_flags               (const GValue   *value);
238
239
240
241 /* --- registration functions --- */
242 /* const_static_values is a NULL terminated array of enum/flags
243  * values that is taken over!
244  */
245 GType   g_enum_register_static     (const gchar       *name,
246                                     const GEnumValue  *const_static_values);
247 GType   g_flags_register_static    (const gchar       *name,
248                                     const GFlagsValue *const_static_values);
249 /* functions to complete the type information
250  * for enums/flags implemented by plugins
251  */
252 void    g_enum_complete_type_info  (GType              g_enum_type,
253                                     GTypeInfo         *info,
254                                     const GEnumValue  *const_values);
255 void    g_flags_complete_type_info (GType              g_flags_type,
256                                     GTypeInfo         *info,
257                                     const GFlagsValue *const_values);
258
259 G_END_DECLS
260
261 #endif /* __G_ENUMS_H__ */