29
#include "gvaluecollector.h"
31
#include "gobjectalias.h"
30
#include "gvaluecollector.h"
31
#include "gobjectalias.h"
35
* SECTION:enumerations_flags
36
* @short_description: Enumeration and flags types
37
* @see_also:#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(),
38
* g_param_spec_flags(),
40
* <link linkend="glib-mkenums">glib-mkenums</link>
41
* @title: Enumeration and Flag Types
43
* The GLib type system provides fundamental types for enumeration and
44
* flags types. (Flags types are like enumerations, but allow their
45
* values to be combined by bitwise or). A registered enumeration or
46
* flags type associates a name and a nickname with each allowed
47
* value, and the methods g_enum_get_value_by_name(),
48
* g_enum_get_value_by_nick(), g_flags_get_value_by_name() and
49
* g_flags_get_value_by_nick() can look up values by their name or
50
* nickname. When an enumeration or flags type is registered with the
51
* GLib type system, it can be used as value type for object
52
* properties, using g_param_spec_enum() or g_param_spec_flags().
54
* GObject ships with a utility called <link
55
* linkend="glib-mkenums">glib-mkenums</link> that can construct
56
* suitable type registration functions from C enumeration
34
61
/* --- prototypes --- */
169
* g_enum_register_static:
170
* @name: A nul-terminated string used as the name of the new type.
171
* @const_static_values: An array of #GEnumValue structs for the possible
172
* enumeration values. The array is terminated by a struct with all
173
* members being 0. GObject keeps a reference to the data, so it cannot
174
* be stack-allocated.
176
* Registers a new static enumeration type with the name @name.
178
* It is normally more convenient to let <link
179
* linkend="glib-mkenums">glib-mkenums</link> generate a
180
* my_enum_get_type() function from a usual C enumeration definition
181
* than to write one yourself using g_enum_register_static().
183
* Returns: The new type identifier.
142
186
g_enum_register_static (const gchar *name,
143
187
const GEnumValue *const_static_values)
214
* g_flags_register_static:
215
* @name: A nul-terminated string used as the name of the new type.
216
* @const_static_values: An array of #GFlagsValue structs for the possible
217
* flags values. The array is terminated by a struct with all members being 0.
218
* GObject keeps a reference to the data, so it cannot be stack-allocated.
220
* Registers a new static flags type with the name @name.
222
* It is normally more convenient to let <link
223
* linkend="glib-mkenums">glib-mkenums</link> generate a
224
* my_flags_get_type() function from a usual C enumeration definition
225
* than to write one yourself using g_flags_register_static().
227
* Returns: The new type identifier.
170
230
g_flags_register_static (const gchar *name,
171
231
const GFlagsValue *const_static_values)
258
* g_enum_complete_type_info:
259
* @g_enum_type: the type identifier of the type being completed
260
* @info: the #GTypeInfo struct to be filled in
261
* @const_values: An array of #GEnumValue structs for the possible
262
* enumeration values. The array is terminated by a struct with all
265
* This function is meant to be called from the complete_type_info()
266
* function of a #GTypePlugin implementation, as in the following
271
* my_enum_complete_type_info (GTypePlugin *plugin,
274
* GTypeValueTable *value_table)
276
* static const GEnumValue values[] = {
277
* { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
278
* { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
282
* g_enum_complete_type_info (type, info, values);
198
287
g_enum_complete_type_info (GType g_enum_type,
211
300
info->class_data = const_values;
304
* g_flags_complete_type_info:
305
* @g_flags_type: the type identifier of the type being completed
306
* @info: the #GTypeInfo struct to be filled in
307
* @const_values: An array of #GFlagsValue structs for the possible
308
* enumeration values. The array is terminated by a struct with all
311
* This function is meant to be called from the complete_type_info()
312
* function of a #GTypePlugin implementation, see the example for
313
* g_enum_complete_type_info() above.
215
316
g_flags_complete_type_info (GType g_flags_type,
381
* g_enum_get_value_by_name:
382
* @enum_class: a #GEnumClass
383
* @name: the name to look up
385
* Looks up a #GEnumValue by name.
387
* Returns: the #GEnumValue with name @name, or %NULL if the
388
* enumeration doesn't have a member with that name
280
391
g_enum_get_value_by_name (GEnumClass *enum_class,
281
392
const gchar *name)
410
* g_flags_get_value_by_name:
411
* @flags_class: a #GFlagsClass
412
* @name: the name to look up
414
* Looks up a #GFlagsValue by name.
416
* Returns: the #GFlagsValue with name @name, or %NULL if there is no
417
* flag with that name
299
420
g_flags_get_value_by_name (GFlagsClass *flags_class,
300
421
const gchar *name)
439
* g_enum_get_value_by_nick:
440
* @enum_class: a #GEnumClass
441
* @nick: the nickname to look up
443
* Looks up a #GEnumValue by nickname.
445
* Returns: the #GEnumValue with nickname @nick, or %NULL if the
446
* enumeration doesn't have a member with that nickname
318
449
g_enum_get_value_by_nick (GEnumClass *enum_class,
319
450
const gchar *nick)
468
* g_flags_get_value_by_nick:
469
* @flags_class: a #GFlagsClass
470
* @nick: the nickname to look up
472
* Looks up a #GFlagsValue by nickname.
474
* Returns: the #GFlagsValue with nickname @nick, or %NULL if there is
475
* no flag with that nickname
337
478
g_flags_get_value_by_nick (GFlagsClass *flags_class,
338
479
const gchar *nick)
498
* @enum_class: a #GEnumClass
499
* @value: the value to look up
501
* Returns the #GEnumValue for a value.
503
* Returns: the #GEnumValue for @value, or %NULL if @value is not a
504
* member of the enumeration
356
507
g_enum_get_value (GEnumClass *enum_class,
525
* g_flags_get_first_value:
526
* @flags_class: a #GFlagsClass
529
* Returns the first #GFlagsValue which is set in @value.
531
* Returns: the first #GFlagsValue which is set in @value, or %NULL if
374
535
g_flags_get_first_value (GFlagsClass *flags_class,
563
* @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
564
* @v_enum: enum value to be set
566
* Set the contents of a %G_TYPE_ENUM #GValue to @v_enum.
401
569
g_value_set_enum (GValue *value,
406
574
value->data[0].v_long = v_enum;
579
* @value: a valid #GValue whose type is derived from %G_TYPE_ENUM
581
* Get the contents of a %G_TYPE_ENUM #GValue.
583
* Returns: enum contents of @value
410
586
g_value_get_enum (const GValue *value)
414
590
return value->data[0].v_long;
595
* @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
596
* @v_flags: flags value to be set
598
* Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags.
418
601
g_value_set_flags (GValue *value,
423
606
value->data[0].v_ulong = v_flags;
611
* @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS
613
* Get the contents of a %G_TYPE_FLAGS #GValue.
615
* Returns: flags contents of @value
427
618
g_value_get_flags (const GValue *value)