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 | |
32 | namespace 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 | */ |
52 | class LookupTable |
53 | { |
54 | class LookupTableImpl; |
55 | |
56 | LookupTableImpl * m_impl; |
57 | |
58 | LookupTable (const LookupTable &); |
59 | const LookupTable & operator= (const LookupTable &); |
60 | |
61 | public: |
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 | |
202 | public: |
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 | */ |
247 | class CommonLookupTable : public LookupTable |
248 | { |
249 | class CommonLookupTableImpl; |
250 | |
251 | CommonLookupTableImpl *m_impl; |
252 | |
253 | CommonLookupTable (const CommonLookupTable &); |
254 | const CommonLookupTable & operator= (const CommonLookupTable &); |
255 | |
256 | public: |
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 | |
278 | public: |
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 | /* |
311 | vi:ts=4:nowrap:ai:expandtab |
312 | */ |
313 | |