IBusInputContext

## IBusInputContext IBusInputContext — IBus input context proxy object. |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IBusInputContext;
                        IBusInputContextClass;
    gboolean            ibus_input_context_process_key_event
                                                            (IBusInputContext *context,
                                                             guint32 keyval,
                                                             guint32 keycode,
                                                             guint32 state);
    void                ibus_input_context_set_cursor_location
                                                            (IBusInputContext *context,
                                                             gint32 x,
                                                             gint32 y,
                                                             gint32 w,
                                                             gint32 h);
    void                ibus_input_context_set_capabilities (IBusInputContext *context,
                                                             guint32 capabilities);
    void                ibus_input_context_property_activate
                                                            (IBusInputContext *context,
                                                             const gchar *prop_name,
                                                             gint32 state);
    void                ibus_input_context_focus_in         (IBusInputContext *context);
    void                ibus_input_context_focus_out        (IBusInputContext *context);
    void                ibus_input_context_reset            (IBusInputContext *context);
    void                ibus_input_context_enable           (IBusInputContext *context);
    void                ibus_input_context_disable          (IBusInputContext *context);
    gboolean            ibus_input_context_is_enabled       (IBusInputContext *context);
    void                ibus_input_context_set_engine       (IBusInputContext *context,
                                                             const gchar *name);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusProxy
                         +----IBusInputContext

## Signals

      "commit-text"                                    : Run Last
      "cursor-down-lookup-table"                       : Run Last
      "cursor-up-lookup-table"                         : Run Last
      "delete-surrounding-text"                        : Run Last
      "disabled"                                       : Run Last
      "enabled"                                        : Run Last
      "forward-key-event"                              : Run Last
      "hide-auxiliary-text"                            : Run Last
      "hide-lookup-table"                              : Run Last
      "hide-preedit-text"                              : Run Last
      "page-down-lookup-table"                         : Run Last
      "page-up-lookup-table"                           : Run Last
      "register-properties"                            : Run Last
      "show-auxiliary-text"                            : Run Last
      "show-lookup-table"                              : Run Last
      "show-preedit-text"                              : Run Last
      "update-auxiliary-text"                          : Run Last
      "update-lookup-table"                            : Run Last
      "update-preedit-text"                            : Run Last
      "update-property"                                : Run Last

## Description

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.

## Details

### IBusInputContext

    typedef struct _IBusInputContext IBusInputContext;

An opaque data type representing an IBusInputContext.

### IBusInputContextClass

    typedef struct {
        IBusProxyClass parent;
        /* signals */
    } IBusInputContextClass;

### ibus_input_context_process_key_event ()

    gboolean            ibus_input_context_process_key_event
                                                            (IBusInputContext *context,
                                                             guint32 keyval,
                                                             guint32 keycode,
                                                             guint32 state);

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.

`see_also`: "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.

### ibus_input_context_set_cursor_location ()

    void                ibus_input_context_set_cursor_location
                                                            (IBusInputContext *context,
                                                             gint32 x,
                                                             gint32 y,
                                                             gint32 w,
                                                             gint32 h);

Set the cursor location of IBus input context.

`see_also`: "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.

### ibus_input_context_set_capabilities ()

    void                ibus_input_context_set_capabilities (IBusInputContext *context,
                                                             guint32 capabilities);

Set the capabilities flags of client application.

`see_also`: "set-capabilities"

`context` : | An IBusInputContext.
`capabilities` : | Capabilities flags of IBusEngine, see IBusCapabilite

### ibus_input_context_property_activate ()

    void                ibus_input_context_property_activate
                                                            (IBusInputContext *context,
                                                             const gchar *prop_name,
                                                             gint32 state);

Activate the property.

`see_also`: "property_activate"

`context` : | An IBusInputContext.
`prop_name` : | A property name (e.g. "InputMode.WideLatin")
`state` : | A status of the property (e.g. PROP_STATE_CHECKED)

### ibus_input_context_focus_in ()

    void                ibus_input_context_focus_in         (IBusInputContext *context);

Invoked when the client application get focus.

`see_also`: "focus_in".

`context` : | An IBusInputContext.

### ibus_input_context_focus_out ()

    void                ibus_input_context_focus_out        (IBusInputContext *context);

Invoked when the client application get focus.

`see_also`: "focus_out".

`context` : | An IBusInputContext.

### ibus_input_context_reset ()

    void                ibus_input_context_reset            (IBusInputContext *context);

Invoked when the IME is reset.

`see_also`: "reset"

`context` : | An IBusInputContext.

### ibus_input_context_enable ()

    void                ibus_input_context_enable           (IBusInputContext *context);

Invoked when the IME is enabled, either by IME switch hotkey or select from the menu.

`see_also`: "enable"

`context` : | An IBusInputContext.

### ibus_input_context_disable ()

    void                ibus_input_context_disable          (IBusInputContext *context);

Invoked when the IME is disabled, either by IME switch hotkey or select from the menu.

`see_also`: "disable"

`context` : | An IBusInputContext.

### ibus_input_context_is_enabled ()

    gboolean            ibus_input_context_is_enabled       (IBusInputContext *context);

