@@ -36,3 +36,6 @@ py-compile ibus-*.tar.* ibus.spec ibus-1.0.pc +i386 +x86_64 + .gitignore @@ -49,6 +49,13 @@ AC_ISC_POSIX AC_HEADER_STDC AM_PROG_LIBTOOL +# For dislpay Date +m4_define(ibus_maybe_datedisplay, + m4_esyscmd([if test x]ibus_released[ != x1; then date '+%a %b %d %Y' | tr -d '\n\r'; fi])) +m4_define([ibus_datedisplay], ibus_maybe_datedisplay) +DATE_DISPLAY="ibus_datedisplay" +AC_SUBST(DATE_DISPLAY) + # If only source code changed, lt_revision + 1 # If any interface added, lt_age + 1 # If any interfaces changed or removed, lt_current + 1 configure.ac @@ -1,7 +1,6 @@ ibus-decl-list.txt ibus-decl.txt ibus-overrides.txt -ibus-sections.txt ibus-undeclared.txt ibus-undocumented.txt ibus-unused.txt docs/reference/ibus/.gitignore @@ -25,7 +25,8 @@ SCANGOBJ_OPTIONS= # Extra options to supply to gtkdoc-scan. # e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" -SCAN_OPTIONS=--rebuild-sections +# SCAN_OPTIONS=--rebuild-sections +SCAN_OPTIONS= # Extra options to supply to gtkdoc-mkdb. # e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml @@ -42,7 +43,7 @@ FIXXREF_OPTIONS= # Used for dependencies. The docs will be rebuilt if any of these change. # e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h # e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c -HFILE_GLOB= +HFILE_GLOB=$(top_srcdir)/src/*.h CFILE_GLOB= # Header files to ignore when scanning. @@ -97,4 +98,10 @@ EXTRA_DIST += # Comment this out if you want your docs-status tested during 'make check' #TESTS = $(GTKDOC_CHECK) -# CLEANFILES += ibus* + +clean-local: + rm -rf tmpl + +CLEANFILES+= *.stamp + + docs/reference/ibus/Makefile.am @@ -3,46 +3,76 @@ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> <bookinfo> - <title>IBus Reference Manual</title> + <title>iBus Reference Manual</title> <releaseinfo> - for ibus 1.1.0 + iBus 1.1.0 reference manual. The latest version of this documentation can be found on-line at <ulink role="online-location" url="http://code.google.com/p/ibus">http://code.google.com/p/ibus</ulink>. </releaseinfo> </bookinfo> <chapter> - <title>API Reference</title> - <xi:include href="xml/ibusfactory.xml"/> - <xi:include href="xml/ibusattribute.xml"/> - <xi:include href="xml/ibusinputcontext.xml"/> - <xi:include href="xml/ibusobservedpath.xml"/> - <xi:include href="xml/ibusengine.xml"/> - <xi:include href="xml/ibusservice.xml"/> - <xi:include href="xml/ibuslookuptable.xml"/> - <xi:include href="xml/ibusproxy.xml"/> - <xi:include href="xml/ibusserver.xml"/> - <xi:include href="xml/ibuscomponent.xml"/> - <xi:include href="xml/ibusconnection.xml"/> - <xi:include href="xml/ibusproperty.xml"/> - <xi:include href="xml/ibustext.xml"/> - <xi:include href="xml/ibusserializable.xml"/> - <xi:include href="xml/ibushotkey.xml"/> - <xi:include href="xml/ibusbus.xml"/> - <xi:include href="xml/ibusenginedesc.xml"/> - <xi:include href="xml/ibusobject.xml"/> - <xi:include href="xml/ibusconfig.xml"/> - <xi:include href="xml/ibusmessage.xml"/> - <xi:include href="xml/ibusdebug.xml"/> - <xi:include href="xml/ibusmarshalers.xml"/> - <xi:include href="xml/keyname-table.xml"/> - <xi:include href="xml/ibustypes.xml"/> - <xi:include href="xml/ibuserror.xml"/> - <xi:include href="xml/ibuspendingcall.xml"/> - <xi:include href="xml/ibuskeysyms.xml"/> - <xi:include href="xml/ibusenumtypes.xml"/> - <xi:include href="xml/ibusxml.xml"/> - <xi:include href="xml/ibusshare.xml"/> - <xi:include href="xml/ibusinternal.xml"/> + <title>API Overviews</title> + <para>The iBus API consists 3 parts: + <emphasis>User interfaces</emphasis> for objects and services which + are relateed to iBus UI such as language bar; + <emphasis>Input method engine</emphasis> for input method main logic and input/output handling; + <emphasis>Configure</emphasis> for services for save, load and listening configures. + </para> + </chapter> + <chapter> + <title>User Interfaces</title> + <para>These APIs directly related to User interfaces, such as + pre-edit buffer, auxiliary text, language bar, button, + radio boxes, and so on. + </para> + <xi:include href="xml/ibusattribute.xml"/> + <xi:include href="xml/ibuslookuptable.xml"/> + <xi:include href="xml/ibusproperty.xml"/> + <xi:include href="xml/ibustext.xml"/> + </chapter> + <chapter> + <title>Input method engine</title> + <para> + </para> + <xi:include href="xml/ibusbus.xml"/> + <xi:include href="xml/ibuscomponent.xml"/> + <xi:include href="xml/ibusconnection.xml"/> + <xi:include href="xml/ibusengine.xml"/> + <xi:include href="xml/ibusenginedesc.xml"/> + <xi:include href="xml/ibusfactory.xml"/> + <xi:include href="xml/ibushotkey.xml"/> + <xi:include href="xml/ibuskeysyms.xml"/> + </chapter> + <chapter> + <title>Configure</title> + <para> + </para> + <xi:include href="xml/ibusconfig.xml"/> + <xi:include href="xml/ibusconfigservice.xml"/> + <xi:include href="xml/ibusxml.xml"/> + </chapter> + <chapter> + <title>Others</title> + <para> + </para> + <xi:include href="xml/ibusdebug.xml"/> + <xi:include href="xml/ibusenumtypes.xml"/> + <xi:include href="xml/ibuserror.xml"/> + <xi:include href="xml/ibusinputcontext.xml"/> + <xi:include href="xml/ibusinternal.xml"/> + <xi:include href="xml/ibusmarshalers.xml"/> + <xi:include href="xml/ibusmessage.xml"/> + <xi:include href="xml/ibusobject.xml"/> + <xi:include href="xml/ibusobservedpath.xml"/> + <xi:include href="xml/ibuspendingcall.xml"/> + <xi:include href="xml/ibusproxy.xml"/> + <xi:include href="xml/ibusserver.xml"/> + <xi:include href="xml/ibusservice.xml"/> + <xi:include href="xml/ibusserializable.xml"/> + <xi:include href="xml/ibusshare.xml"/> + <xi:include href="xml/ibustypes.xml"/> + <xi:include href="xml/keyname-table.xml"/> </chapter> </book> + docs/reference/ibus/ibus-docs.sgml @@ -1,6 +1,8 @@ %{!?python_sitelib: %define python_sitelib %(%{__python} -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")} %{!?gtk_binary_version: %define gtk_binary_version %(pkg-config --variable=gtk_binary_version gtk+-2.0)} %define mod_path ibus-@PACKAGE_VERSION_MAJOR@.@PACKAGE_VERSION_MINOR@ +%define host_vendor %(if [[ "%{_host_vendor}" == "unknown" ]]; then echo redhat; else echo %{_host_vendor}; fi) +%define host %{_host_cpu}-%{host_vendor}-%{_host_os} Name: ibus Version: @PACKAGE_VERSION@ Release: 1%{?dist} @@ -108,13 +110,32 @@ desktop-file-install --delete-original \ %clean rm -rf $RPM_BUILD_ROOT +%pre +if [ "$1" -gt 1 ] ; then +export GCONF_CONFIG_SOURCE=`gconftool-2 --get-default-source` +gconftool-2 --makefile-uninstall-rule \ +%{_sysconfdir}/gconf/schemas/%{name}.schemas >/dev/null || : +fi + +%post +export GCONF_CONFIG_SOURCE=`gconftool-2 --get-default-source` +gconftool-2 --makefile-install-rule \ +%{_sysconfdir}/gconf/schemas/%{name}.schemas > /dev/null || : + +%preun +if [ "$1" -eq 0 ] ; then +export GCONF_CONFIG_SOURCE=`gconftool-2 --get-default-source` +gconftool-2 --makefile-uninstall-rule \ +%{_sysconfdir}/gconf/schemas/%{name}.schemas > /dev/null || : +fi + %post libs /sbin/ldconfig update-desktop-database -q %{_sbindir}/alternatives --install %{_sysconfdir}/X11/xinit/xinputrc xinputrc %{_xinputconf} 83 || : %post gtk -%{_bindir}/update-gtk-immodules %{_host} || : +%{_bindir}/update-gtk-immodules %{host} || : %postun libs /sbin/ldconfig @@ -126,7 +147,7 @@ if [ "$1" = "0" ]; then fi %postun gtk -%{_bindir}/update-gtk-immodules %{_host} || : +%{_bindir}/update-gtk-immodules %{host} || : %files -f %{name}.lang %defattr(-,root,root,-) @@ -140,8 +161,9 @@ fi %{_libexecdir}/ibus-gconf %{_libexecdir}/ibus-ui-gtk %{_libexecdir}/ibus-x11 -%config %{_xinputconf} - +%config(noreplace) %{_xinputconf} +%config(noreplace) %{_sysconfdir}/gconf/schemas/%{name}.schemas +%config(noreplace) %{_sysconfdir}/xdg/autostart/ibus.desktop %files libs %defattr(-,root,root,-) @@ -163,5 +185,9 @@ fi %{_libdir}/pkgconfig/* %changelog -* Thu Aug 07 2008 Huang Peng <shawn.p.huang@gmail.com> - @VERSION@-1 +* @DATE_DISPLAY@ Huang Peng <shawn.p.huang@gmail.com> - @VERSION@-1 +- Current version. + +* Thu Aug 07 2008 Huang Peng <shawn.p.huang@gmail.com> - 0.1.0.20080810-1 - The first version. + ibus.spec.in @@ -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); src/ibusattribute.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_ src/ibusconnection.h @@ -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), src/ibusengine.c @@ -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); src/ibusenginedesc.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" src/ibusobject.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); src/ibusproperty.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 src/ibustext.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 src/ibustypes.h 7c6b337ece598b5c0cf9c92b0888b45f8770ff83 dchen@redhat.com dchen@dchen.redhat.com http://github.com/phuang/ibus/commit/e3fe226e2ddbe7754ed9cb0c60301e4959075eb1 e3fe226e2ddbe7754ed9cb0c60301e4959075eb1 2009-03-26T21:17:35-07:00 2009-03-26T21:17:35-07:00 API-DOC and Fix iBus Google issue 320. 1ead0c2c0db0064775afbdaf24f7a6639cacc8ff dchen@redhat.com dchen@dchen.redhat.com