src/ibusengine.h

   1 /* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
   2 /* vim:set et sts=4: */
   3 /* ibus - The Input Bus
   4  * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
   5  * Copyright (C) 2008-2010 Red Hat, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
  24 #error "Only <ibus.h> can be included directly"
  25 #endif
  26
  27 /**
  28  * SECTION: ibusengine
  29  * @short_description: Input method engine abstract.
  30  * @title: IBusEngine
  31  * @stability: Stable
  32  *
  33  * An IBusEngine provides infrastructure for input method engine.
  34  * Developers can "extend" this class for input method engine development.
  35  *
  36  * see_also: #IBusComponent, #IBusEngineDesc
  37  */
  38 #ifndef __IBUS_ENGINE_H_
  39 #define __IBUS_ENGINE_H_
  40
  41 #include "ibusservice.h"
  42 #include "ibusattribute.h"
  43 #include "ibuslookuptable.h"
  44 #include "ibusproplist.h"
  45
  46 /*
  47  * Type macros.
  48  */
  49
  50 /* define GOBJECT macros */
  51 #define IBUS_TYPE_ENGINE             \
  52     (ibus_engine_get_type ())
  53 #define IBUS_ENGINE(obj)             \
  54     (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_ENGINE, IBusEngine))
  55 #define IBUS_ENGINE_CLASS(klass)     \
  56     (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_ENGINE, IBusEngineClass))
  57 #define IBUS_IS_ENGINE(obj)          \
  58     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_ENGINE))
  59 #define IBUS_IS_ENGINE_CLASS(klass)  \
  60     (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_ENGINE))
  61 #define IBUS_ENGINE_GET_CLASS(obj)   \
  62     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_ENGINE, IBusEngineClass))
  63
  64 G_BEGIN_DECLS
  65
  66 typedef struct _IBusEngine IBusEngine;
  67 typedef struct _IBusEngineClass IBusEngineClass;
  68 typedef struct _IBusEnginePrivate IBusEnginePrivate;
  69
  70 /**
  71  * IBusEngine:
  72  * @enabled: Whether the engine is enabled.
  73  * @has_focus: Whether the engine has focus.
  74  * @cursor_area: Area of cursor.
  75  * @client_capabilities: IBusCapabilite (client capabilities) flags.
  76  *
  77  * IBusEngine properties.
  78  */
  79 struct _IBusEngine {
  80     /*< private >*/
  81     IBusService parent;
  82     IBusEnginePrivate *priv;
  83
  84     /* instance members */
  85     /*< public >*/
  86     gboolean enabled;
  87     gboolean has_focus;
  88
  89     /* cursor location */
  90     IBusRectangle cursor_area;
  91     guint client_capabilities;
  92 };
  93
  94 struct _IBusEngineClass {
  95     /*< private >*/
  96     IBusServiceClass parent;
  97
  98     /* class members */
  99     /*< public >*/
 100     /* signals */
 101     gboolean    (* process_key_event)
 102                                     (IBusEngine     *engine,
 103                                      guint           keyval,
 104                                      guint           keycode,
 105                                      guint           state);
 106     void        (* focus_in)        (IBusEngine     *engine);
 107     void        (* focus_out)       (IBusEngine     *engine);
 108     void        (* reset)           (IBusEngine     *engine);
 109     void        (* enable)          (IBusEngine     *engine);
 110     void        (* disable)         (IBusEngine     *engine);
 111     void        (* set_cursor_location)
 112                                     (IBusEngine     *engine,
 113                                     gint             x,
 114                                     gint             y,
 115                                     gint             w,
 116                                     gint             h);
 117     void        (* set_capabilities)
 118                                     (IBusEngine     *engine,
 119                                      guint           caps);
 120
 121     void        (* page_up)         (IBusEngine     *engine);
 122     void        (* page_down)       (IBusEngine     *engine);
 123     void        (* cursor_up)       (IBusEngine     *engine);
 124     void        (* cursor_down)     (IBusEngine     *engine);
 125
 126     void        (* property_activate)
 127                                     (IBusEngine     *engine,
 128                                      const gchar    *prop_name,
 129                                      guint           prop_state);
 130     void        (* property_show)   (IBusEngine     *engine,
 131                                      const gchar    *prop_name);
 132     void        (* property_hide)   (IBusEngine     *engine,
 133                                      const gchar    *prop_name);
 134     void        (* candidate_clicked)
 135                                     (IBusEngine     *engine,
 136                                      guint           index,
 137                                      guint           button,
 138                                      guint           state);
 139     void        (* set_surrounding_text)
 140                                     (IBusEngine     *engine,
 141                                      IBusText       *text,
 142                                      guint           cursor_index,
 143                                      guint           anchor_pos);
 144     void        (* process_hand_writing_event)
 145                                     (IBusEngine     *engine,
 146                                      const gdouble  *coordinates,
 147                                      guint           coordinates_len);
 148     void        (* cancel_hand_writing)
 149                                     (IBusEngine     *engine,
 150                                      guint           n_strokes);
 151
 152     /*< private >*/
 153     /* padding */
 154     gpointer pdummy[5];
 155 };
 156
 157 GType        ibus_engine_get_type       (void);
 158
 159 /**
 160  * ibus_engine_new:
 161  * @engine_name: Name of the IBusObject.
 162  * @object_path: Path for IBusService.
 163  * @connection: An opened GDBusConnection.
 164  * @returns: A newly allocated IBusEngine.
 165  *
 166  * New an IBusEngine.
 167  */
 168 IBusEngine  *ibus_engine_new            (const gchar        *engine_name,
 169                                          const gchar        *object_path,
 170                                          GDBusConnection    *connection);
 171 /**
 172  * ibus_engine_new_with_type:
 173  * @engine_type: GType of #IBusEngine.
 174  * @engine_name: Name of the IBusObject.
 175  * @object_path: Path for IBusService.
 176  * @connection: An opened GDBusConnection.
 177  * @returns: A newly allocated IBusEngine.
 178  *
 179  * New an IBusEngine.
 180  */
 181 IBusEngine  *ibus_engine_new_with_type  (GType               engine_type,
 182                                          const gchar        *engine_name,
 183                                          const gchar        *object_path,
 184                                          GDBusConnection    *connection);
 185
 186
 187 /**
 188  * ibus_engine_commit_text:
 189  * @engine: An IBusEngine.
 190  * @text: String commit to IBusEngine.
 191  *
 192  * Commit output of input method to IBus client.
 193  *
 194  * (Note: The text object will be released, if it is floating.
 195  *  If caller want to keep the object, caller should make the object
 196  *  sink by g_object_ref_sink.)
 197  */
 198 void         ibus_engine_commit_text    (IBusEngine         *engine,
 199                                          IBusText           *text);
 200
 201 /**
 202  * ibus_engine_update_preedit_text:
 203  * @engine: An IBusEngine.
 204  * @text: Update content.
 205  * @cursor_pos: Current position of cursor
 206  * @visible: Whether the pre-edit buffer is visible.
 207  *
 208  * Update the pre-edit buffer.
 209  *
 210  * (Note: The text object will be released, if it is floating.
 211  *  If caller want to keep the object, caller should make the object
 212  *  sink by g_object_ref_sink.)
 213  */
 214 void         ibus_engine_update_preedit_text
 215                                         (IBusEngine         *engine,
 216                                          IBusText           *text,
 217                                          guint               cursor_pos,
 218                                          gboolean            visible);
 219
 220 /**
 221  * ibus_engine_update_preedit_text_with_mode:
 222  * @engine: An IBusEngine.
 223  * @text: Update content.
 224  * @cursor_pos: Current position of cursor
 225  * @visible: Whether the pre-edit buffer is visible.
 226  * @mode: Pre-edit commit mode when the focus is lost.
 227  *
 228  * Update the pre-edit buffer with commit mode. Similar to
 229  * ibus_engine_update_preedit_text(), this function allows users to specify
 230  * the behavior on focus out when the pre-edit buffer is visible.
 231  *
 232  * If @mode is IBUS_ENGINE_PREEDIT_COMMIT, contents of the pre-edit buffer
 233  * will be comitted and cleared.
 234  * If @mode is IBUS_ENGINE_PREEDIT_CLEAR, contents of the pre-edit buffer
 235  * will be cleared only.
 236  *
 237  * (Note: The text object will be released, if it is floating.
 238  *  If caller want to keep the object, caller should make the object
 239  *  sink by g_object_ref_sink.)
 240  */
 241 void         ibus_engine_update_preedit_text_with_mode
 242                                         (IBusEngine              *engine,
 243                                          IBusText                *text,
 244                                          guint                    cursor_pos,
 245                                          gboolean                 visible,
 246                                          IBusPreeditFocusMode     mode);
 247
 248 /**
 249  * ibus_engine_show_preedit_text:
 250  * @engine: An IBusEngine.
 251  *
 252  * Show the pre-edit buffer.
 253  */
 254 void         ibus_engine_show_preedit_text
 255                                         (IBusEngine         *engine);
 256
 257 /**
 258  * ibus_engine_hide_preedit_text:
 259  * @engine: An IBusEngine.
 260  *
 261  * Hide the pre-edit buffer.
 262  */
 263 void         ibus_engine_hide_preedit_text
 264                                         (IBusEngine         *engine);
 265
 266 /**
 267  * ibus_engine_update_auxiliary_text:
 268  * @engine: An IBusEngine.
 269  * @text: Update content.
 270  * @visible: Whether the auxiliary text bar is visible.
 271  *
 272  * Update the auxiliary bar.
 273  *
 274  * (Note: The text object will be released, if it is floating.
 275  *  If caller want to keep the object, caller should make the object
 276  *  sink by g_object_ref_sink.)
 277  */
 278 void         ibus_engine_update_auxiliary_text
 279                                         (IBusEngine        *engine,
 280                                          IBusText          *text,
 281                                          gboolean           visible);
 282
 283 /**
 284  * ibus_engine_show_auxiliary_text:
 285  * @engine: An IBusEngine.
 286  *
 287  * Show the auxiliary bar.
 288  */
 289 void         ibus_engine_show_auxiliary_text
 290                                         (IBusEngine         *engine);
 291
 292 /**
 293  * ibus_engine_hide_auxiliary_text:
 294  * @engine: An IBusEngine.
 295  *
 296  * Hide the auxiliary bar.
 297  */
 298 void         ibus_engine_hide_auxiliary_text
 299                                         (IBusEngine         *engine);
 300
 301 /**
 302  * ibus_engine_update_lookup_table:
 303  * @engine: An IBusEngine.
 304  * @lookup_table: An lookup_table.
 305  * @visible: Whether the lookup_table is visible.
 306  *
 307  * Update the lookup table.
 308  *
 309  * (Note: The table object will be released, if it is floating.
 310  *  If caller want to keep the object, caller should make the object
 311  *  sink by g_object_ref_sink.)
 312  */
 313 void         ibus_engine_update_lookup_table
 314                                         (IBusEngine         *engine,
 315                                          IBusLookupTable    *lookup_table,
 316                                          gboolean            visible);
 317
 318 /**
 319  * ibus_engine_update_lookup_table_fast:
 320  * @engine: An IBusEngine.
 321  * @lookup_table: An lookup_table.
 322  * @visible: Whether the lookup_table is visible.
 323  *
 324  * Fast update for big lookup table.
 325  *
 326  * If size of lookup table is not over table page size *4,
 327  * then it calls ibus_engine_update_lookup_table().
 328  *
 329  * (Note: The table object will be released, if it is floating.
 330  *  If caller want to keep the object, caller should make the object
 331  *  sink by g_object_ref_sink.)
 332  */
 333 void         ibus_engine_update_lookup_table_fast
 334                                         (IBusEngine         *engine,
 335                                          IBusLookupTable    *lookup_table,
 336                                          gboolean            visible);
 337
 338 /**
 339  * ibus_engine_show_lookup_table:
 340  * @engine: An IBusEngine.
 341  *
 342  * Show the lookup table.
 343  */
 344 void         ibus_engine_show_lookup_table
 345                                         (IBusEngine         *engine);
 346
 347 /**
 348  * ibus_engine_hide_lookup_table:
 349  * @engine: An IBusEngine.
 350  *
 351  * Hide the lookup table.
 352  */
 353 void         ibus_engine_hide_lookup_table
 354                                         (IBusEngine         *engine);
 355
 356 /**
 357  * ibus_engine_forward_key_event:
 358  * @engine: An IBusEngine.
 359  * @keyval: KeySym.
 360  * @keycode: keyboard scancode.
 361  * @state: Key modifier flags.
 362  *
 363  * Forward the key event.
 364  */
 365 void         ibus_engine_forward_key_event
 366                                         (IBusEngine         *engine,
 367                                          guint               keyval,
 368                                          guint               keycode,
 369                                          guint               state);
 370
 371 /**
 372  * ibus_engine_register_properties:
 373  * @engine: An IBusEngine.
 374  * @prop_list: Property List.
 375  *
 376  * Register and show properties in language bar.
 377  *
 378  * (Note: The prop_list object will be released, if it is floating.
 379  *  If caller want to keep the object, caller should make the object
 380  *  sink by g_object_ref_sink.)
 381  */
 382 void         ibus_engine_register_properties
 383                                         (IBusEngine         *engine,
 384                                          IBusPropList       *prop_list);
 385
 386 /**
 387  * ibus_engine_update_property:
 388  * @engine: An IBusEngine.
 389  * @prop: IBusProperty to be updated.
 390  *
 391  * Update the state displayed in language bar.
 392  *
 393  * (Note: The prop object will be released, if it is floating.
 394  *  If caller want to keep the object, caller should make the object
 395  *  sink by g_object_ref_sink.)
 396  */
 397 void         ibus_engine_update_property(IBusEngine         *engine,
 398                                          IBusProperty       *prop);
 399
 400 /**
 401  * ibus_engine_delete_surrounding_text:
 402  * @engine: An IBusEngine.
 403  * @offset: The offset of the first char.
 404  * @nchars: Number of chars to be deleted.
 405  *
 406  * Delete surrounding text.
 407  */
 408 void ibus_engine_delete_surrounding_text(IBusEngine         *engine,
 409                                          gint                offset,
 410                                          guint               nchars);
 411
 412 /**
 413  * ibus_engine_get_surrounding_text:
 414  * @engine: An IBusEngine.
 415  * @text: (out) (transfer none) (allow-none): Location to store surrounding text.
 416  * @cursor_pos: (out) (allow-none): Cursor position in characters in @text.
 417  * @anchor_pos: (out) (allow-none): Anchor position of selection in @text.
 418  *
 419  * Get surrounding text.
 420  *
 421  * It is also used to tell the input-context that the engine will
 422  * utilize surrounding-text.  In that case, it must be called in
 423  * #IBusEngine::enable handler, with both @text and @cursor set to
 424  * %NULL.
 425  *
 426  * see_also #IBusEngine::set-surrounding-text
 427  */
 428 void ibus_engine_get_surrounding_text(IBusEngine         *engine,
 429                                       IBusText          **text,
 430                                       guint              *cursor_pos,
 431                                       guint              *anchor_pos);
 432
 433
 434 /**
 435  * ibus_engine_get_name:
 436  * @engine: An IBusEngine.
 437  * @returns: Name of IBusEngine.
 438  *
 439  * Return the name of IBusEngine.
 440  */
 441 const gchar *ibus_engine_get_name       (IBusEngine         *engine);
 442
 443 G_END_DECLS
 444 #endif