glib/docs/reference/gobject/tmpl/enumerations_flags.sgml

<!-- ##### SECTION Title ##### -->
Enums and Flags

<!-- ##### SECTION Short_Description ##### -->
Enumeration and flags types

<!-- ##### SECTION Long_Description ##### -->
<para>
The GLib type system provides fundamental types for enumeration and flags types. (Flags types
are like enumerations, but allow their values to be combined by bitwise or). A registered 
enumeration or flags type associates a name and a nickname with each allowed value, and 
the methods g_enum_get_value_by_name(), g_enum_get_value_by_nick(), g_flags_get_value_by_name()
and g_flags_get_value_by_nick() can look up values by their name or nickname.
When an enumeration or flags type is registered with the GLib type system, it can
be used as value type for object properties, using g_param_spec_enum() or 
g_param_spec_flags().
</para>
<para>
GObject ships with a utility called <link linkend="glib-mkenums">glib-mkenums</link> that can 
construct suitable type registration functions from C enumeration definitions.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags(), 
<link linkend="glib-mkenums">glib-mkenums</link>
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GEnumClass ##### -->
<para>
The class of an enumeration type holds information about its 
possible values.
</para>

@g_type_class: the parent class
@minimum: the smallest possible value.
@maximum: the largest possible value.
@n_values: the number of possible values.
@values: an array of #GEnumValue structs describing the 
individual values.

<!-- ##### STRUCT GFlagsClass ##### -->
<para>
The class of a flags type holds information about its 
possible values.
</para>

@g_type_class: the parent class
@mask: a mask covering all possible values.
@n_values: the number of possible values.
@values: an array of #GFlagsValue structs describing the 
individual values.

<!-- ##### MACRO G_ENUM_CLASS_TYPE ##### -->
<para>
Returns the type identifier from a given #GEnumClass structure.
</para>

@class: a #GEnumClass


<!-- ##### MACRO G_ENUM_CLASS_TYPE_NAME ##### -->
<para>
Returns the static type name from a given #GEnumClass structure.
</para>

@class: a #GEnumClass


<!-- ##### MACRO G_TYPE_IS_ENUM ##### -->
<para>
Returns whether @type "is a" %G_TYPE_ENUM.
</para>

@type: a #GType ID.


<!-- ##### MACRO G_ENUM_CLASS ##### -->
<para>
Casts a derived #GEnumClass structure into a #GEnumClass structure.
</para>

@class: a valid #GEnumClass


<!-- ##### MACRO G_IS_ENUM_CLASS ##### -->
<para>
Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
or derived.
</para>

@class: a #GEnumClass


<!-- ##### MACRO G_TYPE_IS_FLAGS ##### -->
<para>
Returns whether @type "is a" %G_TYPE_FLAGS.
</para>

@type: a #GType ID.


<!-- ##### MACRO G_FLAGS_CLASS ##### -->
<para>
Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
</para>

@class: a valid #GFlagsClass


<!-- ##### MACRO G_IS_FLAGS_CLASS ##### -->
<para>
Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
or derived.
</para>

@class: a #GFlagsClass


<!-- ##### MACRO G_FLAGS_CLASS_TYPE ##### -->
<para>
Returns the type identifier from a given #GFlagsClass structure.
</para>

@class: a #GFlagsClass


<!-- ##### MACRO G_FLAGS_CLASS_TYPE_NAME ##### -->
<para>
Returns the static type name from a given #GFlagsClass structure.
</para>

@class: a #GFlagsClass


<!-- ##### STRUCT GEnumValue ##### -->
<para>
A structure which contains a single enum value, it's name, and it's
nickname.
</para>

@value: the enum value
@value_name: the name of the value
@value_nick: the nickname of the value

<!-- ##### STRUCT GFlagsValue ##### -->
<para>
A structure which contains a single flags value, it's name, and it's
nickname.
</para>

@value: the flags value
@value_name: the name of the value
@value_nick: the nickname of the value

