IBusEngine

## IBusEngine IBusEngine — Input method engine abstract. |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IBusEngine;
                        IBusEngineClass;
    IBusEngine *        ibus_engine_new                     (const gchar *name,
                                                             const gchar *path,
                                                             IBusConnection *connection);
    void                ibus_engine_commit_text             (IBusEngine *engine,
                                                             IBusText *text);
    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_show_preedit_text       (IBusEngine *engine);
    void                ibus_engine_hide_preedit_text       (IBusEngine *engine);
    void                ibus_engine_update_auxiliary_text   (IBusEngine *engine,
                                                             IBusText *text,
                                                             gboolean visible);
    void                ibus_engine_show_auxiliary_text     (IBusEngine *engine);
    void                ibus_engine_hide_auxiliary_text     (IBusEngine *engine);
    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_show_lookup_table       (IBusEngine *engine);
    void                ibus_engine_hide_lookup_table       (IBusEngine *engine);
    void                ibus_engine_forward_key_event       (IBusEngine *engine,
                                                             guint keyval,
                                                             guint keycode,
                                                             guint state);
    void                ibus_engine_register_properties     (IBusEngine *engine,
                                                             IBusPropList *prop_list);
    void                ibus_engine_update_property         (IBusEngine *engine,
                                                             IBusProperty *prop);
    void                ibus_engine_delete_surrounding_text (IBusEngine *engine,
                                                             gint offset,
                                                             guint nchars);
    const gchar *       ibus_engine_get_name                (IBusEngine *engine);

## Object Hierarchy

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

## Properties

      "connection"               IBusConnection*       : Read / Write / Construct Only
      "name"                     gchar*                : Read / Write / Construct Only

## Signals

      "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-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

## Description

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

`see_also`: IBusComponent, IBusEngineDesc

## Details

### IBusEngine

    typedef struct {
        gboolean enabled;
        gboolean has_focus;

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

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.

### IBusEngineClass

    typedef struct {
        IBusServiceClass parent;

        /* class members */
        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);
    } IBusEngineClass;

### ibus_engine_new ()

    IBusEngine *        ibus_engine_new                     (const gchar *name,
                                                             const gchar *path,
                                                             IBusConnection *connection);

New an IBusEngine.

`name` : | Name of the IBusObject.
`path` : | Path for IBusService.
`connection` : | An opened IBusConnection.
Returns : | A newly allocated IBusEngine.

### 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_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. if mode is IBUS_ENGINE_PREEDIT_CLEAR, ibus_engine_update_preedit_text_with_mode is compatible with ibus_engine_update_preedit_text.

(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_show_preedit_text ()

    void                ibus_engine_show_preedit_text       (IBusEngine *engine);

Show the pre-edit buffer.

`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_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_show_auxiliary_text ()

    void                ibus_engine_show_auxiliary_text     (IBusEngine *engine);

Show the auxiliary bar.

`engine` : | An IBusEngine.

### ibus_engine_hide_auxiliary_text ()

    void                ibus_engine_hide_auxiliary_text     (IBusEngine *engine);

Hide the auxiliary bar.

`engine` : | An IBusEngine.

### 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_show_lookup_table ()

    void                ibus_engine_show_lookup_table       (IBusEngine *engine);

Show the lookup table.

`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_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_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_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.

### 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_get_name ()

    const gchar *       ibus_engine_get_name                (IBusEngine *engine);

Return the name of IBusEngine.

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

## Property Details

### The `"connection"` property

      "connection"               IBusConnection*       : Read / Write / Construct Only

Connection of this IBusEngine.

### The `"name"` property

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

Name of this IBusEngine.

Default value: "noname"

## Signal Details

### 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-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.