(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))
* @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,
#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))
* IBusObject:
*
* All the fields in the <structname>IBusObject</structname> 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;
* @indent: number of indent.
*
* Append the observed path to a string with following format:
- * <path mtime="<i>modified time</i>" ><i>path</i></path>
+ * <path mtime="<i>modified time</i>" ><i>path</i></path>
*/
void ibus_observed_path_output (IBusObservedPath *path,
GString *output,
/*
* 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 ())
(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))
* items.
* @PROP_TYPE_SEPARATOR: A separator for menu.
*
- * Type of IBusProperty.
+ * Type enumeration of IBusProperty.
*/
typedef enum {
PROP_TYPE_NORMAL = 0,
* IBusPropList:
* @properties: GArray that holds IBusProperties.
*
- * A GArray of IBusProperties.
+ * An array of IBusProperties.
*/
struct _IBusPropList {
IBusSerializable parent;
/**
* 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.
/**
* 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.
*/
return type;
}
-/**
- * ibus_serializable_new:
- *
- * Creates a new instance of an #IBusSerializable.
- *
- * Returns: a new instance of #IBusSerializable.
- */
IBusSerializable *
ibus_serializable_new (void)
{
* 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:
+ * <itemizedlist>
+ * <listitem>
+ * <para><function>serialize(object,iter)</function>: for serialize.</para>
+ * </listitem>
+ * <listitem>
+ * <para><function>deserialize(object,iter)</function>: for deserialize.</para>
+ * </listitem>
+ * <listitem>
+ * <para><function>copy(desc,src)</function>: for copy between IBusSerializable.</para>
+ * </listitem>
+ * </itemizedlist>
+ * See IBusSerializableSerializeFunc(), IBusSerializableDeserializeFunc(), IBusSerializableCopyFunc()
+ * for function prototype.
+ */
#ifndef __IBUS_SERIALIZABLE_H_
#define __IBUS_SERIALIZABLE_H_
#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))
typedef struct _IBusSerializable IBusSerializable;
typedef struct _IBusSerializableClass IBusSerializableClass;
+
/**
* IBusSerializable:
*
* All the fields in the <structname>IBusSerializable</structname> 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;
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 {
};
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