diff options
author | dchen@redhat.com <dchen@dchen.redhat.com> | 2009-03-27 14:17:35 +1000 |
---|---|---|
committer | dchen@redhat.com <dchen@dchen.redhat.com> | 2009-03-27 14:17:35 +1000 |
commit | e3fe226e2ddbe7754ed9cb0c60301e4959075eb1 (patch) | |
tree | 1ead0c2c0db0064775afbdaf24f7a6639cacc8ff /src | |
parent | 7c6b337ece598b5c0cf9c92b0888b45f8770ff83 (diff) | |
download | ibus-e3fe226e2ddbe7754ed9cb0c60301e4959075eb1.tar.gz ibus-e3fe226e2ddbe7754ed9cb0c60301e4959075eb1.tar.xz ibus-e3fe226e2ddbe7754ed9cb0c60301e4959075eb1.zip |
API-DOC and Fix iBus Google issue 320.
Diffstat (limited to 'src')
-rw-r--r-- | src/ibusattribute.h | 121 | ||||
-rw-r--r-- | src/ibusconnection.h | 9 | ||||
-rw-r--r-- | src/ibusengine.c | 118 | ||||
-rw-r--r-- | src/ibusenginedesc.h | 68 | ||||
-rw-r--r-- | src/ibusobject.h | 15 | ||||
-rw-r--r-- | src/ibusproperty.h | 155 | ||||
-rw-r--r-- | src/ibustext.h | 82 | ||||
-rw-r--r-- | src/ibustypes.h | 61 |
8 files changed, 621 insertions, 8 deletions
diff --git a/src/ibusattribute.h b/src/ibusattribute.h index 3a0ff7f..a3907c7 100644 --- a/src/ibusattribute.h +++ b/src/ibusattribute.h @@ -17,11 +17,19 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusattribute + * @short_description: Attributes of IBusText. + * @stability: Stable + * @see_also: #IBusText + * + * An IBusAttribute represents an attribute that associate to IBusText. + * It decorates preedit buffer and auxiliary text with underline, foreground and background colors. + */ #ifndef __IBUS_ATTRIBUTE_H_ #define __IBUS_ATTRIBUTE_H_ #include "ibusserializable.h" - /* * Type macros. */ @@ -53,12 +61,29 @@ #define IBUS_ATTR_LIST_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_ATTR_LIST, IBusAttrListClass)) +/** + * IBusAttrType: + * @IBUS_ATTR_TYPE_UNDERLINE: Decorate with underline. + * @IBUS_ATTR_TYPE_FOREGROUND: Foreground color. + * @IBUS_ATTR_TYPE_BACKGROUND: Background color. + * + * Type of IBusText attribute. + */ typedef enum { IBUS_ATTR_TYPE_UNDERLINE = 1, IBUS_ATTR_TYPE_FOREGROUND = 2, IBUS_ATTR_TYPE_BACKGROUND = 3, } IBusAttrType; +/** + * IBusAttrUnderline: + * @IBUS_ATTR_UNDERLINE_NONE: No underline. + * @IBUS_ATTR_UNDERLINE_SINGLE: Single underline. + * @IBUS_ATTR_UNDERLINE_DOUBLE: Double underline. + * @IBUS_ATTR_UNDERLINE_LOW: Low underline ? %FIXME + * + * Type of IBusText attribute. + */ typedef enum { IBUS_ATTR_UNDERLINE_NONE = 0, IBUS_ATTR_UNDERLINE_SINGLE = 1, @@ -73,10 +98,21 @@ typedef struct _IBusAttributeClass IBusAttributeClass; typedef struct _IBusAttrList IBusAttrList; typedef struct _IBusAttrListClass IBusAttrListClass; + +/** + * IBusAttribute: + * @type: IBusAttributeType + * @value: Value for the type. + * @start_index: The starting index, inclusive. + * @end_index: The ending index, exclusive. + * + * Signify the type, value and scope of the attribute. + * The scope starts from @start_index till the @end_index-1. + */ struct _IBusAttribute { IBusSerializable parent; - /* members */ + /*< public >*/ guint type; guint value; guint start_index; @@ -87,10 +123,16 @@ struct _IBusAttributeClass { IBusSerializableClass parent; }; +/** + * IBusAttrList: + * @attributes: GArray that holds #IBusAttribute. + * + * Array of IBusAttribute. + */ struct _IBusAttrList { IBusSerializable parent; - /* members */ + /*< public >*/ GArray *attributes; }; @@ -98,26 +140,99 @@ struct _IBusAttrListClass { IBusSerializableClass parent; }; +/** + * ibus_attribute_get_type: + * @returns: GType of IBusAttribute. + * + * Returns GType of IBusAttribute. + */ GType ibus_attribute_get_type (); + +/** + * ibus_attribute_new: + * @type: Type of the attribute. + * @value: Value of the attribute. + * @start_index: Where attribute starts. + * @end_index: Where attribute ends. + * @returns: A newly allocated IBusAttribute. + * + * New an IBusAttribute. + */ IBusAttribute *ibus_attribute_new (guint type, guint value, guint start_index, guint end_index); +/** + * ibus_attr_underline_new: + * @underline_type: Type of underline. + * @start_index: Where attribute starts. + * @end_index: Where attribute ends. + * @returns: A newly allocated IBusAttribute. + * + * New an underline IBusAttribute. + */ IBusAttribute *ibus_attr_underline_new (guint underline_type, guint start_index, guint end_index); +/** + * ibus_attr_foreground_new: + * @color: Color in RGB. + * @start_index: Where attribute starts. + * @end_index: Where attribute ends. + * @returns: A newly allocated IBusAttribute. + * + * New an foreground IBusAttribute. + */ IBusAttribute *ibus_attr_foreground_new (guint color, guint start_index, guint end_index); +/** + * ibus_attr_background_new: + * @color: Color in RGB. + * @start_index: Where attribute starts. + * @end_index: Where attribute ends. + * @returns: A newly allocated IBusAttribute. + * + * New an background IBusAttribute. + */ IBusAttribute *ibus_attr_background_new (guint color, guint start_index, guint end_index); +/** + * ibus_attr_list_get_type: + * @returns: GType of IBusAttrList. + * + * Returns GType of IBusAttrList. + */ GType ibus_attr_list_get_type (); + +/** + * ibus_attr_list_new: + * @returns: A newly allocated IBusAttrList. + * + * New an IBusAttrList. + */ IBusAttrList *ibus_attr_list_new (); + +/** + * ibus_attr_list_append: + * @attr_list: An IBusAttrList instance. + * @attr: The IBusAttribute instance to be appended. + * + * Append an IBusAttribute to IBusAttrList. + */ void ibus_attr_list_append (IBusAttrList *attr_list, IBusAttribute *attr); +/** + * ibus_attr_list_get: + * @attr_list: An IBusAttrList instance. + * @index: Index of the @attr_list. + * @returns: IBusAttribute at given index, NULL if no such IBusAttribute. + * + * Returns IBusAttribute at given index. + */ IBusAttribute *ibus_attr_list_get (IBusAttrList *attr_list, guint index); diff --git a/src/ibusconnection.h b/src/ibusconnection.h index 5a8e099..7ebf6e6 100644 --- a/src/ibusconnection.h +++ b/src/ibusconnection.h @@ -17,6 +17,15 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusconnection + * @short_description: DBusConnection wrapper. + * @see_also: <ulink url="http://dbus.freedesktop.org/doc/api/html/structDBusConnection.html">DBusConnection</ulink> + * + * An IBusConnection provides DBusConnection wrapper. + * It can be used to connect to either dBus or iBus daemon. + */ + #ifndef __IBUS_CONNECTION_H_ #define __IBUS_CONNECTION_H_ diff --git a/src/ibusengine.c b/src/ibusengine.c index aa02b2f..13ec52e 100644 --- a/src/ibusengine.c +++ b/src/ibusengine.c @@ -190,6 +190,11 @@ ibus_engine_class_init (IBusEngineClass *klass) /* install properties */ + /** + * IBusEngine:name: + * + * Name of this IBusEngine. + */ g_object_class_install_property (gobject_class, PROP_NAME, g_param_spec_string ("name", @@ -198,7 +203,11 @@ ibus_engine_class_init (IBusEngineClass *klass) "noname", G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); - + /** + * IBusEngine:connection: + * + * Connection for this IBusEngine. + */ g_object_class_install_property (gobject_class, PROP_CONNECTION, g_param_spec_object ("connection", @@ -208,6 +217,15 @@ ibus_engine_class_init (IBusEngineClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); /* install signals */ + /** + * IBusEngine::process-key-event: + * @engine: An IBusEngine. + * @keyval: KeySym of the key press. + * @state: Key modifier flags + * + * This signal is emitted whenever a key event is received. + * Implement process_key_event() in extend class to receive this signal. + */ engine_signals[PROCESS_KEY_EVENT] = g_signal_new (I_("process-key-event"), G_TYPE_FROM_CLASS (gobject_class), @@ -220,6 +238,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_UINT, G_TYPE_UINT); + /** + * IBusEngine::focus-in: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the client application get the focus. + * Implement focus_in() in extend class to receive this signal. + */ engine_signals[FOCUS_IN] = g_signal_new (I_("focus-in"), G_TYPE_FROM_CLASS (gobject_class), @@ -230,6 +255,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::focus-out: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the client application lost the focus. + * Implement focus_out() in extend class to receive this signal. + */ engine_signals[FOCUS_OUT] = g_signal_new (I_("focus-out"), G_TYPE_FROM_CLASS (gobject_class), @@ -240,6 +272,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::reset: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the IME is reset. + * Implement reset() in extend class to receive this signal. + */ engine_signals[RESET] = g_signal_new (I_("reset"), G_TYPE_FROM_CLASS (gobject_class), @@ -250,6 +289,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::enable: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the IME is enabled. + * Implement enable() in extend class to receive this signal. + */ engine_signals[ENABLE] = g_signal_new (I_("enable"), G_TYPE_FROM_CLASS (gobject_class), @@ -260,6 +306,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::disable: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the IME is disabled. + * Implement disable() in extend class to receive this signal. + */ engine_signals[DISABLE] = g_signal_new (I_("disable"), G_TYPE_FROM_CLASS (gobject_class), @@ -270,6 +323,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::set-cursor-location: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the location of IME is set. + * Implement set_cursor_location() in extend class to receive this signal. + */ engine_signals[SET_CURSOR_LOCATION] = g_signal_new (I_("set-cursor-location"), G_TYPE_FROM_CLASS (gobject_class), @@ -284,6 +344,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_INT, G_TYPE_INT); + /** + * IBusEngine::set-capabilities: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the client application capabilities is set. + * Implement set_cursor_location() in extend class to receive this signal. + */ engine_signals[SET_CAPABILITIES] = g_signal_new (I_("set-capabilities"), G_TYPE_FROM_CLASS (gobject_class), @@ -295,6 +362,13 @@ ibus_engine_class_init (IBusEngineClass *klass) 1, G_TYPE_UINT); + /** + * IBusEngine::page-up: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the page-up key is pressed. + * Implement page_up() in extend class to receive this signal. + */ engine_signals[PAGE_UP] = g_signal_new (I_("page-up"), G_TYPE_FROM_CLASS (gobject_class), @@ -305,6 +379,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::page-down: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the page-down key is pressed. + * Implement page_down() in extend class to receive this signal. + */ engine_signals[PAGE_DOWN] = g_signal_new (I_("page-down"), G_TYPE_FROM_CLASS (gobject_class), @@ -315,6 +396,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::cursor-up: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the up cursor key is pressed. + * Implement cursor_up() in extend class to receive this signal. + */ engine_signals[CURSOR_UP] = g_signal_new (I_("cursor-up"), G_TYPE_FROM_CLASS (gobject_class), @@ -325,6 +413,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::cursor-down: + * @engine: An IBusEngine. + * + * This signal is emitted whenever the down cursor key is pressed. + * Implement cursor_down() in extend class to receive this signal. + */ engine_signals[CURSOR_DOWN] = g_signal_new (I_("cursor-down"), G_TYPE_FROM_CLASS (gobject_class), @@ -335,6 +430,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_NONE, 0); + /** + * IBusEngine::property-activate: + * @engine: An IBusEngine. + * + * This signal is emitted whenever a property is activated or change changed. + * Implement property_activate() in extend class to receive this signal. + */ engine_signals[PROPERTY_ACTIVATE] = g_signal_new (I_("property-activate"), G_TYPE_FROM_CLASS (gobject_class), @@ -347,6 +449,13 @@ ibus_engine_class_init (IBusEngineClass *klass) G_TYPE_STRING, G_TYPE_UINT); + /** + * IBusEngine::property-show: + * @engine: An IBusEngine. + * + * This signal is emitted whenever a property is shown. + * Implement property_show() in extend class to receive this signal. + */ engine_signals[PROPERTY_SHOW] = g_signal_new (I_("property-show"), G_TYPE_FROM_CLASS (gobject_class), @@ -358,6 +467,13 @@ ibus_engine_class_init (IBusEngineClass *klass) 1, G_TYPE_STRING); + /** + * IBusEngine::property-hide: + * @engine: An IBusEngine. + * + * This signal is emitted whenever a property is hidden. + * Implement property_hide() in extend class to receive this signal. + */ engine_signals[PROPERTY_HIDE] = g_signal_new (I_("property-hide"), G_TYPE_FROM_CLASS (gobject_class), diff --git a/src/ibusenginedesc.h b/src/ibusenginedesc.h index 1ba9153..ad83f1f 100644 --- a/src/ibusenginedesc.h +++ b/src/ibusenginedesc.h @@ -17,6 +17,22 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusenginedesc + * @short_description: Input method engine description data. + * @stability: Stable + * @see_also: #IBusComponent, #IBusEngine + * + * An IBusEngineDesc stores description data of IBusEngine. + * The description data can either be passed to ibus_engine_desc_new(), + * or loaded from an XML node through ibus_engine_desc_new_from_xml_node() + * to construct IBusEngineDesc. + * + * However, the recommended way to load engine description data is + * using ibus_component_new_from_file() to load a component file, + * which also includes engine description data. + */ + #ifndef __ENGINE_DESC_H_ #define __ENGINE_DESC_H_ @@ -47,10 +63,26 @@ typedef struct _IBusEngineDesc IBusEngineDesc; typedef struct _IBusEngineDescClass IBusEngineDescClass; typedef struct _BusComponent BusComponent; +/** + * IBusEngineDesc: + * @name: Name of the engine. + * @longname: Long name of the input method engine. + * @description: Input method engine description. + * @language: Language (e.g. zh, jp) supported by this input method engine. + * @license: License of the input method engine. + * @author: Author of the input method engine. + * @icon: Icon file of this engine. + * @layout: Keyboard layout + * @rank: Preference rank among engines, the highest ranked IME will put in + * the front. + * + * Input method engine description data. + */ struct _IBusEngineDesc { IBusSerializable parent; /* instance members */ + /*< public >*/ gchar *name; gchar *longname; gchar *description; @@ -64,11 +96,25 @@ struct _IBusEngineDesc { struct _IBusEngineDescClass { IBusSerializableClass parent; - /* class members */ }; GType ibus_engine_desc_get_type (void); + +/** + * ibus_engine_desc_new: + * @name: Name of the engine. + * @longname: Long name of the input method engine. + * @description: Input method engine description. + * @language: Language (e.g. zh, jp) supported by this input method engine. + * @license: License of the input method engine. + * @author: Author of the input method engine. + * @icon: Icon file of this engine. + * @layout: Keyboard layout + * @returns: A newly allocated IBusEngineDesc. + * + * New a IBusEngineDesc. + */ IBusEngineDesc *ibus_engine_desc_new (const gchar *name, const gchar *longname, const gchar *description, @@ -77,8 +123,28 @@ IBusEngineDesc *ibus_engine_desc_new (const gchar *name, const gchar *author, const gchar *icon, const gchar *layout); +/** + * ibus_engine_desc_new_from_xml_node: + * @node: An XML node + * @returns: A newly allocated IBusEngineDesc that contains description from + * @node. + * + * New a IBusEngineDesc from an XML node. + * <note><para>This function is called by ibus_component_new_from_file(), + * so developers normally do not need to call it directly. + * </para></note> + */ IBusEngineDesc *ibus_engine_desc_new_from_xml_node (XMLNode *node); +/** + * ibus_engine_desc_output: + * @info: An IBusEngineDesc + * @output: XML-formatted Input method engine description. + * @indent: Number of indent (showed as 4 spaces). + * + * Output XML-formatted input method engine description. + * The result will be append to GString specified in @output. + */ void ibus_engine_desc_output (IBusEngineDesc *info, GString *output, gint indent); diff --git a/src/ibusobject.h b/src/ibusobject.h index 67fb95b..a3adfe2 100644 --- a/src/ibusobject.h +++ b/src/ibusobject.h @@ -17,9 +17,24 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusobject + * @short_description: Base Object of iBus. + * @stability: Stable + * + * iBus Object is the base object for all objects in iBus. + */ #ifndef __IBUS_OBJECT_H_ #define __IBUS_OBJECT_H_ +/** + * SECTION: iBusObject + * @short_description: Base object of iBus. + * + * + * This module provides essential definition and functions for manipulating + * iBus base object. + */ #include <glib-object.h> #include "ibusmarshalers.h" #include "ibustypes.h" diff --git a/src/ibusproperty.h b/src/ibusproperty.h index 19ff33c..d28d3a8 100644 --- a/src/ibusproperty.h +++ b/src/ibusproperty.h @@ -17,6 +17,19 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusproperty + * @short_description: UI component for input method engine property. + * @stability: Stable + * @see_also: #IBusEngine + * + * An IBusProperty is an UI component like a button or a menu item + * which shows the status of corresponding input method engine property. + * End user can operate and see the current status of IME through these components. + * For example, ibus-chewing users change the English/Chinese input mode by + * pressing ctrl-space or click on the Eng/Chi switch button. + * And the IBusProperty shows the change correspondingly. + */ #ifndef __IBUS_PROPERTY_H_ #define __IBUS_PROPERTY_H_ @@ -59,7 +72,17 @@ G_BEGIN_DECLS #define IBUS_PROP_LIST_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROP_LIST, IBusPropListClass)) - +/** + * IBusPropType: + * @PROP_TYPE_NORMAL: Property is shown as normal text. + * @PROP_TYPE_TOGGLE: Property is shown as a toggle button. + * @PROP_TYPE_RADIO: Property is shown as a radio selection option. + * @PROP_TYPE_MENU: Property is shown as a menu, usually imply it has sub menu + * items. + * @PROP_TYPE_SEPARATOR: A separator for menu. + * + * Type of IBusProperty. + */ typedef enum { PROP_TYPE_NORMAL = 0, PROP_TYPE_TOGGLE = 1, @@ -68,6 +91,28 @@ typedef enum { PROP_TYPE_SEPARATOR = 4, } IBusPropType; +/** + * IBusPropState: + * @PROP_STATE_UNCHECKED: Property option is unchecked. + * @PROP_STATE_CHECKED: Property option is checked. + * @PROP_STATE_INCONSISTENT: The state is inconsistent with the associated IME + * property. + * + * State of IBusProperty. The actual effect depends on #IBusPropType of the + * IBusProperty. + * + * <variablelist> + * <varlistentry> + * <term>PROP_TYPE_TOGGLE</term> + * <listitem><para>Emphasized if PROP_STATE_CHECKED, normal otherwise.</para></listitem> + * </varlistentry> + * <varlistentry> + * <term>PROP_TYPE_RADIO</term> + * <listitem><para>Option checked if PROP_STATE_CHECKED, unchecked otherwise.</para></listitem> + * </varlistentry> + * </variablelist> + * No effect on other types. + */ typedef enum { PROP_STATE_UNCHECKED = 0, PROP_STATE_CHECKED = 1, @@ -80,9 +125,25 @@ typedef struct _IBusPropertyClass IBusPropertyClass; typedef struct _IBusPropList IBusPropList; typedef struct _IBusPropListClass IBusPropListClass; +/** + * IBusProperty: + * @key: Unique Identity for the IBusProperty. + * @icon: Icon file for the IBusProperty. + * @label: Text shown in UI. + * @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. + * @sub_props: IBusPropList that contains sub IBusProperties. These IBusProperties are usually + * shown as sub menu item. + * + * UI component for input method engine property. + */ struct _IBusProperty { IBusSerializable parent; + /*< public >*/ gchar *key; gchar *icon; IBusText *label; @@ -100,9 +161,16 @@ struct _IBusPropertyClass { IBusSerializableClass parent; }; +/** + * IBusPropList: + * @properties: GArray that holds IBusProperties. + * + * A GArray of IBusProperties. + */ struct _IBusPropList { IBusSerializable parent; + /*< public >*/ GArray *properties; }; @@ -111,6 +179,22 @@ struct _IBusPropListClass { }; GType ibus_property_get_type (); + +/** + * ibus_property_new: + * @key: Unique Identity for the IBusProperty. + * @icon: Icon file for the IBusProperty. + * @label: Text shown in UI. + * @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. + * + * New a IBusProperty. + */ IBusProperty *ibus_property_new (const gchar *key, IBusPropType type, IBusText *label, @@ -120,21 +204,90 @@ IBusProperty *ibus_property_new (const gchar *key, gboolean visible, IBusPropState state, IBusPropList *prop_list); + +/** + * ibus_property_set_label: + * @prop: An IBusProperty. + * @label: Text shown in UI. + * + * Set the label of IBusProperty. + */ void ibus_property_set_label (IBusProperty *prop, IBusText *label); + +/** + * ibus_property_set_visible: + * @prop: An IBusProperty. + * @visible: Whether the IBusProperty is visible. + * + * Set whether the IBusProperty is visible. + */ void ibus_property_set_visible (IBusProperty *prop, gboolean visible); + +/** + * ibus_property_set_sub_props: + * @prop: An IBusProperty. + * @prop_list: IBusPropList that contains sub IBusProperties. + * + * Set the sub IBusProperties. + */ void ibus_property_set_sub_props(IBusProperty *prop, IBusPropList *prop_list); + +/** + * ibus_property_update: + * @prop: An IBusProperty. + * @prop_update: IBusPropList that contains sub IBusProperties. + * @returns: TRUE for update suceeded; FALSE otherwise. + * + * Update the content of an IBusProperty. + * IBusProperty @prop_update can either be sub-property of @prop, + * or holds new values for @prop. + */ + gboolean ibus_property_update (IBusProperty *prop, IBusProperty *prop_update); GType ibus_prop_list_get_type (); + +/** + * ibus_prop_list_new: + * @returns: A newly allocated IBusPropList. + * + * New a IBusPropList. + */ IBusPropList *ibus_prop_list_new (); + +/** + * ibus_prop_list_append: + * @prop_list: An IBusPropList. + * @prop: IBusProperty to be append to @prop_list. + * + * Append an IBusProperty to an IBusPropList. + */ void ibus_prop_list_append (IBusPropList *prop_list, IBusProperty *prop); + +/** + * ibus_prop_list_get: + * @prop_list: An IBusPropList. + * @index: Index of an IBusPropList. + * @returns: IBusProperty at given index, NULL if no such IBusProperty. + * + * Returns IBusProperty at given index. + */ IBusProperty *ibus_prop_list_get (IBusPropList *prop_list, guint index); + +/** + * ibus_prop_list_update_property: + * @prop_list: An IBusPropList. + * @prop: IBusProperty to be update. + * @returns: TRUE if succeeded, FALSE otherwise. + * + * Update an IBusProperty in IBusPropList. + */ gboolean ibus_prop_list_update_property (IBusPropList *prop_list, IBusProperty *prop); diff --git a/src/ibustext.h b/src/ibustext.h index 9696f80..1c48c1e 100644 --- a/src/ibustext.h +++ b/src/ibustext.h @@ -17,6 +17,17 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibustext + * @short_description: Text with decorating information. + * @see_also: #IBusAttribute + * + * An IBusText is the main text object in IBus. + * The text is decorated according to associated IBusAttribute, + * e.g. the foreground/background color, underline, and + * applied scope. + */ + #ifndef __IBUS_TEXT_H_ #define __IBUS_TEXT_H_ @@ -45,10 +56,19 @@ G_BEGIN_DECLS typedef struct _IBusText IBusText; typedef struct _IBusTextClass IBusTextClass; +/** + * IBusText: + * @is_static: Whether @text is static, i.e., no need and will not be freed. Only TRUE if IBusText is newed from ibus_text_new_from_static_string(). + * @text: The string content of IBusText in UTF-8. + * @attrs: Associated IBusAttributes. + * + * A text object in IBus. + */ struct _IBusText { IBusSerializable parent; /* members */ + /*< public >*/ gboolean is_static; gchar *text; IBusAttrList *attrs; @@ -59,17 +79,79 @@ struct _IBusTextClass { }; GType ibus_text_get_type (void); + +/** + * ibus_text_new_from_string: + * @str: An text string to be set. + * @returns: A newly allocated IBusText. + * + * New an IBusText whose content is copied from a text string. + */ IBusText *ibus_text_new_from_string (const gchar *str); + +/** + * ibus_text_new_from_ucs4: + * @str: An text string to be set. + * @returns: A newly allocated IBusText. + * + * New an IBusText whose content is copied from a UCS4 encoded text string. + */ IBusText *ibus_text_new_from_ucs4 (const gunichar *str); + +/** + * ibus_text_new_from_static_string: + * @str: An text string to be set. + * @returns: A newly allocated IBusText. + * + * New an IBusText whose content is from a static string. + * Note that it is the developer's duty to ensure @str is static. + */ IBusText *ibus_text_new_from_static_string (const gchar *str); + +/** + * ibus_text_new_from_printf: + * @fmt: printf format string. + * @...: arguments for @fmt. + * @returns: A newly allocated IBusText. + * + * New an IBusText from a printf expression. + */ IBusText *ibus_text_new_from_printf (const gchar *fmt, ...); + +/** + * ibus_text_new_from_unichar: + * @c: A single UCS4-encoded character. + * @returns: A newly allocated IBusText. + * + * New an IBusText from a single UCS4-encoded character. + */ IBusText *ibus_text_new_from_unichar (gunichar c); + +/** + * ibus_text_append_attribute: + * @text: an IBusText + * @type: IBusAttributeType for @text. + * @value: Value for the type. + * @start_index: The starting index, inclusive. + * @end_index: The ending index, exclusive. + * + * Append an IBusAttribute for IBusText. + */ void ibus_text_append_attribute (IBusText *text, guint type, guint value, guint start_index, gint end_index); +/** + * ibus_text_get_length: + * @text: An IBusText. + * @returns: Number of character in @text, not counted by bytes. + * + * Return number of characters in an IBusText. + * This function is based on g_utf8_strlen(), so unlike strlen(), + * it does not count by bytes but characters instead. + */ guint ibus_text_get_length (IBusText *text); G_END_DECLS diff --git a/src/ibustypes.h b/src/ibustypes.h index a977db4..b2ea627 100644 --- a/src/ibustypes.h +++ b/src/ibustypes.h @@ -17,9 +17,41 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibustypes + * @short_description: Generic types for iBus. + * @stability: Stable + * + * This session consists generic types for iBus, including shift/control key modifiers, + * and a rectangle structure. + */ #ifndef __IBUS_TYPES_H_ #define __IBUS_TYPES_H_ +/** + * IBusModifierType: + * @IBUS_SHIFT_MASK: Shift is activated. + * @IBUS_LOCK_MASK: Cap Lock is locked. + * @IBUS_CONTROL_MASK: Control key is activated. + * @IBUS_MOD1_MASK: Modifier 1 (Usually Alt_L (0x40), Alt_R (0x6c), Meta_L (0xcd)) activated. + * @IBUS_MOD2_MASK: Modifier 2 (Usually Num_Lock (0x4d)) activated. + * @IBUS_MOD3_MASK: Modifier 3 activated. + * @IBUS_MOD4_MASK: Modifier 4 (Usually Super_L (0xce), Hyper_L (0xcf)) activated. + * @IBUS_MOD5_MASK: Modifier 5 (ISO_Level3_Shift (0x5c), Mode_switch (0xcb)) activated. + * @IBUS_BUTTON1_MASK: Mouse button 1 (left) is activated. + * @IBUS_BUTTON2_MASK: Mouse button 2 (middle) is activated. + * @IBUS_BUTTON3_MASK: Mouse button 3 (right) is activated. + * @IBUS_BUTTON4_MASK: Mouse button 4 (scroll up) is activated. + * @IBUS_BUTTON5_MASK: Mouse button 5 (scroll down) is activated. + * @IBUS_FORWARD_MASK: Forward mask. + * @IBUS_SUPER_MASK: Super (Usually Win) key is activated. + * @IBUS_HYPER_MASK: Hyper key is activated. + * @IBUS_RELEASE_MASK: Key is released. + * @IBUS_MODIFIER_MASK: Modifier mask for the all the masks above. + * + * Handles key modifier such as control, shift and alt and release event. + * Note that nits 15 - 25 are currently unused, while bit 29 is used internally. + */ typedef enum { IBUS_SHIFT_MASK = 1 << 0, @@ -40,7 +72,7 @@ typedef enum * Bits 15 - 25 are currently unused. Bit 29 is used internally. */ - /* forard mask */ + /* forward mask */ IBUS_FORWARD_MASK = 1 << 25, IBUS_SUPER_MASK = 1 << 26, @@ -52,6 +84,16 @@ typedef enum IBUS_MODIFIER_MASK = 0x5c001fff } IBusModifierType; +/** + * IBusCapabilite: + * @IBUS_CAP_PREEDIT_TEXT: UI is capable to show pre-edit text. + * @IBUS_CAP_AUXILIARY_TEXT: UI is capable to show auxiliary text. + * @IBUS_CAP_LOOKUP_TABLE: UI is capable to show the lookup table. + * @IBUS_CAP_FOCUS: UI is capable to get focus. + * @IBUS_CAP_PROPERTY: UI is capable to have property. + * + * Capability flags of UI. + */ typedef enum { IBUS_CAP_PREEDIT_TEXT = 1 << 0, IBUS_CAP_AUXILIARY_TEXT = 1 << 1, @@ -60,6 +102,15 @@ typedef enum { IBUS_CAP_PROPERTY = 1 << 4, } IBusCapabilite; +/** + * IBusRectangle: + * @x: x coordinate. + * @y: y coordinate. + * @width: width of the rectangle. + * @height: height of the renctangl. + * + * Rectangle definition. + */ typedef struct _IBusRectangle IBusRectangle; struct _IBusRectangle { gint x; @@ -68,7 +119,13 @@ struct _IBusRectangle { gint height; }; -typedef void (* IBusFreeFunc) (gpointer ); +/** + * IBusFreeFunc: + * @object: object to be freed. + * + * Free function prototype. + */ +typedef void (* IBusFreeFunc) (gpointer object); #endif |