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
65G_BEGIN_DECLS
66
67typedef struct _IBusInputContext IBusInputContext;
68typedef struct _IBusInputContextClass IBusInputContextClass;
69
70/**
71 * IBusInputContext:
72 *
73 * An opaque data type representing an IBusInputContext.
74 */
75struct _IBusInputContext {
76 IBusProxy parent;
77 /* instance members */
78};
79
80struct _IBusInputContextClass {
81 IBusProxyClass parent;
82 /* signals */
83
84 /*< private >*/
85 /* padding */
86 gpointer pdummy[24];
87};
88
89GType 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 */
102IBusInputContext *
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 */
118void 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 */
134IBusInputContext *
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 */
147IBusInputContext *
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 */
162void 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 */
180IBusInputContext *
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 */
203void 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 */
217void 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 */
253void 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 */
276gboolean 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 */
295gboolean 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 */
314void 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 */
330void 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 */
347void 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 */
361void 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 */
375void 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 */
385void 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 */
396void 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 */
409void 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 */
428IBusEngineDesc *
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 */
443IBusEngineDesc *
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 */
454void 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*/
464void 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 */
479gboolean 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 */
497void 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 */
522void ibus_input_context_set_client_commit_preedit (
523 IBusInputContext *context,
524 gboolean client_commit);
525
526G_END_DECLS
527#endif
528