## IBusEngine

IBusEngine — Input method engine abstract.

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    struct              IBusEngine;
    struct              IBusEngineClass;
    void                ibus_engine_commit_text             (IBusEngine *engine,
                                                             IBusText *text);
    void                ibus_engine_delete_surrounding_text (IBusEngine *engine,
                                                             gint offset,
                                                             guint nchars);
    void                ibus_engine_forward_key_event       (IBusEngine *engine,
                                                             guint keyval,
                                                             guint keycode,
                                                             guint state);
    const gchar *       ibus_engine_get_name                (IBusEngine *engine);
    void                ibus_engine_get_surrounding_text    (IBusEngine *engine,
                                                             IBusText **text,
                                                             guint *cursor_pos,
                                                             guint *anchor_pos);
    void                ibus_engine_hide_auxiliary_text     (IBusEngine *engine);
    void                ibus_engine_hide_lookup_table       (IBusEngine *engine);
    void                ibus_engine_hide_preedit_text       (IBusEngine *engine);
    IBusEngine *        ibus_engine_new                     (const gchar *engine_name,
                                                             const gchar *object_path,
                                                             GDBusConnection *connection);
    IBusEngine *        ibus_engine_new_with_type           (GType engine_type,
                                                             const gchar *engine_name,
                                                             const gchar *object_path,
                                                             GDBusConnection *connection);
    void                ibus_engine_register_properties     (IBusEngine *engine,
                                                             IBusPropList *prop_list);
    void                ibus_engine_show_auxiliary_text     (IBusEngine *engine);
    void                ibus_engine_show_lookup_table       (IBusEngine *engine);
    void                ibus_engine_show_preedit_text       (IBusEngine *engine);
    void                ibus_engine_update_auxiliary_text   (IBusEngine *engine,
                                                             IBusText *text,
                                                             gboolean visible);
    void                ibus_engine_update_lookup_table     (IBusEngine *engine,
                                                             IBusLookupTable *lookup_table,
                                                             gboolean visible);
    void                ibus_engine_update_lookup_table_fast
                                                            (IBusEngine *engine,
                                                             IBusLookupTable *lookup_table,
                                                             gboolean visible);
    void                ibus_engine_update_preedit_text     (IBusEngine *engine,
                                                             IBusText *text,
                                                             guint cursor_pos,
                                                             gboolean visible);
    void                ibus_engine_update_preedit_text_with_mode
                                                            (IBusEngine *engine,
                                                             IBusText *text,
                                                             guint cursor_pos,
                                                             gboolean visible,
                                                             IBusPreeditFocusMode mode);
    void                ibus_engine_update_property         (IBusEngine *engine,
                                                             IBusProperty *prop);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusService
                         +----IBusEngine

## Properties

      "engine-name"              gchar*                : Read / Write / Construct Only

## Signals

      "cancel-hand-writing"                            : Run Last
      "candidate-clicked"                              : Run Last
      "cursor-down"                                    : Run Last
      "cursor-up"                                      : Run Last
      "disable"                                        : Run Last
      "enable"                                         : Run Last
      "focus-in"                                       : Run Last
      "focus-out"                                      : Run Last
      "page-down"                                      : Run Last
      "page-up"                                        : Run Last
      "process-hand-writing-event"                     : Run Last
      "process-key-event"                              : Run Last
      "property-activate"                              : Run Last
      "property-hide"                                  : Run Last
      "property-show"                                  : Run Last
      "reset"                                          : Run Last
      "set-capabilities"                               : Run Last
      "set-cursor-location"                            : Run Last
      "set-surrounding-text"                           : Run Last

## Description

An IBusEngine provides infrastructure for input method engine. Developers can "extend" this class for input method engine development.

see_also: IBusComponent, IBusEngineDesc

## Details

### struct IBusEngine

    struct IBusEngine {
        gboolean enabled;
        gboolean has_focus;

        /* cursor location */
        IBusRectangle cursor_area;
        guint client_capabilities;
    };

IBusEngine properties.

gboolean `enabled`; | Whether the engine is enabled.
gboolean `has_focus`; | Whether the engine has focus.
IBusRectangle `cursor_area`; | Area of cursor.
guint `client_capabilities`; | IBusCapabilite (client capabilities) flags.