<!-- ##### FUNCTION g_enum_get_value ##### -->
<para>
Returns the #GEnumValue for a value.
</para>

@enum_class: a #GEnumClass
@value: the value to look up
@Returns: the #GEnumValue for @value, or %NULL if @value is not 
a member of the enumeration


<!-- ##### FUNCTION g_enum_get_value_by_name ##### -->
<para>
Looks up a #GEnumValue by name.
</para>

@enum_class: a #GEnumClass
@name: the name to look up
@Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn'
t have a member with that name


<!-- ##### FUNCTION g_enum_get_value_by_nick ##### -->
<para>
Looks up a #GEnumValue by nickname.
</para>

@enum_class: a #GEnumClass
@nick: the nickname to look up
@Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn'
t have a member with that nickname


<!-- ##### FUNCTION g_flags_get_first_value ##### -->
<para>
Returns the first #GFlagsValue which is set in @value.
</para>

@flags_class: a #GFlagsClass
@value: the value
@Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set


<!-- ##### FUNCTION g_flags_get_value_by_name ##### -->
<para>
Looks up a #GFlagsValue by name.
</para>

@flags_class: a #GFlagsClass
@name: the name to look up
@Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with
that name


<!-- ##### FUNCTION g_flags_get_value_by_nick ##### -->
<para>
Looks up a #GFlagsValue by nickname.
</para>

@flags_class: a #GFlagsClass
@nick: the nickname to look up
@Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag
with that nickname


<!-- ##### FUNCTION g_enum_register_static ##### -->
<para>
Registers a new static enumeration type with the name @name. 
</para>
<para>
It is normally more convenient to let <link linkend="glib-mkenums">glib-mkenums</link> 
generate a my_enum_get_type() function from a usual C enumeration definition
than to write one yourself using g_enum_register_static().
</para>

@name: A nul-terminated string used as the name of the new type.
@const_static_values: An array of #GEnumValue structs for the possible
  enumeration values. The array is terminated by a struct with all 
  members being 0. GObject keeps a reference to the data, so it cannot
  be stack-allocated.
@Returns: The new type identifier.


<!-- ##### FUNCTION g_flags_register_static ##### -->
<para>
Registers a new static flags type with the name @name. 
</para>
<para>
It is normally more convenient to let <link linkend="glib-mkenums">glib-mkenums</link> 
generate a my_flags_get_type() function from a usual C enumeration definition
than to write one yourself using g_flags_register_static().
</para>

@name: A nul-terminated string used as the name of the new type.
@const_static_values: An array of #GFlagsValue structs for the possible
  flags values. The array is terminated by a struct with all members being 0.
  GObject keeps a reference to the data, so it cannot be stack-allocated.
@Returns: The new type identifier.


<!-- ##### FUNCTION g_enum_complete_type_info ##### -->
<para>
This function is meant to be called from the complete_type_info() function 
of a #GTypePlugin implementation, as in the following example:
<informalexample>
<programlisting>
static void
my_enum_complete_type_info (GTypePlugin     *plugin,
                            GType            g_type,
                            GTypeInfo       *info,
                            GTypeValueTable *value_table)
{
  static const GEnumValue values[] = {
    { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
    { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
    { 0, NULL, NULL }
  };  
   
  g_enum_complete_type_info (type, info, values);  
}
</programlisting>
</informalexample>
</para>

@g_enum_type: the type identifier of the type being completed
@info: the #GTypeInfo struct to be filled in
@const_values: An array of #GEnumValue structs for the possible
  enumeration values. The array is terminated by a struct with all 
  members being 0.


<!-- ##### FUNCTION g_flags_complete_type_info ##### -->
<para>
This function is meant to be called from the complete_type_info() function 
of a #GTypePlugin implementation, see the example for 
g_enumeration_complete_type_info() above.
</para>

@g_flags_type: the type identifier of the type being completed
@info: the #GTypeInfo struct to be filled in
@const_values: An array of #GFlagsValue structs for the possible
  enumeration values. The array is terminated by a struct with all 
  members being 0.