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