### struct IBusEngineClass

    struct IBusEngineClass {
        /* signals */
        gboolean    (* process_key_event)
                                        (IBusEngine     *engine,
                                         guint           keyval,
                                         guint           keycode,
                                         guint           state);
        void        (* focus_in)        (IBusEngine     *engine);
        void        (* focus_out)       (IBusEngine     *engine);
        void        (* reset)           (IBusEngine     *engine);
        void        (* enable)          (IBusEngine     *engine);
        void        (* disable)         (IBusEngine     *engine);
        void        (* set_cursor_location)
                                        (IBusEngine     *engine,
                                        gint             x,
                                        gint             y,
                                        gint             w,
                                        gint             h);
        void        (* set_capabilities)
                                        (IBusEngine     *engine,
                                         guint           caps);

        void        (* page_up)         (IBusEngine     *engine);
        void        (* page_down)       (IBusEngine     *engine);
        void        (* cursor_up)       (IBusEngine     *engine);
        void        (* cursor_down)     (IBusEngine     *engine);

        void        (* property_activate)
                                        (IBusEngine     *engine,
                                         const gchar    *prop_name,
                                         guint           prop_state);
        void        (* property_show)   (IBusEngine     *engine,
                                         const gchar    *prop_name);
        void        (* property_hide)   (IBusEngine     *engine,
                                         const gchar    *prop_name);
        void        (* candidate_clicked)
                                        (IBusEngine     *engine,
                                         guint           index,
                                         guint           button,
                                         guint           state);
        void        (* set_surrounding_text)
                                        (IBusEngine     *engine,
                                         IBusText       *text,
                                         guint           cursor_index,
                                         guint           anchor_pos);
        void        (* process_hand_writing_event)
                                        (IBusEngine     *engine,
                                         const gdouble  *coordinates,
                                         guint           coordinates_len);
        void        (* cancel_hand_writing)
                                        (IBusEngine     *engine,
                                         guint           n_strokes);
    };

### ibus_engine_commit_text ()

    void                ibus_engine_commit_text             (IBusEngine *engine,
                                                             IBusText *text);

Commit output of input method to IBus client.

