ism/src/scim_lookup_table.h

   1 /** @file scim_lookup_table.h
   2  * @brief definition of LookupTable classes.
   3  */
   4
   5 /* ISF is based on SCIM 1.4.7 and extended for supporting more mobile fitable. */
   6
   7 /*
   8  * Smart Common Input Method
   9  *
  10  * Copyright (c) 2002-2005 James Su <suzhe@tsinghua.org.cn>
  11  *
  12  *
  13  * This library is free software; you can redistribute it and/or
  14  * modify it under the terms of the GNU Lesser General Public
  15  * License as published by the Free Software Foundation; either
  16  * version 2 of the License, or (at your option) any later version.
  17  *
  18  * This library is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU Lesser General Public
  24  * License along with this program; if not, write to the
  25  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  26  * Boston, MA  02111-1307  USA
  27  *
  28  * $Id: scim_lookup_table.h,v 1.32 2005/05/13 04:21:29 suzhe Exp $
  29  */
  30
  31 #ifndef __SCIM_LOOKUP_TABLE_H
  32 #define __SCIM_LOOKUP_TABLE_H
  33
  34 namespace scim {
  35 /**
  36  * @addtogroup Accessories
  37  * @ingroup InputServiceFramework
  38  * @{
  39  */
  40
  41 #define SCIM_LOOKUP_TABLE_MAX_PAGESIZE  128
  42
  43 /**
  44  * @brief The base class of lookup table.
  45  *
  46  * LookupTable is used to store the candidate phrases, it provides a easy way
  47  * to manage the content of candidates and flip between multiple pages.
  48  *
  49  * It also can manage the attributes for each candidate string.
  50  *
  51  * This is abstract class and cannot store data.
  52  * IMEngine should use its derivation class.
  53  * This class is the interface that uses within FrontEnd class.
  54  */
  55 class LookupTable
  56 {
  57     class LookupTableImpl;
  58
  59     LookupTableImpl * m_impl;
  60
  61     LookupTable (const LookupTable &);
  62     const LookupTable & operator= (const LookupTable &);
  63
  64 public:
  65     /**
  66      * @brief Constructor
  67      * @param page_size - the maximum page size, can be set by set_page_size() later.
  68      */
  69     LookupTable (int page_size = 10);
  70
  71     /**
  72      * @brief Virtual destructor.
  73      */
  74     virtual ~LookupTable ();
  75
  76     /**
  77      * @brief Set the strings to label the candidates in one page.
  78      * @param labels - the strings to label the candidates in one page.
  79      */
  80     void set_candidate_labels (const std::vector<WideString> &labels);
  81
  82     /**
  83      * @brief Get the label string of a candidate in a page.
  84      * @param page_index - the index in a page, 0 to (max page size - 1).
  85      * @return the corresponding label of the index.
  86      */
  87     WideString get_candidate_label (int page_index) const;
  88
  89     /**
  90      * @brief Set the maximum page size.
  91      * @param page_size - the max page size of the table.
  92      */
  93     void set_page_size (int page_size);
  94
  95     /**
  96      * @brief Get the maximum page size.
  97      * @return the max page size of the table.
  98      */
  99     int get_page_size () const;
 100
 101     /**
 102      * @brief Get current page size,
 103      * @return the page size of current page.It can be less than the max page size.
 104      */
 105     int get_current_page_size () const;
 106
 107     /**
 108      * @brief Get the start index of current page.
 109      * @return the start item index of current page, starting from 0.
 110      */
 111     int get_current_page_start () const;
 112
 113     /**
 114      * @brief Check if the cursor is visible.
 115      * @return true if the cursor should be shown.
 116      */
 117     bool is_cursor_visible () const;
 118
 119     /**
 120      * @brief Check if the page size is fixed, aka. couldn't reduced by FrontEnd.
 121      * @return true if the page size shouldn't be reduced by FrontEnd.
 122      */
 123     bool is_page_size_fixed () const;
 124
 125     /**
 126      * @brief Get current cursor position.
 127      * @return the cursor position in the table, starting from 0.
 128      */
 129     int get_cursor_pos () const;
 130
 131     /**
 132      * @brief Get the cursor position in current page.
 133      * @return the cursor position in current page,
 134      *         equals to get_cursor_pos () - get_current_page_start ().
 135      */
 136     int get_cursor_pos_in_current_page () const;
 137
 138     /**
 139      * @brief Flip to the previous page.
 140      * @return true if success, false if it's already in the first page.
 141      */
 142     bool page_up ();
 143
 144     /**
 145      * @brief Flip to the next page.
 146      * @return true if success, false if it's already in the last page.
 147      */
 148     bool page_down ();
 149
 150     /**
 151      * @brief Move cursor position to the previous entry.
 152      * @return true if success, false if it's already at the first entry.
 153      */
 154     bool cursor_up ();
 155
 156     /**
 157      * @brief Move cursor position to the next entry.
 158      * @return true if success. false if it's already at the last entry.
 159      */
 160     bool cursor_down ();
 161
 162     /**
 163      * @brief Set the cursor visibility.
 164      * @param show - true to show the cursor.
 165      */
 166     void show_cursor (bool show=true);
 167
 168     /**
 169      * @brief Set the page size to be fixed, aka. prevent from being changed by FrontEnd.
 170      */
 171     void fix_page_size (bool fixed=true);
 172
 173     /**
 174      * @brief Set the cursor position.
 175      * @param pos - the absolute position of the cursor.
 176      */
 177     void set_cursor_pos (int pos);
 178
 179     /**
 180      * @brief Set the cursor position in current page.
 181      * @param pos - the relative position of the cursor in current page.
 182      */
 183     void set_cursor_pos_in_current_page (int pos);
 184
 185     /**
 186      * @brief Get a candidate in current page.
 187      *
 188      * @param page_index - the candidate index in current page.
 189      * @return the content of this candidate.
 190      *
 191      * @sa get_candidate
 192      */
 193     WideString get_candidate_in_current_page (int page_index) const;
 194
 195     /**
 196      * @brief Get the display attributes of a candidate in current page.
 197      *
 198      * @param page_index - the index in current page.
 199      * @return the AttributeList object holding the attributes of this candidate.
 200      *
 201      * @sa get_attributes
 202      */
 203     AttributeList get_attributes_in_current_page (int page_index) const;
 204
 205 public:
 206     /**
 207      * @name Pure Virtual functions.
 208      * These functions should be implemented in derivation classes.
 209      *
 210      * @{
 211      */
 212
 213     /**
 214      * @brief Get a candidate.
 215      * @param index - the candidate index in the lookup table.
 216      * @return the content of this candidate.
 217      */
 218     virtual WideString get_candidate (int index) const = 0;
 219
 220     /**
 221      * @brief Get the attributes of a candidate.
 222      * @param index - the index in the lookup table.
 223      * @return the AttributeList object holding the attributes of this candidate.
 224      */
 225     virtual AttributeList get_attributes (int index) const = 0;
 226
 227     /**
 228      * @brief Return the number of candidates in this table.
 229      * @return the number of entries currently in this table.
 230      */
 231     virtual uint32 number_of_candidates () const = 0;
 232
 233     /**
 234      * @brief Clear the table.
 235      */
 236     virtual void clear () = 0;
 237
 238     /**
 239      * @}
 240      */
 241 };
 242
 243
 244 /**
 245  * @brief A common lookup table class.
 246  *
 247  * This class implements the LookupTable interface in a common way.
 248  *
 249  */
 250 class CommonLookupTable : public LookupTable
 251 {
 252     class CommonLookupTableImpl;
 253
 254     CommonLookupTableImpl *m_impl;
 255
 256     CommonLookupTable (const CommonLookupTable &);
 257     const CommonLookupTable & operator= (const CommonLookupTable &);
 258
 259 public:
 260     CommonLookupTable (int page_size = 10);
 261
 262     /**
 263      * @brief Constructor
 264      *
 265      * @param page_size - the maximum page size, can be set by set_page_size () later.
 266      * @param labels - the strings to label the candidates in one page.
 267      */
 268     CommonLookupTable (int                            page_size,
 269                        const std::vector<WideString> &labels);
 270
 271     ~CommonLookupTable ();
 272
 273     virtual WideString get_candidate (int index) const;
 274
 275     virtual AttributeList get_attributes (int index) const;
 276
 277     virtual uint32 number_of_candidates () const;
 278
 279     virtual void clear ();
 280
 281 public:
 282     /**
 283      * @brief Append a candidate string into the table.
 284      *
 285      * @param cand  - a candidate string to be added into the table.
 286      * @param attrs - the attributes to control the display effect of this entry.
 287      *                It can be omitted if no attribute.
 288      *
 289      * @return true if success.
 290      */
 291     bool append_candidate (const WideString    &cand,
 292                            const AttributeList &attrs = AttributeList ());
 293
 294     /**
 295      * @brief Append a candidate char into the table.
 296      *
 297      * @param cand  - a candidate char to be added into the table.
 298      * @param attrs - the attributes to control the display effect of this entry.
 299      *                It can be omitted if no attribute.
 300      *
 301      * @return true if success.
 302      */
 303     bool append_candidate (ucs4_t               cand,
 304                            const AttributeList &attrs = AttributeList ());
 305 };
 306
 307 /** @} */
 308
 309 } // namespace scim
 310
 311 #endif //__SCIM_LOOKUP_TABLE_H
 312
 313 /*
 314 vi:ts=4:nowrap:ai:expandtab
 315 */