IBusEngine

IBusEngine — Input method engine abstract.

Stability Level

Stable, unless otherwise indicated

Synopsis

struct              IBusEngine;
struct              IBusEngineClass;
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_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);
void                ibus_engine_get_surrounding_text    (IBusEngine *engine,
                                                         IBusText **text,
                                                         guint *cursor_pos,
                                                         guint *anchor_pos);
void                ibus_engine_get_content_type        (IBusEngine *engine,
                                                         guint *purpose,
                                                         guint *hints);
const gchar *       ibus_engine_get_name                (IBusEngine *engine);

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-content-type"                               : 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);
    void        (* set_content_type)
                                    (IBusEngine     *engine,
                                     guint           purpose,
                                     guint           hints);
};

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

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.

engine :

 An IBusEngine.

Returns :

 Name of IBusEngine.

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-content-type" signal

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

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

Note

Argument user_data is ignored in this function.

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.

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.
Generated by GTK-Doc V1.19