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