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_LOOKUP_TABLE_H_
28#define __IBUS_LOOKUP_TABLE_H_
29
30/**
31 * SECTION: ibuslookuptable
32 * @short_description: Candidate word/phrase lookup table.
33 * @stability: Stable
34 *
35 * An IBusLookuptable stores the candidate words or phrases for users to
36 * choose from.
37 *
38 * Use ibus_engine_update_lookup_table(), ibus_engine_show_lookup_table(),
39 * and ibus_engine_hide_lookup_table() to update, show and hide the lookup
40 * table.
41 *
42 * see_also: #IBusEngine
43 */
44
45#include "ibusserializable.h"
46#include "ibustext.h"
47
48/*
49 * Type macros.
50 */
51/* define IBusLookupTable macros */
52#define IBUS_TYPE_LOOKUP_TABLE \
53 (ibus_lookup_table_get_type ())
54#define IBUS_LOOKUP_TABLE(obj) \
55 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_LOOKUP_TABLE, IBusLookupTable))
56#define IBUS_LOOKUP_TABLE_CLASS(klass) \
57 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_LOOKUP_TABLE, IBusLookupTableClass))
58#define IBUS_IS_LOOKUP_TABLE(obj) \
59 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_LOOKUP_TABLE))
60#define IBUS_IS_LOOKUP_TABLE_CLASS(klass) \
61 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_LOOKUP_TABLE))
62#define IBUS_LOOKUP_TABLE_GET_CLASS(obj) \
63 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_LOOKUP_TABLE, IBusLookupTableClass))
64
65
66G_BEGIN_DECLS
67
68typedef struct _IBusLookupTable IBusLookupTable;
69typedef struct _IBusLookupTableClass IBusLookupTableClass;
70
71/**
72 * IBusLookupTable:
73 * @page_size: number of candidate shown per page.
74 * @cursor_pos: position index of cursor.
75 * @cursor_visible: whether the cursor is visible.
76 * @round: TRUE for lookup table wrap around.
77 * @orientation: orientation of the table.
78 * @candidates: Candidate words/phrases.
79 * @labels: Candidate labels which identify individual candidates in the same page. Default is 1, 2, 3, 4 ...
80 *
81 * An IBusLookuptable stores the candidate words or phrases for users to choose from.
82 * Note that some input methods allow you to select candidate by pressing non-numeric
83 * keys such as "asdfghjkl;".
84 * Developers of these input methods should change the labels with
85 * ibus_lookup_table_append_label().
86 */
87struct _IBusLookupTable {
88 IBusSerializable parent;
89
90 /*< public >*/
91 guint page_size;
92 guint cursor_pos;
93 gboolean cursor_visible;
94 gboolean round;
95 gint orientation;
96
97 GArray *candidates;
98 GArray *labels;
99};
100
101struct _IBusLookupTableClass {
102 IBusSerializableClass parent;
103};
104
105
106GType ibus_lookup_table_get_type (void);
107
108/**
109 * ibus_lookup_table_new:
110 * @page_size: number of candidate shown per page, the max value is 16.
111 * @cursor_pos: position index of cursor.
112 * @cursor_visible: whether the cursor is visible.
113 * @round: TRUE for lookup table wrap around.
114 *
115 * Craetes a new #IBusLookupTable.
116 *
117 * Returns: A newly allocated #IBusLookupTable.
118 */
119IBusLookupTable *ibus_lookup_table_new (guint page_size,
120 guint cursor_pos,
121 gboolean cursor_visible,
122 gboolean round);
123
124/**
125 * ibus_lookup_table_append_candidate:
126 * @table: An IBusLookupTable.
127 * @text: candidate word/phrase to be appended (in IBusText format).
128 *
129 * Append a candidate word/phrase to IBusLookupTable, and increase reference.
130 */
131void ibus_lookup_table_append_candidate
132 (IBusLookupTable *table,
133 IBusText *text);
134
135/**
136 * ibus_lookup_table_get_number_of_candidates:
137 * @table: An IBusLookupTable.
138 *
139 * Return the number of candidate in the table.
140 *
141 * Returns: The number of candidates in the table
142 */
143guint ibus_lookup_table_get_number_of_candidates
144 (IBusLookupTable *table);
145
146/**
147 * ibus_lookup_table_get_candidate:
148 * @table: An IBusLookupTable.
149 * @index: Index in the Lookup table.
150 *
151 * Return #IBusText at the given index. Borrowed reference.
152 *
153 * Returns: (transfer none): IBusText at the given index; NULL if no such
154 * #IBusText.
155 */
156IBusText *ibus_lookup_table_get_candidate
157 (IBusLookupTable *table,
158 guint index);
159
160/**
161 * ibus_lookup_table_append_label:
162 * @table: An IBusLookupTable.
163 * @text: A candidate label to be appended (in IBusText format).
164 *
165 * Append a candidate word/phrase to IBusLookupTable, and increase reference.
166 * This function is needed if the input method select candidate with
167 * non-numeric keys such as "asdfghjkl;".
168 */
169void ibus_lookup_table_append_label
170 (IBusLookupTable *table,
171 IBusText *text);
172
173/**
174 * ibus_lookup_table_set_label:
175 * @table: An IBusLookupTable.
176 * @index: Intex in the Lookup table.
177 * @text: A candidate label to be appended (in IBusText format).
178 *
179 * Append a candidate word/phrase to IBusLookupTable, and increase reference.
180 * This function is needed if the input method select candidate with
181 * non-numeric keys such as "asdfghjkl;".
182 */
183void ibus_lookup_table_set_label
184 (IBusLookupTable *table,
185 guint index,
186 IBusText *text);
187
188/**
189 * ibus_lookup_table_get_label:
190 * @table: An IBusLookupTable.
191 * @index: Index in the Lookup table.
192 *
193 * Return #IBusText at the given index. Borrowed reference.
194 *
195 * Returns: (transfer none): #IBusText at the given index; %NULL if no such
196 * #IBusText.
197 */
198IBusText *ibus_lookup_table_get_label
199 (IBusLookupTable *table,
200 guint index);
201
202
203/**
204 * ibus_lookup_table_set_cursor_pos:
205 * @table: An IBusLookupTable.
206 * @cursor_pos: The position of cursor.
207 *
208 * Set the cursor position of IBusLookupTable.
209 */
210void ibus_lookup_table_set_cursor_pos
211 (IBusLookupTable *table,
212 guint cursor_pos);
213
214/**
215 * ibus_lookup_table_get_cursor_pos:
216 * @table: An IBusLookupTable.
217 *
218 * Gets the cursor position of #IBusLookupTable.
219 *
220 * Returns: The position of cursor.
221 */
222guint ibus_lookup_table_get_cursor_pos
223 (IBusLookupTable *table);
224
225/**
226 * ibus_lookup_table_set_cursor_visible:
227 * @table: An IBusLookupTable.
228 * @visible: Whether to make the cursor of @table visible.
229 *
230 * Set whether to make the cursor of an IBusLookupTable visible or not.
231 */
232void ibus_lookup_table_set_cursor_visible
233 (IBusLookupTable *table,
234 gboolean visible);
235
236/**
237 * ibus_lookup_table_is_cursor_visible:
238 * @table: An #IBusLookupTable.
239 *
240 * Returns whether the cursor of an #IBusLookupTable is visible.
241 *
242 * Returns: Whether the cursor of @table is visible.
243 */
244gboolean ibus_lookup_table_is_cursor_visible
245 (IBusLookupTable *table);
246
247/**
248 * ibus_lookup_table_get_cursor_in_page:
249 * @table: An IBusLookupTable.
250 *
251 * Gets the cursor position in current page of #IBusLookupTable.
252 *
253 * Returns: The position of cursor in current page.
254 */
255guint ibus_lookup_table_get_cursor_in_page
256 (IBusLookupTable *table);
257
258/**
259 * ibus_lookup_table_set_page_size:
260 * @table: An IBusLookupTable.
261 * @page_size: number of candidate shown per page.
262 *
263 * Set the number of candidate shown per page.
264 */
265void ibus_lookup_table_set_page_size
266 (IBusLookupTable *table,
267 guint page_size);
268/**
269 * ibus_lookup_table_get_page_size:
270 * @table: An IBusLookupTable.
271 *
272 * Gets the number of candidate shown per page.
273 *
274 * Returns: Page size, i.e., number of candidate shown per page.
275dd
276 */
277guint ibus_lookup_table_get_page_size
278 (IBusLookupTable *table);
279
280/**
281 * ibus_lookup_table_set_round:
282 * @table: An IBusLookupTable.
283 * @round: Whether to make @table round.
284 *
285 * Set whether to make the IBusLookupTable round or not.
286 */
287void ibus_lookup_table_set_round
288 (IBusLookupTable *table,
289 gboolean round);
290/**
291 * ibus_lookup_table_is_round:
292 * @table: An IBusLookupTable.
293 *
294 * Returns whether the #IBusLookupTable is round.
295 *
296 * Returns: Whether the @table is round.
297 */
298gboolean ibus_lookup_table_is_round (IBusLookupTable *table);
299
300/**
301 * ibus_lookup_table_set_orientation:
302 * @table: An IBusLookupTable.
303 * @orientation: .
304 *
305 * Set the orientation.
306 */
307void ibus_lookup_table_set_orientation
308 (IBusLookupTable *table,
309 gint orientation);
310
311/**
312 * ibus_lookup_table_get_orientation:
313 * @table: An IBusLookupTable.
314 *
315 * Returns the orientation of the #IBusLookupTable.
316 *
317 * Returns: The orientation of the @table.
318 */
319gint ibus_lookup_table_get_orientation
320 (IBusLookupTable *table);
321
322
323/**
324 * ibus_lookup_table_clear:
325 * @table: An IBusLookupTable.
326 *
327 * Clear and remove all candidate from an IBusLookupTable.
328 */
329void ibus_lookup_table_clear (IBusLookupTable *table);
330
331/**
332 * ibus_lookup_table_page_up:
333 * @table: An IBusLookupTable.
334 *
335 * Go to previous page of an #IBusLookupTable.
336 *
337 * It returns FALSE if it is already at the first page,
338 * unless <code>table&gt;-round==TRUE</code>, where it will go
339 * to the last page.
340 *
341 * Returns: %TRUE if succeed.
342 */
343gboolean ibus_lookup_table_page_up (IBusLookupTable *table);
344
345/**
346 * ibus_lookup_table_page_down:
347 * @table: An IBusLookupTable.
348 *
349 * Go to next page of an #IBusLookupTable.
350 *
351 * It returns FALSE if it is already at the last page,
352 * unless <code>table&gt;-round==TRUE</code>, where it will go
353 * to the first page.
354 *
355 * Returns: %TRUE if succeed.
356 */
357gboolean ibus_lookup_table_page_down(IBusLookupTable *table);
358
359/**
360 * ibus_lookup_table_cursor_up:
361 * @table: An IBusLookupTable.
362 *
363 * Go to previous candidate of an #IBusLookupTable.
364 *
365 * It returns FALSE if it is already at the first candidate,
366 * unless <code>table&gt;-round==TRUE</code>, where it will go
367 * to the last candidate.
368 *
369 * Returns: %TRUE if succeed.
370 */
371gboolean ibus_lookup_table_cursor_up(IBusLookupTable *table);
372
373/**
374 * ibus_lookup_table_cursor_down:
375 * @table: An IBusLookupTable.
376 *
377 * Go to next candidate of an #IBusLookupTable.
378 *
379 * It returns FALSE if it is already at the last candidate,
380 * unless <code>table&gt;-round==TRUE</code>, where it will go
381 * to the first candidate.
382 *
383 * Returns: %TRUE if succeed.
384 */
385gboolean ibus_lookup_table_cursor_down
386 (IBusLookupTable *table);
387G_END_DECLS
388#endif
389
390