/*
* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 <e32base.h>
#include <badesca.h> 
#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<TInt>* 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<TInt>& 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<TInt>& 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<TPtiNumericKeyBinding>& aResult);                        
		
        IMPORT_C HBufC* GetCandidatesByInputString(const TDesC& aInputString, 
                                                         RPointerArray<HBufC>& 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<TUid>& 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<TInt>& 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<TPtiKeyboardType>& 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<TPtiNumericKeyBinding>& 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<TPtiKeyboardType>& 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<TPtiNumericKeyBinding>& 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<TPtiNumericKeyBinding>& 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 __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 //__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
