IBusEngine: IBus Reference Manual

## IBusEngine IBusEngine — Input method engine abstract. |

## Stability Level

Stable, unless otherwise indicated

## Functions

IBusEngine * | ibus_engine_new ()
IBusEngine * | ibus_engine_new_with_type ()
void | ibus_engine_commit_text ()
void | ibus_engine_update_preedit_text ()
void | ibus_engine_update_preedit_text_with_mode ()
void | ibus_engine_show_preedit_text ()
void | ibus_engine_hide_preedit_text ()
void | ibus_engine_update_auxiliary_text ()
void | ibus_engine_show_auxiliary_text ()
void | ibus_engine_hide_auxiliary_text ()
void | ibus_engine_update_lookup_table ()
void | ibus_engine_update_lookup_table_fast ()
void | ibus_engine_show_lookup_table ()
void | ibus_engine_hide_lookup_table ()
void | ibus_engine_forward_key_event ()
void | ibus_engine_register_properties ()
void | ibus_engine_update_property ()
void | ibus_engine_delete_surrounding_text ()
void | ibus_engine_get_surrounding_text ()
void | ibus_engine_get_content_type ()
const gchar * | ibus_engine_get_name ()

## Properties

gboolean | active-surrounding-text | Read / Write / Construct Only
char * | engine-name | Read / Write / Construct Only
gboolean | has-focus-id | Read / Write / Construct Only

## Signals

void | cancel-hand-writing | Run Last
void | candidate-clicked | Run Last
void | cursor-down | Run Last
void | cursor-up | Run Last
void | disable | Run Last
void | enable | Run Last
void | focus-in | Run Last
void | focus-in-id | Run Last
void | focus-out | Run Last
void | focus-out-id | Run Last
void | page-down | Run Last
void | page-up | Run Last
void | process-hand-writing-event | Run Last
gboolean | process-key-event | Run Last
void | property-activate | Run Last
void | property-hide | Run Last
void | property-show | Run Last
void | reset | Run Last
void | set-capabilities | Run Last
void | set-content-type | Run Last
void | set-cursor-location | Run Last
void | set-surrounding-text | Run Last

## Types and Values

struct | IBusEngine

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── IBusObject
                ╰── IBusService
                    ╰── IBusEngine
                        ╰── IBusEngineSimple

## Description

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

see_also: IBusComponent, IBusEngineDesc

## Functions

### ibus_engine_new ()

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

Create a new IBusEngine.

#### Parameters

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);

Create a new IBusEngine.

#### Parameters

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

#### Parameters

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

#### Parameters

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 committed 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.)

#### Parameters

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.

#### Parameters

engine | An IBusEngine. |

### ibus_engine_hide_preedit_text ()

    void
    ibus_engine_hide_preedit_text (IBusEngine *engine);

Hide the pre-edit buffer.

#### Parameters

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

#### Parameters

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.

#### Parameters

engine | An IBusEngine. |

### ibus_engine_hide_auxiliary_text ()

    void
    ibus_engine_hide_auxiliary_text (IBusEngine *engine);

Hide the auxiliary bar.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

engine | An IBusEngine. |

### ibus_engine_hide_lookup_table ()

    void
    ibus_engine_hide_lookup_table (IBusEngine *engine);

Hide the lookup table.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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

    void
    ibus_engine_get_content_type (IBusEngine *engine,
                                  guint *purpose,
                                  guint *hints);

Get content-type (primary purpose and hints) of the current input context.

See also: “set-content-type”

#### Parameters

engine | An IBusEngine. |
purpose | Primary purpose of the input context. | [out][allow-none]
hints | Hints that augument `purpose` . | [out][allow-none]

### ibus_engine_get_name ()

    const gchar *
    ibus_engine_get_name (IBusEngine *engine);

Return the name of IBusEngine.

#### Parameters

engine | An IBusEngine. |

#### Returns

Name of IBusEngine.

## Types and Values

