GNOME.org
 

glib r7066 - in trunk: . docs/reference/gobject/tmpl gobject

Author: stefkost
Date: Sat Jun 21 11:27:45 2008
New Revision: 7066
URL: http://svn.gnome.org/viewvc/glib?rev=7066&view=rev

Log:
	* docs/reference/gobject/tmpl/enumerations_flags.sgml:
	* gobject/genums.c:
	* gobject/genums.h:
	  Migrating docs.



Removed:
   trunk/docs/reference/gobject/tmpl/enumerations_flags.sgml
Modified:
   trunk/ChangeLog
   trunk/docs/reference/gobject/tmpl/   (props changed)
   trunk/gobject/genums.c
   trunk/gobject/genums.h

Modified: trunk/gobject/genums.c
==============================================================================
--- trunk/gobject/genums.c	(original)
+++ trunk/gobject/genums.c	Sat Jun 21 11:27:45 2008
@@ -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(), 
+ * <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
@@ -138,6 +156,22 @@
   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)
@@ -166,6 +200,21 @@
   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)
@@ -194,6 +243,34 @@
   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 @@
   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_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 @@
   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 @@
   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 @@
   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 @@
   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 @@
   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)

Modified: trunk/gobject/genums.h
==============================================================================
--- trunk/gobject/genums.h	(original)
+++ trunk/gobject/genums.h	Sat Jun 21 11:27:45 2008
@@ -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 _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 @@
   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 @@
   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;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]