glib/docs/reference/gobject/tmpl/enumerations_flags.sgml
Matthias Clasen d619ee159b Additions.
Tue Oct 21 23:29:54 2003  Matthias Clasen  <maclas@gmx.de>

	* gobject/tmpl/gtypemodule.sgml:
	* gobject/tmpl/enumerations_flags.sgml:
	* gobject/tmpl/gtype.sgml: Additions.
2003-10-21 21:49:21 +00:00

287 lines
7.0 KiB
Plaintext

<!-- ##### 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" }
};
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.