path: root/src/ibusengine.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_ENGINE_H_
#define __IBUS_ENGINE_H_

/**
 * SECTION: ibusengine
 * @short_description: Input method engine abstract.
 * @title: IBusEngine
 * @stability: Stable
 *
 * An IBusEngine provides infrastructure for input method engine.
 * Developers can "extend" this class for input method engine development.
 *
 * see_also: #IBusComponent, #IBusEngineDesc
 */

#include "ibusservice.h"
#include "ibusattribute.h"
#include "ibuslookuptable.h"
#include "ibusproplist.h"

/*
 * Type macros.
 */

/* define GOBJECT macros */
#define IBUS_TYPE_ENGINE             \
    (ibus_engine_get_type ())
#define IBUS_ENGINE(obj)             \
    (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_ENGINE, IBusEngine))
#define IBUS_ENGINE_CLASS(klass)     \
    (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_ENGINE, IBusEngineClass))
#define IBUS_IS_ENGINE(obj)          \
    (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_ENGINE))
#define IBUS_IS_ENGINE_CLASS(klass)  \
    (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_ENGINE))
#define IBUS_ENGINE_GET_CLASS(obj)   \
    (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_ENGINE, IBusEngineClass))

G_BEGIN_DECLS

typedef struct _IBusEngine IBusEngine;
typedef struct _IBusEngineClass IBusEngineClass;
typedef struct _IBusEnginePrivate IBusEnginePrivate;

/**
 * IBusEngine:
 * @enabled: Whether the engine is enabled.
 * @has_focus: Whether the engine has focus.
 * @cursor_area: Area of cursor.
 * @client_capabilities: IBusCapabilite (client capabilities) flags.
 * @client_purpose: IBusInputPurpose (client input purpose).
 * @client_hints: IBusInputHints (client input hints) flags.
 *
 * IBusEngine properties.
 */
struct _IBusEngine {
    /*< private >*/
    IBusService parent;
    IBusEnginePrivate *priv;

    /* instance members */
    /*< public >*/
    gboolean enabled;
    gboolean has_focus;

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

struct _IBusEngineClass {
    /*< private >*/
    IBusServiceClass parent;

