1
<!-- ##### SECTION Title ##### -->
4
<!-- ##### SECTION Short_Description ##### -->
5
Enumeration and flags types
7
<!-- ##### SECTION Long_Description ##### -->
9
The GLib type system provides fundamental types for enumeration and flags types. (Flags types
10
are like enumerations, but allow their values to be combined by bitwise or). A registered
11
enumeration or flags type associates a name and a nickname with each allowed value, and
12
the methods g_enum_get_value_by_name(), g_enum_get_value_by_nick(), g_flags_get_value_by_name()
13
and g_flags_get_value_by_nick() can look up values by their name or nickname.
14
When an enumeration or flags type is registered with the GLib type system, it can
15
be used as value type for object properties, using g_param_spec_enum() or
19
GObject ships with a utility called <link linkend="glib-mkenums">glib-mkenums</link> that can
20
construct suitable type registration functions from C enumeration definitions.
23
<!-- ##### SECTION See_Also ##### -->
25
#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags(),
26
<link linkend="glib-mkenums">glib-mkenums</link>
29
<!-- ##### SECTION Stability_Level ##### -->
32
<!-- ##### STRUCT GEnumClass ##### -->
34
The class of an enumeration type holds information about its
38
@g_type_class: the parent class
39
@minimum: the smallest possible value.
40
@maximum: the largest possible value.
41
@n_values: the number of possible values.
42
@values: an array of #GEnumValue structs describing the
45
<!-- ##### STRUCT GFlagsClass ##### -->
47
The class of a flags type holds information about its
51
@g_type_class: the parent class
52
@mask: a mask covering all possible values.
53
@n_values: the number of possible values.
54
@values: an array of #GFlagsValue structs describing the
57
<!-- ##### MACRO G_ENUM_CLASS_TYPE ##### -->
59
Returns the type identifier from a given #GEnumClass structure.
65
<!-- ##### MACRO G_ENUM_CLASS_TYPE_NAME ##### -->
67
Returns the static type name from a given #GEnumClass structure.
73
<!-- ##### MACRO G_TYPE_IS_ENUM ##### -->
75
Returns whether @type "is a" %G_TYPE_ENUM.
81
<!-- ##### MACRO G_ENUM_CLASS ##### -->
83
Casts a derived #GEnumClass structure into a #GEnumClass structure.
86
@class: a valid #GEnumClass
89
<!-- ##### MACRO G_IS_ENUM_CLASS ##### -->
91
Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
98
<!-- ##### MACRO G_TYPE_IS_FLAGS ##### -->
100
Returns whether @type "is a" %G_TYPE_FLAGS.
106
<!-- ##### MACRO G_FLAGS_CLASS ##### -->
108
Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
111
@class: a valid #GFlagsClass
114
<!-- ##### MACRO G_IS_FLAGS_CLASS ##### -->
116
Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
120
@class: a #GFlagsClass
123
<!-- ##### MACRO G_FLAGS_CLASS_TYPE ##### -->
125
Returns the type identifier from a given #GFlagsClass structure.
128
@class: a #GFlagsClass
131
<!-- ##### MACRO G_FLAGS_CLASS_TYPE_NAME ##### -->
133
Returns the static type name from a given #GFlagsClass structure.
136
@class: a #GFlagsClass
139
<!-- ##### STRUCT GEnumValue ##### -->
141
A structure which contains a single enum value, it's name, and it's
145
@value: the enum value
146
@value_name: the name of the value
147
@value_nick: the nickname of the value
149
<!-- ##### STRUCT GFlagsValue ##### -->
151
A structure which contains a single flags value, it's name, and it's
155
@value: the flags value
156
@value_name: the name of the value
157
@value_nick: the nickname of the value
159
<!-- ##### FUNCTION g_enum_get_value ##### -->
161
Returns the #GEnumValue for a value.
164
@enum_class: a #GEnumClass
165
@value: the value to look up
166
@Returns: the #GEnumValue for @value, or %NULL if @value is not
167
a member of the enumeration
170
<!-- ##### FUNCTION g_enum_get_value_by_name ##### -->
172
Looks up a #GEnumValue by name.
175
@enum_class: a #GEnumClass
176
@name: the name to look up
177
@Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn'
178
t have a member with that name
181
<!-- ##### FUNCTION g_enum_get_value_by_nick ##### -->
183
Looks up a #GEnumValue by nickname.
186
@enum_class: a #GEnumClass
187
@nick: the nickname to look up
188
@Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn'
189
t have a member with that nickname
192
<!-- ##### FUNCTION g_flags_get_first_value ##### -->
194
Returns the first #GFlagsValue which is set in @value.
197
@flags_class: a #GFlagsClass
199
@Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set
202
<!-- ##### FUNCTION g_flags_get_value_by_name ##### -->
204
Looks up a #GFlagsValue by name.
207
@flags_class: a #GFlagsClass
208
@name: the name to look up
209
@Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with
213
<!-- ##### FUNCTION g_flags_get_value_by_nick ##### -->
215
Looks up a #GFlagsValue by nickname.
218
@flags_class: a #GFlagsClass
219
@nick: the nickname to look up
220
@Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag
224
<!-- ##### FUNCTION g_enum_register_static ##### -->
226
Registers a new static enumeration type with the name @name.
229
It is normally more convenient to let <link linkend="glib-mkenums">glib-mkenums</link>
230
generate a my_enum_get_type() function from a usual C enumeration definition
231
than to write one yourself using g_enum_register_static().
234
@name: A nul-terminated string used as the name of the new type.
236
@Returns: The new type identifier.
237
<!-- # Unused Parameters # -->
238
@const_static_values: An array of #GEnumValue structs for the possible
239
enumeration values. The array is terminated by a struct with all
243
<!-- ##### FUNCTION g_flags_register_static ##### -->
245
Registers a new static flags type with the name @name.
248
It is normally more convenient to let <link linkend="glib-mkenums">glib-mkenums</link>
249
generate a my_flags_get_type() function from a usual C enumeration definition
250
than to write one yourself using g_flags_register_static().
253
@name: A nul-terminated string used as the name of the new type.
255
@Returns: The new type identifier.
256
<!-- # Unused Parameters # -->
257
@const_static_values: An array of #GFlagsValue structs for the possible
258
flags values. The array is terminated by a struct with all members being 0.
261
<!-- ##### FUNCTION g_enum_complete_type_info ##### -->
263
This function is meant to be called from the complete_type_info() function
264
of a #GTypePlugin implementation, as in the following example:
268
my_enum_complete_type_info (GTypePlugin *plugin,
271
GTypeValueTable *value_table)
273
static const GEnumValue values[] = {
274
{ MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
275
{ MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
279
g_enum_complete_type_info (type, info, values);
285
@g_enum_type: the type identifier of the type being completed
286
@info: the #GTypeInfo struct to be filled in
288
<!-- # Unused Parameters # -->
289
@const_values: An array of #GEnumValue structs for the possible
290
enumeration values. The array is terminated by a struct with all
294
<!-- ##### FUNCTION g_flags_complete_type_info ##### -->
296
This function is meant to be called from the complete_type_info() function
297
of a #GTypePlugin implementation, see the example for
298
g_enumeration_complete_type_info() above.
301
@g_flags_type: the type identifier of the type being completed
302
@info: the #GTypeInfo struct to be filled in
304
<!-- # Unused Parameters # -->
305
@const_values: An array of #GFlagsValue structs for the possible
306
enumeration values. The array is terminated by a struct with all
added
removed
docs/reference/gobject/tmpl/enumerations_flags.sgml
