/*

* 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