mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-30 17:36:16 +01:00
304 lines
8.2 KiB
Plaintext
304 lines
8.2 KiB
Plaintext
<!-- ##### 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.
|
|
|
|
|