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