diff -r 000000000000 -r eb1f2e154e89 inputmethods_pub/ptiengine_iti_api/inc/PtiEngine.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inputmethods_pub/ptiengine_iti_api/inc/PtiEngine.h Tue Feb 02 01:02:04 2010 +0200 @@ -0,0 +1,1283 @@ +/* +* Copyright (c) 2003-2008 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0"" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Predective text input engine API header +* +*/ + + + + + + + + + + + + + + + +#ifndef _PTI_ENGINE_H +#define _PTI_ENGINE_H + +// INCLUDES +#include +#include +#include "PtiDefs.h" +#include "PtiObserver.h" +#include "PtiLanguage.h" + +// FORWARD DECLARATIONS +class CPtiUserDictionary; +class MPtiUserDictionary; +class MPtiEngineCompositionDataInterface; +class MPtiUserDictionaryEntry; +class CPtiEngineImpl; +class MPtiHwrRecognizer; + +/** +* CPtiEngine class. +* +* This is the main client side API for PtiEngine. The purpose of PtiEngine API is +* to provide a single calling point for low level (below UI) text input functionality. +* The API provides methods for querying and activating installed input languages, changing +* input modes and text cases and performing text input operations. The API contains +* set of methods for latin based, Chinese and Japanese text input. Some of the methods +* are common to all of those variants. PtiEngine also provides access to predictive +* text input functionality, in case there is need to use it directly without +* standard CEikEdwin / FEP chain (hence the name 'predictive text input engine') +* Predictive text engine integration is hidden behind PtiCore plugin API and is used +* through PtiEngine main API. +* +* Usage: +* PtiEngine is created by calling CPtiEngine::NewL method. In typical use case +* there is no need to pass core uid parameter to NewL method. +* Constructor will load and set up available core objects. +* +* Typical use cases: +* +* Entering text in latin multitapping mode +* ---------------------------------------- +* +* CPtiEngine* aEngine = CPtiEngine::NewL(); +* aEngine->ActivateLanguageL(ELangEnglish, EPtiEngineMultitapping); +* aEngine->AppendKeyPress(EPtiKey3); +* aEngine->AppendKeyPress(EPtiKey6); +* aEngine->AppendKeyPress(EPtiKey6); +* aEngine->AppendKeyPress(EPtiKey6); +* aEngine->AppendKeyPress(EPtiKey4); +* TBuf<100> temp; +* temp.Copy(aEngine->CurrentWord()); // At this point temp would contain +* // word "dog". +* +* Entering text in latin predictive mode +* -------------------------------------- +* +* CPtiEngine* aEngine = CPtiEngine::NewL(); +* aEngine->ActivateLanguageL(ELangEnglish, EPtiEnginePredicitve); +* aEngine->AppendKeyPress(EPtiKey8); +* aEngine->AppendKeyPress(EPtiKey4); +* aEngine->AppendKeyPress(EPtiKey4); +* aEngine->AppendKeyPress(EPtiKey7); +* TBuf<100> temp; +* temp.Copy(aEngine->CurrentWord()); // At this point temp would contain +* // (depending on the underlying engine) +* // word "this". +* temp.Copy(aEngine->NextCandidate()); // Move on to next candidate. +* aEngine->CommitCurrentWord(); // Tell engine that current word was accepted, +* // so that the underlyinbg engine keeps +* // frequency information up-to-date. +* Entering text in latin qwerty mode +* ---------------------------------- +* +* CPtiEngine* aEngine = CPtiEngine::NewL(); +* aEngine->ActivateLanguageL(ELangEnglish, EPtiEngineQwerty); +* aEngine->AppendKeyPress(EPtiKeyQwertyQ); +* aEngine->AppendKeyPress(EPtiKeyQwertyW); +* aEngine->AppendKeyPress(EPtiKeyQwertyE); +* aEngine->AppendKeyPress(EPtiKeyQwertyR); +* aEngine->AppendKeyPress(EPtiKeyQwertyT); +* aEngine->AppendKeyPress(EPtiKeyQwertyY); +* TBuf<100> temp; +* temp.Copy(aEngine->CurrentWord()); // At this point temp would contain +* // word "qwerty". +* // Next line requires that French key mappings are available in device. +* aEngine->ActivateLanguageL(ELangFrench, EPtiEngineQwerty); +* aEngine->SetCase(EPtiCaseUpper); +* aEngine->ClearCurrentWord(); +* aEngine->AppendKeyPress(EPtiKeyQwertyQ); +* aEngine->AppendKeyPress(EPtiKeyQwertyW); +* aEngine->AppendKeyPress(EPtiKeyQwertyE); +* aEngine->AppendKeyPress(EPtiKeyQwertyR); +* aEngine->AppendKeyPress(EPtiKeyQwertyT); +* aEngine->AppendKeyPress(EPtiKeyQwertyY); +* temp.Copy(aEngine->CurrentWord()); // At this point temp would contain +* // word "AZERTY". +* +* Entering text in preditcive latin qwerty mode +* --------------------------------------------- +* CPtiEngine* aEngine = CPtiEngine::NewL(); +* aEngine->ActivateLanguageL(ELangEnglish, EPtiEngineQwertyPredictive); +* aEngine->AppendKeyPress(EPtiKeyQwertyE); +* aEngine->AppendKeyPress(EPtiKeyQwertyN); +* aEngine->AppendKeyPress(EPtiKeyQwertyT); +* aEngine->AppendKeyPress(EPtiKeyQwertyE); +* aEngine->AppendKeyPress(EPtiKeyQwertyR); +* aEngine->AppendKeyPress(EPtiKeyQwertyT); +* aEngine->AppendKeyPress(EPtiKeyQwertyA); +* TBuf<100> temp; +* temp.Copy(aEngine->CurrentWord()); // At this point temp would contain +* // for example word "entertainment", assuming the. +* // underlying prediction engine supports word completion. +* +*/ +NONSHARABLE_CLASS(CPtiEngine) : public CBase + { + public: + /** + * Two phase constructor. + * + * @param aUseDefaultUserDictionary + * @return + */ + IMPORT_C static CPtiEngine* NewL(TBool aUseDefaultUserDictionary = EFalse); + + /** + * Two phase constructor. + * + * NOTE: THIS METHOD IS DEPRECATED AND WILL LEAVE WHEN CALLED. + */ + IMPORT_C static CPtiEngine* NewL(const TDesC& aCoreName, TBool aUseDefaultUserDictionary = EFalse); + + /** + * Two phase constructor. + * + * @param aCoreUid + * @param aUseDefaultUserDictionary + * @return + */ + IMPORT_C static CPtiEngine* NewL(const TUid aCoreUid, TBool aUseDefaultUserDictionary = EFalse); + + /** + * Destructor. + */ + IMPORT_C ~CPtiEngine(); + + /** + * Activates language in requested input mode. After calling this method + * language is ready to be used with all input modes it supports. + * + * @since S60 V2.6 + * @param aEpocLanguageID Language to be activated. + * @param aMode Input mode after activation. If thise is left to default + * value, then default input mode is activated. + * @return KErrNone if success or system wide error code. + */ + IMPORT_C TInt ActivateLanguageL(TInt aEpocLanguageID, TPtiEngineInputMode aMode = EPtiEngineInputModeNone); + + /** + * Closes active language. After calling this method there + * won't be active language and most PtiEngine API methods + * will return error until ActivateLanguageL is called again. + * Core objects for active language are asked to release + * related resources. + * + * @since S60 V2.6 + */ + IMPORT_C void CloseCurrentLanguageL(); + + /** + * Returns core info structure for given input mode. + * + * @since S60 V2.6 + * @return Pointer to core info object. + * NULL if core for given input mode was not found. + */ + IMPORT_C MPtiCoreInfo* CoreInfo(TPtiEngineInputMode aMode) const; + + /** + * Returns pointer to currently active language. + * + * @since S60 V2.6 + * @return Pointer to currently active language object. + */ + IMPORT_C MPtiLanguage* CurrentLanguage(); + + /** + * Returns pointer to requested language. + * + * @since S60 V2.6 + * @param aCode Language code for requested language. + * @return Pointer to requested language object. + * NULL if no language for given code. + */ + IMPORT_C MPtiLanguage* GetLanguage(TInt aCode) const; + + /** + * Returns number of candidate words for current + * input sequence. + * + * @since S60 V2.6 + * @return number of cadidate words. + */ + IMPORT_C TInt NumberOfCandidates(); + + /** + * This method handles key press and forwards it to + * correct core object depending on active language and + * input mode. The current word buffer is updated accordingly. + * If input sequence buffer has reached its maximum length + * then nothing will be done. + * + * @since S60 V2.6 + * @param aKey Key code. + * @return Pointer to current word buffer. + */ + IMPORT_C TPtrC AppendKeyPress(TPtiKey aKey); + + /** + * Deletes last character in current word buffer and updates + * candidate list accordingly. + * + * @since S60 V2.6 + * @return Pointer to current word buffer. + */ + IMPORT_C TPtrC DeleteKeyPress(); + + /** + * DEPRECATED (will leave if called). + */ + IMPORT_C TInt AddCoreL(const TDesC& aFileName, TBool aUseDefaultUserDictionary = EFalse); + + /** + * Loads and constructs new core object. Core object is added + * to the list of available cores and is ready to be used + * after that. + * + * @since S60 V2.6 + * @param aCoreUid Uid for core plugin. + * @param aUseDefaultUserDictionary .... + * @return KErrNone if operation was successful or system + * wide error code. + */ + IMPORT_C TInt AddCoreL(const TUid aCoreUid, TBool aUseDefaultUserDictionary = EFalse); + + /** + * Returns list of candidate words for current input sequence. + * If word completion feature is on, then words accepted to + * result list may contain more letters than the number + * of key presses in current input sequence. + * + * @since S60 V2.6 + * @param aList a list to be filled with candidate words. + * @return KErrNone if success, otherwise system wide error + * code. + */ + IMPORT_C TInt GetCandidateListL(CDesCArray& aList); + + /** + * Returns next word candidate list. This method requires that + * current core object supports next word prediction feature + * and it is turned on. + * + * @since S60 V2.6 + * @param aList A List to be filled with next word cadidates. + * @return KErrNone if list was successfully filled. + * KErrNotSupported if current predictive core doesn't + * support next word prediction or + * the feature is not turned on. + */ + IMPORT_C TInt GetNextWordCandidateListL(CDesCArray& aList); + + /** + * Returns pointer to first word in candidate list. + * If there isn't any candidate words the returned pointer + * will point to empty descriptor. + * + * @since S60 V2.6 + * @return Pointer to first word in candidate list. + */ + IMPORT_C TPtrC FirstCandidate(); + + /** + * Returns pointer to next word in candidate list. + * FirstCandidate() must be called before calling + * this method. Returns pointer to empty descriptor if there + * isn't more candidates available. + * + * @since S60 V2.6 + * @return Pointer to next word in candidate list. + */ + IMPORT_C TPtrC NextCandidate(); + + /** + * Returns pointer to previous word in candidate list. + * If there isn't previous candidate available + * (NextCandidate() wasn't succesfully called) then the + * return value will point to an empty string. + * + * @since S60 V2.6 + * @return Pointer to previous word in candidate list. + */ + IMPORT_C TPtrC PreviousCandidate(); + + /** + * Activates requested input mode for active language. + * + * @since S60 V2.6 + * @param aMode requested input mode. + * @return KErrNone if input mode was activated. + * KErrNotSupported if current language doesn't + * support requested input mode. + */ + IMPORT_C TInt SetInputMode(TPtiEngineInputMode aMode); + + /** + * Returns active input mode. + * + * @since S60 V2.6 + * @return Current input mode. + */ + IMPORT_C TPtiEngineInputMode InputMode() const; + + /** + * Turns reordering feature on or off. This method can be used only + * if active core object supports reordering feature. + * It is also possible that core object supports reordering feature, + * but it can't be turned off. Reordeing feature keeps track + * of usage frequency for entered words and promotes most frequently + * used words in the candidate list. Details depend on underlying + * prediction engine. + * + * @since S60 V2.6 + * @param aStatus New status for reordering feature. + * @return KErrNone if success, otherwise an error code. + */ + IMPORT_C TInt SetReordering(TBool aStatus); + + /** + * Fills text buffer with given word, refreshes + * current input sequence and asks current core object + * to update candidate list accordingly. + * + * @since S60 V2.6 + * @param aWord a word to be set as current word. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt SetCurrentWord(TPtrC aWord); + + /** + * Returns pointer to current word buffer. + * + * @since S60 V2.6 + * @return Pointer to current word buffer. + */ + IMPORT_C TPtrC CurrentWord(); + + /** + * Clears current word buffer. Calling this method means + * that current word was reject and will not be part of edited + * text. Either this method or CommitCurrentWord() must be called + * before starting a new word. + * + * @since S60 V2.6 + */ + IMPORT_C void ClearCurrentWord(); + + /** + * Sets text case. + * + * @since S60 V2.6 + * @param aCase Text case to be set. Possible values are: + * + * EPtiCaseLower Normal lower text case + * EPtiCaseUpper Normal capitalized text case + * EPtiCaseChrLower Lower text case when Chr key is being held + * EPtiCaseChrUpper Upper text case when Chr key is being held + * EPtiCaseFnLower Lower text case when Fn key is being held + * EPtiCaseFnUpper Upper text case when Fn key is being held + */ + IMPORT_C void SetCase(TPtiTextCase aCase); + + /** + * Returns active text case. + * + * @since S60 V2.6 + * @return Current text case. + */ + IMPORT_C TPtiTextCase Case() const; + + /** + * Returns list of available input languages. + * + * @since S60 V2.6 + * @param aResult List to be filled with language codes. + */ + IMPORT_C void GetAvailableLanguagesL(CArrayFix* aResult); + + /** + * Returns list of available input languages. + * + * @since S60 V2.6 + * @param aResult List to be filled with language codes. + */ + IMPORT_C void GetAvailableLanguagesL(RArray& aResult); + + /** + * Returns number of available input languages. + * + * @since S60 V2.6 + * @return Number of available languages. + */ + IMPORT_C TInt NumberOfLanguages() const; + + /** + * Creates new user dictionary file, inserts given list of + * words into it and attaches it to active core + * object for requested input mode. Active language must + * support requested input mode. + * + * @since S60 V2.6 + * @param aFileName File name for new user dictionary. + * @param aWords A list of words to be inserted to new + * user dictionary. + * @param aMode Input mode for core object. + * @return KErrNone if success, otherwise system wide error + * code. + */ + IMPORT_C TInt CreateUserDictionaryL(TDesC& aFileName, CDesCArrayFlat* aWords, TPtiEngineInputMode aMode); + + /** + * Attach user dictionary in given file to core for requested + * input mode. + * + * @since S60 V2.6 + * @param aFileName User dictionary file name. + * @return Pointer to user dictionary object. NULL if failure. + */ + IMPORT_C MPtiUserDictionary* AttachUserDictionaryL(TDesC& aFileName); + + /** + * Attach default user dictionary. + * + * @since S60 V2.6 + * @param aCoreUid Uid for owner core object. + * @param aSymbolClass Symbol class for udb data. + * @return Pointer to user dictionary object. NULL if failure. + */ + IMPORT_C MPtiUserDictionary* AttachDefaultUserDictionaryL(TUid aCoreUid, TInt aSymbolClass); + + /** + * Detaches currently attached user dictionary. + * + * @since S60 V2.6 + * @param aFileName User dictionary file name. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt DetachUserDictionary(TDesC& aFileName); + + /** + * Detaches currently attached user dictionary. + * + * @since S60 V2.6 + * @param aId User dictionary id. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt DetachUserDictionary(TInt aId); + + /** + * Returns localized language name for given language. This method + * is quite inefficient (always reads name table from resource file), + * when possible use Getlanguage()->LocalizedName() instead. + * This method can be used also when requested language is + * not among available input languages. + * + * @since S60 V2.6 + * @param Epoc language code. + * @return Localized language name. + */ + IMPORT_C void GetLocalizedLanguageName(TInt aLangCode, TDes& aResult); + + /** + * Commits current word. Commiting means that core object is isntructed + * to end inline editing operation and accepted active word as part of edited + * text. Core object may then update frequency information, add unrecognized + * word to user dictioary or perform any other operation related to commiting a word. + * Word buffer is cleared. Either this method or ClearCurrentWord() must + * be called before starting a new word. + * + * @since S60 V2.6 + * @return KErrNone if success. + * KErrNoActiveLanguage if no active language. + */ + IMPORT_C TInt CommitCurrentWord(); + + /** + * Converts given string of characters to one coding + * system to another. See definition of TPtiCharConversion + * for list of supported conversion types. It is possible + * that only a small subset of supported conversion types + * is actually available at run time (that depends on + * available core objects). AvailableCharConversions() + * method can be used for querying available conversion + * types before using this method. + * + * @since S60 V2.6 + * @param aType Requested conversion type. + * @param aInput Input string. This parameter may point to + * either 8-bit or 16-bit data depending + * on conversion type. + * @param aInputLength Number of characters in input string. + * @param aOutput Output string. This parameter may pint to + * either 8-bit or 16-bit data depending + * on conversion type. + */ + IMPORT_C TInt CharConversion(TPtiCharConversion aType, + TAny* aInput, + TInt aInputLength, + TAny* aOutput); + + /** + * Returns value indicating currently available + * character conversions. + * + * @since S60 V2.6 + * @return Currently available character conversions. There + * is a bit set for each available char conversion. + * See definition of TPtiCharConversion. + */ + IMPORT_C TUint32 AvailableCharConversions() const; + + /** + * Replaces key map for single key. + * + * @since S60 V2.6 + * @param aMode Input mode of key map. + * @param aKey Key to be replaced. + * @param aKeyMap New key sequence for aKey. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt SetExternalKeyMapL(TPtiEngineInputMode aMode, + TPtiKey aKey, + TDesC& aKeyMap, + TPtiTextCase aCase); + + /** + * Returns last entered key press. + * + * @since S60 V2.6 + * @return last entered key press. + */ + IMPORT_C TPtiKey LastEnteredKey() const; + + /** + * Returns current input sequence (a list of key presses). + * Bytes in returned descriptor are TPtiKey enum values. + * + * @since S60 V2.6 + * @return a descriptor containing current input sequence. + */ + IMPORT_C TPtrC8 CurrentInputSequence() const; + + /** + * Returns alternate spelling for given character. + * + * @since S60 V2.6 + * @param aInput a character to be converted to requested spelling. + * @param aOutput output will be stored to this descriptor. + * @param aType spelling type + * @return KErrNone if operation was successful, + * KErrNotSupported if requested spelling type is not supported. + */ + IMPORT_C TInt GetSpelling(TUint16 aInput, TDes& aOutput, TPtiSpelling aType); + + /** + * Front end processeor uses this method for indicating + * PtiEngine that all key press related timers should be + * canceled. + * + * @since S60 V2.6 + * @return KErrNone if timers were successfully canceled. + * KErrNotFound if no active timers were found. + */ + IMPORT_C TInt CancelTimerActivity(); + + /** + * Returns key for given character. Returned key + * depends on current language and input mode. + * + * @since S60 V2.6 + * @param aChar Requested character. + * @return Key for requested character. EPtiKeyNone if + * no key was found for given character. + */ + IMPORT_C TPtiKey CharacterToKey(TUint16 aChar); + + /** + * Adds new entry (in most cases a word) to default user dictionary of + * currently active core object. + * + * @since S60 V2.6 + * @param aEntry An entry to be added to dictionary. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry); + + /** + * Adds entry to specific user dictionary. + * + * @since S60 V2.6 + * @param aEntry An entry to be added to dictionary. + * @param aId User dictionary id. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, TInt aId); + + /** + * Removes entry from default user dictionary of currently active core + * object. + * + * @since S60 V2.6 + * @param aEntry an entry to be removed from default dictionary. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt RemoveEntryFromUserDictionary(MPtiUserDictionaryEntry& aEntry); + + /** + * Removes word from specific user dictionary. + * + * @since S60 V2.6 + * @param aEntry an entry to be removed from default dictionary. + * @param aId User dictionary id. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt RemoveEntryFromUserDictionary(MPtiUserDictionaryEntry& aEntry, TInt aId); + + /** + * Returns number of entries in default user dictionary. + * + * @since S60 V2.6 + * @return Number of entries in default user dictionary. + * KErrNotSupported if core can't return requested value. + */ + IMPORT_C TInt NumberOfEntriesInUserDictionary(); + + /** + * Returns entry for given index in default user dictionary. + * + * @since S60 V2.6 + * @param aIndex An index for requested entry. + * @param aResult Result will be stored here. + * @return KErrNone if success, otherwise system wide error code. + */ + IMPORT_C TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult); + + /** + * Returns default user dictionary for given input mode. + * + * @since S60 V2.6 + * @return User dictionary for given input mode. + * NULL if wasn't found. + */ + IMPORT_C MPtiUserDictionary* DefaultUserDictionary(TPtiEngineInputMode aMode); + + /** + * Sets observer. See PtiObserver.h for observer API details. + * + * @since S60 V2.6 + * @param aObserver A observer to be set. + */ + IMPORT_C void SetObserver(MPtiObserver* aObserver); + + /** + * Returns current observer. + * + * @since S60 V2.6 + * @return Pointer to current observer object. + */ + IMPORT_C MPtiObserver* Observer(); + + /** + * General command handling method. This method can be used for + * controlling core objects that require more information than + * just sequence of key presses. + * + * @since S60 V2.6 + * @param aCommand A command to be handled. + * @param aParams Possible input data or parameters for command. + * @return KErrNone if success, otherwise an error code. + */ + IMPORT_C TInt HandleCommandL(TPtiEngineCommand aCommand, TAny* aParams = NULL); + + /** + * Returns pointer to current Chinese candidate page. + * + * @since S60 V2.6 + * @return Pointer to current Chinese candidate page. + */ + IMPORT_C TPtrC CandidatePage(); + + /** + * Changes to next Chinese candidate page. + * + * @since S60 V2.6 + * @return ETrue if success. + * EFalse if there are no more candidate pages. + */ + IMPORT_C TBool NextCandidatePage(); + + /** + * Changes to previous Chinese candidate page. + * + * @since S60 V2.6 + * @return ETrue if success. + * EFalse if current candidate page is first. + */ + IMPORT_C TBool PreviousCandidatePage(); + + /** + * Returns a boolean value indicating whether there are more + * candidate pages available. + * + * @since S60 V2.6 + * @return ETrue if there are more candidate pages available. + * EFalse otherwise. + */ + IMPORT_C TBool MoreCandidatePages(); + + /** + * Sets length of Chinese candidate page. + * + * @since S60 V2.6 + * @param aLength Length of Chinese candidate page. + */ + IMPORT_C void SetCandidatePageLength(TInt aLength); + + /** + * Returns phonetic spelling for current input. + * + * @since S60 V2.6 + * @param aIndex Index of requested phonetic spelling. + * @return Pointer to phonetic spelling. + */ + IMPORT_C TPtrC GetPhoneticSpelling(TInt aIndex) const; + + /** + * Returns a value specifying how many phonetic spellings + * there is available for current input. + * + * @since S60 V2.6 + * @return Number of phonetic spellings available for + * current input. + */ + IMPORT_C TInt PhoneticSpellingCount() const; + + /** + * Selects given phonetic spelling for current input. + * + * @since S60 V2.6 + * @param aIndex Index of requested phonetic spelling. + */ + IMPORT_C TBool SelectPhoneticSpelling(TInt aIndex); + + /** + * Returns the index of currently selected phonetic spelling. + * + * @since S60 V2.6 + * @return The index of currently selected phonetic spelling. + * Returned value is negative if there isn't phonetic + * spelling available. + */ + IMPORT_C TInt SelectedPhoneticSpelling() const; + + /** + * Enables or disables tone marks. + * + * @since S60 V2.6 + * @param aValue A boolean value specifying whether tone marks + * will be on or off. + */ + IMPORT_C void EnableToneMarks(TBool aValue); + + /** + * Resets tone mark. + * + * @since S60 V2.6 + */ + IMPORT_C void ResetToneMark(); + + /** + * Returns unicode value for current tone mark. + * + * @since S60 V2.6 + * @param aToneMark resulting tone mark is store here. + * @return ETrue if tone mark was available. + * EFalse otherwise. + */ + IMPORT_C TBool ToneMark(TText& aToneMark) const; + + /** + * Returns boolean value indicating whether current tone mark + * is valid for spelling. + * + * @since S60 V2.6 + * @return ETrue if tone mark is valid for spelling. + * EFalse otherwise + */ + IMPORT_C TBool IsToneMarkValidForSpelling() const; + + /** + * Cycles to next tone mark in core related tone mark list. + * + * @since S60 V2.6 + * @param aOverrideInvalid Indicates whether invalid tone marks + * should be skipped. + * @return ETrue If new tone mark was found and set. + * EFalse Otherwise. + */ + IMPORT_C TBool IncrementToneMark(TBool aOverrideInvalid); + + /** + * Selects Chinese character (meaning that user has accepted character to be + * inserted into editor). Predictive candidate lists will be updated with + * Chinese characters associated to selected character. Associated charcaters + * can be accessed via ...CandidatePage() -methods. Return value can be + * ignored in current implementation. + * + * @since S60 V2.6 + * @param aChar A character to be selected. + * @return Please ignore the return value. + */ + IMPORT_C TBool SetPredictiveChineseChar(const TDesC& aChar); + + /** + * Returns pointer to composition data interface (used with Japanese input). + * + * @since S60 V2.6 + * @return Pointer to composition data interface. + */ + IMPORT_C MPtiEngineCompositionDataInterface* CompositionData(); + + /** + * Returns reading text for Japanese input. + * + * @since S60 V2.6 + * @return Reading text for Japanese input. + */ + IMPORT_C TPtrC ReadingTextL(); + + /** + * Returns mode name index table for given Chinese variant. + * + * @since S60 V2.6 + * @param aVariant Chinese variant to be queried. + * @param aResult Resulting index table. + */ + IMPORT_C void GetModeNameIndexL(TPtiChineseVariant aVariant, RArray& aResult); + + /** + * Fills list with all the phonetic spellings for current + * input sequence. + * + * @since S60 V2.6 + * @param aList A descriptor list to be filled with + * phonetic spellings. Any previous items in aList are cleared. + * @return Number of items in list. + */ + IMPORT_C TInt GetPhoneticSpellingsL(CDesCArray& aList); + + /** + * Fills list with phrase candidates for currently + * selected phonetic spelling. + * + * @since S60 V2.6 + * @param aList A descriptor list to be filled with + * phrase candidates. Any previous items in aList are cleared. + * @return Number of items in list. + */ + IMPORT_C TInt GetChinesePhraseCandidatesL(CDesCArray& aList); + + /** + * Sets tone mark directly. This method is used if client wants + * to override default core dependant tone mark set or traditional + * cycle-through tone mark system doesn't suit its porposes. + * + * @since S60 V2.8 + * @param aToneMark Tone mark to be set. + * @return ETrue if tone mark was legal, ie. produced candidates. + * EFalse otherwise. + */ + IMPORT_C TBool SetToneMark(TInt aToneMark); + + /** + * A convinience method for cheking qwerty based input mode. + * + * @since S60 V3.0 + * @param aMode Input mode to be checked. + * @return ETrue If aMode is qwerty based input mode. + * EFalse Otherwise. + */ + IMPORT_C TBool IsQwertyBasedMode(TPtiEngineInputMode aMode) const; + + /** + * Creates empty user default dictionary file for given core object + * and initializes it to PtiEngine user dictionary format. If file already + * exists, then this method does nothing. Normally this method is + * only used by core objects. + * + * @since S60 V3.0 + * @param aCoreUid Uid for requesting core object. + * @param aSymbolClass Symbol class for udb data. + */ + IMPORT_C void CreateDefaultUserDictionaryFileL(TUid aCoreUid, TInt aSymbolClass); + + /** + * Creates secondary data file for given core object. Existing file will be overwritten. + * This data file may contain any additional data that the core object needs to store + * between sessions (for example used word dictionary, if the engine keeps reordering data in + * separate memory area). + * + * @since S60 V3.0 + * @param aCoreUid Uid number for requesting core object. + * @param aIndexNumber Index number. Core object may use this parameter for numerating data files + * if it needs more than one of then. Otherwise zero. + */ + IMPORT_C void WriteSecondaryDataFileL(TUid aCoreUid, TInt aIndexNumber, HBufC8* aData); + + /** + * Returns a heap buffer containing data from given secondary data file. + * Returns null if file is not found. + * + * @since S60 V3.0 + * @param aCoreUid Uid number for requesting core object. + * @param aIndexNumber Index number (see CreateDefaultUserDictionaryFileL). + * @return A heap buffer conataining requested data. + * NULL if file not found. + */ + IMPORT_C HBufC8* ReadSecondaryDataFileL(TUid aCoreUid, TInt aIndexNumber); + + /** + * Returns keymapping data for given key. Returned data depends on active + * language and input mode. Result string will be empty if there isn't + * key mapping adta available. + * + * @since S60 V3.0 + * @param aKey A key to be queried. + * @param aResult Resulting mapping data. + */ + IMPORT_C void MappingDataForKey(TPtiKey aKey, TDes& aResult, TPtiTextCase aCase); + + /** + * Qwerty input mode has different keymapping layout for each language. Therefore + * the characters for numeric input mode may be mapped to different keys depending + * on language. There are several situations where client application needs to know + * which key and case combination produce numeric characters for given language. + * This convinience method can be used for extracting that information easily + * (it is also possible to achieve same result directly via CPtiCoreLanguage object). + * Result array will be left empty if requested language is not available or it doesn't + * support qwerty input mode. + * Returned list includes key bindings for characters: "0123456789pw+#*" + * (Not necessarily in this order). + * See also ExtendedNumericModeKeysForQwertyL. + * + * This version first tries to return mappings according to currently + * active physical keyboard. It current keyboard is not qwerty based, + * it searches data for the first qwerty based keyboard type it can find. + * That is done in same order as keyboard types are defined in PtiDefs.h. + * There is also another version this method, which gets keyboard type as a + * parameter. + * + * @since S60 V3.1 + * @param aLanguage Language id for requested mappings. + * @param aResult Array for storing resulting mappings. + */ + IMPORT_C void GetNumericModeKeysForQwertyL(TInt aLanguage, RArray& aResult); + + IMPORT_C HBufC* GetCandidatesByInputString(const TDesC& aInputString, + RPointerArray& aList, + const TBool aIsPredictive); + /** + * Get first hwr implementation support the specified language + * + * @since S60 V4.0 + * @param aLanguage The language that hwr implementation supported + * @return The pointer points to hwr implementation instance + */ + IMPORT_C MPtiHwrRecognizer* GetHwrRecognizerL(TLanguage aLanguage); + + /** + * Get hwr implementation by give implementation uid + * + * @since S60 V4.0 + * @param aImpId Given specific implementation uid + * @return The pointer points to hwr implementation instance + */ + IMPORT_C MPtiHwrRecognizer* GetHwrRecognizerL(TInt aImpId); + + /** + * Get hwr implementation uid list which support given language + * + * @since S60 V4.0 + * @param aLanguage The language that hwr implementation supported + * @return The array of implementation uid list + */ + IMPORT_C RArray& ListHwrRecognizerL(TLanguage aLanguage); + + /** + * Get hwr available languages list + * + * @since S60 V4.0 + * @param aResult Carry the hwr available languages list on return + * @return None + */ + IMPORT_C void GetHwrAvailableLanguagesL(RArray& aResult); + + /** + * Returns a list containing keyboard type values for all available + * physical keyboards connected to the device. Keyboard doesn't have to be + * active at calling time to be included in the output list. + * + * @since S60 V5.0 + * @param aResult An array to be filled with available keyboard types. + */ + IMPORT_C static void ListAvailablePhysicalKeyboardsL(RArray& aResult); + + /** + * This method is same as GetNumericModeKeysForQwertyL, expect that instead of returning + * strict list of key bindings used in phone number editor, it returns list of all + * possible characters used in any of the "number only" editor variations. + * Returned list includes key bindings for characters: "*+pw#1234567890;.,-E?/" + * (Not necessarily in this order). + * See also GetNumericModeKeysForQwertyL. + * + * This version first tries to return mappings according to currently + * active physical keyboard. It current keyboard is not qwerty based, + * it searches data for the first qwerty based keyboard type it can find. + * That is done in same order as keyboard types are defined in PtiDefs.h. + * There is also another version this method, which gets keyboard type as a + * parameter. + * + * @since S60 V3.2 + * @param aLanguage Language id for requested mappings. + * @param aResult Array for storing resulting mappings. + */ + IMPORT_C const RArray& ExtendedNumericModeKeysForQwertyL(TInt aLanguage); + + /** + * Turns auto substitution feature on or off. Auto substitution + * feature replaces predefined strings with other strings. For example, + * if user types xmas, it could be auto substituted with Christmas. + * + * @since S60 V5.0 + * @param aStatus New status for auto substituiton feature + * @return KErrNone or system wide error code. + */ + IMPORT_C TInt SetAutoSubstitution(TBool aStatus); + + /** + * Adds new auto substitution entry to database. If entry for given shorcut + * already exists, then the old entry will be automatically deleted. + * + * @since S60 V5.0 + * @param aShortcut Shortcut part for new entry. + * @param aSubstitution Substitution part for new entry. + * @return KErrNone or system wide error code. + */ + IMPORT_C TInt AddAutoSubstitutionEntry(const TDesC& aShortcut, + const TDesC& aSubstituition); + + /** + * Remove auto substitution entry. + * + * @since S60 V5.0 + * @param aShortcut Shortcut for auto substitution entry to be removed. + * @return KErrNone or system wide error code. + * KErrNotFound if given shortcut was nout found. + */ + IMPORT_C TInt DeleteAutoSubstitutionEntry(const TDesC& aShortcut); + + /** + * Returns the number of auto substitution entries in auto subst db. + * + * @since S60 V5.0 + * @return Number of entries in auto substitution db. Zero if the + * feature is not supported or is not activated. + */ + IMPORT_C TInt NumberOfAutoSubstitutionEntries() const; + + /** + * Return auto substitution entry for given index. + * + * @since S60 V5.0 + * @param aIndex Index for entry to be returned. + * @param aShortcut Shortcut part of the result entry will be stored here. + * @param aSubstitution Substitution part of result entry will be stored here. + * @return KErrNone or system wide error code. + */ + IMPORT_C TInt GetAutoSubstitutionEntry(TInt aIndex, TDes& aShortcut, + TDes& aSubstitution); + /** + * Returns currently selected qwerty keyboard type. + * + * @since S60 V5.0 + * @return Currently selected keyboard type. + */ + IMPORT_C TPtiKeyboardType KeyboardType() const; + + /** + * Sets keyboard type for non-virtual keyboard. Keyboard type specifies which + * set of key mapping data is used. + * + * @since S60 V5.0 + * @param aType New keyboard type. + * @return KErrNone if successful + * KErrNotSupported if currently selected language/input mode combination + * does not allow given keyboard type, or mapping + * data doesn't contain block for it. + */ + IMPORT_C TInt SetKeyboardType(TPtiKeyboardType aType); + + /** + * Lists keyboard blocks available in keymapping data for given language. + * + * @since S60 V5.0 + * @param aLanguage A language to be queried. + * @param aResult Resulting list of keyboard types will we stored here. + */ + IMPORT_C void KeyboardTypesSupportedByLanguageL(TInt aLanguage, + RArray& aResult); + /** + * Same as previous version of GetNumericModeKeysForQwertyL (see description above) but + * keyboard type is given as a parameter and mappings are return only for given keyboard + * type. + * + * @since S60 V5.0 + * @param aLanguage Language id for requested mappings. + * @param aResult Array for storing resulting mappings. + * @param aKeyboardType keyboard type. + */ + IMPORT_C void GetNumericModeKeysForQwertyL(TInt aLanguage, + RArray& aResult, + TPtiKeyboardType aKeyboardType); + /** + * Same as previous version of ExtendedNumericModeKeysForQwertyL (see description above), but + * keyboard type is given as a parameter and mappings are return only for given keyboard + * type. + * + * @since S60 V5.0 + * @param aLanguage Language id for requested mappings. + * @param aKeyboardType keyboard type. + * @param aResult Array for storing resulting mappings. + */ + IMPORT_C const RArray& ExtendedNumericModeKeysForQwertyL(TInt aLanguage, + TPtiKeyboardType aKeyboardType); + + /** + * Sets a boolean value indicating whether number candidates are included to + * predictive candidate list. Number candidates are strings containing only digits. + * Number candidate feature must be supported by active prediction engine, + * otherwise this setting will be ignored. + * + * @since S60 V5.0 + * @param aStatus A boolean value indicating whether number candidates + * are included to cadidate list. + * @return KErrNone or a system wide error code. + */ + IMPORT_C TInt SetNumberCandidateStatus(TBool aStatus); + + /** + * Returns a boolean value indicating whether given scan code is allowed for + * current input mode. + * + * @since S60 V5.0 + * @param aKey A key to be queried. + * @return ETrue if given scan code is allowed fore currently active input mode. + * EFalse otherwise. + */ + IMPORT_C TBool IsValidKey(TPtiKey aKey) const; + + /** + * Sets the maximum length for auto completed words. This method can be used when the + * client needs to be sure that all provided word completions will fit into remaining + * editor buffer. When the number of key presses in an input sequence exceeds the value + * given in aMaxLength, core will automatically reset this value to "no limit". + * + * @since S60 V5.0 + * @param aMaxLength The maximum length fo auto completed candinates. + * Value 0 means no limit. + * @return KErrNone If the operation succeeded. + * Otherwise system wide error code. + */ + IMPORT_C TInt SetMaxLengthForAutoCompletedCandidates(TInt aMaxLength); + + /** + * Some core objects may provide different set of results depending on whether + * the auto captitalization feature was used for entering the word or not. There is + * now way to tell on core level whether the word was auto-capitalizedby FEP or + * capitalized normally by the user. This method can be used to incicate + * core object that auto-capitalization was used for current input sequence. + * Clearing or commiting the word will cancel the effect of this method. + * + * @since S60 V5.0 + */ + IMPORT_C void MarkAutoCapitalized(); + + /** + * Returns text case buffer. Case buffer contains shift state + * for each key press used for producing active word, ie. it remembers + * case values for each AppendKeyPress call. Case buffer is + * cleared when active word is commited or cleared. Return + * value is TPtrC8 containing string of EPtiTextCase values. + * + * @since S60 V5.0 + * @return A string of EPtiTextCase values. + */ + IMPORT_C TPtrC8 CaseSequence(); + + /** + * Some prediction engines support next word prediction feature but + * require database to be pre-filled with suitable phrase data. + * This method adds one new phrase or sentence to phrase dictionary. + * Active core object needs to support phrase based next word prediction, + * otherwise an error code is returned. + * + * @since S60 V5.0 + * @param aNewPhrase New phrase to be added to phrase dictionary. + * @return KErrNone or system wide error code. + */ + IMPORT_C TInt AddPhrase(const TDesC& aNewPhrase); + +#ifdef FF_DUAL_LANGUAGE_SUPPORT + /** + * Activates specified secondary input language in current input mode. + * + * @since S60 V5.0 + * @param aEpocLanguageID Language to be activated. + * @return KErrNone if success or system wide error code. + */ + IMPORT_C TInt SetSecondaryInputL(TInt aEpocLanguageID); +#endif //FF_DUAL_LANGUAGE_SUPPORT + private: + CPtiEngine(); + void ConstructL(TBool aUseDefaultUserDictionary); + void ConstructL(const TUid aCoreUid, TBool aUseDefaultUserDictionary); + + private: + CPtiEngineImpl* iImpl; + }; + +#endif _PTI_ENGINE_H + +// End of file