2 * Copyright (c) 2003-2008 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of "Eclipse Public License v1.0""
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Predective text input engine API header
39 #include "PtiObserver.h"
40 #include "PtiLanguage.h"
42 // FORWARD DECLARATIONS
43 class CPtiUserDictionary;
44 class MPtiUserDictionary;
45 class MPtiEngineCompositionDataInterface;
46 class MPtiUserDictionaryEntry;
48 class MPtiHwrRecognizer;
53 * This is the main client side API for PtiEngine. The purpose of PtiEngine API is
54 * to provide a single calling point for low level (below UI) text input functionality.
55 * The API provides methods for querying and activating installed input languages, changing
56 * input modes and text cases and performing text input operations. The API contains
57 * set of methods for latin based, Chinese and Japanese text input. Some of the methods
58 * are common to all of those variants. PtiEngine also provides access to predictive
59 * text input functionality, in case there is need to use it directly without
60 * standard CEikEdwin / FEP chain (hence the name 'predictive text input engine')
61 * Predictive text engine integration is hidden behind PtiCore plugin API and is used
62 * through PtiEngine main API.
65 * PtiEngine is created by calling CPtiEngine::NewL method. In typical use case
66 * there is no need to pass core uid parameter to NewL method.
67 * Constructor will load and set up available core objects.
71 * Entering text in latin multitapping mode
72 * ----------------------------------------
74 * CPtiEngine* aEngine = CPtiEngine::NewL();
75 * aEngine->ActivateLanguageL(ELangEnglish, EPtiEngineMultitapping);
76 * aEngine->AppendKeyPress(EPtiKey3);
77 * aEngine->AppendKeyPress(EPtiKey6);
78 * aEngine->AppendKeyPress(EPtiKey6);
79 * aEngine->AppendKeyPress(EPtiKey6);
80 * aEngine->AppendKeyPress(EPtiKey4);
82 * temp.Copy(aEngine->CurrentWord()); // At this point temp would contain
85 * Entering text in latin predictive mode
86 * --------------------------------------
88 * CPtiEngine* aEngine = CPtiEngine::NewL();
89 * aEngine->ActivateLanguageL(ELangEnglish, EPtiEnginePredicitve);
90 * aEngine->AppendKeyPress(EPtiKey8);
91 * aEngine->AppendKeyPress(EPtiKey4);
92 * aEngine->AppendKeyPress(EPtiKey4);
93 * aEngine->AppendKeyPress(EPtiKey7);
95 * temp.Copy(aEngine->CurrentWord()); // At this point temp would contain
96 * // (depending on the underlying engine)
98 * temp.Copy(aEngine->NextCandidate()); // Move on to next candidate.
99 * aEngine->CommitCurrentWord(); // Tell engine that current word was accepted,
100 * // so that the underlyinbg engine keeps
101 * // frequency information up-to-date.
102 * Entering text in latin qwerty mode
103 * ----------------------------------
105 * CPtiEngine* aEngine = CPtiEngine::NewL();
106 * aEngine->ActivateLanguageL(ELangEnglish, EPtiEngineQwerty);
107 * aEngine->AppendKeyPress(EPtiKeyQwertyQ);
108 * aEngine->AppendKeyPress(EPtiKeyQwertyW);
109 * aEngine->AppendKeyPress(EPtiKeyQwertyE);
110 * aEngine->AppendKeyPress(EPtiKeyQwertyR);
111 * aEngine->AppendKeyPress(EPtiKeyQwertyT);
112 * aEngine->AppendKeyPress(EPtiKeyQwertyY);
114 * temp.Copy(aEngine->CurrentWord()); // At this point temp would contain
116 * // Next line requires that French key mappings are available in device.
117 * aEngine->ActivateLanguageL(ELangFrench, EPtiEngineQwerty);
118 * aEngine->SetCase(EPtiCaseUpper);
119 * aEngine->ClearCurrentWord();
120 * aEngine->AppendKeyPress(EPtiKeyQwertyQ);
121 * aEngine->AppendKeyPress(EPtiKeyQwertyW);
122 * aEngine->AppendKeyPress(EPtiKeyQwertyE);
123 * aEngine->AppendKeyPress(EPtiKeyQwertyR);
124 * aEngine->AppendKeyPress(EPtiKeyQwertyT);
125 * aEngine->AppendKeyPress(EPtiKeyQwertyY);
126 * temp.Copy(aEngine->CurrentWord()); // At this point temp would contain
129 * Entering text in preditcive latin qwerty mode
130 * ---------------------------------------------
131 * CPtiEngine* aEngine = CPtiEngine::NewL();
132 * aEngine->ActivateLanguageL(ELangEnglish, EPtiEngineQwertyPredictive);
133 * aEngine->AppendKeyPress(EPtiKeyQwertyE);
134 * aEngine->AppendKeyPress(EPtiKeyQwertyN);
135 * aEngine->AppendKeyPress(EPtiKeyQwertyT);
136 * aEngine->AppendKeyPress(EPtiKeyQwertyE);
137 * aEngine->AppendKeyPress(EPtiKeyQwertyR);
138 * aEngine->AppendKeyPress(EPtiKeyQwertyT);
139 * aEngine->AppendKeyPress(EPtiKeyQwertyA);
141 * temp.Copy(aEngine->CurrentWord()); // At this point temp would contain
142 * // for example word "entertainment", assuming the.
143 * // underlying prediction engine supports word completion.
146 NONSHARABLE_CLASS(CPtiEngine) : public CBase
150 * Two phase constructor.
152 * @param aUseDefaultUserDictionary
155 IMPORT_C static CPtiEngine* NewL(TBool aUseDefaultUserDictionary = EFalse);
158 * Two phase constructor.
160 * NOTE: THIS METHOD IS DEPRECATED AND WILL LEAVE WHEN CALLED.
162 IMPORT_C static CPtiEngine* NewL(const TDesC& aCoreName, TBool aUseDefaultUserDictionary = EFalse);
165 * Two phase constructor.
168 * @param aUseDefaultUserDictionary
171 IMPORT_C static CPtiEngine* NewL(const TUid aCoreUid, TBool aUseDefaultUserDictionary = EFalse);
176 IMPORT_C ~CPtiEngine();
179 * Activates language in requested input mode. After calling this method
180 * language is ready to be used with all input modes it supports.
183 * @param aEpocLanguageID Language to be activated.
184 * @param aMode Input mode after activation. If thise is left to default
185 * value, then default input mode is activated.
186 * @return KErrNone if success or system wide error code.
188 IMPORT_C TInt ActivateLanguageL(TInt aEpocLanguageID, TPtiEngineInputMode aMode = EPtiEngineInputModeNone);
191 * Closes active language. After calling this method there
192 * won't be active language and most PtiEngine API methods
193 * will return error until ActivateLanguageL is called again.
194 * Core objects for active language are asked to release
199 IMPORT_C void CloseCurrentLanguageL();
202 * Returns core info structure for given input mode.
205 * @return Pointer to core info object.
206 * NULL if core for given input mode was not found.
208 IMPORT_C MPtiCoreInfo* CoreInfo(TPtiEngineInputMode aMode) const;
211 * Returns pointer to currently active language.
214 * @return Pointer to currently active language object.
216 IMPORT_C MPtiLanguage* CurrentLanguage();
219 * Returns pointer to requested language.
222 * @param aCode Language code for requested language.
223 * @return Pointer to requested language object.
224 * NULL if no language for given code.
226 IMPORT_C MPtiLanguage* GetLanguage(TInt aCode) const;
229 * Returns number of candidate words for current
233 * @return number of cadidate words.
235 IMPORT_C TInt NumberOfCandidates();
238 * This method handles key press and forwards it to
239 * correct core object depending on active language and
240 * input mode. The current word buffer is updated accordingly.
241 * If input sequence buffer has reached its maximum length
242 * then nothing will be done.
245 * @param aKey Key code.
246 * @return Pointer to current word buffer.
248 IMPORT_C TPtrC AppendKeyPress(TPtiKey aKey);
251 * Deletes last character in current word buffer and updates
252 * candidate list accordingly.
255 * @return Pointer to current word buffer.
257 IMPORT_C TPtrC DeleteKeyPress();
260 * DEPRECATED (will leave if called).
262 IMPORT_C TInt AddCoreL(const TDesC& aFileName, TBool aUseDefaultUserDictionary = EFalse);
265 * Loads and constructs new core object. Core object is added
266 * to the list of available cores and is ready to be used
270 * @param aCoreUid Uid for core plugin.
271 * @param aUseDefaultUserDictionary ....
272 * @return KErrNone if operation was successful or system
275 IMPORT_C TInt AddCoreL(const TUid aCoreUid, TBool aUseDefaultUserDictionary = EFalse);
278 * Returns list of candidate words for current input sequence.
279 * If word completion feature is on, then words accepted to
280 * result list may contain more letters than the number
281 * of key presses in current input sequence.
284 * @param aList a list to be filled with candidate words.
285 * @return KErrNone if success, otherwise system wide error
288 IMPORT_C TInt GetCandidateListL(CDesCArray& aList);
291 * Returns next word candidate list. This method requires that
292 * current core object supports next word prediction feature
293 * and it is turned on.
296 * @param aList A List to be filled with next word cadidates.
297 * @return KErrNone if list was successfully filled.
298 * KErrNotSupported if current predictive core doesn't
299 * support next word prediction or
300 * the feature is not turned on.
302 IMPORT_C TInt GetNextWordCandidateListL(CDesCArray& aList);
305 * Returns pointer to first word in candidate list.
306 * If there isn't any candidate words the returned pointer
307 * will point to empty descriptor.
310 * @return Pointer to first word in candidate list.
312 IMPORT_C TPtrC FirstCandidate();
315 * Returns pointer to next word in candidate list.
316 * FirstCandidate() must be called before calling
317 * this method. Returns pointer to empty descriptor if there
318 * isn't more candidates available.
321 * @return Pointer to next word in candidate list.
323 IMPORT_C TPtrC NextCandidate();
326 * Returns pointer to previous word in candidate list.
327 * If there isn't previous candidate available
328 * (NextCandidate() wasn't succesfully called) then the
329 * return value will point to an empty string.
332 * @return Pointer to previous word in candidate list.
334 IMPORT_C TPtrC PreviousCandidate();
337 * Activates requested input mode for active language.
340 * @param aMode requested input mode.
341 * @return KErrNone if input mode was activated.
342 * KErrNotSupported if current language doesn't
343 * support requested input mode.
345 IMPORT_C TInt SetInputMode(TPtiEngineInputMode aMode);
348 * Returns active input mode.
351 * @return Current input mode.
353 IMPORT_C TPtiEngineInputMode InputMode() const;
356 * Turns reordering feature on or off. This method can be used only
357 * if active core object supports reordering feature.
358 * It is also possible that core object supports reordering feature,
359 * but it can't be turned off. Reordeing feature keeps track
360 * of usage frequency for entered words and promotes most frequently
361 * used words in the candidate list. Details depend on underlying
365 * @param aStatus New status for reordering feature.
366 * @return KErrNone if success, otherwise an error code.
368 IMPORT_C TInt SetReordering(TBool aStatus);
371 * Fills text buffer with given word, refreshes
372 * current input sequence and asks current core object
373 * to update candidate list accordingly.
376 * @param aWord a word to be set as current word.
377 * @return KErrNone if success, otherwise system wide error code.
379 IMPORT_C TInt SetCurrentWord(TPtrC aWord);
382 * Returns pointer to current word buffer.
385 * @return Pointer to current word buffer.
387 IMPORT_C TPtrC CurrentWord();
390 * Clears current word buffer. Calling this method means
391 * that current word was reject and will not be part of edited
392 * text. Either this method or CommitCurrentWord() must be called
393 * before starting a new word.
397 IMPORT_C void ClearCurrentWord();
403 * @param aCase Text case to be set. Possible values are:
405 * EPtiCaseLower Normal lower text case
406 * EPtiCaseUpper Normal capitalized text case
407 * EPtiCaseChrLower Lower text case when Chr key is being held
408 * EPtiCaseChrUpper Upper text case when Chr key is being held
409 * EPtiCaseFnLower Lower text case when Fn key is being held
410 * EPtiCaseFnUpper Upper text case when Fn key is being held
412 IMPORT_C void SetCase(TPtiTextCase aCase);
415 * Returns active text case.
418 * @return Current text case.
420 IMPORT_C TPtiTextCase Case() const;
423 * Returns list of available input languages.
426 * @param aResult List to be filled with language codes.
428 IMPORT_C void GetAvailableLanguagesL(CArrayFix<TInt>* aResult);
431 * Returns list of available input languages.
434 * @param aResult List to be filled with language codes.
436 IMPORT_C void GetAvailableLanguagesL(RArray<TInt>& aResult);
439 * Returns number of available input languages.
442 * @return Number of available languages.
444 IMPORT_C TInt NumberOfLanguages() const;
447 * Creates new user dictionary file, inserts given list of
448 * words into it and attaches it to active core
449 * object for requested input mode. Active language must
450 * support requested input mode.
453 * @param aFileName File name for new user dictionary.
454 * @param aWords A list of words to be inserted to new
456 * @param aMode Input mode for core object.
457 * @return KErrNone if success, otherwise system wide error
460 IMPORT_C TInt CreateUserDictionaryL(TDesC& aFileName, CDesCArrayFlat* aWords, TPtiEngineInputMode aMode);
463 * Attach user dictionary in given file to core for requested
467 * @param aFileName User dictionary file name.
468 * @return Pointer to user dictionary object. NULL if failure.
470 IMPORT_C MPtiUserDictionary* AttachUserDictionaryL(TDesC& aFileName);
473 * Attach default user dictionary.
476 * @param aCoreUid Uid for owner core object.
477 * @param aSymbolClass Symbol class for udb data.
478 * @return Pointer to user dictionary object. NULL if failure.
480 IMPORT_C MPtiUserDictionary* AttachDefaultUserDictionaryL(TUid aCoreUid, TInt aSymbolClass);
483 * Detaches currently attached user dictionary.
486 * @param aFileName User dictionary file name.
487 * @return KErrNone if success, otherwise system wide error code.
489 IMPORT_C TInt DetachUserDictionary(TDesC& aFileName);
492 * Detaches currently attached user dictionary.
495 * @param aId User dictionary id.
496 * @return KErrNone if success, otherwise system wide error code.
498 IMPORT_C TInt DetachUserDictionary(TInt aId);
501 * Returns localized language name for given language. This method
502 * is quite inefficient (always reads name table from resource file),
503 * when possible use Getlanguage()->LocalizedName() instead.
504 * This method can be used also when requested language is
505 * not among available input languages.
508 * @param Epoc language code.
509 * @return Localized language name.
511 IMPORT_C void GetLocalizedLanguageName(TInt aLangCode, TDes& aResult);
514 * Commits current word. Commiting means that core object is isntructed
515 * to end inline editing operation and accepted active word as part of edited
516 * text. Core object may then update frequency information, add unrecognized
517 * word to user dictioary or perform any other operation related to commiting a word.
518 * Word buffer is cleared. Either this method or ClearCurrentWord() must
519 * be called before starting a new word.
522 * @return KErrNone if success.
523 * KErrNoActiveLanguage if no active language.
525 IMPORT_C TInt CommitCurrentWord();
528 * Converts given string of characters to one coding
529 * system to another. See definition of TPtiCharConversion
530 * for list of supported conversion types. It is possible
531 * that only a small subset of supported conversion types
532 * is actually available at run time (that depends on
533 * available core objects). AvailableCharConversions()
534 * method can be used for querying available conversion
535 * types before using this method.
538 * @param aType Requested conversion type.
539 * @param aInput Input string. This parameter may point to
540 * either 8-bit or 16-bit data depending
541 * on conversion type.
542 * @param aInputLength Number of characters in input string.
543 * @param aOutput Output string. This parameter may pint to
544 * either 8-bit or 16-bit data depending
545 * on conversion type.
547 IMPORT_C TInt CharConversion(TPtiCharConversion aType,
553 * Returns value indicating currently available
554 * character conversions.
557 * @return Currently available character conversions. There
558 * is a bit set for each available char conversion.
559 * See definition of TPtiCharConversion.
561 IMPORT_C TUint32 AvailableCharConversions() const;
564 * Replaces key map for single key.
567 * @param aMode Input mode of key map.
568 * @param aKey Key to be replaced.
569 * @param aKeyMap New key sequence for aKey.
570 * @return KErrNone if success, otherwise system wide error code.
572 IMPORT_C TInt SetExternalKeyMapL(TPtiEngineInputMode aMode,
578 * Returns last entered key press.
581 * @return last entered key press.
583 IMPORT_C TPtiKey LastEnteredKey() const;
586 * Returns current input sequence (a list of key presses).
587 * Bytes in returned descriptor are TPtiKey enum values.
590 * @return a descriptor containing current input sequence.
592 IMPORT_C TPtrC8 CurrentInputSequence() const;
595 * Returns alternate spelling for given character.
598 * @param aInput a character to be converted to requested spelling.
599 * @param aOutput output will be stored to this descriptor.
600 * @param aType spelling type
601 * @return KErrNone if operation was successful,
602 * KErrNotSupported if requested spelling type is not supported.
604 IMPORT_C TInt GetSpelling(TUint16 aInput, TDes& aOutput, TPtiSpelling aType);
607 * Front end processeor uses this method for indicating
608 * PtiEngine that all key press related timers should be
612 * @return KErrNone if timers were successfully canceled.
613 * KErrNotFound if no active timers were found.
615 IMPORT_C TInt CancelTimerActivity();
618 * Returns key for given character. Returned key
619 * depends on current language and input mode.
622 * @param aChar Requested character.
623 * @return Key for requested character. EPtiKeyNone if
624 * no key was found for given character.
626 IMPORT_C TPtiKey CharacterToKey(TUint16 aChar);
629 * Adds new entry (in most cases a word) to default user dictionary of
630 * currently active core object.
633 * @param aEntry An entry to be added to dictionary.
634 * @return KErrNone if success, otherwise system wide error code.
636 IMPORT_C TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry);
639 * Adds entry to specific user dictionary.
642 * @param aEntry An entry to be added to dictionary.
643 * @param aId User dictionary id.
644 * @return KErrNone if success, otherwise system wide error code.
646 IMPORT_C TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, TInt aId);
649 * Removes entry from default user dictionary of currently active core
653 * @param aEntry an entry to be removed from default dictionary.
654 * @return KErrNone if success, otherwise system wide error code.
656 IMPORT_C TInt RemoveEntryFromUserDictionary(MPtiUserDictionaryEntry& aEntry);
659 * Removes word from specific user dictionary.
662 * @param aEntry an entry to be removed from default dictionary.
663 * @param aId User dictionary id.
664 * @return KErrNone if success, otherwise system wide error code.
666 IMPORT_C TInt RemoveEntryFromUserDictionary(MPtiUserDictionaryEntry& aEntry, TInt aId);
669 * Returns number of entries in default user dictionary.
672 * @return Number of entries in default user dictionary.
673 * KErrNotSupported if core can't return requested value.
675 IMPORT_C TInt NumberOfEntriesInUserDictionary();
678 * Returns entry for given index in default user dictionary.
681 * @param aIndex An index for requested entry.
682 * @param aResult Result will be stored here.
683 * @return KErrNone if success, otherwise system wide error code.
685 IMPORT_C TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult);
688 * Returns default user dictionary for given input mode.
691 * @return User dictionary for given input mode.
692 * NULL if wasn't found.
694 IMPORT_C MPtiUserDictionary* DefaultUserDictionary(TPtiEngineInputMode aMode);
697 * Sets observer. See PtiObserver.h for observer API details.
700 * @param aObserver A observer to be set.
702 IMPORT_C void SetObserver(MPtiObserver* aObserver);
705 * Returns current observer.
708 * @return Pointer to current observer object.
710 IMPORT_C MPtiObserver* Observer();
713 * General command handling method. This method can be used for
714 * controlling core objects that require more information than
715 * just sequence of key presses.
718 * @param aCommand A command to be handled.
719 * @param aParams Possible input data or parameters for command.
720 * @return KErrNone if success, otherwise an error code.
722 IMPORT_C TInt HandleCommandL(TPtiEngineCommand aCommand, TAny* aParams = NULL);
725 * Returns pointer to current Chinese candidate page.
728 * @return Pointer to current Chinese candidate page.
730 IMPORT_C TPtrC CandidatePage();
733 * Changes to next Chinese candidate page.
736 * @return ETrue if success.
737 * EFalse if there are no more candidate pages.
739 IMPORT_C TBool NextCandidatePage();
742 * Changes to previous Chinese candidate page.
745 * @return ETrue if success.
746 * EFalse if current candidate page is first.
748 IMPORT_C TBool PreviousCandidatePage();
751 * Returns a boolean value indicating whether there are more
752 * candidate pages available.
755 * @return ETrue if there are more candidate pages available.
758 IMPORT_C TBool MoreCandidatePages();
761 * Sets length of Chinese candidate page.
764 * @param aLength Length of Chinese candidate page.
766 IMPORT_C void SetCandidatePageLength(TInt aLength);
769 * Returns phonetic spelling for current input.
772 * @param aIndex Index of requested phonetic spelling.
773 * @return Pointer to phonetic spelling.
775 IMPORT_C TPtrC GetPhoneticSpelling(TInt aIndex) const;
778 * Returns a value specifying how many phonetic spellings
779 * there is available for current input.
782 * @return Number of phonetic spellings available for
785 IMPORT_C TInt PhoneticSpellingCount() const;
788 * Selects given phonetic spelling for current input.
791 * @param aIndex Index of requested phonetic spelling.
793 IMPORT_C TBool SelectPhoneticSpelling(TInt aIndex);
796 * Returns the index of currently selected phonetic spelling.
799 * @return The index of currently selected phonetic spelling.
800 * Returned value is negative if there isn't phonetic
801 * spelling available.
803 IMPORT_C TInt SelectedPhoneticSpelling() const;
806 * Enables or disables tone marks.
809 * @param aValue A boolean value specifying whether tone marks
812 IMPORT_C void EnableToneMarks(TBool aValue);
819 IMPORT_C void ResetToneMark();
822 * Returns unicode value for current tone mark.
825 * @param aToneMark resulting tone mark is store here.
826 * @return ETrue if tone mark was available.
829 IMPORT_C TBool ToneMark(TText& aToneMark) const;
832 * Returns boolean value indicating whether current tone mark
833 * is valid for spelling.
836 * @return ETrue if tone mark is valid for spelling.
839 IMPORT_C TBool IsToneMarkValidForSpelling() const;
842 * Cycles to next tone mark in core related tone mark list.
845 * @param aOverrideInvalid Indicates whether invalid tone marks
847 * @return ETrue If new tone mark was found and set.
850 IMPORT_C TBool IncrementToneMark(TBool aOverrideInvalid);
853 * Selects Chinese character (meaning that user has accepted character to be
854 * inserted into editor). Predictive candidate lists will be updated with
855 * Chinese characters associated to selected character. Associated charcaters
856 * can be accessed via ...CandidatePage() -methods. Return value can be
857 * ignored in current implementation.
860 * @param aChar A character to be selected.
861 * @return Please ignore the return value.
863 IMPORT_C TBool SetPredictiveChineseChar(const TDesC& aChar);
866 * Returns pointer to composition data interface (used with Japanese input).
869 * @return Pointer to composition data interface.
871 IMPORT_C MPtiEngineCompositionDataInterface* CompositionData();
874 * Returns reading text for Japanese input.
877 * @return Reading text for Japanese input.
879 IMPORT_C TPtrC ReadingTextL();
882 * Returns mode name index table for given Chinese variant.
885 * @param aVariant Chinese variant to be queried.
886 * @param aResult Resulting index table.
888 IMPORT_C void GetModeNameIndexL(TPtiChineseVariant aVariant, RArray<TInt>& aResult);
891 * Fills list with all the phonetic spellings for current
895 * @param aList A descriptor list to be filled with
896 * phonetic spellings. Any previous items in aList are cleared.
897 * @return Number of items in list.
899 IMPORT_C TInt GetPhoneticSpellingsL(CDesCArray& aList);
902 * Fills list with phrase candidates for currently
903 * selected phonetic spelling.
906 * @param aList A descriptor list to be filled with
907 * phrase candidates. Any previous items in aList are cleared.
908 * @return Number of items in list.
910 IMPORT_C TInt GetChinesePhraseCandidatesL(CDesCArray& aList);
913 * Sets tone mark directly. This method is used if client wants
914 * to override default core dependant tone mark set or traditional
915 * cycle-through tone mark system doesn't suit its porposes.
918 * @param aToneMark Tone mark to be set.
919 * @return ETrue if tone mark was legal, ie. produced candidates.
922 IMPORT_C TBool SetToneMark(TInt aToneMark);
925 * A convinience method for cheking qwerty based input mode.
928 * @param aMode Input mode to be checked.
929 * @return ETrue If aMode is qwerty based input mode.
932 IMPORT_C TBool IsQwertyBasedMode(TPtiEngineInputMode aMode) const;
935 * Creates empty user default dictionary file for given core object
936 * and initializes it to PtiEngine user dictionary format. If file already
937 * exists, then this method does nothing. Normally this method is
938 * only used by core objects.
941 * @param aCoreUid Uid for requesting core object.
942 * @param aSymbolClass Symbol class for udb data.
944 IMPORT_C void CreateDefaultUserDictionaryFileL(TUid aCoreUid, TInt aSymbolClass);
947 * Creates secondary data file for given core object. Existing file will be overwritten.
948 * This data file may contain any additional data that the core object needs to store
949 * between sessions (for example used word dictionary, if the engine keeps reordering data in
950 * separate memory area).
953 * @param aCoreUid Uid number for requesting core object.
954 * @param aIndexNumber Index number. Core object may use this parameter for numerating data files
955 * if it needs more than one of then. Otherwise zero.
957 IMPORT_C void WriteSecondaryDataFileL(TUid aCoreUid, TInt aIndexNumber, HBufC8* aData);
960 * Returns a heap buffer containing data from given secondary data file.
961 * Returns null if file is not found.
964 * @param aCoreUid Uid number for requesting core object.
965 * @param aIndexNumber Index number (see CreateDefaultUserDictionaryFileL).
966 * @return A heap buffer conataining requested data.
967 * NULL if file not found.
969 IMPORT_C HBufC8* ReadSecondaryDataFileL(TUid aCoreUid, TInt aIndexNumber);
972 * Returns keymapping data for given key. Returned data depends on active
973 * language and input mode. Result string will be empty if there isn't
974 * key mapping adta available.
977 * @param aKey A key to be queried.
978 * @param aResult Resulting mapping data.
980 IMPORT_C void MappingDataForKey(TPtiKey aKey, TDes& aResult, TPtiTextCase aCase);
983 * Qwerty input mode has different keymapping layout for each language. Therefore
984 * the characters for numeric input mode may be mapped to different keys depending
985 * on language. There are several situations where client application needs to know
986 * which key and case combination produce numeric characters for given language.
987 * This convinience method can be used for extracting that information easily
988 * (it is also possible to achieve same result directly via CPtiCoreLanguage object).
989 * Result array will be left empty if requested language is not available or it doesn't
990 * support qwerty input mode.
991 * Returned list includes key bindings for characters: "0123456789pw+#*"
992 * (Not necessarily in this order).
993 * See also ExtendedNumericModeKeysForQwertyL.
995 * This version first tries to return mappings according to currently
996 * active physical keyboard. It current keyboard is not qwerty based,
997 * it searches data for the first qwerty based keyboard type it can find.
998 * That is done in same order as keyboard types are defined in PtiDefs.h.
999 * There is also another version this method, which gets keyboard type as a
1003 * @param aLanguage Language id for requested mappings.
1004 * @param aResult Array for storing resulting mappings.
1006 IMPORT_C void GetNumericModeKeysForQwertyL(TInt aLanguage, RArray<TPtiNumericKeyBinding>& aResult);
1008 IMPORT_C HBufC* GetCandidatesByInputString(const TDesC& aInputString,
1009 RPointerArray<HBufC>& aList,
1010 const TBool aIsPredictive);
1012 * Get first hwr implementation support the specified language
1015 * @param aLanguage The language that hwr implementation supported
1016 * @return The pointer points to hwr implementation instance
1018 IMPORT_C MPtiHwrRecognizer* GetHwrRecognizerL(TLanguage aLanguage);
1021 * Get hwr implementation by give implementation uid
1024 * @param aImpId Given specific implementation uid
1025 * @return The pointer points to hwr implementation instance
1027 IMPORT_C MPtiHwrRecognizer* GetHwrRecognizerL(TInt aImpId);
1030 * Get hwr implementation uid list which support given language
1033 * @param aLanguage The language that hwr implementation supported
1034 * @return The array of implementation uid list
1036 IMPORT_C RArray<TUid>& ListHwrRecognizerL(TLanguage aLanguage);
1039 * Get hwr available languages list
1042 * @param aResult Carry the hwr available languages list on return
1045 IMPORT_C void GetHwrAvailableLanguagesL(RArray<TInt>& aResult);
1048 * Returns a list containing keyboard type values for all available
1049 * physical keyboards connected to the device. Keyboard doesn't have to be
1050 * active at calling time to be included in the output list.
1053 * @param aResult An array to be filled with available keyboard types.
1055 IMPORT_C static void ListAvailablePhysicalKeyboardsL(RArray<TPtiKeyboardType>& aResult);
1058 * This method is same as GetNumericModeKeysForQwertyL, expect that instead of returning
1059 * strict list of key bindings used in phone number editor, it returns list of all
1060 * possible characters used in any of the "number only" editor variations.
1061 * Returned list includes key bindings for characters: "*+pw#1234567890;.,-E?/"
1062 * (Not necessarily in this order).
1063 * See also GetNumericModeKeysForQwertyL.
1065 * This version first tries to return mappings according to currently
1066 * active physical keyboard. It current keyboard is not qwerty based,
1067 * it searches data for the first qwerty based keyboard type it can find.
1068 * That is done in same order as keyboard types are defined in PtiDefs.h.
1069 * There is also another version this method, which gets keyboard type as a
1073 * @param aLanguage Language id for requested mappings.
1074 * @param aResult Array for storing resulting mappings.
1076 IMPORT_C const RArray<TPtiNumericKeyBinding>& ExtendedNumericModeKeysForQwertyL(TInt aLanguage);
1079 * Turns auto substitution feature on or off. Auto substitution
1080 * feature replaces predefined strings with other strings. For example,
1081 * if user types xmas, it could be auto substituted with Christmas.
1084 * @param aStatus New status for auto substituiton feature
1085 * @return KErrNone or system wide error code.
1087 IMPORT_C TInt SetAutoSubstitution(TBool aStatus);
1090 * Adds new auto substitution entry to database. If entry for given shorcut
1091 * already exists, then the old entry will be automatically deleted.
1094 * @param aShortcut Shortcut part for new entry.
1095 * @param aSubstitution Substitution part for new entry.
1096 * @return KErrNone or system wide error code.
1098 IMPORT_C TInt AddAutoSubstitutionEntry(const TDesC& aShortcut,
1099 const TDesC& aSubstituition);
1102 * Remove auto substitution entry.
1105 * @param aShortcut Shortcut for auto substitution entry to be removed.
1106 * @return KErrNone or system wide error code.
1107 * KErrNotFound if given shortcut was nout found.
1109 IMPORT_C TInt DeleteAutoSubstitutionEntry(const TDesC& aShortcut);
1112 * Returns the number of auto substitution entries in auto subst db.
1115 * @return Number of entries in auto substitution db. Zero if the
1116 * feature is not supported or is not activated.
1118 IMPORT_C TInt NumberOfAutoSubstitutionEntries() const;
1121 * Return auto substitution entry for given index.
1124 * @param aIndex Index for entry to be returned.
1125 * @param aShortcut Shortcut part of the result entry will be stored here.
1126 * @param aSubstitution Substitution part of result entry will be stored here.
1127 * @return KErrNone or system wide error code.
1129 IMPORT_C TInt GetAutoSubstitutionEntry(TInt aIndex, TDes& aShortcut,
1130 TDes& aSubstitution);
1132 * Returns currently selected qwerty keyboard type.
1135 * @return Currently selected keyboard type.
1137 IMPORT_C TPtiKeyboardType KeyboardType() const;
1140 * Sets keyboard type for non-virtual keyboard. Keyboard type specifies which
1141 * set of key mapping data is used.
1144 * @param aType New keyboard type.
1145 * @return KErrNone if successful
1146 * KErrNotSupported if currently selected language/input mode combination
1147 * does not allow given keyboard type, or mapping
1148 * data doesn't contain block for it.
1150 IMPORT_C TInt SetKeyboardType(TPtiKeyboardType aType);
1153 * Lists keyboard blocks available in keymapping data for given language.
1156 * @param aLanguage A language to be queried.
1157 * @param aResult Resulting list of keyboard types will we stored here.
1159 IMPORT_C void KeyboardTypesSupportedByLanguageL(TInt aLanguage,
1160 RArray<TPtiKeyboardType>& aResult);
1162 * Same as previous version of GetNumericModeKeysForQwertyL (see description above) but
1163 * keyboard type is given as a parameter and mappings are return only for given keyboard
1167 * @param aLanguage Language id for requested mappings.
1168 * @param aResult Array for storing resulting mappings.
1169 * @param aKeyboardType keyboard type.
1171 IMPORT_C void GetNumericModeKeysForQwertyL(TInt aLanguage,
1172 RArray<TPtiNumericKeyBinding>& aResult,
1173 TPtiKeyboardType aKeyboardType);
1175 * Same as previous version of ExtendedNumericModeKeysForQwertyL (see description above), but
1176 * keyboard type is given as a parameter and mappings are return only for given keyboard
1180 * @param aLanguage Language id for requested mappings.
1181 * @param aKeyboardType keyboard type.
1182 * @param aResult Array for storing resulting mappings.
1184 IMPORT_C const RArray<TPtiNumericKeyBinding>& ExtendedNumericModeKeysForQwertyL(TInt aLanguage,
1185 TPtiKeyboardType aKeyboardType);
1188 * Sets a boolean value indicating whether number candidates are included to
1189 * predictive candidate list. Number candidates are strings containing only digits.
1190 * Number candidate feature must be supported by active prediction engine,
1191 * otherwise this setting will be ignored.
1194 * @param aStatus A boolean value indicating whether number candidates
1195 * are included to cadidate list.
1196 * @return KErrNone or a system wide error code.
1198 IMPORT_C TInt SetNumberCandidateStatus(TBool aStatus);
1201 * Returns a boolean value indicating whether given scan code is allowed for
1202 * current input mode.
1205 * @param aKey A key to be queried.
1206 * @return ETrue if given scan code is allowed fore currently active input mode.
1209 IMPORT_C TBool IsValidKey(TPtiKey aKey) const;
1212 * Sets the maximum length for auto completed words. This method can be used when the
1213 * client needs to be sure that all provided word completions will fit into remaining
1214 * editor buffer. When the number of key presses in an input sequence exceeds the value
1215 * given in aMaxLength, core will automatically reset this value to "no limit".
1218 * @param aMaxLength The maximum length fo auto completed candinates.
1219 * Value 0 means no limit.
1220 * @return KErrNone If the operation succeeded.
1221 * Otherwise system wide error code.
1223 IMPORT_C TInt SetMaxLengthForAutoCompletedCandidates(TInt aMaxLength);
1226 * Some core objects may provide different set of results depending on whether
1227 * the auto captitalization feature was used for entering the word or not. There is
1228 * now way to tell on core level whether the word was auto-capitalizedby FEP or
1229 * capitalized normally by the user. This method can be used to incicate
1230 * core object that auto-capitalization was used for current input sequence.
1231 * Clearing or commiting the word will cancel the effect of this method.
1235 IMPORT_C void MarkAutoCapitalized();
1238 * Returns text case buffer. Case buffer contains shift state
1239 * for each key press used for producing active word, ie. it remembers
1240 * case values for each AppendKeyPress call. Case buffer is
1241 * cleared when active word is commited or cleared. Return
1242 * value is TPtrC8 containing string of EPtiTextCase values.
1245 * @return A string of EPtiTextCase values.
1247 IMPORT_C TPtrC8 CaseSequence();
1250 * Some prediction engines support next word prediction feature but
1251 * require database to be pre-filled with suitable phrase data.
1252 * This method adds one new phrase or sentence to phrase dictionary.
1253 * Active core object needs to support phrase based next word prediction,
1254 * otherwise an error code is returned.
1257 * @param aNewPhrase New phrase to be added to phrase dictionary.
1258 * @return KErrNone or system wide error code.
1260 IMPORT_C TInt AddPhrase(const TDesC& aNewPhrase);
1262 #ifdef FF_DUAL_LANGUAGE_SUPPORT
1264 * Activates specified secondary input language in current input mode.
1267 * @param aEpocLanguageID Language to be activated.
1268 * @return KErrNone if success or system wide error code.
1270 IMPORT_C TInt SetSecondaryInputL(TInt aEpocLanguageID);
1271 #endif //FF_DUAL_LANGUAGE_SUPPORT
1274 void ConstructL(TBool aUseDefaultUserDictionary);
1275 void ConstructL(const TUid aCoreUid, TBool aUseDefaultUserDictionary);
1278 CPtiEngineImpl* iImpl;
1281 #endif _PTI_ENGINE_H