1 /***************************************************************************
2  *   Copyright (C) 2011~2012 by CSSlayer                                   *
3  *   wengxt@gmail.com                                                      *
4  *                                                                         *
5  *   This program is free software; you can redistribute it and/or modify  *
6  *   it under the terms of the GNU General Public License as published by  *
7  *   the Free Software Foundation; either version 2 of the License, or     *
8  *   (at your option) any later version.                                   *
9  *                                                                         *
10  *   This program is distributed in the hope that it will be useful,       *
11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
13  *   GNU General Public License for more details.                          *
14  *                                                                         *
15  *   You should have received a copy of the GNU General Public License     *
16  *   along with this program; if not, write to the                         *
17  *   Free Software Foundation, Inc.,                                       *
18  *   51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.              *
19  ***************************************************************************/
20 
21 /**
22  * @addtogroup Fcitx
23  * @{
24  */
25 
26 /**
27  * @file candidate.h
28  *
29  * Fcitx candidate word list related definition and function
30  */
31 
32 #ifndef FCITX_CANDIDATE_H
33 #define FCITX_CANDIDATE_H
34 #include <fcitx-utils/utarray.h>
35 #include <fcitx-config/fcitx-config.h>
36 #include <fcitx/ime.h>
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 /** max candidate word number for single page */
43 #define MAX_CAND_WORD    10
44 
45     struct _FcitxCandidateWord;
46     struct _FcitxCandidateWordList;
47 
48     /**
49      * a hint to let the candidate list to show with specific layout
50      *
51      * it's only a soft hint for UI, it depends on UI implement it or not
52      *
53      * and it will be automatically reset to CLH_NotSet when Reset Candidate List
54      *
55      * @since 4.2.7
56      */
57     typedef enum _FcitxCandidateLayoutHint {
58         CLH_NotSet,
59         CLH_Vertical,
60         CLH_Horizontal
61     } FcitxCandidateLayoutHint;
62 
63     /** fcitx candidate workd list */
64     typedef struct _FcitxCandidateWordList FcitxCandidateWordList;
65 
66     /** callback for a single candidate word being chosen */
67     typedef INPUT_RETURN_VALUE(*FcitxCandidateWordCommitCallback)(void* arg, struct _FcitxCandidateWord* candWord);
68 
69     /**
70      * A Single Candidate Word
71      **/
72     typedef struct _FcitxCandidateWord {
73         /**
74          * String display in the front
75          **/
76         char* strWord;
77         /**
78          * String display after strWord
79          **/
80         char* strExtra;
81         /**
82          * Callback when string is going to commit
83          **/
84         FcitxCandidateWordCommitCallback callback;
85         /**
86          * Store the candidateWord Type
87          **/
88         FcitxMessageType wordType;
89         /**
90          * Store the extra Type
91          **/
92         FcitxMessageType extraType;
93         /**
94          * Pointer can identify where the candidatework come from
95          **/
96         void* owner;
97         /**
98          * Store a candidateWord Specific data, usually index of input method data
99          **/
100         void* priv;
101     } FcitxCandidateWord;
102 
103     /**
104      * Initialize a word list
105      *
106      * @return Word List
107      **/
108     struct _FcitxCandidateWordList* FcitxCandidateWordNewList();
109 
110     /**
111      * Free a word list
112      *
113      * @param list list to free
114      * @return void
115      */
116     void FcitxCandidateWordFreeList(struct _FcitxCandidateWordList* list);
117 
118     /**
119      * Insert a candidate to position
120      *
121      * @param candList candidate word list
122      * @param candWord candidate word
123      * @param position position to insert
124      * @return void
125      **/
126     void FcitxCandidateWordInsert(FcitxCandidateWordList* candList,
127                                   FcitxCandidateWord* candWord, int position);
128 
129     /**
130      * Merge newList into candList at a certain position
131      * (newList will be cleared)
132      *
133      * @param candList candidate words list
134      * @param newList candidate words list to be inserted
135      * @param position position to insert (less than 0 to append)
136      * @return void
137      *
138      * @since 4.2.6
139      **/
140     void FcitxCandidateWordMerge(FcitxCandidateWordList* candList,
141                                    FcitxCandidateWordList* newList,
142                                    int position);
143     /**
144      * Insert non-display place holder candidate to position
145      *
146      * @param candList candidate word list
147      * @param position position to insert
148      * @return void
149      **/
150     void FcitxCandidateWordInsertPlaceHolder(struct _FcitxCandidateWordList* candList, int position);
151 
152     /**
153      * move candidate word via shift policy, for example
154      * 1, 2, 3, move from 0 to 2, result is 2, 3, 1
155      * 1, 2, 3, move from 2 to 0, result is 3, 1, 2
156      *
157      * @param candList candidate word list
158      * @param from from position
159      * @param to to position
160      *
161      * @since 4.2.5
162      **/
163     void FcitxCandidateWordMove(FcitxCandidateWordList* candList, int from, int to);
164 
165     /**
166      * @param candList candidate word list
167      * @param from from position
168      * @param to to position
169      *
170      * @see FcitxCandidateWordMove
171      *
172      * @since 4.2.5
173      **/
174     void FcitxCandidateWordMoveByWord(FcitxCandidateWordList* candList, FcitxCandidateWord* candWord, int to);
175 
176     /**
177      * add a candidate word at last
178      *
179      * @param candList candidate word list
180      * @param candWord candidate word
181      * @return void
182      **/
183     void FcitxCandidateWordAppend(struct _FcitxCandidateWordList* candList, FcitxCandidateWord* candWord);
184 
185     /**
186      * remove a candidate word from list
187      *
188      * @param candList candidate word list
189      * @param candWord candidate word
190      * @return void
191      *
192      * @since 4.2
193      **/
194     void FcitxCandidateWordRemove(struct _FcitxCandidateWordList* candList, FcitxCandidateWord* candWord);
195 
196     /**
197      * remove a candidate word at certain index from list
198      *
199      * @param candList candidate word list
200      * @param idx index of the word to be removed
201      * @return void
202      *
203      * @since 4.2.6
204      **/
205     void FcitxCandidateWordRemoveByIndex(FcitxCandidateWordList *candList,
206                                          int idx);
207 
208     /**
209      * set page by index
210      *
211      * @param candList candidate word list
212      * @param index page index
213      * @return void
214      *
215      * @since 4.2.5
216      **/
217     void FcitxCandidateWordSetPage(struct _FcitxCandidateWordList* candList, int index);
218 
219     /**
220      * set page by word index
221      *
222      * @param candList candidate word list
223      * @param index index of candidate word
224      * @return void
225      *
226      * @since 4.2.1
227      **/
228     void FcitxCandidateWordSetFocus(struct _FcitxCandidateWordList* candList, int index);
229 
230     /**
231      * Get index of the first word on current page
232      *
233      * @param candList candidate word list
234      * @return int index of the current word
235      *
236      * @since 4.2.5
237      **/
238     int FcitxCandidateWordGetCurrentIndex(struct _FcitxCandidateWordList* candList);
239 
240     /**
241      * Get the first word on current page
242      *
243      * @param candList candidate word list
244      * @return FcitxCandidateWord* first candidate word of current page
245      **/
246     FcitxCandidateWord* FcitxCandidateWordGetCurrentWindow(struct _FcitxCandidateWordList* candList);
247 
248     /**
249      * get next word of current page, useful when you want to iteration over current candidate words
250      *
251      * @param candList candidate word list
252      * @param candWord current cand word
253      * @return FcitxCandidateWord* next cand word
254      **/
255     FcitxCandidateWord* FcitxCandidateWordGetCurrentWindowNext(struct _FcitxCandidateWordList* candList, FcitxCandidateWord* candWord);
256 
257     /**
258      * get prev word of current page, useful when you want to iteration over current candidate words
259      *
260      * @param candList candidate word list
261      * @param candWord current cand word
262      * @return FcitxCandidateWord* prev cand word
263      *
264      * @since 4.2.7
265      **/
266     FcitxCandidateWord* FcitxCandidateWordGetCurrentWindowPrev(struct _FcitxCandidateWordList* candList, FcitxCandidateWord* candWord);
267 
268     /**
269      * get candidate word by total index
270      *
271      * @param candList candidate word list
272      * @param index index of word
273      * @return FcitxCandidateWord*
274      *
275      * @since 4.2.5
276      **/
277     FcitxCandidateWord* FcitxCandidateWordGetByTotalIndex(struct _FcitxCandidateWordList* candList, int index);
278 
279     /**
280      * get the index of the candidate word
281      *
282      * @param candList candidate word list
283      * @param FcitxCandidateWord*
284      * @return index index of word
285      *
286      * @since 4.2.7
287      **/
288     int FcitxCandidateWordGetIndex(FcitxCandidateWordList *candList,
289                                    FcitxCandidateWord *word);
290     /**
291      * get candidate word by index within current page
292      *
293      * @param candList candidate word list
294      * @param index index of word on current page
295      * @return FcitxCandidateWord*
296      **/
297     FcitxCandidateWord* FcitxCandidateWordGetByIndex(struct _FcitxCandidateWordList* candList, int index);
298 
299     /**
300      * do the candidate word selection, will trigger the candidate word callback
301      *
302      * @param candList candidate word list
303      * @param index index of current page
304      * @return INPUT_RETURN_VALUE
305      **/
306     INPUT_RETURN_VALUE FcitxCandidateWordChooseByIndex(struct _FcitxCandidateWordList* candList, int index);
307 
308     /**
309      * do the candidate word selection, will trigger the candidate word callback
310      *
311      * @param candList candidate word list
312      * @param index index of current page
313      * @return INPUT_RETURN_VALUE
314      *
315      * @since 4.2.7
316      **/
317     INPUT_RETURN_VALUE FcitxCandidateWordChooseByTotalIndex(struct _FcitxCandidateWordList* candList, int index);
318 
319     /**
320      * Free a candidate word, used by utarray
321      *
322      * @param arg candidateWord
323      * @return void
324      **/
325     void FcitxCandidateWordFree(void* arg);
326 
327     /**
328      * check candidate word has next page or not
329      *
330      * @param candList candidate word list
331      * @return boolean
332      **/
333     boolean FcitxCandidateWordHasNext(struct _FcitxCandidateWordList* candList);
334 
335     /**
336      * check candidate word has prev page or not
337      *
338      * @param candList candidate word list
339      * @return boolean
340      **/
341     boolean FcitxCandidateWordHasPrev(struct _FcitxCandidateWordList* candList);
342 
343     /**
344      * get number of total page
345      *
346      * @param candList candidate word list
347      * @return int
348      **/
349     int FcitxCandidateWordPageCount(struct _FcitxCandidateWordList* candList);
350 
351     /**
352      * clear all candidate words
353      *
354      * @param candList candidate word list
355      * @return void
356      **/
357     void FcitxCandidateWordReset(struct _FcitxCandidateWordList* candList);
358 
359     /**
360      * go to prev page, return operation successful or not
361      *
362      * @param candList candidate word list
363      * @return boolean
364      **/
365     boolean FcitxCandidateWordGoPrevPage(struct _FcitxCandidateWordList* candList);
366 
367     /**
368      * go to next page, return operation successful or not
369      *
370      * @param candList candidate word list
371      * @return boolean
372      **/
373     boolean FcitxCandidateWordGoNextPage(struct _FcitxCandidateWordList* candList);
374 
375     /**
376      * set the select key string, length up to 10, usually "1234567890"
377      *
378      * @param candList candidate word list
379      * @param strChoose select key string
380      * @return void
381      **/
382     void FcitxCandidateWordSetChoose(struct _FcitxCandidateWordList* candList, const char* strChoose);
383 
384     /**
385      * set the select key string, length up to 10, usually "1234567890"
386      *
387      * @param candList candidate word list
388      * @param strChoose select key string
389      * @param state keystate
390      * @return void
391      **/
392     void FcitxCandidateWordSetChooseAndModifier(struct _FcitxCandidateWordList* candList, const char* strChoose, unsigned int state);
393 
394     /**
395      * get the select key string
396      *
397      * @param candList candidate word list
398      * @return const char* select key string
399      **/
400     const char* FcitxCandidateWordGetChoose(struct _FcitxCandidateWordList* candList);
401 
402 
403     /**
404      * get select key state
405      *
406      * @param candList candidate word list
407      * @return unsigned int
408      **/
409     unsigned int FcitxCandidateWordGetModifier(struct _FcitxCandidateWordList* candList);
410 
411     /**
412      * resize the candidate word length
413      *
414      * @param candList candidate word list
415      * @param length new length
416      * @return void
417      **/
418     void FcitxCandidateWordResize(struct _FcitxCandidateWordList* candList, int length);
419 
420     /**
421      * Get current page size of candidate list
422      *
423      * @param candList candidate word list
424      * @return int
425      **/
426     int FcitxCandidateWordGetPageSize(struct _FcitxCandidateWordList* candList);
427 
428     /**
429      * Set current page size of candidate list
430      *
431      * @param candList candidate word list
432      * @param size new page size
433      * @return void
434      **/
435     void FcitxCandidateWordSetPageSize(struct _FcitxCandidateWordList* candList, int size);
436 
437     /**
438      * get current page number
439      *
440      * @param candList candidate word list
441      * @return int
442      **/
443     int FcitxCandidateWordGetCurrentPage(struct _FcitxCandidateWordList* candList);
444 
445     /**
446      * get current page window size, may less than max page size
447      *
448      * @param candList candidate word list
449      * @return int
450      **/
451     int FcitxCandidateWordGetCurrentWindowSize(struct _FcitxCandidateWordList* candList);
452 
453     /**
454      * get total candidate word count
455      *
456      * @param candList candidate word list
457      * @return int
458      **/
459 
460     int FcitxCandidateWordGetListSize(struct _FcitxCandidateWordList* candList);
461 
462     /**
463      * check this have been goto prev page or not
464      *
465      * @param candList candidate word list
466      * @return boolean
467      */
468     boolean FcitxCandidateWordGetHasGoneToPrevPage(FcitxCandidateWordList* candList);
469 
470     /**
471      * check this have been goto next page or not
472      *
473      * @param candList candidate word list
474      * @return boolean
475      */
476     boolean FcitxCandidateWordGetHasGoneToNextPage(FcitxCandidateWordList* candList);
477 
478     /**
479      * get first candidate word
480      *
481      * @param candList candidate word list
482      * @return FcitxCandidateWord*
483      **/
484     FcitxCandidateWord *FcitxCandidateWordGetFirst(FcitxCandidateWordList *candList);
485 
486     /**
487      * get last candidate word
488      *
489      * @param candList candidate word list
490      * @return FcitxCandidateWord*
491      *
492      * @since 4.2.7
493      **/
494     FcitxCandidateWord *FcitxCandidateWordGetLast(FcitxCandidateWordList *candList);
495 
496     /**
497      * get next candidate word, useful when want to iterate over whole list
498      *
499      * @param candList candidate word list
500      * @param candWord current candidate word
501      * @return FcitxCandidateWord*
502      **/
503     FcitxCandidateWord* FcitxCandidateWordGetNext(FcitxCandidateWordList* candList, FcitxCandidateWord* candWord);
504 
505     /**
506      * get previous candidate word
507      *
508      * @param candList candidate word list
509      * @param candWord current candidate word
510      * @return FcitxCandidateWord*
511      *
512      * @since 4.2.7
513      **/
514     FcitxCandidateWord *FcitxCandidateWordGetPrev(FcitxCandidateWordList *candList, FcitxCandidateWord *candWord);
515 
516     /**
517      * check is choose key or not, if so, return the choose index
518      *
519      * @param candList candidate words
520      * @param sym keysym
521      * @param state keystate
522      * @return int
523      *
524      * @since 4.2.6
525      **/
526     int FcitxCandidateWordCheckChooseKey(FcitxCandidateWordList *candList,
527                                          FcitxKeySym sym, unsigned int state);
528 
529     /**
530      * Set Candidate word layout hint
531      *
532      * @param candList candidate words
533      * @param hint layout hint
534      * @return void
535      *
536      * @since 4.2.7
537      */
538     void FcitxCandidateWordSetLayoutHint(FcitxCandidateWordList* candList, FcitxCandidateLayoutHint hint);
539 
540     /**
541      * Get Candidate word layout hint
542      *
543      * @param candList candidate words
544      * @return layout hint
545      *
546      * @since 4.2.7
547      */
548     FcitxCandidateLayoutHint FcitxCandidateWordGetLayoutHint(FcitxCandidateWordList* candList);
549 
550     typedef boolean (*FcitxPaging)(void* arg, boolean prev);
551 
552     /**
553      * override default paging
554      *
555      * @param candList candidate words
556      * @param hasPrev has prev page
557      * @param hasNext has next page
558      * @param paging callback
559      * @param arg arg
560      * @param destroyNotify destroyNotify
561      * @return void
562      *
563      * @since 4.2.7
564      **/
565     void FcitxCandidateWordSetOverridePaging(FcitxCandidateWordList* candList,
566                                              boolean hasPrev,
567                                              boolean hasNext,
568                                              FcitxPaging paging,
569                                              void* arg,
570                                              FcitxDestroyNotify destroyNotify
571                                             );
572 
573     /**
574      * override default highlight
575      *
576      * @param candList candidate words
577      * @param overrideValue value
578      *
579      * @since 4.2.8
580      */
581     void FcitxCandidateWordSetOverrideDefaultHighlight(FcitxCandidateWordList* candList, boolean overrideValue);
582 
583 /** convinient string for candidate word */
584 #define DIGIT_STR_CHOOSE "1234567890"
585 
586     static inline void
FcitxCandidateWordSetType(FcitxCandidateWord * cand_word,FcitxMessageType type)587     FcitxCandidateWordSetType(FcitxCandidateWord *cand_word,
588                               FcitxMessageType type)
589     {
590         cand_word->wordType = (FcitxMessageType)((cand_word->wordType &
591                                                   ~MSG_REGULAR_MASK) | type);
592     }
593 
594     static inline boolean
FcitxCandidateWordCheckFocus(FcitxCandidateWord * cand_word,boolean clear)595     FcitxCandidateWordCheckFocus(FcitxCandidateWord *cand_word, boolean clear)
596     {
597         if ((cand_word->wordType & MSG_REGULAR_MASK) == MSG_CANDIATE_CURSOR) {
598             if (clear)
599                 FcitxCandidateWordSetType(cand_word, MSG_OTHER);
600             return true;
601         }
602         return false;
603     }
604 
605     FcitxCandidateWord *FcitxCandidateWordGetFocus(
606         FcitxCandidateWordList *cand_list, boolean clear);
607 
608 #ifdef __cplusplus
609 }
610 #endif
611 
612 #endif
613 /**
614  * @}
615  */
616 // kate: indent-mode cstyle; space-indent on; indent-width 0;
617