2008-06-21 Stefan Kost <ensonic@users.sf.net>
+ * docs/reference/gobject/tmpl/enumerations_flags.sgml:
+ * gobject/genums.c:
+ * gobject/genums.h:
+ Migrating docs.
+
+2008-06-21 Stefan Kost <ensonic@users.sf.net>
+
* docs/reference/gobject/tmpl/gboxed.sgml:
* gobject/gboxed.c:
* gobject/gboxed.h:
+++ /dev/null
-<!-- ##### 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.
-
-
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:Enums and Flags
+ * @Short_description: Enumeration and flags types
+ * @See_also:#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags(),
+ * <link linkend="glib-mkenums">glib-mkenums</link>
+ *
+ * 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().
+ *
+ * GObject ships with a utility called <link linkend="glib-mkenums">glib-mkenums</link> that can
+ * construct suitable type registration functions from C enumeration definitions.
+ */
/*
* MT safe
return NULL;
}
+/**
+ * g_enum_register_static:
+ * @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.
+ *
+ * Registers a new static enumeration type with the name @name.
+ *
+ * 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().
+ *
+ * Returns: The new type identifier.
+ */
GType
g_enum_register_static (const gchar *name,
const GEnumValue *const_static_values)
return type;
}
+/**
+ * g_flags_register_static:
+ * @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.
+ *
+ * Registers a new static flags type with the name @name.
+ *
+ * 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().
+ *
+ * Returns: The new type identifier.
+ */
GType
g_flags_register_static (const gchar *name,
const GFlagsValue *const_static_values)
return type;
}
+/**
+ * g_enum_complete_type_info:
+ * @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.
+ *
+ * This function is meant to be called from the complete_type_info() function
+ * of a #GTypePlugin implementation, as in the following example:
+ *
+ * |[
+ * 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);
+ * }
+ * ]|
+ */
void
g_enum_complete_type_info (GType g_enum_type,
GTypeInfo *info,
info->class_data = const_values;
}
+/**
+ * g_flags_complete_type_info:
+ * @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.
+ *
+ * This function is meant to be called from the complete_type_info() function
+ * of a #GTypePlugin implementation, see the example for
+ * g_enum_complete_type_info() above.
+ */
void
g_flags_complete_type_info (GType g_flags_type,
GTypeInfo *info,
}
}
+/**
+ * g_enum_get_value_by_name:
+ * @enum_class: a #GEnumClass
+ * @name: the name to look up
+ *
+ * Looks up a #GEnumValue by name.
+ *
+ * Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn'
+ * t have a member with that name
+ */
GEnumValue*
g_enum_get_value_by_name (GEnumClass *enum_class,
const gchar *name)
return NULL;
}
+/**
+ * g_flags_get_value_by_name:
+ * @flags_class: a #GFlagsClass
+ * @name: the name to look up
+ *
+ * Looks up a #GFlagsValue by name.
+ *
+ * Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with
+ * that name
+ */
GFlagsValue*
g_flags_get_value_by_name (GFlagsClass *flags_class,
const gchar *name)
return NULL;
}
+/**
+ * g_enum_get_value_by_nick:
+ * @enum_class: a #GEnumClass
+ * @nick: the nickname to look up
+ *
+ * Looks up a #GEnumValue by nickname.
+ *
+ * Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn'
+ * t have a member with that nickname
+ */
GEnumValue*
g_enum_get_value_by_nick (GEnumClass *enum_class,
const gchar *nick)
return NULL;
}
+/**
+ * g_flags_get_value_by_nick:
+ * @flags_class: a #GFlagsClass
+ * @nick: the nickname to look up
+ *
+ * Looks up a #GFlagsValue by nickname.
+ *
+ * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag
+ * with that nickname
+ */
GFlagsValue*
g_flags_get_value_by_nick (GFlagsClass *flags_class,
const gchar *nick)
return NULL;
}
+/**
+ * g_enum_get_value:
+ * @enum_class: a #GEnumClass
+ * @value: the value to look up
+ *
+ * Returns the #GEnumValue for a value.
+ *
+ * Returns: the #GEnumValue for @value, or %NULL if @value is not
+ * a member of the enumeration
+ */
GEnumValue*
g_enum_get_value (GEnumClass *enum_class,
gint value)
return NULL;
}
+/**
+ * g_flags_get_first_value:
+ * @flags_class: a #GFlagsClass
+ * @value: the value
+ *
+ * Returns the first #GFlagsValue which is set in @value.
+ *
+ * Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set
+ */
GFlagsValue*
g_flags_get_first_value (GFlagsClass *flags_class,
guint value)
G_BEGIN_DECLS
/* --- type macros --- */
+/**
+ * G_TYPE_IS_ENUM:
+ * @type: a #GType ID.
+ *
+ * Returns: whether @type "is a" %G_TYPE_ENUM.
+ */
#define G_TYPE_IS_ENUM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_ENUM)
+/**
+ * G_ENUM_CLASS:
+ * @class: a valid #GEnumClass
+ *
+ * Casts a derived #GEnumClass structure into a #GEnumClass structure.
+ */
#define G_ENUM_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_ENUM, GEnumClass))
+/**
+ * G_IS_ENUM_CLASS:
+ * @class: a #GEnumClass
+ *
+ * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
+ * or derived.
+ */
#define G_IS_ENUM_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_ENUM))
+/**
+ * G_ENUM_CLASS_TYPE:
+ * @class: a #GEnumClass
+ *
+ * Returns: the type identifier from a given #GEnumClass structure.
+ */
#define G_ENUM_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class))
+/**
+ * G_ENUM_CLASS_TYPE_NAME:
+ * @class: a #GEnumClass
+ *
+ * Returns: the static type name from a given #GEnumClass structure.
+ */
#define G_ENUM_CLASS_TYPE_NAME(class) (g_type_name (G_ENUM_CLASS_TYPE (class)))
+
+
+/**
+ * G_TYPE_IS_FLAGS:
+ * @type: a #GType ID.
+ *
+ * Returns: whether @type "is a" %G_TYPE_FLAGS.
+ */
#define G_TYPE_IS_FLAGS(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_FLAGS)
+/**
+ * G_FLAGS_CLASS:
+ * @class: a valid #GFlagsClass
+ *
+ * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
+ */
#define G_FLAGS_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_FLAGS, GFlagsClass))
+/**
+ * G_IS_FLAGS_CLASS:
+ * @class: a #GFlagsClass
+ *
+ * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
+ * or derived.
+ */
#define G_IS_FLAGS_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_FLAGS))
+/**
+ * G_FLAGS_CLASS_TYPE:
+ * @class: a #GFlagsClass
+ *
+ * Returns: the type identifier from a given #GFlagsClass structure.
+ */
#define G_FLAGS_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class))
+/**
+ * G_FLAGS_CLASS_TYPE_NAME:
+ * @class: a #GFlagsClass
+ *
+ * Returns: the static type name from a given #GFlagsClass structure.
+ */
#define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class)))
+
+
#define G_VALUE_HOLDS_ENUM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM))
#define G_VALUE_HOLDS_FLAGS(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS))
typedef struct _GFlagsClass GFlagsClass;
typedef struct _GEnumValue GEnumValue;
typedef struct _GFlagsValue GFlagsValue;
+
+/**
+ * GEnumClass:
+ * @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.
+ *
+ * The class of an enumeration type holds information about its
+ * possible values.
+ */
struct _GEnumClass
{
GTypeClass g_type_class;
guint n_values;
GEnumValue *values;
};
+/**
+ * GFlagsClass:
+ * @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.
+ *
+ * The class of a flags type holds information about its
+ * possible values.
+ */
struct _GFlagsClass
{
GTypeClass g_type_class;
guint n_values;
GFlagsValue *values;
};
+/**
+ * GEnumValue:
+ * @value: the enum value
+ * @value_name: the name of the value
+ * @value_nick: the nickname of the value
+ *
+ * A structure which contains a single enum value, it's name, and it's
+ * nickname.
+ */
struct _GEnumValue
{
gint value;
const gchar *value_name;
const gchar *value_nick;
};
+/**
+ * GFlagsValue:
+ * @value: the flags value
+ * @value_name: the name of the value
+ * @value_nick: the nickname of the value
+ *
+ * A structure which contains a single flags value, it's name, and it's
+ * nickname.
+ */
struct _GFlagsValue
{
guint value;
projects / platform / upstream / glib.git / commitdiff