From: Stefan Kost Date: Sat, 21 Jun 2008 11:27:45 +0000 (+0000) Subject: Migrating docs. X-Git-Tag: GLIB_2_17_3~64 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=672caa1a5138523516e76160de94ea2452eeada7;p=platform%2Fupstream%2Fglib.git Migrating docs. * docs/reference/gobject/tmpl/enumerations_flags.sgml: * gobject/genums.c: * gobject/genums.h: Migrating docs. svn path=/trunk/; revision=7066 --- diff --git a/ChangeLog b/ChangeLog index 85a612d16..1ee23ccc2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2008-06-21 Stefan Kost + + * docs/reference/gobject/tmpl/enumerations_flags.sgml: + * gobject/genums.c: + * gobject/genums.h: + Migrating docs. + 2008-06-21 Stefan Kost * docs/reference/gobject/tmpl/gboxed.sgml: diff --git a/docs/reference/gobject/tmpl/enumerations_flags.sgml b/docs/reference/gobject/tmpl/enumerations_flags.sgml deleted file mode 100644 index 2b72931f2..000000000 --- a/docs/reference/gobject/tmpl/enumerations_flags.sgml +++ /dev/null @@ -1,303 +0,0 @@ - -Enums and Flags - - -Enumeration and flags types - - - -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 glib-mkenums that can -construct suitable type registration functions from C enumeration definitions. - - - - -#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags(), -glib-mkenums - - - - - - - -The class of an enumeration type holds information about its -possible values. - - -@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 a flags type holds information about its -possible values. - - -@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. - - - -Returns the type identifier from a given #GEnumClass structure. - - -@class: a #GEnumClass - - - - -Returns the static type name from a given #GEnumClass structure. - - -@class: a #GEnumClass - - - - -Returns whether @type "is a" %G_TYPE_ENUM. - - -@type: a #GType ID. - - - - -Casts a derived #GEnumClass structure into a #GEnumClass structure. - - -@class: a valid #GEnumClass - - - - -Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM -or derived. - - -@class: a #GEnumClass - - - - -Returns whether @type "is a" %G_TYPE_FLAGS. - - -@type: a #GType ID. - - - - -Casts a derived #GFlagsClass structure into a #GFlagsClass structure. - - -@class: a valid #GFlagsClass - - - - -Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS -or derived. - - -@class: a #GFlagsClass - - - - -Returns the type identifier from a given #GFlagsClass structure. - - -@class: a #GFlagsClass - - - - -Returns the static type name from a given #GFlagsClass structure. - - -@class: a #GFlagsClass - - - - -A structure which contains a single enum value, it's name, and it's -nickname. - - -@value: the enum 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. - - -@value: the flags value -@value_name: the name of the value -@value_nick: the nickname of the value - - - -Returns the #GEnumValue for a value. - - -@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 - - - - -Looks up a #GEnumValue by name. - - -@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 - - - - -Looks up a #GEnumValue by nickname. - - -@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 - - - - -Returns the first #GFlagsValue which is set in @value. - - -@flags_class: a #GFlagsClass -@value: the value -@Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set - - - - -Looks up a #GFlagsValue by name. - - -@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 - - - - -Looks up a #GFlagsValue by nickname. - - -@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 - - - - -Registers a new static enumeration type with the name @name. - - -It is normally more convenient to let glib-mkenums -generate a my_enum_get_type() function from a usual C enumeration definition -than to write one yourself using 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. -@Returns: The new type identifier. - - - - -Registers a new static flags type with the name @name. - - -It is normally more convenient to let glib-mkenums -generate a my_flags_get_type() function from a usual C enumeration definition -than to write one yourself using 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. -@Returns: The new type identifier. - - - - -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); -} - - - - -@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, see the example for -g_enumeration_complete_type_info() above. - - -@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. - - diff --git a/gobject/genums.c b/gobject/genums.c index f5d2115b0..4c826a1bd 100644 --- a/gobject/genums.c +++ b/gobject/genums.c @@ -16,6 +16,24 @@ * 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(), + * glib-mkenums + * + * 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 glib-mkenums that can + * construct suitable type registration functions from C enumeration definitions. + */ /* * MT safe @@ -138,6 +156,22 @@ value_flags_enum_lcopy_value (const GValue *value, 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 glib-mkenums + * 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) @@ -166,6 +200,21 @@ g_enum_register_static (const gchar *name, 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 glib-mkenums + * 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) @@ -194,6 +243,34 @@ g_flags_register_static (const gchar *name, 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, @@ -211,6 +288,18 @@ g_enum_complete_type_info (GType g_enum_type, 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, @@ -276,6 +365,16 @@ g_flags_class_init (GFlagsClass *class, } } +/** + * 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) @@ -295,6 +394,16 @@ g_enum_get_value_by_name (GEnumClass *enum_class, 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) @@ -314,6 +423,16 @@ g_flags_get_value_by_name (GFlagsClass *flags_class, 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) @@ -333,6 +452,16 @@ g_enum_get_value_by_nick (GEnumClass *enum_class, 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) @@ -352,6 +481,16 @@ g_flags_get_value_by_nick (GFlagsClass *flags_class, 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) @@ -370,6 +509,15 @@ g_enum_get_value (GEnumClass *enum_class, 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) diff --git a/gobject/genums.h b/gobject/genums.h index 5d16c53c0..c8382a2ae 100644 --- a/gobject/genums.h +++ b/gobject/genums.h @@ -28,16 +28,82 @@ 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)) @@ -47,6 +113,19 @@ typedef struct _GEnumClass GEnumClass; 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; @@ -57,6 +136,17 @@ struct _GEnumClass 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; @@ -66,12 +156,30 @@ struct _GFlagsClass 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;