From: Ding-Yi Chen Date: Mon, 24 Aug 2009 07:55:57 +0000 (+1000) Subject: APIDOC: New: IBusSerializable. X-Git-Tag: 1.2.0.20090828~14^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=cca94cfa8938e7b07f84ba402a6e33db45b7ea5b;p=platform%2Fupstream%2Fibus.git APIDOC: New: IBusSerializable. Revised: IBusAttribute, IBusFactory, IBusObject, IBusObservedPath, IBusProperty --- diff --git a/src/ibusattribute.h b/src/ibusattribute.h index dc5e616..ac40b6d 100644 --- a/src/ibusattribute.h +++ b/src/ibusattribute.h @@ -48,16 +48,58 @@ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_ATTRIBUTE, IBusAttributeClass)) /* define IBusAttrList macros */ +/** + * IBUS_TYPE_ATTR_LIST: + * + * Return GType of IBus attribute list. + */ #define IBUS_TYPE_ATTR_LIST \ (ibus_attr_list_get_type ()) + +/** + * IBUS_ATTR_LIST: + * @obj: An object which is subject to casting. + * + * Casts an IBUS_ATTR_LIST or derived pointer into a (IBusAttrList*) pointer. + * Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. + */ #define IBUS_ATTR_LIST(obj) \ (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_ATTR_LIST, IBusAttrList)) + +/** + * IBUS_ATTR_LIST_CLASS: + * @klass: A class to be casted. + * + * Casts a derived IBusAttrListClass structure into a IBusAttrListClass structure. + */ #define IBUS_ATTR_LIST_CLASS(klass) \ (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_ATTR_LIST, IBusAttrListClass)) + +/** + * IBUS_IS_ATTR_LIST: + * @obj: Instance to check for being a IBUS_ATTR_LIST. + * + * Checks whether a valid GTypeInstance pointer is of type IBUS_ATTR_LIST. + */ #define IBUS_IS_ATTR_LIST(obj) \ (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_ATTR_LIST)) + +/** + * IBUS_IS_ATTR_LIST_CLASS: + * @klass: A class to be checked. + * + * Checks whether class "is a" valid IBusAttrListClass structure of type IBUS_ATTR_LIST or derived. + */ #define IBUS_IS_ATTR_LIST_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_ATTR_LIST)) + +/** + * IBUS_ATTR_LIST_GET_CLASS: + * @obj: An object. + * + * Get the class of a given object and cast the class to IBusAttrListClass. + */ #define IBUS_ATTR_LIST_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_ATTR_LIST, IBusAttrListClass)) @@ -67,7 +109,7 @@ * @IBUS_ATTR_TYPE_FOREGROUND: Foreground color. * @IBUS_ATTR_TYPE_BACKGROUND: Background color. * - * Type of IBusText attribute. + * Type enumeration of IBusText attribute. */ typedef enum { IBUS_ATTR_TYPE_UNDERLINE = 1, diff --git a/src/ibusfactory.h b/src/ibusfactory.h index 6d1eac8..95f8a68 100644 --- a/src/ibusfactory.h +++ b/src/ibusfactory.h @@ -52,16 +52,58 @@ #define IBUS_FACTORY_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_FACTORY, IBusFactoryClass)) +/** + * IBUS_TYPE_FACTORY_INFO: + * + * Return GType of IBus factory information. + */ #define IBUS_TYPE_FACTORY_INFO \ (ibus_factory_info_get_type ()) + +/** + * IBUS_FACTORY_INFO: + * @obj: An object which is subject to casting. + * + * Casts an IBUS_FACTORY_INFO or derived pointer into a (IBusFactoryInfo*) pointer. + * Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. + */ #define IBUS_FACTORY_INFO(obj) \ (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_FACTORY_INFO, IBusFactoryInfo)) + +/** + * IBUS_FACTORY_INFO_CLASS: + * @klass: A class to be casted. + * + * Casts a derived IBusFactoryInfoClass structure into a IBusFactoryInfoClass structure. + */ #define IBUS_FACTORY_INFO_CLASS(klass) \ (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_FACTORY_INFO, IBusFactoryInfoClass)) + +/** + * IBUS_IS_FACTORY_INFO: + * @obj: Instance to check for being a IBUS_FACTORY_INFO. + * + * Checks whether a valid GTypeInstance pointer is of type IBUS_FACTORY_INFO. + */ #define IBUS_IS_FACTORY_INFO(obj) \ (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_FACTORY_INFO)) + +/** + * IBUS_IS_FACTORY_INFO_CLASS: + * @klass: A class to be checked. + * + * Checks whether class "is a" valid IBusFactoryInfoClass structure of type IBUS_FACTORY_INFO or derived. + */ #define IBUS_IS_FACTORY_INFO_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_FACTORY_INFO)) + +/** + * IBUS_FACTORY_INFO_GET_CLASS: + * @obj: An object. + * + * Get the class of a given object and cast the class to IBusFactoryInfoClass. + */ #define IBUS_FACTORY_INFO_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_FACTORY_INFO, IBusFactoryInfoClass)) diff --git a/src/ibusobject.h b/src/ibusobject.h index 987f66e..a08bb5a 100644 --- a/src/ibusobject.h +++ b/src/ibusobject.h @@ -78,7 +78,7 @@ typedef struct _IBusObjectClass IBusObjectClass; * IBusObject: * * All the fields in the IBusObject structure are - * prtivate to the #IBusObject and should never be accessed directly. + * private to the #IBusObject and should never be accessed directly. */ struct _IBusObject { GObject parent; diff --git a/src/ibusobservedpath.h b/src/ibusobservedpath.h index eb2c6c1..d0e9fe5 100644 --- a/src/ibusobservedpath.h +++ b/src/ibusobservedpath.h @@ -132,7 +132,7 @@ gboolean ibus_observed_path_check_modification (IBusObservedPath * @indent: number of indent. * * Append the observed path to a string with following format: - * <path mtime="modified time" >path</path> + * <path mtime="<i>modified time</i>" ><i>path</i></path> */ void ibus_observed_path_output (IBusObservedPath *path, GString *output, diff --git a/src/ibusproperty.h b/src/ibusproperty.h index bb895b2..3460bc2 100644 --- a/src/ibusproperty.h +++ b/src/ibusproperty.h @@ -41,9 +41,6 @@ G_BEGIN_DECLS /* * Type macros. */ -#define IBUS_TYPE_PROPERTY (ibus_property_get_type ()) -#define IBUS_TYPE_PROP_LIST (ibus_prop_list_get_type ()) - /* define IBusProperty macros */ #define IBUS_TYPE_PROPERTY \ (ibus_property_get_type ()) @@ -59,16 +56,59 @@ G_BEGIN_DECLS (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROPERTY, IBusPropertyClass)) /* define IBusPropList macros */ +/** + * IBUS_TYPE_PROP_LIST: + * @returns: IBusPropList GType. + * + * Returns GType of IBus property list. + */ #define IBUS_TYPE_PROP_LIST \ (ibus_prop_list_get_type ()) + +/** + * IBUS_PROP_LIST: + * @obj: An object which is subject to casting. + * + * Casts an IBUS_PROP_LIST or derived pointer into a (IBusPropList*) pointer. + * Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. + */ #define IBUS_PROP_LIST(obj) \ (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_PROP_LIST, IBusPropList)) + +/** + * IBUS_PROP_LIST_CLASS: + * @klass: A class to be casted. + * + * Casts a derived IBusPropListClass structure into a IBusPropListClass structure. + */ #define IBUS_PROP_LIST_CLASS(klass) \ (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_PROP_LIST, IBusPropListClass)) + +/** + * IBUS_IS_PROP_LIST: + * @obj: Instance to check for being a IBUS_PROP_LIST. + * + * Checks whether a valid GTypeInstance pointer is of type IBUS_PROP_LIST. + */ #define IBUS_IS_PROP_LIST(obj) \ (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_PROP_LIST)) + +/** + * IBUS_IS_PROP_LIST_CLASS: + * @klass: A class to be checked. + * + * Checks whether class "is a" valid IBusPropListClass structure of type IBUS_PROP_LIST or derived. + */ #define IBUS_IS_PROP_LIST_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_PROP_LIST)) + +/** + * IBUS_PROP_LIST_GET_CLASS: + * @obj: An object. + * + * Get the class of a given object and cast the class to IBusPropListClass. + */ #define IBUS_PROP_LIST_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROP_LIST, IBusPropListClass)) @@ -81,7 +121,7 @@ G_BEGIN_DECLS * items. * @PROP_TYPE_SEPARATOR: A separator for menu. * - * Type of IBusProperty. + * Type enumeration of IBusProperty. */ typedef enum { PROP_TYPE_NORMAL = 0, @@ -165,7 +205,7 @@ struct _IBusPropertyClass { * IBusPropList: * @properties: GArray that holds IBusProperties. * - * A GArray of IBusProperties. + * An array of IBusProperties. */ struct _IBusPropList { IBusSerializable parent; @@ -183,12 +223,12 @@ GType ibus_property_get_type (); /** * ibus_property_new: * @key: Unique Identity for the IBusProperty. - * @icon: Icon file for the IBusProperty. + * @type: IBusPropType of IBusProperty. * @label: Text shown in UI. + * @icon: Icon file for the IBusProperty. * @tooltip: Message shown if mouse hovered the IBusProperty. * @sensitive: Whether the IBusProperty is sensitive to keyboard and mouse event. * @visible: Whether the IBusProperty is visible. - * @type: IBusPropType of IBusProperty. * @state: IBusPropState of IBusProperty. * @prop_list: IBusPropList that contains sub IBusProperties. * @returns: A newly allocated IBusProperty. @@ -218,7 +258,7 @@ void ibus_property_set_label (IBusProperty *prop, /** * ibus_property_set_icon: * @prop: An IBusProperty. - * @icon: Icon shown in UI. It could be a full path of an icon file or an icon name. + * @icon: Icon shown in UI. It could be a full path of an icon file or an icon name. * * Set the icon of IBusProperty. */ diff --git a/src/ibusserializable.c b/src/ibusserializable.c index 8ece9fc..74b2e9c 100644 --- a/src/ibusserializable.c +++ b/src/ibusserializable.c @@ -78,13 +78,6 @@ ibus_serializable_get_type (void) return type; } -/** - * ibus_serializable_new: - * - * Creates a new instance of an #IBusSerializable. - * - * Returns: a new instance of #IBusSerializable. - */ IBusSerializable * ibus_serializable_new (void) { diff --git a/src/ibusserializable.h b/src/ibusserializable.h index a99f123..1b9f6c4 100644 --- a/src/ibusserializable.h +++ b/src/ibusserializable.h @@ -17,6 +17,30 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusserializable + * @short_description: A serializable object. + * @stability: Stable + * + * An IBusSerializable is an IBus object which can be serialized, that is, + * to be to and from an IBusMessage. + * + * This class is to be extended by other class that requires serialization. + * An extended class should overrides following methods: + * + * + * serialize(object,iter): for serialize. + * + * + * deserialize(object,iter): for deserialize. + * + * + * copy(desc,src): for copy between IBusSerializable. + * + * + * See IBusSerializableSerializeFunc(), IBusSerializableDeserializeFunc(), IBusSerializableCopyFunc() + * for function prototype. + */ #ifndef __IBUS_SERIALIZABLE_H_ #define __IBUS_SERIALIZABLE_H_ @@ -41,10 +65,38 @@ #define IBUS_SERIALIZABLE_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_SERIALIZABLE, IBusSerializableClass)) +/** + * ibus_serializable_set_attachment: + * @o: An IBusSerializable. + * @k: String formatted key for indexing value. + * @v: Value to be attached. Should be also serializable. + * + * Attach a value to an IBusSerializable. + * This macro is an convenient wrapper of ibus_serializable_set_qattachment(). + */ #define ibus_serializable_set_attachment(o, k, v) \ ibus_serializable_set_qattachment (o, g_quark_from_string (k), v) + +/** + * ibus_serializable_get_attachment: + * @o: An IBusSerializable. + * @k: String formatted key for indexing value. + * @v: Value to be attached. Should be also serializable. + * + * Get a value from attachment of an IBusSerializable. + * This macro is an convenient wrapper of ibus_serializable_get_qattachment(). + */ #define ibus_serializable_get_attachment(o, k, v) \ ibus_serializable_get_qattachment (o, g_quark_from_string (k)) + +/** + * ibus_serializable_remove_attachment: + * @o: An IBusSerializable. + * @k: String formatted key for indexing value. + * + * Remove a value from attachment of an IBusSerializable. + * This macro is an convenient wrapper of ibus_serializable_remove_qattachment(). + */ #define ibus_serializable_remove_attachment(o, k) \ ibus_serializable_remove_qattachment (o, g_quark_from_string (k)) @@ -52,11 +104,12 @@ G_BEGIN_DECLS typedef struct _IBusSerializable IBusSerializable; typedef struct _IBusSerializableClass IBusSerializableClass; + /** * IBusSerializable: * * All the fields in the IBusSerializable structure are - * prtivate to the #IBusSerializable and should never be accessed directly. + * private to the #IBusSerializable and should never be accessed directly. */ struct _IBusSerializable { GObject parent; @@ -64,10 +117,43 @@ struct _IBusSerializable { guint32 flags; }; +/** + * IBusSerializableSerializeFunc: + * @object: An IBusSerializable. + * @iter: An IBusMessageIter. + * @returns: TRUE if succeed; FALSE otherwise. + * + * Prototype of serialize function. + * Serialize function convert an IBusSerializable to IBusMessageIter. + * Returns a gboolean value which indicates whether the conversion is success. + * Return TRUE if succeed. + */ typedef gboolean (* IBusSerializableSerializeFunc) (IBusSerializable *object, IBusMessageIter *iter); + +/** + * IBusSerializableDeserializeFunc: + * @object: An IBusSerializable. + * @iter: An IBusMessageIter. + * @returns: TRUE if succeed; FALSE otherwise. + * + * Prototype of deserialize function. + * Deserialize function convert an IBusMessageIter to IBusSerializable. + * Returns a gboolean value which indicates whether the conversion is success. + */ typedef gboolean (* IBusSerializableDeserializeFunc) (IBusSerializable *object, IBusMessageIter *iter); + +/** + * IBusSerializableCopyFunc: + * @dest: The destination IBusSerializable. + * @src: A source IBusMessageIter. + * @returns: TRUE if succeed; FALSE otherwise. + * + * Prototype of copy function. + * Copy function copy from source IBusSerializable to the destination one. + * Returns a gboolean value which indicates whether the copying is success. + */ typedef gboolean (* IBusSerializableCopyFunc) (IBusSerializable *dest, const IBusSerializable *src); struct _IBusSerializableClass { @@ -89,18 +175,92 @@ struct _IBusSerializableClass { }; GType ibus_serializable_get_type (void); + +/** + * ibus_serializable_new: + * + * Creates a new instance of an #IBusSerializable. + * + * Returns: a new instance of #IBusSerializable. + */ IBusSerializable * ibus_serializable_new (void); + +/** + * ibus_serializable_set_qattachment: + * @object: An IBusSerializable. + * @key: String formatted key for indexing value. + * @value: Value to be attached. Should be also serializable. + * @returns: TRUE if succeed; FALSE otherwise. + * + * Attach a value to an IBusSerializable. The value should be serializable as well. + * Basic type such as integer, string are deemed to be serializable. + * + * @see_also: ibus_serializable_set_attachment(). + */ gboolean ibus_serializable_set_qattachment (IBusSerializable *object, GQuark key, const GValue *value); + +/** + * ibus_serializable_get_qattachment: + * @object: An IBusSerializable. + * @key: String formatted key for indexing value. + * @returns: The attached value; or NULL if fail to retrieve the value. + * + * Get a value from attachment of an IBusSerializable. + * @see_also: ibus_serializable_set_attachment(). + */ const GValue *ibus_serializable_get_qattachment (IBusSerializable *object, GQuark key); + +/** + * ibus_serializable_remove_qattachment: + * @object: An IBusSerializable. + * @key: String formatted key for indexing value. + * + * Remove a value from attachment of an IBusSerializable. + * @see_also: ibus_serializable_remove_attachment(). + */ void ibus_serializable_remove_qattachment (IBusSerializable *object, GQuark key); + +/** + * ibus_serializable_copy: + * @object: An IBusSerializable. + * @returns: A newly allocated clone object; or NULL if @object is not serializable. + * + * Clone an IBusSerializable. + * The copy method should be implemented in extended class. + * + * @see_also: IBusSerializableCopyFunc(). + */ IBusSerializable *ibus_serializable_copy (IBusSerializable *object); + +/** + * ibus_serializable_serialize: + * @object: An IBusSerializable. + * @iter: An IBusMessageIter. + * @returns: TRUE if succeed; FALSE otherwise. + * + * Serialize an IBusSerializable to an IBusMessageIter. + * The serialize method should be implemented in extended class. + * + * @see_also: IBusSerializableCopyFunc(). + */ gboolean ibus_serializable_serialize (IBusSerializable *object, IBusMessageIter *iter); + +/** + * ibus_serializable_deserialize: + * @iter: An IBusMessageIter. + * @returns: The deserialized IBusSerializable. + * + * Deserialize an IBusMessageIter to an IBusSerializable/ + * The deserialize method should be implemented in extended class. + * + * @see_also: IBusSerializableCopyFunc(). + */ IBusSerializable *ibus_serializable_deserialize (IBusMessageIter *iter); G_END_DECLS