From d72689240398232387187e383938186cda47ff99 Mon Sep 17 00:00:00 2001 From: Ding-Yi Chen Date: Mon, 22 Jun 2009 18:08:55 +1000 Subject: [PATCH] APIDOC: revised IBusEngine, IBusInputContext --- ibus.spec.in | 6 ++-- src/ibusengine.c | 19 ++++++++-- src/ibusinputcontext.h | 96 ++++++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 113 insertions(+), 8 deletions(-) diff --git a/ibus.spec.in b/ibus.spec.in index 0449167..a896c94 100644 --- a/ibus.spec.in +++ b/ibus.spec.in @@ -88,7 +88,7 @@ This package contains ibus im module for gtk2 # Group: System Environment/Libraries # Requires: %{name} = %{version}-%{release} # Requires: qt >= 4.4.2 -# +# # %description qt # This package contains ibus im module for qt4 @@ -184,10 +184,10 @@ fi /sbin/ldconfig %post gtk -%{_bindir}/update-gtk-immodules %{_host} || : +%{_bindir}/update-gtk-immodules %{host} || : %postun gtk -%{_bindir}/update-gtk-immodules %{_host} || : +%{_bindir}/update-gtk-immodules %{host} || : %files -f %{name}.lang %defattr(-,root,root,-) diff --git a/src/ibusengine.c b/src/ibusengine.c index 392307c..b2ab122 100644 --- a/src/ibusengine.c +++ b/src/ibusengine.c @@ -228,11 +228,18 @@ ibus_engine_class_init (IBusEngineClass *klass) /** * IBusEngine::process-key-event: * @engine: An IBusEngine. - * @keyval: KeySym of the key press. - * @state: Key modifier flags + * @keyval: Key symbol of the key press. + * @keycode: KeyCode of the key press. + * @state: Key modifier flags. * * Emitted when a key event is received. * Implement the member function process_key_event() in extended class to receive this signal. + * Both the key symbol and keycode are passed to the member function. + * See ibus_input_context_process_key_event() for further explanation of + * key symbol, keycode and which to use. + * + * Returns: TRUE for successfully process the key; FALSE otherwise. + * See also: ibus_input_context_process_key_event(). * * @user_data is not actually a valid parameter. It is displayed because of GtkDoc bug. */ @@ -256,6 +263,7 @@ ibus_engine_class_init (IBusEngineClass *klass) * Emitted when the client application get the focus. * Implement the member function focus_in() in extended class to receive this signal. * + * See also: ibus_input_context_focus_in() * @user_data is not actually a valid parameter. It is displayed because of GtkDoc bug. */ engine_signals[FOCUS_IN] = @@ -275,6 +283,7 @@ ibus_engine_class_init (IBusEngineClass *klass) * Emitted when the client application lost the focus. * Implement the member function focus_out() in extended class to receive this signal. * + * See also: ibus_input_context_focus_out() * @user_data is not actually a valid parameter. It is displayed because of GtkDoc bug. */ engine_signals[FOCUS_OUT] = @@ -347,10 +356,15 @@ ibus_engine_class_init (IBusEngineClass *klass) /** * IBusEngine::set-cursor-location: * @engine: An IBusEngine. + * @x: X coordinate of the cursor. + * @y: Y coordinate of the cursor. + * @w: Width of the cursor. + * @h: Height of the cursor. * * Emitted when the location of IME is set. * Implement the member function set_cursor_location() in extended class to receive this signal. * + * See also: ibus_input_context_set_cursor_location(). * @user_data is not actually a valid parameter. It is displayed because of GtkDoc bug. */ engine_signals[SET_CURSOR_LOCATION] = @@ -375,6 +389,7 @@ ibus_engine_class_init (IBusEngineClass *klass) * Emitted when the client application capabilities is set. * Implement the member function set_capabilities() in extended class to receive this signal. * + * See also: ibus_input_context_set_capabilities(). * @user_data is not actually a valid parameter. It is displayed because of GtkDoc bug. */ engine_signals[SET_CAPABILITIES] = diff --git a/src/ibusinputcontext.h b/src/ibusinputcontext.h index 3f5508c..a21f782 100644 --- a/src/ibusinputcontext.h +++ b/src/ibusinputcontext.h @@ -22,9 +22,12 @@ * @short_description: IBus input context proxy object. * @stability: Stable * - * An IBusInputContext is a proxy object of InputContext. - * Clients call the IBusInputContext to invoke InputContext, - * through which invoke IBusEngine. + * An IBusInputContext is a proxy object of BusInputContext, + * which manages the context for input methods that supports + * text input in various natural languages. + * + * Clients call the IBusInputContext to invoke BusInputContext, + * through which invokes IBusEngine. */ #ifndef __IBUS_INPUT_CONTEXT_H_ #define __IBUS_INPUT_CONTEXT_H_ @@ -54,6 +57,11 @@ G_BEGIN_DECLS typedef struct _IBusInputContext IBusInputContext; typedef struct _IBusInputContextClass IBusInputContextClass; +/** + * IBusInputContext: + * + * An opaque data type representing an IBusInputContext. + */ struct _IBusInputContext { IBusProxy parent; /* instance members */ @@ -69,25 +77,107 @@ struct _IBusInputContextClass { }; GType ibus_input_context_get_type (void); + +/** + * ibus_input_context_new: + * @path: The path to the object that emitting the signal. + * @connection: An IBusConnection. + * @returns: A newly allocated IBusInputContext. + * + * New an IBusInputContext. + */ IBusInputContext *ibus_input_context_new (const gchar *path, IBusConnection *connection); +/** + * ibus_input_context_process_key_event: + * @context: An IBusInputContext. + * @keyval: Key symbol of a key event. + * @keycode: Keycode of a key event. + * @state: Key modifier flags. + * @returns: TRUE for successfully process the key; FALSE otherwise. + * @see_also: IBusEngine::process-key-event + * + * Pass the key event to input method engine. + * + * Key symbols are characters/symbols produced by key press, for example, + * pressing "s" generates key symbol "s"; pressing shift-"s" generates key symbol "S". + * Same key on keyboard may produce different key symbols on different keyboard layout. + * e.g., "s" key on QWERTY keyboard produces "o" in DVORAK layout. + * + * Unlike key symbol, keycode is only determined by the location of the key, and + * irrelevant of the keyboard layout. + * + * Briefly speaking, input methods that expect certain keyboard layout should use + * keycode; otherwise keyval is sufficient. + * For example, Chewing, Cangjie, Wubi expect an en-US QWERTY keyboard, these should + * use keycode; while pinyin can rely on keyval only, as it is less sensitive to + * the keyboard layout change, DVORAK users can still use DVORAK layout to input pinyin. + * + * Use ibus_keymap_lookup_keysym() to convert keycode to keysym in given keyboard layout. + * + */ gboolean ibus_input_context_process_key_event (IBusInputContext *context, guint32 keyval, guint32 keycode, guint32 state); + +/** + * ibus_input_context_set_cursor_location: + * @context: An IBusInputContext. + * @x: X coordinate of the cursor. + * @y: Y coordinate of the cursor. + * @w: Width of the cursor. + * @h: Height of the cursor. + * @see_also: IBusEngine::set-cursor-location + * + * Set the cursor location of IBus input context. + */ void ibus_input_context_set_cursor_location (IBusInputContext *context, gint32 x, gint32 y, gint32 w, gint32 h); +/** + * ibus_input_context_set_capabilities: + * @context: An IBusInputContext. + * @capabilities: Capabilities flags of IBusEngine, see #IBusCapabilite + * @see_also: IBusEngine::set_capabilities + * + * Set the capabilities flags of client application. + */ void ibus_input_context_set_capabilities (IBusInputContext *context, guint32 capabilites); + +/** + * ibus_input_context_focus_in: + * @context: An IBusInputContext. + * @see_also: IBusEngine::focus_in. + * + * Invoked when the client application get focus. + */ void ibus_input_context_focus_in (IBusInputContext *context); + +/** + * ibus_input_context_focus_out: + * @context: An IBusInputContext. + * @see_also: IBusEngine::focus_out. + * + * Invoked when the client application get focus. + */ void ibus_input_context_focus_out (IBusInputContext *context); + + +/** + * ibus_input_context_focus_out: + * @context: An IBusInputContext. + * @see_also: IBusEngine::reset. + * + * Invoked when the IME is reset. + */ void ibus_input_context_reset (IBusInputContext *context); void ibus_input_context_enable (IBusInputContext *context); void ibus_input_context_disable (IBusInputContext *context); -- 2.7.4