path: root/docs/reference/gobject/tmpl/enumerations_flags.sgml

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

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

<!-- ##### SECTION Long_Description ##### -->
<para>
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

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

@g_type_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: 
@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.
@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.
@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.