### struct IBusEngine

    struct IBusEngine {
        gboolean enabled;
        gboolean has_focus;

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

IBusEngine properties.

#### Members

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

## Property Details

### The `“active-surrounding-text”` property

      “active-surrounding-text”  gboolean

When this property is set to `TRUE`, "RequireSurroundingText" D-Bus signal will be called by ibus-daemon on every focus-in/out event, with no need for the engine to call `ibus_engine_get_surrounding_text()`. This property can only be set at construct time.

Owner: IBusEngine

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“engine-name”` property

      “engine-name”              char *

Name of this IBusEngine.

Owner: IBusEngine

Flags: Read / Write / Construct Only

Default value: "noname"

### The `“has-focus-id”` property

      “has-focus-id”             gboolean

Use IBusEngine::`focus_in_id()`/`focus_out_id()` class method insteads of `focus_in()`/`focus_out()` class methods when this property is set to `TRUE`. Otherwise, use IBusEngine::`focus_in()`/focus_out class methods. This property can only be set at construct time.

See also: IBusEngine::focus-in-id

Owner: IBusEngine

Flags: Read / Write / Construct Only

Default value: FALSE

## Signal Details

### The `“cancel-hand-writing”` signal

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

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“candidate-clicked”` signal

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

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“cursor-down”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“cursor-up”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“disable”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

Emitted when the IME is disabled. Implement the member function IBusEngineClass::disable in extended class to receive this signal.

See also: `ibus_bus_set_global_engine()`.

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“enable”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

Emitted when the IME is enabled. Implement the member function IBusEngineClass::enable in extended class to receive this signal.

See also: `ibus_bus_set_global_engine()`.

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“focus-in”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

Emitted when the client application get the focus. Implement the member function IBusEngineClass::focus_in in extended class to receive this signal.

See also: `ibus_input_context_focus_in()`

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“focus-in-id”` signal

    void
    user_function (IBusEngine *engine,
                   char       *object_path,
                   char       *client,
                   gpointer    user_data)

Emitted when the client application get the focus. Implement the member function IBusEngineClass::focus_in in extended class to receive this signal. `object_path` is a unique id by input context. `client` indicates a client type: 'fake': focus is on desktop background or other programs where no input is possible 'xim': old X11 programs like xterm, emacs, ... GTK3 programs in a Gnome Xorg session when GTK_IM_MODULE is unset also use xim 'gtk-im:<client-name>': Gtk2 input module is used 'gtk3-im:<client-name>': Gtk3 input module is used 'gtk4-im:<client-name>': Gtk4 input module is used In case of the Gtk input modules, the name of the client is also shown after the “:”, for example like 'gtk3-im:firefox', 'gtk4-im:gnome-text-editor', … 'gnome-shell': Entries handled by gnome-shell (like the command line dialog opened with Alt+F2 or the search field when pressing the Super key.) When GTK_IM_MODULE is unset in a Gnome Wayland session all programs which would show 'gtk3-im' or 'gtk4-im' with GTK_IM_MODULE=ibus then show 'gnome-shell' instead. 'Qt': Qt4 programs like keepassx-2.0.3 … 'QIBusInputContext': Qt5 programs like keepassxc-2.7.1, anki-2.1.15 telegram-desktop-3.7.3,

You need to set “has-focus-id” property to `TRUE` when you construct an IBusEngine to use this class method.

See also: `ibus_input_context_focus_in()`

Argument `user_data` is ignored in this function.

#### Parameters

engine | An IBusEngine. |
object_path | An object path. |
client | An client name. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“focus-out”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

Emitted when the client application lost the focus. Implement the member function IBusEngineClass::focus_out in extended class to receive this signal.

See also: `ibus_input_context_focus_out()`

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“focus-out-id”` signal

    void
    user_function (IBusEngine *engine,
                   char       *object_path,
                   gpointer    user_data)

Emitted when the client application lost the focus. Implement the member function IBusEngineClass::focus_out in extended class to receive this signal. `object_path` is a unique id by input context. You need to set “has-focus-id” property to `TRUE` when you construct an IBusEngine to use this class method.

See also: `ibus_input_context_focus_out()`

Argument `user_data` is ignored in this function.

#### Parameters

engine | An IBusEngine. |
object_path | An object path. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“page-down”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“page-up”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“process-hand-writing-event”` signal

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

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“process-key-event”` signal

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

Emitted when a key event is received. Implement the member function IBusEngineClass::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.

#### Parameters

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()`.

Argument `user_data` is ignored in this function.

Flags: Run Last

### The `“property-activate”` signal

    void
    user_function (IBusEngine *engine,
                   char       *name,
                   guint       state,
                   gpointer    user_data)

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

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“property-hide”` signal

    void
    user_function (IBusEngine *engine,
                   char       *name,
                   gpointer    user_data)

Emitted when a property is hidden. Implement the member function IBusEngineClass::property_hide in extended class to receive this signal.

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“property-show”` signal

    void
    user_function (IBusEngine *engine,
                   char       *name,
                   gpointer    user_data)

Emitted when a property is shown. Implement the member function IBusEngineClass::property_side in extended class to receive this signal.

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“reset”` signal

    void
    user_function (IBusEngine *engine,
                   gpointer    user_data)

Emitted when the IME is reset. Implement the member function IBusEngineClass::reset in extended class to receive this signal.

See also: `ibus_input_context_reset()`.

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“set-capabilities”` signal

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

Emitted when the client application capabilities is set. Implement the member function IBusEngineClass::set_capabilities in extended class to receive this signal.

See also: `ibus_input_context_set_capabilities()`.

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“set-content-type”` signal

    void
    user_function (IBusEngine *engine,
                   guint       purpose,
                   guint       hints,
                   gpointer    user_data)

Emitted when the client application content-type (primary purpose and hints) is set. The engine could change the behavior according to the content-type. Implement the member function IBusEngineClass::set_content_type in extended class to receive this signal.

For example, if the client application wants to restrict input to numbers, this signal will be emitted with `purpose` set to IBUS_INPUT_PURPOSE_NUMBER, so the engine can switch the input mode to latin.

Argument `user_data` is ignored in this function.

#### Parameters

engine | An IBusEngine. |
purpose | Primary purpose of the input context, as an IBusInputPurpose. |
hints | Hints that augment `purpose` , as an IBusInputHints. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“set-cursor-location”` signal

    void
    user_function (IBusEngine *engine,
                   int         x,
                   int         y,
                   int         w,
                   int         h,
                   gpointer    user_data)

Emitted when the location of IME is set. Implement the member function IBusEngineClass::set_cursor_location in extended class to receive this signal.

See also: `ibus_input_context_set_cursor_location()`.

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last

### The `“set-surrounding-text”` signal

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

Emitted when a surrounding text is set. Implement the member function IBusEngineClass::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".

Argument `user_data` is ignored in this function.

#### Parameters

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

Flags: Run Last