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-2013 Peng Huang <shawn.p.huang@gmail.com> 5 * Copyright (C) 2018 Takao Fujiwara <takao.fujiwara1@gmail.com> 6 * Copyright (C) 2008-2018 Red Hat, Inc. 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 21 * USA 22 */ 23 24 #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION) 25 #error "Only <ibus.h> can be included directly" 26 #endif 27 28 #ifndef __IBUS_INPUT_CONTEXT_H_ 29 #define __IBUS_INPUT_CONTEXT_H_ 30 31 /** 32 * SECTION: ibusinputcontext 33 * @short_description: IBus input context proxy object. 34 * @stability: Stable 35 * 36 * An IBusInputContext is a proxy object of BusInputContext, 37 * which manages the context for input methods that supports 38 * text input in various natural languages. 39 * 40 * Clients call the IBusInputContext to invoke BusInputContext, 41 * through which invokes IBusEngine. 42 */ 43 #include "ibusproxy.h" 44 #include "ibusenginedesc.h" 45 #include "ibustext.h" 46 47 /* 48 * Type macros. 49 */ 50 51 /* define GOBJECT macros */ 52 #define IBUS_TYPE_INPUT_CONTEXT \ 53 (ibus_input_context_get_type ()) 54 #define IBUS_INPUT_CONTEXT(obj) \ 55 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_INPUT_CONTEXT, IBusInputContext)) 56 #define IBUS_INPUT_CONTEXT_CLASS(klass) \ 57 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_INPUT_CONTEXT, IBusInputContextClass)) 58 #define IBUS_IS_INPUT_CONTEXT(obj) \ 59 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_INPUT_CONTEXT)) 60 #define IBUS_IS_INPUT_CONTEXT_CLASS(klass) \ 61 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_INPUT_CONTEXT)) 62 #define IBUS_INPUT_CONTEXT_GET_CLASS(obj) \ 63 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_INPUT_CONTEXT, IBusInputContextClass)) 64 65 G_BEGIN_DECLS 66 67 typedef struct _IBusInputContext IBusInputContext; 68 typedef struct _IBusInputContextClass IBusInputContextClass; 69 70 /** 71 * IBusInputContext: 72 * 73 * An opaque data type representing an IBusInputContext. 74 */ 75 struct _IBusInputContext { 76 IBusProxy parent; 77 /* instance members */ 78 }; 79 80 struct _IBusInputContextClass { 81 IBusProxyClass parent; 82 /* signals */ 83 84 /*< private >*/ 85 /* padding */ 86 gpointer pdummy[24]; 87 }; 88 89 GType ibus_input_context_get_type (void); 90 91 /** 92 * ibus_input_context_new: 93 * @path: The path to the object that emitting the signal. 94 * @connection: A #GDBusConnection. 95 * @cancellable: A #GCancellable or %NULL. 96 * @error: Return location for error or %NULL. 97 * 98 * Creates a new #IBusInputContext. 99 * 100 * Returns: A newly allocated #IBusInputContext. 101 */ 102 IBusInputContext * 103 ibus_input_context_new (const gchar *path, 104 GDBusConnection *connection, 105 GCancellable *cancellable, 106 GError **error); 107 /** 108 * ibus_input_context_new_async: 109 * @path: The path to the object that emitting the signal. 110 * @connection: A #GDBusConnection. 111 * @cancellable: A #GCancellable or %NULL. 112 * @callback: A #GAsyncReadyCallback to call when the request is satisfied. 113 * The callback should not be %NULL. 114 * @user_data: The data to pass to callback. 115 * 116 * Creates a new #IBusInputContext asynchronously. 117 */ 118 void ibus_input_context_new_async (const gchar *path, 119 GDBusConnection *connection, 120 GCancellable *cancellable, 121 GAsyncReadyCallback callback, 122 gpointer user_data); 123 124 /** 125 * ibus_input_context_new_async_finish: 126 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to 127 * ibus_input_context_new_async(). 128 * @error: Return location for error or %NULL. 129 * 130 * Finishes an operation started with ibus_input_context_new_async(). 131 * 132 * Returns: A newly allocated #IBusInputContext. 133 */ 134 IBusInputContext * 135 ibus_input_context_new_async_finish 136 (GAsyncResult *res, 137 GError **error); 138 /** 139 * ibus_input_context_get_input_context: 140 * @path: The path to the object that emitting the signal. 141 * @connection: A GDBusConnection. 142 * 143 * Gets an existing IBusInputContext. 144 * 145 * Returns: (transfer none): An existing #IBusInputContext. 146 */ 147 IBusInputContext * 148 ibus_input_context_get_input_context 149 (const gchar *path, 150 GDBusConnection *connection); 151 /** 152 * ibus_input_context_get_input_context_async: 153 * @path: The path to the object that emitting the signal. 154 * @connection: A #GDBusConnection. 155 * @cancellable: A #GCancellable or %NULL. 156 * @callback: A #GAsyncReadyCallback to call when the request is satisfied. 157 * The callback should not be %NULL. 158 * @user_data: The data to pass to callback. 159 * 160 * Gets an existing #IBusInputContext asynchronously. 161 */ 162 void ibus_input_context_get_input_context_async 163 (const gchar *path, 164 GDBusConnection *connection, 165 GCancellable *cancellable, 166 GAsyncReadyCallback callback, 167 gpointer user_data); 168 169 /** 170 * ibus_input_context_get_input_context_async_finish: 171 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to 172 * ibus_input_context_get_input_context_async(). 173 * @error: Return location for error or %NULL. 174 * 175 * Finishes an operation started with 176 * ibus_input_context_get_input_context_async(). 177 * 178 * Returns: (transfer none): An existing #IBusInputContext. 179 */ 180 IBusInputContext * 181 ibus_input_context_get_input_context_async_finish 182 (GAsyncResult *res, 183 GError **error); 184 185 /** 186 * ibus_input_context_process_hand_writing_event: 187 * @context: An IBusInputContext. 188 * @coordinates: An array of gdouble (0.0 to 1.0) which represents a stroke (i.e. [x1, y1, x2, y2, x3, y3, ...]). 189 * @coordinates_len: The number of elements in the array. The number should be even and >= 4. 190 * 191 * Pass a handwriting stroke to an input method engine. 192 * 193 * In this API, a coordinate (0.0, 0.0) represents the top-left corner of an area for 194 * handwriting, and (1.0, 1.0) does the bottom-right. Therefore, for example, if 195 * a user writes a character 'L', the array would be something like [0.0, 0.0, 0.0, 1.0, 1.0, 1.0] 196 * and coordinates_len would be 6. 197 * 198 * The function is usually called when a user releases the mouse button in a hand 199 * writing area. 200 * 201 * see_also: #IBusEngine::process-hand-writing-event 202 */ 203 void ibus_input_context_process_hand_writing_event 204 (IBusInputContext *context, 205 const gdouble *coordinates, 206 guint coordinates_len); 207 208 /** 209 * ibus_input_context_cancel_hand_writing: 210 * @context: An IBusInputContext. 211 * @n_strokes: The number of strokes to be removed. Pass 0 to remove all. 212 * 213 * Clear handwriting stroke(s) in the current input method engine. 214 * 215 * see_also: #IBusEngine::cancel-hand-writing 216 */ 217 void ibus_input_context_cancel_hand_writing 218 (IBusInputContext *context, 219 guint n_strokes); 220 221 /** 222 * ibus_input_context_process_key_event_async: 223 * @context: An IBusInputContext. 224 * @keyval: Key symbol of a key event. 225 * @keycode: Keycode of a key event. 226 * @state: Key modifier flags. 227 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout. 228 * @cancellable: A GCancellable or NULL. 229 * @callback: A GAsyncReadyCallback to call when the request is satisfied or NULL 230 * if you don't care about the result of the method invocation. 231 * @user_data: The data to pass to callback. 232 * 233 * Pass the key event to input method engine. 234 * 235 * Key symbols are characters/symbols produced by key press, for example, 236 * pressing "s" generates key symbol "s"; pressing shift-"s" generates key symbol "S". 237 * Same key on keyboard may produce different key symbols on different keyboard layout. 238 * e.g., "s" key on QWERTY keyboard produces "o" in DVORAK layout. 239 * 240 * Unlike key symbol, keycode is only determined by the location of the key, and 241 * irrelevant of the keyboard layout. 242 * 243 * Briefly speaking, input methods that expect certain keyboard layout should use 244 * keycode; otherwise keyval is sufficient. 245 * For example, Chewing, Cangjie, Wubi expect an en-US QWERTY keyboard, these should 246 * use keycode; while pinyin can rely on keyval only, as it is less sensitive to 247 * the keyboard layout change, DVORAK users can still use DVORAK layout to input pinyin. 248 * 249 * Use ibus_keymap_lookup_keysym() to convert keycode to keysym in given keyboard layout. 250 * 251 * see_also: #IBusEngine::process-key-event 252 */ 253 void ibus_input_context_process_key_event_async 254 (IBusInputContext *context, 255 guint32 keyval, 256 guint32 keycode, 257 guint32 state, 258 gint timeout_msec, 259 GCancellable *cancellable, 260 GAsyncReadyCallback callback, 261 gpointer user_data); 262 263 /** 264 * ibus_input_context_process_key_event_async_finish: 265 * @context: An #IBusInputContext. 266 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to 267 * ibus_input_context_process_key_event_async(). 268 * @error: Return location for error or %NULL. 269 * 270 * Finishes an operation started with 271 * ibus_input_context_process_key_event_async(). 272 * 273 * Returns: %TRUE if the key event is processed; 274 * %FALSE otherwise or some errors happen and the @error will be set. 275 */ 276 gboolean ibus_input_context_process_key_event_async_finish 277 (IBusInputContext *context, 278 GAsyncResult *res, 279 GError **error); 280 281 /** 282 * ibus_input_context_process_key_event: 283 * @context: An #IBusInputContext. 284 * @keyval: Key symbol of a key event. 285 * @keycode: Keycode of a key event. 286 * @state: Key modifier flags. 287 * 288 * Pass the key event to input method engine and wait for the reply from 289 * ibus (i.e. synchronous IPC). 290 * 291 * Returns: %TRUE for successfully process the key; %FALSE otherwise. 292 * 293 * See also: ibus_input_context_process_key_event_async() 294 */ 295 gboolean ibus_input_context_process_key_event 296 (IBusInputContext *context, 297 guint32 keyval, 298 guint32 keycode, 299 guint32 state); 300 301 302 /** 303 * ibus_input_context_set_cursor_location: 304 * @context: An IBusInputContext. 305 * @x: X coordinate of the cursor. 306 * @y: Y coordinate of the cursor. 307 * @w: Width of the cursor. 308 * @h: Height of the cursor. 309 * 310 * Set the cursor location of IBus input context asynchronously. 311 * 312 * see_also: #IBusEngine::set-cursor-location 313 */ 314 void ibus_input_context_set_cursor_location 315 (IBusInputContext *context, 316 gint32 x, 317 gint32 y, 318 gint32 w, 319 gint32 h); 320 /** 321 * ibus_input_context_set_cursor_location_relative: 322 * @context: An IBusInputContext. 323 * @x: X coordinate of the cursor. 324 * @y: Y coordinate of the cursor. 325 * @w: Width of the cursor. 326 * @h: Height of the cursor. 327 * 328 * Set the relative cursor location of IBus input context asynchronously. 329 */ 330 void ibus_input_context_set_cursor_location_relative 331 (IBusInputContext *context, 332 gint32 x, 333 gint32 y, 334 gint32 w, 335 gint32 h); 336 /** 337 * ibus_input_context_set_capabilities: 338 * @context: An IBusInputContext. 339 * @capabilities: Capabilities flags of IBusEngine, see #IBusCapabilite 340 * 341 * Set the capabilities flags of client application asynchronously. 342 * 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. 343 * The panel component does nothing for an application that doesn't support focus. 344 * 345 * see_also: #IBusEngine::set-capabilities 346 */ 347 void ibus_input_context_set_capabilities 348 (IBusInputContext *context, 349 guint32 capabilities); 350 351 /** 352 * ibus_input_context_property_activate: 353 * @context: An #IBusInputContext. 354 * @prop_name: A property name (e.g. "InputMode.WideLatin") 355 * @state: A status of the property (e.g. PROP_STATE_CHECKED) 356 * 357 * Activate the property asynchronously. 358 * 359 * See also: #IBusEngine::property_activate 360 */ 361 void ibus_input_context_property_activate 362 (IBusInputContext *context, 363 const gchar *prop_name, 364 guint32 state); 365 366 /** 367 * ibus_input_context_focus_in: 368 * @context: An #IBusInputContext. 369 * 370 * Invoked when the client application get focus. An asynchronous IPC will 371 * be performed. 372 * 373 * see_also: #IBusEngine::focus_in. 374 */ 375 void ibus_input_context_focus_in (IBusInputContext *context); 376 377 /** 378 * ibus_input_context_focus_out: 379 * @context: An #IBusInputContext. 380 * 381 * Invoked when the client application get focus. An asynchronous IPC will be performed. 382 * 383 * see_also: #IBusEngine::focus_out. 384 */ 385 void ibus_input_context_focus_out (IBusInputContext *context); 386 387 388 /** 389 * ibus_input_context_reset: 390 * @context: An #IBusInputContext. 391 * 392 * Invoked when the IME is reset. An asynchronous IPC will be performed. 393 * 394 * see_also: #IBusEngine::reset 395 */ 396 void ibus_input_context_reset (IBusInputContext *context); 397 398 /** 399 * ibus_input_context_get_engine_async: 400 * @context: An #IBusInputContext. 401 * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout. 402 * @cancellable: A #GCancellable or %NULL. 403 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or 404 * %NULL if you don't care about the result of the method invocation. 405 * @user_data: The data to pass to callback. 406 * 407 * An asynchronous IPC will be performed. 408 */ 409 void ibus_input_context_get_engine_async 410 (IBusInputContext *context, 411 gint timeout_msec, 412 GCancellable *cancellable, 413 GAsyncReadyCallback callback, 414 gpointer user_data); 415 416 /** 417 * ibus_input_context_get_engine_async_finish: 418 * @context: An #IBusInputContext. 419 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to 420 * ibus_input_context_get_engine_async(). 421 * @error: Return location for error or %NULL. 422 * 423 * Finishes an operation started with ibus_input_context_get_engine_async(). 424 * 425 * Returns: (transfer none): An IME engine description for the context, or 426 * %NULL. 427 */ 428 IBusEngineDesc * 429 ibus_input_context_get_engine_async_finish 430 (IBusInputContext *context, 431 GAsyncResult *res, 432 GError **error); 433 434 /** 435 * ibus_input_context_get_engine: 436 * @context: An #IBusInputContext. 437 * 438 * Gets an IME engine description for the context. 439 * A synchronous IPC will be performed. 440 * 441 * Returns: (transfer none): An IME engine description for the context, or NULL. 442 */ 443 IBusEngineDesc * 444 ibus_input_context_get_engine (IBusInputContext *context); 445 446 /** 447 * ibus_input_context_set_engine: 448 * @context: An #IBusInputContext. 449 * @name: A name of the engine. 450 * 451 * Invoked when the IME engine is changed. 452 * An asynchronous IPC will be performed. 453 */ 454 void ibus_input_context_set_engine (IBusInputContext *context, 455 const gchar *name); 456 457 /** 458 * ibus_input_context_set_surrounding_text: 459 * @context: An #IBusInputContext. 460 * @text: An #IBusText surrounding the current cursor on the application. 461 * @cursor_pos: Current cursor position in characters in @text. 462 * @anchor_pos: Anchor position of selection in @text. 463 */ 464 void ibus_input_context_set_surrounding_text 465 (IBusInputContext *context, 466 IBusText *text, 467 guint32 cursor_pos, 468 guint32 anchor_pos); 469 470 /** 471 * ibus_input_context_needs_surrounding_text: 472 * @context: An #IBusInputContext. 473 * 474 * Check whether the current engine requires surrounding-text. 475 * 476 * Returns: %TRUE if surrounding-text is needed by the current engine; 477 * %FALSE otherwise. 478 */ 479 gboolean ibus_input_context_needs_surrounding_text 480 (IBusInputContext *context); 481 482 /** 483 * ibus_input_context_set_content_type: 484 * @context: An #IBusInputContext. 485 * @purpose: Primary purpose of the input context, as an #IBusInputPurpose. 486 * @hints: Hints that augment @purpose, as an #IBusInputHints. 487 * 488 * Set content-type (primary purpose and hints) of the context. This 489 * information is particularly useful to implement intelligent 490 * behavior in engines, such as automatic input-mode switch and text 491 * prediction. For example, to restrict input to numbers, the client 492 * can call this function with @purpose set to 493 * #IBUS_INPUT_PURPOSE_NUMBER. 494 * 495 * See also: #IBusEngine::set-content-type 496 */ 497 void ibus_input_context_set_content_type 498 (IBusInputContext *context, 499 guint purpose, 500 guint hints); 501 502 /** 503 * ibus_input_context_set_client_commit_preedit: 504 * @context: An #IBusInputContext. 505 * @client_commit: %TRUE if your input context commits pre-edit texts 506 * with Space or Enter key events or mouse click events. %FALSE if 507 * ibus-daemon commits pre-edit texts with those events. 508 * The default is %FALSE. The behavior is decided with 509 * ibus_engine_update_preedit_text_with_mode() to commit, clear or 510 * keep the pre-edit text and this API is important in ibus-hangul. 511 * 512 * Set whether #IBusInputContext commits pre-edit texts or not. 513 * If %TRUE, 'update-preedit-text-with-mode' signal is emitted 514 * instead of 'update-preedit-text' signal. 515 * If your client receives the 'update-preedit-text-with-mode' signal, 516 * the client needs to implement commit_text() of pre-edit text when 517 * GtkIMContextClass.focus_out() is called in case an IME desires that 518 * behavior but it depends on each IME. 519 * 520 * See also ibus_engine_update_preedit_text_with_mode(). 521 */ 522 void ibus_input_context_set_client_commit_preedit ( 523 IBusInputContext *context, 524 gboolean client_commit); 525 526 G_END_DECLS 527 #endif 528