APIDOC: revised IBusEngine, IBusInputContext

diff --git a/ibus.spec.in b/ibus.spec.in
index 044916730bc62d64a080a7908f67efff66ad5dec..a896c946b60e59d162d4ca6a8f13e2f865114a84 100644 (file)
--- 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 392307ca903bc4f77a3be1d8fe7e74ceed080d65..b2ab122bf439b8d9316e83121285e6048fb29f83 100644 (file)
--- 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().
      *
      * <note><para>@user_data is not actually a valid parameter. It is displayed because of GtkDoc bug.</para></note>
      */
@@ -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()
      * <note><para>@user_data is not actually a valid parameter. It is displayed because of GtkDoc bug.</para></note>
      */
     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()
      * <note><para>@user_data is not actually a valid parameter. It is displayed because of GtkDoc bug.</para></note>
      */
     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().
      * <note><para>@user_data is not actually a valid parameter. It is displayed because of GtkDoc bug.</para></note>
      */
     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().
      * <note><para>@user_data is not actually a valid parameter. It is displayed because of GtkDoc bug.</para></note>
      */
     engine_signals[SET_CAPABILITIES] =

diff --git a/src/ibusinputcontext.h b/src/ibusinputcontext.h
index 3f5508cf2092e896e5d4e435be45aa5f1279895f..a21f7820fe3475be90bee4a06eb1505b9f052bcd 100644 (file)
--- 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);