/*

* 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 <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.