/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */ /* vim:set et sts=4: */ /* ibus - The Input Bus * Copyright (C) 2008-2013 Peng Huang * Copyright (C) 2018 Takao Fujiwara * Copyright (C) 2008-2018 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 * USA */ #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION) #error "Only can be included directly" #endif #ifndef __IBUS_INPUT_CONTEXT_H_ #define __IBUS_INPUT_CONTEXT_H_ /** * SECTION: ibusinputcontext * @short_description: IBus input context proxy object. * @stability: Stable * * 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. */ #include "ibusproxy.h" #include "ibusenginedesc.h" #include "ibustext.h" /* * Type macros. */ /* define GOBJECT macros */ #define IBUS_TYPE_INPUT_CONTEXT \ (ibus_input_context_get_type ()) #define IBUS_INPUT_CONTEXT(obj) \ (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_INPUT_CONTEXT, IBusInputContext)) #define IBUS_INPUT_CONTEXT_CLASS(klass) \ (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_INPUT_CONTEXT, IBusInputContextClass)) #define IBUS_IS_INPUT_CONTEXT(obj) \ (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_INPUT_CONTEXT)) #define IBUS_IS_INPUT_CONTEXT_CLASS(klass) \ (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_INPUT_CONTEXT)) #define IBUS_INPUT_CONTEXT_GET_CLASS(obj) \ (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_INPUT_CONTEXT, IBusInputContextClass)) G_BEGIN_DECLS typedef struct _IBusInputContext IBusInputContext; typedef struct _IBusInputContextClass IBusInputContextClass; /** * IBusInputContext: * * An opaque data type representing an IBusInputContext. */ struct _IBusInputContext { IBusProxy parent; /* instance members */ }; struct _IBusInputContextClass { IBusProxyClass parent; /* signals */ /*< private >*/ /* padding */ gpointer pdummy[24]; }; GType ibus_input_context_get_type (void); /** * ibus_input_context_new: * @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. * * Creates a new #IBusInputContext. * * Returns: A newly allocated #IBusInputContext. */ IBusInputContext * ibus_input_context_new (const gchar *path, GDBusConnection *connection, GCancellable *cancellable, GError **error); /** * ibus_input_context_new_async: * @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. * * Creates a new #IBusInputContext asynchronously. */ void ibus_input_context_new_async (const gchar *path, GDBusConnection *connection, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); /** * ibus_input_context_new_async_finish: * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to * ibus_input_context_new_async(). * @error: Return location for error or %NULL. * * Finishes an operation started with ibus_input_context_new_async(). * * Returns: A newly allocated #IBusInputContext. */ IBusInputContext * ibus_input_context_new_async_finish (GAsyncResult *res, GError **error); /** * ibus_input_context_get_input_context: * @path: The path to the object that emitting the signal. * @connection: A GDBusConnection. * * Gets an existing IBusInputContext. * * Returns: (transfer none): An existing #IBusInputContext. */ IBusInputContext * ibus_input_context_get_input_context (const gchar *path, GDBusConnection *connection); /** * ibus_input_context_get_input_context_async: * @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. * * Gets an existing #IBusInputContext asynchronously. */ void ibus_input_context_get_input_context_async (const gchar *path, GDBusConnection *connection, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); /** * ibus_input_context_get_input_context_async_finish: * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to * ibus_input_context_get_input_context_async(). * @error: Return location for error or %NULL. * * Finishes an operation started with * ibus_input_context_get_input_context_async(). * * Returns: (transfer none): An existing #IBusInputContext. */ IBusInputContext * ibus_input_context_get_input_context_async_finish (GAsyncResult *res, GError **error); /** * ibus_input_context_process_hand_writing_event: * @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. * * 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: #IBusEngine::process-hand-writing-event */ void ibus_input_context_process_hand_writing_event (IBusInputContext *context, const gdouble *coordinates, guint coordinates_len); /** * ibus_input_context_cancel_hand_writing: * @context: An IBusInputContext. * @n_strokes: The number of strokes to be removed. Pass 0 to remove all. * * Clear handwriting stroke(s) in the current input method engine. * * see_also: #IBusEngine::cancel-hand-writing */ void ibus_input_context_cancel_hand_writing (IBusInputContext *context, guint n_strokes); /** * ibus_input_context_process_key_event_async: * @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. * * 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: #IBusEngine::process-key-event */ 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); /** * ibus_input_context_process_key_event_async_finish: * @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. * * Finishes an operation started with * ibus_input_context_process_key_event_async(). * * Returns: %TRUE if the key event is processed; * %FALSE otherwise or some errors happen and the @error will be set. */ gboolean ibus_input_context_process_key_event_async_finish (IBusInputContext *context, GAsyncResult *res, GError **error); /** * ibus_input_context_process_key_event: * @context: An #IBusInputContext. * @keyval: Key symbol of a key event. * @keycode: Keycode of a key event. * @state: Key modifier flags. * * Pass the key event to input method engine and wait for the reply from * ibus (i.e. synchronous IPC). * * Returns: %TRUE for successfully process the key; %FALSE otherwise. * * See also: ibus_input_context_process_key_event_async() */ gboolean ibus_input_context_process_key_event (IBusInputContext *context, guint32 keyval, guint32 keycode, guint32 state); /** * ibus_input_context_set_cursor_location: * @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. * * Set the cursor location of IBus input context asynchronously. * * see_also: #IBusEngine::set-cursor-location */ void ibus_input_context_set_cursor_location (IBusInputContext *context, gint32 x, gint32 y, gint32 w, gint32 h); /** * ibus_input_context_set_cursor_location_relative: * @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. * * Set the relative cursor location of IBus input context asynchronously. */ void ibus_input_context_set_cursor_location_relative (IBusInputContext *context, gint32 x, gint32 y, gint32 w, gint32 h); /** * ibus_input_context_set_capabilities: * @context: An IBusInputContext. * @capabilities: Capabilities flags of IBusEngine, see #IBusCapabilite * * 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: #IBusEngine::set-capabilities */ void ibus_input_context_set_capabilities (IBusInputContext *context, guint32 capabilities); /** * ibus_input_context_property_activate: * @context: An #IBusInputContext. * @prop_name: A property name (e.g. "InputMode.WideLatin") * @state: A status of the property (e.g. PROP_STATE_CHECKED) * * Activate the property asynchronously. * * See also: #IBusEngine::property_activate */ void ibus_input_context_property_activate (IBusInputContext *context, const gchar *prop_name, guint32 state); /** * ibus_input_context_focus_in: * @context: An #IBusInputContext. * * Invoked when the client application get focus. An asynchronous IPC will * be performed. * * see_also: #IBusEngine::focus_in. */ void ibus_input_context_focus_in (IBusInputContext *context); /** * ibus_input_context_focus_out: * @context: An #IBusInputContext. * * Invoked when the client application get focus. An asynchronous IPC will be performed. * * see_also: #IBusEngine::focus_out. */ void ibus_input_context_focus_out (IBusInputContext *context); /** * ibus_input_context_reset: * @context: An #IBusInputContext. * * Invoked when the IME is reset. An asynchronous IPC will be performed. * * see_also: #IBusEngine::reset */ void ibus_input_context_reset (IBusInputContext *context); /** * ibus_input_context_get_engine_async: * @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. * * An asynchronous IPC will be performed. */ void ibus_input_context_get_engine_async (IBusInputContext *context, gint timeout_msec, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); /** * ibus_input_context_get_engine_async_finish: * @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. * * Finishes an operation started with ibus_input_context_get_engine_async(). * * Returns: (transfer none): An IME engine description for the context, or * %NULL. */ IBusEngineDesc * ibus_input_context_get_engine_async_finish (IBusInputContext *context, GAsyncResult *res, GError **error); /** * ibus_input_context_get_engine: * @context: An #IBusInputContext. * * Gets an IME engine description for the context. * A synchronous IPC will be performed. * * Returns: (transfer none): An IME engine description for the context, or NULL. */ IBusEngineDesc * ibus_input_context_get_engine (IBusInputContext *context); /** * ibus_input_context_set_engine: * @context: An #IBusInputContext. * @name: A name of the engine. * * Invoked when the IME engine is changed. * An asynchronous IPC will be performed. */ void ibus_input_context_set_engine (IBusInputContext *context, const gchar *name); /** * ibus_input_context_set_surrounding_text: * @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. */ void ibus_input_context_set_surrounding_text (IBusInputContext *context, IBusText *text, guint32 cursor_pos, guint32 anchor_pos); /** * ibus_input_context_needs_surrounding_text: * @context: An #IBusInputContext. * * Check whether the current engine requires surrounding-text. * * Returns: %TRUE if surrounding-text is needed by the current engine; * %FALSE otherwise. */ gboolean ibus_input_context_needs_surrounding_text (IBusInputContext *context); /** * ibus_input_context_set_content_type: * @context: An #IBusInputContext. * @purpose: Primary purpose of the input context, as an #IBusInputPurpose. * @hints: Hints that augment @purpose, as an #IBusInputHints. * * 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. * * See also: #IBusEngine::set-content-type */ void ibus_input_context_set_content_type (IBusInputContext *context, guint purpose, guint hints); /** * ibus_input_context_set_client_commit_preedit: * @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. * * 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. * * See also ibus_engine_update_preedit_text_with_mode(). */ void ibus_input_context_set_client_commit_preedit ( IBusInputContext *context, gboolean client_commit); G_END_DECLS #endif