(Note: The text object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`text` : | String commit to IBusEngine.

### ibus_engine_delete_surrounding_text ()

    void                ibus_engine_delete_surrounding_text (IBusEngine *engine,
                                                             gint offset,
                                                             guint nchars);

Delete surrounding text.

`engine` : | An IBusEngine.
`offset` : | The offset of the first char.
`nchars` : | Number of chars to be deleted.

### ibus_engine_forward_key_event ()

    void                ibus_engine_forward_key_event       (IBusEngine *engine,
                                                             guint keyval,
                                                             guint keycode,
                                                             guint state);

Forward the key event.

`engine` : | An IBusEngine.
`keyval` : | KeySym.
`keycode` : | keyboard scancode.
`state` : | Key modifier flags.

### ibus_engine_get_name ()

    const gchar *       ibus_engine_get_name                (IBusEngine *engine);

Return the name of IBusEngine.

`engine` : | An IBusEngine.
Returns : | Name of IBusEngine.

### ibus_engine_get_surrounding_text ()

    void                ibus_engine_get_surrounding_text    (IBusEngine *engine,
                                                             IBusText **text,
                                                             guint *cursor_pos,
                                                             guint *anchor_pos);

Get surrounding text.

It is also used to tell the input-context that the engine will utilize surrounding-text. In that case, it must be called in "enable" handler, with both `text` and `cursor` set to `NULL`.

see_also "set-surrounding-text"

`engine` : | An IBusEngine.
`text` : | Location to store surrounding text. [out][transfer none][allow-none]
`cursor_pos` : | Cursor position in characters in `text`. [out][allow-none]
`anchor_pos` : | Anchor position of selection in `text`. [out][allow-none]

### ibus_engine_hide_auxiliary_text ()

    void                ibus_engine_hide_auxiliary_text     (IBusEngine *engine);

Hide the auxiliary bar.

`engine` : | An IBusEngine.

### ibus_engine_hide_lookup_table ()

    void                ibus_engine_hide_lookup_table       (IBusEngine *engine);

Hide the lookup table.

`engine` : | An IBusEngine.

### ibus_engine_hide_preedit_text ()

    void                ibus_engine_hide_preedit_text       (IBusEngine *engine);

Hide the pre-edit buffer.

`engine` : | An IBusEngine.

### ibus_engine_new ()

    IBusEngine *        ibus_engine_new                     (const gchar *engine_name,
                                                             const gchar *object_path,
                                                             GDBusConnection *connection);

New an IBusEngine.

`engine_name` : | Name of the IBusObject.
`object_path` : | Path for IBusService.
`connection` : | An opened GDBusConnection.
Returns : | A newly allocated IBusEngine.

### ibus_engine_new_with_type ()

    IBusEngine *        ibus_engine_new_with_type           (GType engine_type,
                                                             const gchar *engine_name,
                                                             const gchar *object_path,
                                                             GDBusConnection *connection);

New an IBusEngine.

`engine_type` : | GType of IBusEngine.
`engine_name` : | Name of the IBusObject.
`object_path` : | Path for IBusService.
`connection` : | An opened GDBusConnection.
Returns : | A newly allocated IBusEngine.

### ibus_engine_register_properties ()

    void                ibus_engine_register_properties     (IBusEngine *engine,
                                                             IBusPropList *prop_list);

Register and show properties in language bar.

(Note: The prop_list object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`prop_list` : | Property List.

### ibus_engine_show_auxiliary_text ()

    void                ibus_engine_show_auxiliary_text     (IBusEngine *engine);

Show the auxiliary bar.

`engine` : | An IBusEngine.

### ibus_engine_show_lookup_table ()

    void                ibus_engine_show_lookup_table       (IBusEngine *engine);

Show the lookup table.

`engine` : | An IBusEngine.

### ibus_engine_show_preedit_text ()

    void                ibus_engine_show_preedit_text       (IBusEngine *engine);

Show the pre-edit buffer.

`engine` : | An IBusEngine.

### ibus_engine_update_auxiliary_text ()

    void                ibus_engine_update_auxiliary_text   (IBusEngine *engine,
                                                             IBusText *text,
                                                             gboolean visible);

Update the auxiliary bar.

(Note: The text object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`text` : | Update content.
`visible` : | Whether the auxiliary text bar is visible.

### ibus_engine_update_lookup_table ()

    void                ibus_engine_update_lookup_table     (IBusEngine *engine,
                                                             IBusLookupTable *lookup_table,
                                                             gboolean visible);

Update the lookup table.

(Note: The table object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`lookup_table` : | An lookup_table.
`visible` : | Whether the lookup_table is visible.

### ibus_engine_update_lookup_table_fast ()

    void                ibus_engine_update_lookup_table_fast
                                                            (IBusEngine *engine,
                                                             IBusLookupTable *lookup_table,
                                                             gboolean visible);

Fast update for big lookup table.

If size of lookup table is not over table page size *4, then it calls `ibus_engine_update_lookup_table()`.

(Note: The table object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`lookup_table` : | An lookup_table.
`visible` : | Whether the lookup_table is visible.

### ibus_engine_update_preedit_text ()

    void                ibus_engine_update_preedit_text     (IBusEngine *engine,
                                                             IBusText *text,
                                                             guint cursor_pos,
                                                             gboolean visible);

Update the pre-edit buffer.

(Note: The text object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`text` : | Update content.
`cursor_pos` : | Current position of cursor
`visible` : | Whether the pre-edit buffer is visible.

### ibus_engine_update_preedit_text_with_mode ()

    void                ibus_engine_update_preedit_text_with_mode
                                                            (IBusEngine *engine,
                                                             IBusText *text,
                                                             guint cursor_pos,
                                                             gboolean visible,
                                                             IBusPreeditFocusMode mode);

Update the pre-edit buffer with commit mode. Similar to `ibus_engine_update_preedit_text()`, this function allows users to specify the behavior on focus out when the pre-edit buffer is visible.

If `mode` is IBUS_ENGINE_PREEDIT_COMMIT, contents of the pre-edit buffer will be comitted and cleared. If `mode` is IBUS_ENGINE_PREEDIT_CLEAR, contents of the pre-edit buffer will be cleared only.

(Note: The text object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`text` : | Update content.
`cursor_pos` : | Current position of cursor
`visible` : | Whether the pre-edit buffer is visible.
`mode` : | Pre-edit commit mode when the focus is lost.

### ibus_engine_update_property ()

    void                ibus_engine_update_property         (IBusEngine *engine,
                                                             IBusProperty *prop);

Update the state displayed in language bar.

(Note: The prop object will be released, if it is floating. If caller want to keep the object, caller should make the object sink by g_object_ref_sink.)

`engine` : | An IBusEngine.
`prop` : | IBusProperty to be updated.

## Property Details

### The `"engine-name"` property

      "engine-name"              gchar*                : Read / Write / Construct Only

engine name.

Default value: "noname"

## Signal Details

### The `"cancel-hand-writing"` signal

    void                user_function                      (IBusEngine *engine,
                                                            guint       n_strokes,
                                                            gpointer    user_data)      : Run Last

Emitted when a hand writing operation is cancelled. Implement the member function `cancel_hand_writing()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`n_strokes` : | The number of strokes to be removed. 0 means "remove all".
`user_data` : | user data set when the signal handler was connected.

### The `"candidate-clicked"` signal

    void                user_function                      (IBusEngine *engine,
                                                            guint       index,
                                                            guint       button,
                                                            guint       state,
                                                            gpointer    user_data)      : Run Last

Emitted when candidate on lookup table is clicked. Implement the member function `candidate_clicked()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`index` : | Index of candidate be clicked.
`button` : | Mouse button.
`state` : | Keyboard state.
`user_data` : | user data set when the signal handler was connected.

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

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

Emitted when the down cursor button is pressed. Implement the member function `cursor_down()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

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

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

Emitted when the up cursor button is pressed. Implement the member function `cursor_up()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

### The `"disable"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

Emitted when the IME is disabled. Implement the member function `set_disable()` in extended class to receive this signal.

See also: `ibus_input_context_disable()`.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

### The `"enable"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

Emitted when the IME is enabled. Implement the member function `set_enable()` in extended class to receive this signal.

See also: `ibus_input_context_enable()`.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

### The `"focus-in"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

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

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

### The `"focus-out"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

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

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

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

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

Emitted when the page-down button is pressed. Implement the member function `page_down()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

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

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

Emitted when the page-up button is pressed. Implement the member function `page_up()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

### The `"process-hand-writing-event"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    coordinates,
                                                            guint       coordinates_len,
                                                            gpointer    user_data)            : Run Last

Emitted when a hand writing operation is cancelled. Implement the member function `cancel_hand_writing()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`coordinates` : | An array of double (0.0 to 1.0) which represents a stroke (i.e. [x1, y1, x2, y2, x3, y3, ...]).
`coordinates_len` : | The number of elements in the array.
`user_data` : | user data set when the signal handler was connected.

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

    gboolean            user_function                      (IBusEngine *engine,
                                                            guint       keyval,
                                                            guint       keycode,
                                                            guint       state,
                                                            gpointer    user_data)      : Run Last

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.

`engine` : | An IBusEngine.
`keyval` : | Key symbol of the key press.
`keycode` : | KeyCode of the key press.
`state` : | Key modifier flags.
`user_data` : | user data set when the signal handler was connected.

Returns :

TRUE for successfully process the key; FALSE otherwise. See also: `ibus_input_context_process_key_event()`.

### Note

Argument `user_data` is ignored in this function.

### The `"property-activate"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gchar      *name,
                                                            guint       state,
                                                            gpointer    user_data)      : Run Last

Emitted when a property is activated or change changed. Implement the member function `property_activate()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`name` : | Property name.
`state` : | Property state.
`user_data` : | user data set when the signal handler was connected.

### The `"property-hide"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gchar      *name,
                                                            gpointer    user_data)      : Run Last

Emitted when a property is hidden. Implement the member function `property_hide()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`name` : | Property name.
`user_data` : | user data set when the signal handler was connected.

### The `"property-show"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gchar      *name,
                                                            gpointer    user_data)      : Run Last

Emitted when a property is shown. Implement the member function `property_side()` in extended class to receive this signal.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`name` : | Property name.
`user_data` : | user data set when the signal handler was connected.

### The `"reset"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gpointer    user_data)      : Run Last

Emitted when the IME is reset. Implement the member function `reset()` in extended class to receive this signal.

See also: `ibus_input_context_reset()`.

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`user_data` : | user data set when the signal handler was connected.

### The `"set-capabilities"` signal

    void                user_function                      (IBusEngine *engine,
                                                            guint       caps,
                                                            gpointer    user_data)      : Run Last

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

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`caps` : | Capabilities flags of IBusEngine, see IBusCapabilite
`user_data` : | user data set when the signal handler was connected.

### The `"set-cursor-location"` signal

    void                user_function                      (IBusEngine *engine,
                                                            gint        x,
                                                            gint        y,
                                                            gint        w,
                                                            gint        h,
                                                            gpointer    user_data)      : Run Last

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

Argument `user_data` is ignored in this function.

`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.
`user_data` : | user data set when the signal handler was connected.

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

    void                user_function                      (IBusEngine *engine,
                                                            GObject    *text,
                                                            guint       cursor_pos,
                                                            guint       anchor_pos,
                                                            gpointer    user_data)       : Run Last

Emitted when a surrounding text is set. Implement the member function `set_surrounding_text()` in extended class to receive this signal. If anchor_pos equals to cursor_pos, it means "there are no selection" or "does not support selection retrival".

### Note

Argument `user_data` is ignored in this function.

`engine` : | An IBusEngine.
`text` : | The surrounding text.
`cursor_pos` : | The cursor position on surrounding text.
`anchor_pos` : | The anchor position on selection area.
`user_data` : | user data set when the signal handler was connected.