IBusInputContext: IBus Reference Manual

IBusInputContext

IBusInputContext — IBus input context proxy object.

Stability Level

Stable, unless otherwise indicated

Functions

IBusInputContext *	ibus_input_context_new ()
void	ibus_input_context_new_async ()
IBusInputContext *	ibus_input_context_new_async_finish ()
IBusInputContext *	ibus_input_context_get_input_context ()
void	ibus_input_context_get_input_context_async ()
IBusInputContext *	ibus_input_context_get_input_context_async_finish ()
void	ibus_input_context_process_hand_writing_event ()
void	ibus_input_context_cancel_hand_writing ()
void	ibus_input_context_process_key_event_async ()
gboolean	ibus_input_context_process_key_event_async_finish ()
gboolean	ibus_input_context_process_key_event ()
void	ibus_input_context_set_cursor_location ()
void	ibus_input_context_set_cursor_location_relative ()
void	ibus_input_context_set_capabilities ()
void	ibus_input_context_property_activate ()
void	ibus_input_context_focus_in ()
void	ibus_input_context_focus_out ()
void	ibus_input_context_reset ()
void	ibus_input_context_get_engine_async ()
IBusEngineDesc *	ibus_input_context_get_engine_async_finish ()
IBusEngineDesc *	ibus_input_context_get_engine ()
void	ibus_input_context_set_engine ()
void	ibus_input_context_set_surrounding_text ()
gboolean	ibus_input_context_needs_surrounding_text ()
void	ibus_input_context_set_content_type ()
void	ibus_input_context_set_client_commit_preedit ()

Signals

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

Types and Values

struct

IBusInputContext

Object Hierarchy

    GObject
    ╰── GDBusProxy
        ╰── IBusProxy
            ╰── IBusInputContext

Implemented Interfaces

IBusInputContext implements GDBusInterface, GInitable and GAsyncInitable.

Description

An IBusInputContext is a proxy object of BusInputContext, which manages the context for input methods that supports text input in various natural languages.

Clients call the IBusInputContext to invoke BusInputContext, through which invokes IBusEngine.

Functions

ibus_input_context_new ()

IBusInputContext *
ibus_input_context_new (const gchar *path,
                        GDBusConnection *connection,
                        GCancellable *cancellable,
                        GError **error);

Creates a new IBusInputContext.

Parameters

path	The path to the object that emitting the signal.
connection	A GDBusConnection.
cancellable	A GCancellable or `NULL`.
error	Return location for error or `NULL`.

Returns

A newly allocated IBusInputContext.

ibus_input_context_new_async ()

