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