    /* class members */
    /*< public >*/
    /* 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);

    /*< private >*/
    /* padding */
    gpointer pdummy[4];
};

GType        ibus_engine_get_type       (void);

/**
 * ibus_engine_new:
 * @engine_name: Name of the IBusObject.
 * @object_path: Path for IBusService.
 * @connection: An opened GDBusConnection.
 * @returns: A newly allocated IBusEngine.
 *
 * New an IBusEngine.
 */
IBusEngine  *ibus_engine_new            (const gchar        *engine_name,
                                         const gchar        *object_path,
                                         GDBusConnection    *connection);
/**
 * ibus_engine_new_with_type:
 * @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.
 *
 * New an IBusEngine.
 */
IBusEngine  *ibus_engine_new_with_type  (GType               engine_type,
                                         const gchar        *engine_name,
                                         const gchar        *object_path,
                                         GDBusConnection    *connection);


/**
 * ibus_engine_commit_text:
 * @engine: An IBusEngine.
 * @text: String commit to IBusEngine.
 *
 * 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.)
 */
void         ibus_engine_commit_text    (IBusEngine         *engine,
                                         IBusText           *text);

/**
 * ibus_engine_update_preedit_text:
 * @engine: An IBusEngine.
 * @text: Update content.
 * @cursor_pos: Current position of cursor
 * @visible: Whether the pre-edit buffer is 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.)
 */
void         ibus_engine_update_preedit_text
                                        (IBusEngine         *engine,
                                         IBusText           *text,
                                         guint               cursor_pos,
                                         gboolean            visible);

/**
 * ibus_engine_update_preedit_text_with_mode:
 * @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.
 *
 * 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.)
 */
void         ibus_engine_update_preedit_text_with_mode
                                        (IBusEngine              *engine,
                                         IBusText                *text,
                                         guint                    cursor_pos,
                                         gboolean                 visible,
                                         IBusPreeditFocusMode     mode);

/**
 * ibus_engine_show_preedit_text:
 * @engine: An IBusEngine.
 *
 * Show the pre-edit buffer.
 */
void         ibus_engine_show_preedit_text
                                        (IBusEngine         *engine);

/**
 * ibus_engine_hide_preedit_text:
 * @engine: An IBusEngine.
 *
 * Hide the pre-edit buffer.
 */
void         ibus_engine_hide_preedit_text
                                        (IBusEngine         *engine);

/**
 * ibus_engine_update_auxiliary_text:
 * @engine: An IBusEngine.
 * @text: Update content.
 * @visible: Whether the auxiliary text bar is 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.)
 */
void         ibus_engine_update_auxiliary_text
                                        (IBusEngine        *engine,
                                         IBusText          *text,
                                         gboolean           visible);

/**
 * ibus_engine_show_auxiliary_text:
 * @engine: An IBusEngine.
 *
 * Show the auxiliary bar.
 */
void         ibus_engine_show_auxiliary_text
                                        (IBusEngine         *engine);

/**
 * ibus_engine_hide_auxiliary_text:
 * @engine: An IBusEngine.
 *
 * Hide the auxiliary bar.
 */
void         ibus_engine_hide_auxiliary_text
                                        (IBusEngine         *engine);

/**
 * ibus_engine_update_lookup_table:
 * @engine: An IBusEngine.
 * @lookup_table: An lookup_table.
 * @visible: Whether the lookup_table is 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.)
 */
void         ibus_engine_update_lookup_table
                                        (IBusEngine         *engine,
                                         IBusLookupTable    *lookup_table,
                                         gboolean            visible);

/**
 * ibus_engine_update_lookup_table_fast:
 * @engine: An IBusEngine.
 * @lookup_table: An lookup_table.
 * @visible: Whether the lookup_table is 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.)
 */
void         ibus_engine_update_lookup_table_fast
                                        (IBusEngine         *engine,
                                         IBusLookupTable    *lookup_table,
                                         gboolean            visible);

/**
 * ibus_engine_show_lookup_table:
 * @engine: An IBusEngine.
 *
 * Show the lookup table.
 */
void         ibus_engine_show_lookup_table
                                        (IBusEngine         *engine);

/**
 * ibus_engine_hide_lookup_table:
 * @engine: An IBusEngine.
 *
 * Hide the lookup table.
 */
void         ibus_engine_hide_lookup_table
                                        (IBusEngine         *engine);

/**
 * ibus_engine_forward_key_event:
 * @engine: An IBusEngine.
 * @keyval: KeySym.
 * @keycode: keyboard scancode.
 * @state: Key modifier flags.
 *
 * Forward the key event.
 */
void         ibus_engine_forward_key_event
                                        (IBusEngine         *engine,
                                         guint               keyval,
                                         guint               keycode,
                                         guint               state);

/**
 * ibus_engine_register_properties:
 * @engine: An IBusEngine.
 * @prop_list: Property 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.)
 */
void         ibus_engine_register_properties
                                        (IBusEngine         *engine,
                                         IBusPropList       *prop_list);

/**
 * ibus_engine_update_property:
 * @engine: An IBusEngine.
 * @prop: IBusProperty to be updated.
 *
 * 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.)
 */
void         ibus_engine_update_property(IBusEngine         *engine,
                                         IBusProperty       *prop);

/**
 * ibus_engine_delete_surrounding_text:
 * @engine: An IBusEngine.
 * @offset: The offset of the first char.
 * @nchars: Number of chars to be deleted.
 *
 * Delete surrounding text.
 */
void ibus_engine_delete_surrounding_text(IBusEngine         *engine,
                                         gint                offset,
                                         guint               nchars);

/**
 * ibus_engine_get_surrounding_text:
 * @engine: An IBusEngine.
 * @text: (out) (transfer full) (allow-none): Location to store surrounding text.
 * @cursor_pos: (out) (allow-none): Cursor position in characters in @text.
 * @anchor_pos: (out) (allow-none): Anchor position of selection in @text.
 *
 * 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
 * #IBusEngine::enable handler, with both @text and @cursor set to
 * %NULL.
 *
 * See also: #IBusEngine::set-surrounding-text
 */
void ibus_engine_get_surrounding_text   (IBusEngine         *engine,
                                         IBusText          **text,
                                         guint              *cursor_pos,
                                         guint              *anchor_pos);


/**
 * ibus_engine_get_content_type:
 * @engine: An #IBusEngine.
 * @purpose: (out) (allow-none): Primary purpose of the input context.
 * @hints: (out) (allow-none): Hints that augument @purpose.
 *
 * Get content-type (primary purpose and hints) of the current input
 * context.
 *
 * See also: #IBusEngine::set-content-type
 */
void ibus_engine_get_content_type       (IBusEngine         *engine,
                                         guint              *purpose,
                                         guint              *hints);

/**
 * ibus_engine_get_name:
 * @engine: An IBusEngine.
 * @returns: Name of IBusEngine.
 *
 * Return the name of IBusEngine.
 */
const gchar *ibus_engine_get_name       (IBusEngine         *engine);

G_END_DECLS
#endif