void
ibus_input_context_new_async (const gchar *path,
                              GDBusConnection *connection,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Creates a new IBusInputContext asynchronously.

Parameters

path	The path to the object that emitting the signal.
connection	A GDBusConnection.
cancellable	A GCancellable or `NULL`.
callback	A GAsyncReadyCallback to call when the request is satisfied. The callback should not be `NULL`.
user_data	The data to pass to callback.

ibus_input_context_new_async_finish ()

IBusInputContext *
ibus_input_context_new_async_finish (GAsyncResult *res,
                                     GError **error);

Finishes an operation started with ibus_input_context_new_async().

Parameters

res	A GAsyncResult obtained from the GAsyncReadyCallback pass to `ibus_input_context_new_async()`.
error	Return location for error or `NULL`.

Returns

A newly allocated IBusInputContext.

ibus_input_context_get_input_context ()

IBusInputContext *
ibus_input_context_get_input_context (const gchar *path,
                                      GDBusConnection *connection);

Gets an existing IBusInputContext.

Parameters

path	The path to the object that emitting the signal.
connection	A GDBusConnection.

Returns

An existing IBusInputContext.

[transfer none]

ibus_input_context_get_input_context_async ()

void
ibus_input_context_get_input_context_async
                               (const gchar *path,
                                GDBusConnection *connection,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Gets an existing IBusInputContext asynchronously.

Parameters

path	The path to the object that emitting the signal.
connection	A GDBusConnection.
cancellable	A GCancellable or `NULL`.
callback	A GAsyncReadyCallback to call when the request is satisfied. The callback should not be `NULL`.
user_data	The data to pass to callback.

ibus_input_context_get_input_context_async_finish ()

IBusInputContext *
ibus_input_context_get_input_context_async_finish
                               (GAsyncResult *res,
                                GError **error);

Finishes an operation started with ibus_input_context_get_input_context_async().

Parameters

res	A GAsyncResult obtained from the GAsyncReadyCallback pass to `ibus_input_context_get_input_context_async()`.
error	Return location for error or `NULL`.

Returns

An existing IBusInputContext.

[transfer none]

ibus_input_context_process_hand_writing_event ()

void
ibus_input_context_process_hand_writing_event
                               (IBusInputContext *context,
                                const gdouble *coordinates,
                                guint coordinates_len);

Pass a handwriting stroke to an input method engine.

In this API, a coordinate (0.0, 0.0) represents the top-left corner of an area for handwriting, and (1.0, 1.0) does the bottom-right. Therefore, for example, if a user writes a character 'L', the array would be something like [0.0, 0.0, 0.0, 1.0, 1.0, 1.0] and coordinates_len would be 6.

The function is usually called when a user releases the mouse button in a hand writing area.

see_also: “process-hand-writing-event”

Parameters

context	An IBusInputContext.
coordinates	An array of gdouble (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. The number should be even and >= 4.

ibus_input_context_cancel_hand_writing ()

void
ibus_input_context_cancel_hand_writing
                               (IBusInputContext *context,
                                guint n_strokes);

Clear handwriting stroke(s) in the current input method engine.

see_also: “cancel-hand-writing”

Parameters

context	An IBusInputContext.
n_strokes	The number of strokes to be removed. Pass 0 to remove all.

ibus_input_context_process_key_event_async ()

void
ibus_input_context_process_key_event_async
                               (IBusInputContext *context,
                                guint32 keyval,
                                guint32 keycode,
                                guint32 state,
                                gint timeout_msec,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Pass the key event to input method engine.

Key symbols are characters/symbols produced by key press, for example, pressing "s" generates key symbol "s"; pressing shift-"s" generates key symbol "S". Same key on keyboard may produce different key symbols on different keyboard layout. e.g., "s" key on QWERTY keyboard produces "o" in DVORAK layout.

Unlike key symbol, keycode is only determined by the location of the key, and irrelevant of the keyboard layout.

Briefly speaking, input methods that expect certain keyboard layout should use keycode; otherwise keyval is sufficient. For example, Chewing, Cangjie, Wubi expect an en-US QWERTY keyboard, these should use keycode; while pinyin can rely on keyval only, as it is less sensitive to the keyboard layout change, DVORAK users can still use DVORAK layout to input pinyin.

Use ibus_keymap_lookup_keysym() to convert keycode to keysym in given keyboard layout.

see_also: “process-key-event”

Parameters

context	An IBusInputContext.
keyval	Key symbol of a key event.
keycode	Keycode of a key event.
state	Key modifier flags.
timeout_msec	The timeout in milliseconds or -1 to use the default timeout.
cancellable	A GCancellable or NULL.
callback	A GAsyncReadyCallback to call when the request is satisfied or NULL if you don't care about the result of the method invocation.
user_data	The data to pass to callback.

ibus_input_context_process_key_event_async_finish ()

gboolean
ibus_input_context_process_key_event_async_finish
                               (IBusInputContext *context,
                                GAsyncResult *res,
                                GError **error);

Finishes an operation started with ibus_input_context_process_key_event_async().

Parameters

context	An IBusInputContext.
res	A GAsyncResult obtained from the GAsyncReadyCallback passed to `ibus_input_context_process_key_event_async()`.
error	Return location for error or `NULL`.

Returns

TRUE if the key event is processed; FALSE otherwise or some errors happen and the error will be set.

ibus_input_context_process_key_event ()

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

Pass the key event to input method engine and wait for the reply from ibus (i.e. synchronous IPC).

Parameters

context	An IBusInputContext.
keyval	Key symbol of a key event.
keycode	Keycode of a key event.
state	Key modifier flags.

Returns

TRUE for successfully process the key; FALSE otherwise.

ibus_input_context_set_cursor_location ()

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

Set the cursor location of IBus input context asynchronously.

see_also: “set-cursor-location”

Parameters

context	An IBusInputContext.
x	X coordinate of the cursor.
y	Y coordinate of the cursor.
w	Width of the cursor.
h	Height of the cursor.

ibus_input_context_set_cursor_location_relative ()

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

Set the relative cursor location of IBus input context asynchronously.

Parameters

context	An IBusInputContext.
x	X coordinate of the cursor.
y	Y coordinate of the cursor.
w	Width of the cursor.
h	Height of the cursor.

ibus_input_context_set_capabilities ()

void
ibus_input_context_set_capabilities (IBusInputContext *context,
                                     guint32 capabilities);

Set the capabilities flags of client application asynchronously. When IBUS_CAP_FOCUS is not set, IBUS_CAP_PREEDIT_TEXT, IBUS_CAP_AUXILIARY_TEXT, IBUS_CAP_LOOKUP_TABLE, and IBUS_CAP_PROPERTY have to be all set. The panel component does nothing for an application that doesn't support focus.

see_also: “set-capabilities”

Parameters

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

ibus_input_context_property_activate ()

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

Activate the property asynchronously.

Parameters

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

ibus_input_context_focus_in ()

void
ibus_input_context_focus_in (IBusInputContext *context);

Invoked when the client application get focus. An asynchronous IPC will be performed.

see_also: “focus_in”.

Parameters

context

An IBusInputContext.

ibus_input_context_focus_out ()

void
ibus_input_context_focus_out (IBusInputContext *context);

Invoked when the client application get focus. An asynchronous IPC will be performed.

see_also: “focus_out”.

Parameters

context

An IBusInputContext.

ibus_input_context_reset ()

void
ibus_input_context_reset (IBusInputContext *context);

Invoked when the IME is reset. An asynchronous IPC will be performed.

see_also: “reset”

Parameters

context

An IBusInputContext.

ibus_input_context_get_engine_async ()

void
ibus_input_context_get_engine_async (IBusInputContext *context,
                                     gint timeout_msec,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

An asynchronous IPC will be performed.

Parameters

context	An IBusInputContext.
timeout_msec	The timeout in milliseconds or -1 to use the default timeout.
cancellable	A GCancellable or `NULL`.
callback	A GAsyncReadyCallback to call when the request is satisfied or `NULL` if you don't care about the result of the method invocation.
user_data	The data to pass to callback.

ibus_input_context_get_engine_async_finish ()

IBusEngineDesc *
ibus_input_context_get_engine_async_finish
                               (IBusInputContext *context,
                                GAsyncResult *res,
                                GError **error);

Finishes an operation started with ibus_input_context_get_engine_async().

Parameters

context	An IBusInputContext.
res	A GAsyncResult obtained from the GAsyncReadyCallback passed to `ibus_input_context_get_engine_async()`.
error	Return location for error or `NULL`.

Returns

An IME engine description for the context, or NULL.

[transfer none]

ibus_input_context_get_engine ()

IBusEngineDesc *
ibus_input_context_get_engine (IBusInputContext *context);

Gets an IME engine description for the context. A synchronous IPC will be performed.

Parameters

context

An IBusInputContext.

Returns

An IME engine description for the context, or NULL.

[transfer none]

ibus_input_context_set_engine ()

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

Invoked when the IME engine is changed. An asynchronous IPC will be performed.

Parameters

context	An IBusInputContext.
name	A name of the engine.

ibus_input_context_set_surrounding_text ()

void
ibus_input_context_set_surrounding_text
                               (IBusInputContext *context,
                                IBusText *text,
                                guint32 cursor_pos,
                                guint32 anchor_pos);

Parameters

context	An IBusInputContext.
text	An IBusText surrounding the current cursor on the application.
cursor_pos	Current cursor position in characters in `text` .
anchor_pos	Anchor position of selection in `text` .

ibus_input_context_needs_surrounding_text ()

gboolean
ibus_input_context_needs_surrounding_text
                               (IBusInputContext *context);

Check whether the current engine requires surrounding-text.

Parameters

context

An IBusInputContext.

Returns

TRUE if surrounding-text is needed by the current engine; FALSE otherwise.

ibus_input_context_set_content_type ()

void
ibus_input_context_set_content_type (IBusInputContext *context,
                                     guint purpose,
                                     guint hints);

Set content-type (primary purpose and hints) of the context. This information is particularly useful to implement intelligent behavior in engines, such as automatic input-mode switch and text prediction. For example, to restrict input to numbers, the client can call this function with purpose set to IBUS_INPUT_PURPOSE_NUMBER.

Parameters

context	An IBusInputContext.
purpose	Primary purpose of the input context, as an IBusInputPurpose.
hints	Hints that augment `purpose` , as an IBusInputHints.

ibus_input_context_set_client_commit_preedit ()

void
ibus_input_context_set_client_commit_preedit
                               (IBusInputContext *context,
                                gboolean client_commit);

Set whether IBusInputContext commits pre-edit texts or not. If TRUE, 'update-preedit-text-with-mode' signal is emitted instead of 'update-preedit-text' signal. If your client receives the 'update-preedit-text-with-mode' signal, the client needs to implement commit_text() of pre-edit text when GtkIMContextClass.focus_out() is called in case an IME desires that behavior but it depends on each IME.

Parameters

context	An IBusInputContext.
client_commit	`TRUE` if your input context commits pre-edit texts with Space or Enter key events or mouse click events. `FALSE` if ibus-daemon commits pre-edit texts with those events. The default is `FALSE`. The behavior is decided with `ibus_engine_update_preedit_text_with_mode()` to commit, clear or keep the pre-edit text and this API is important in ibus-hangul.

Types and Values

struct IBusInputContext

struct IBusInputContext;

An opaque data type representing an IBusInputContext.

Signal Details

The `“commit-text”` signal

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

Emitted when the text is going to be committed.

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

Parameters

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

Flags: Run Last

The `“cursor-down-lookup-table”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to select next candidate of lookup table.

Parameters

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

Flags: Run Last

The `“cursor-up-lookup-table”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to select previous candidate of lookup table.

Parameters

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

Flags: Run Last

The `“delete-surrounding-text”` signal

void
user_function (IBusInputContext *context,
               int               offset,
               guint             n_chars,
               gpointer          user_data)

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

Parameters

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

Flags: Run Last

The `“disabled”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted when an IME is disabled.

Parameters

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

Flags: Run Last

The `“enabled”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted when an IME is enabled.

Parameters

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

Flags: Run Last

The `“forward-key-event”` signal

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

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

Parameters

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

Flags: Run Last

The `“hide-auxiliary-text”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to hide auxiliary text.

Parameters

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

Flags: Run Last

The `“hide-lookup-table”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to hide lookup table.

Parameters

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

Flags: Run Last

The `“hide-preedit-text”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to hide preedit text.

Parameters

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

Flags: Run Last

The `“page-down-lookup-table”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to view the next page of lookup table.

Parameters

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

Flags: Run Last

The `“page-up-lookup-table”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to view the previous page of lookup table.

Parameters

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

Flags: Run Last

The `“register-properties”` signal

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

Emitted to register the properties in props .

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

Parameters

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

Flags: Run Last

The `“require-surrounding-text”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to receive the RequireSurroundingText signal from the daemon.

Parameters

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

Flags: Run Last

The `“show-auxiliary-text”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to show auxiliary text.

Parameters

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

Flags: Run Last

The `“show-lookup-table”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to show lookup table.

Parameters

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

Flags: Run Last

The `“show-preedit-text”` signal

void
user_function (IBusInputContext *context,
               gpointer          user_data)

Emitted to show preedit text.

Parameters

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

Flags: Run Last

The `“update-auxiliary-text”` signal

void
user_function (IBusInputContext *context,
               IBusText         *text,
               gboolean          visible,
               gpointer          user_data)

Emitted to hide auxilary text.

Parameters

context	An IBusInputContext.
text	An auxiliary text
visible	The visibility of `text`
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“update-lookup-table”` signal

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

Emitted to update lookup table.

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

Parameters

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

Flags: Run Last

The `“update-preedit-text”` signal

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

Emitted to update preedit text.

Parameters

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

Flags: Run Last

The `“update-preedit-text-with-mode”` signal

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

Emitted to update preedit text with the mode.

Parameters

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

Flags: Run Last

The `“update-property”` signal

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

Emitted to update the property prop .

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

Parameters

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

Flags: Run Last