src/ibuslookuptable.h

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