path: root/src/ibusinputcontext.h

/* -*- 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 <shawn.p.huang@gmail.com>
 * Copyright (C) 2008-2013 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 <ibus.h> 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: An #GDBusConnection.
 * @cancellable: A #GCancellable or %NULL.
 * @error: Return location for error or %NULL.
 * @returns: A newly allocated IBusInputContext.
 *
 * New an 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: An #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.
 *
 * New an #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.
 * @returns: A newly allocated #IBusInputContext.
 *
 * Finishes an operation started with ibus_input_context_new_async().
 */
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: An #GDBusConnection.
 * @returns: (transfer none): An existing #IBusInputContext.
 *
 * Gets 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: An #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.
 *
 * Get 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.
 * @returns: (transfer none): An existing #IBusInputContext.
 *
 * Finishes an operation started with ibus_input_contex_get_input_context_async().
 */
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.
 * @returns: %TRUE if the key event is processed;
 *      %FALSE otherwise or some errors happen and the @error will be set.
 *
 * Finishes an operation started with ibus_input_context_process_key_event_async().
 */
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.
 * @returns: TRUE for successfully process the key; FALSE otherwise.
 *
 * Pass the key event to input method engine and wait for the reply from ibus (i.e. synchronous IPC).
 *
 * 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_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.
 * @returns: (transfer none): An IME engine description for the context, or %NULL.
 *
 * Finishes an operation started with ibus_input_context_get_engine_async().
 */
IBusEngineDesc *
             ibus_input_context_get_engine_async_finish
                                            (IBusInputContext   *context,
                                             GAsyncResult       *res,
                                             GError            **error);

/**
 * ibus_input_context_get_engine:
 * @context: An IBusInputContext.
 * @returns: (transfer none): An IME engine description for the context, or NULL.
 *
 * Returns an IME engine description for the context.
 * A synchronous IPC will be performed.
 */
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.
 * @returns: %TRUE if surrounding-text is needed by the current engine;
 * %FALSE otherwise.
 *
 * Check whether the current engine requires surrounding-text.
 */
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);

G_END_DECLS
#endif