Returns TRUE if the IME is enabled on the context.

`context` : | An IBusInputContext.
Returns : | TRUE if the IME is enabled on the context.

### ibus_input_context_set_engine ()

    void                ibus_input_context_set_engine       (IBusInputContext *context,
                                                             const gchar *name);

Invoked when the IME engine is changed.

`context` : | An IBusInputContext.
`name` : | A name of the engine.

## Signal Details

### The `"commit-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            IBusText         *text,
                                                            gpointer          user_data)      : Run Last

Emitted when the text is going to be committed.

(Note: The text object is floating, and it will be released after the signal. If singal handler want to keep the object, the handler should use `g_object_ref_sink()` to get the ownership of the object.)

`context` : | An IBusInputContext.
`text` : | Text to be committed.
`user_data` : | user data set when the signal handler was connected.

### The `"cursor-down-lookup-table"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to select next candidate of lookup table.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"cursor-up-lookup-table"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to select previous candidate of lookup table.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"delete-surrounding-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gint              offset,
                                                            guint             n_chars,
                                                            gpointer          user_data)      : Run Last

Emitted to delete surrounding text event from IME to client of IME.

`context` : | An IBusInputContext.
`offset` : | the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor.
`n_chars` : | the number of characters to be deleted.
`user_data` : | user data set when the signal handler was connected.

### The `"disabled"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted when an IME is disabled.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"enabled"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted when an IME is enabled.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"forward-key-event"` signal

    void                user_function                      (IBusInputContext *context,
                                                            guint             keyval,
                                                            guint             keycode,
                                                            guint             modifiers,
                                                            gpointer          user_data)      : Run Last

Emitted to forward key event from IME to client of IME.

`context` : | An IBusInputContext.
`keyval` : | Key symbol of the keyboard event.
`keycode` : | Key symbol of the keyboard event.
`modifiers` : | Key modifier flags.
`user_data` : | user data set when the signal handler was connected.

### The `"hide-auxiliary-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to hide auxiliary text.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"hide-lookup-table"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to hide lookup table.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"hide-preedit-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to hide preedit text.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"page-down-lookup-table"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to view the next page of lookup table.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"page-up-lookup-table"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to view the previous page of lookup table.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"register-properties"` signal

    void                user_function                      (IBusInputContext *context,
                                                            IBusPropList     *props,
                                                            gpointer          user_data)      : Run Last

Emitted to register the properties in `props`.

(Note: The props object is floating, and it will be released after the signal. If singal handler want to keep the object, the handler should use `g_object_ref_sink()` to get the ownership of the object.)

`context` : | An IBusInputContext.
`props` : | An IBusPropList that contains properties.
`user_data` : | user data set when the signal handler was connected.

### The `"show-auxiliary-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to show auxiliary text.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"show-lookup-table"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to show lookup table.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"show-preedit-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            gpointer          user_data)      : Run Last

Emitted to show preedit text.

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"update-auxiliary-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            IBusText         *arg1,
                                                            gboolean          arg2,
                                                            gpointer          user_data)      : Run Last

Emitted to hide auxilary text.

(Note: The text object is floating, and it will be released after the signal. If singal handler want to keep the object, the handler should use `g_object_ref_sink()` to get the ownership of the object.)

`context` : | An IBusInputContext.
`user_data` : | user data set when the signal handler was connected.

### The `"update-lookup-table"` signal

    void                user_function                      (IBusInputContext *context,
                                                            IBusLookupTable  *table,
                                                            gboolean          visible,
                                                            gpointer          user_data)      : Run Last

Emitted to update lookup table.

(Note: The table object is floating, and it will be released after the signal. If singal handler want to keep the object, the handler should use `g_object_ref_sink()` to get the ownership of the object.)

`context` : | An IBusInputContext.
`table` : | An IBusLookupTable to be updated.
`visible` : | Whether the table should be visible.
`user_data` : | user data set when the signal handler was connected.

### The `"update-preedit-text"` signal

    void                user_function                      (IBusInputContext *context,
                                                            IBusText         *text,
                                                            guint             cursor_pos,
                                                            gboolean          visible,
                                                            gpointer          user_data)       : Run Last

Emitted to update preedit text.

(Note: The text object is floating, and it will be released after the signal. If singal handler want to keep the object, the handler should use `g_object_ref_sink()` to get the ownership of the object.)

`context` : | An IBusInputContext.
`text` : | Text to be updated.
`cursor_pos` : | Cursor position.
`visible` : | Whether the update is visible.
`user_data` : | user data set when the signal handler was connected.

### The `"update-property"` signal

    void                user_function                      (IBusInputContext *context,
                                                            IBusProperty     *prop,
                                                            gpointer          user_data)      : Run Last

Emitted to update the property `prop`.

(Note: The prop object is floating, and it will be released after the signal. If singal handler want to keep the object, the handler should use `g_object_ref_sink()` to get the ownership of the object.)

`context` : | An IBusInputContext.
`prop` : | The IBusProperty to be updated.
`user_data` : | user data set when the signal handler was connected.