/*
* Copyright (c) 2003-2005 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 core interface.
*
*/














#ifndef _PTI_CORE_H
#define _PTI_CORE_H

// INCLUDES
#include <badesca.h> 
#include "PtiDefs.h"
#include "PtiLanguage.h"
#include "PtiUserDictionary.h"

// FORWARD DECLARATIONS
class CPtiEngine;
class MPtiEngineCompositionDataInterface;
class MPtiUserDictionaryEntry;

// CONSTANTS
const TInt KDefaultCoresGran = 3;

/**
* This is abstract base class of all PtiEngine core objects. A PtiEngine core object implements set of
* input modes and input related services for a set of languages. This class defines core side
* PtiEngine API.
*/
class MPtiCore
	{
	//
	// General API
	//
	public:
		/**
		* Initialized core object. This method is called by PtiEngine framework when core object
		* is loaded.		
		*
		* @since 2.6
		* @param aOwner Pointer to onwing PtiEngine framework instance.
		* @param aTextBuffer A pointer to PtiEngine main text buffer.
		* @param aLanguageList A language list to be filled with language bindings to this core
		*                      onbject
		* @param aUseDefautUserDictionary A boolean value indicating whether default user dictionary shoulkd be used
		*                                 (in case this core object supports user dictionaries).
		*/	
		virtual void InitializeL(CPtiEngine* aOwner, TDes* aTextBuffer, CArrayPtrFlat<CPtiCoreLanguage>* aLanguageList, TBool aUseDefautUserDictionary) = 0;
		
		/**
		* Removes languages associated to this core object from given language list. Languages
		* not associated to this core abject are not touched.
		* 
		* @since 2.6
		* @param aLanguageList A language list to be cleaned.
		*/
		virtual void DropLanguages(CArrayPtrFlat<CPtiCoreLanguage>* aLanguageList) = 0;
		
		/**
		* Opens resources for given language and itinialized them.
		*
		* @since 2.6
		* @param aLanguage Symbian OS language code a language to be initialized.
		* @return KErrNone or a system wide error code.
		*/
		virtual TInt OpenLanguageL(CPtiCoreLanguage *aLanguage) = 0;
		
		/**
		* Closes currently activate language and frees resources associated to it.
		*
		* @since 2.6
		* @return KErrNone of system wide error ocde.
		*/
		virtual TInt CloseLanguageL() = 0;
		
		/**
		* Returns the contents of text buffer.
		* 
		* @since 2.6
		* @return A constant pointer to text buffer.
		*/	
		virtual TPtrC GetCurrentWord() const = 0;
		
		/**
		* Commits current word. Commiting means that user has added current
		* word as part of text. Frequency information and other related attributes
		* can then be updated.
		*
		* @since 2.6
		* @return KErrNone or a system wide error code.
		*/
		virtual TInt CommitCurrentWord() = 0;		
		
		/**
		* Returns a pointer core info structure. Core info struct contains useful 
		* information about core object and its features.
		*
		*/				
		virtual MPtiCoreInfo* GetCoreInfo() = 0;
				
		/**
		* Turns reoreding feature on or off. Reordering means that prediction engine
		* maintains frequency information for used words and modifys the order of candidate list
		* based on that information. This feature may not be supported by all prediction engines.
		* 
		* @since 2.6
		* @param aStatus New status for reorderinf feature.
		* @return KErrNone or a system wide error code.
		*/
		virtual TInt SetReordering(TBool aStatus) = 0;
		
		/**
		* This is the single most important core API method, most of the text input functionality
		* will be utilize this method. Call to this method indicates core object that a key was
		* pressed and it should act accordingly and fill the output buffer.
		* 
		* @since 2.6
		* @param aKey Enum value for pressed key.
		*/
		virtual void AppendKeyPress(TPtiKey aKey) = 0;
		
		/**
		* Indicates core object that it should perform 'delete key press'-operation.
		*
		* @since 2.6
		*/
		virtual void DeleteKeyPress() = 0;
		
		/**
		* Call to this method notifys core object that input buffer was cleared.
		*
		* @since 2.6
		*/
		virtual void ClearBuffer() = 0;
		
		/**
		* Sets current input sequence. The end result of this operation must be same as 
		* if user had entered keys in input array as individual key presses.
		*
		* @since 2.6
		* @param aInput An array containing sequence of key presses (type TPtiKey).
		* @return KErrNone or a system wide error code.
		*/
		virtual TInt SetCurrentInputSequence(TPtrC8 aInput) = 0;
		
		/**
		* Converts given string from one character set to another. Possible conversion types
		* are defined in PtiDefs.h
		*
		* @since 2.6
		* @param aType        Conversion type.
		* @param aInput       Pointer to input string to be converted.
		* @param aInputLength Length of input buffer.
		* @param aOutput      pointer to output buffer.
		* @return KErrNone or a system wide error code.
		*/
		virtual TInt Convert(TPtiCharConversion aType,
							 TAny* aInput,
							 TInt aInputLength,
							 TAny* aOutput) = 0;

		/**
		* Re-defines keymappings for given key / input mode / case combination. Previous 
		* keymapping will be deleted and new mappings will be used instead.
		*
		* @since 2.6
		* @param aMode Input mode for new key mapping.
		* @param aKey  A key to be replaced.
		* @param aKeyMap New keymapping data for aKey.
		* @param aCase   Text case to be replaced.
		* @return KErrNone or system wide error code.
		*/
		virtual TInt SetExternalKeyMapL(TPtiEngineInputMode aMode,
			                            TPtiKey aKey,
									    TDesC& aKeyMap,
										TPtiTextCase aCase) = 0;
		/**
		* Returns alternate spelling for given unicode characters. Possible conversion
		* types are defined in header PtiDefs.h.
		*										
		* @sinec 2.6
		* @aInput A character to be converted.
		* @aOutput Resulting alternate spelling will be stored here.
		* @aType   Spelling conversion type.
		* @return  KErrNone or system wide error code.
		*/								
		virtual TInt GetSpelling(TUint16 aInput, TDes& aOutput, TPtiSpelling aType) = 0;
		
		/**
		* Cancels all on-going core obejct timner activity.
		*
		* @since 2.6
		* @return KErrNone or system wide error code.
		*/
		virtual TInt CancelTimerActivity() = 0;
		
		/**
		* A generic command handling method for extending PtiEngine API without adding
		* new base class methods. It is recommended to use this only in force major
		* situations, where there is no other way.
		* 
		* @since 2.6
		* @param aCommand A Command id value. Platform wide command ids are defined in PtiDefs.h.
		* @param aParams  TAny pointer for passing any required parameters.
		* @return An integer containing possible return value related to command.
		*/
		virtual TInt HandleCommandL(TPtiEngineCommand aCommand, TAny* aParams) = 0;

	//
	// Predictive latin API
	//  
	public:    
	    /**
	    * Returns number of candidates for currently entered key sequence.
	    *
	    * @since 2.6
	    * @return Number of prediction candidates for currently entered key sequence.
	    */
		virtual TInt NumberOfCandidates() = 0;
		
		/**		
		* Returns a list of candidate words for currently entered key sequence.
		*
		* @since 2.6
		* @param aList A list to be filled with candidate words.
		* @return Number of candidate works in aList.
		*/
		virtual TInt GetCandidateListL(CDesCArray& aList) = 0;
		
		/**
		* Returns next word candidate list. Next word candidates are words
		* potentially related to currently selected candidate. Next word prediction
		* feature must supported by the engine and turned on.
		*
		* @since 2.6
		*/
		virtual TInt GetNextWordCandidateListL(CDesCArray& aList) = 0;
		
		/**
		* Returns first word in list of candidate words for current input sequence.
		* 
		* @since 2.6
		* @param aResult A descriptor where resulting word will be stored.
		* @return KErrnNone or system wide error code.
		*/		
		virtual TInt GetFirstCandidate(TDes& aResult) = 0;
		
		/**
		* Returns next word in list of candidate words for current input sequence.
		* 
		* @since 2.6
		* @param aResult A descriptor where resulting word will be stored.
		* @return KErrnNone or system wide error code.
		*/						
		virtual TInt GetNextCandidate(TDes& aResult) = 0;
		
		/**
		* Returns previous word in list of candidate words for current input sequence.
		* 
		* @since 2.6
		* @param aResult A descriptor where resulting word will be stored.
		* @return KErrnNone or system wide error code.
		*/								
		virtual TInt GetPreviousCandidate(TDes& aResult) = 0;
	
	//
	// User dictionary API
	//
	public:
		virtual TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict) = 0;
		virtual TInt RemoveUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict) = 0;
        virtual TInt NumberOfEntriesInUserDictionary(CPtiUserDictionary* aDict) = 0;
		virtual TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult, CPtiUserDictionary* aDict) = 0;
		virtual CPtiUserDictionary* CreateEmptyUserDictionaryL(TInt aMaxSize) = 0;
		virtual TInt AttachUserDictionary(CPtiUserDictionary* aDict) = 0;
		virtual TBool DetachUserDictionary(CPtiUserDictionary* aDict) = 0;		

	//
	// Chinese API
	//
	public:
		virtual TPtrC GetCandidatePage() = 0;
		virtual TBool NextCandidatePage() = 0;
		virtual TBool PreviousCandidatePage() = 0;
		virtual TBool MoreCandidatePages() = 0;
		virtual void SetCandidatePageLength(TInt aLength) = 0;
		virtual TPtrC GetPhoneticSpelling(TInt aIndex) const = 0; 
		virtual TInt PhoneticSpellingCount() const = 0;	
	    virtual TBool SelectPhoneticSpelling(TInt aIndex) = 0;
	    virtual TInt SelectedPhoneticSpelling() const = 0; 
		virtual TBool ToneMark(TText& aToneMark) const = 0;
		virtual TBool IsToneMarkValidForSpelling() = 0;
		virtual TBool SetPredictiveChineseChar(const TDesC& aChar) = 0;
		virtual TBool SetToneMark(TInt aToneMark) = 0;


   	//
	// Japanese API
	//
	public:
		virtual TPtrC ReadingTextL() = 0;
		virtual MPtiEngineCompositionDataInterface* CompositionData() = 0;

	//
	// Chinese API
	//
	public:
	        virtual HBufC* GetCandidatesByInputString(const TDesC& aInputString, 
                                                        RPointerArray<HBufC>& aList, 
                                                        const TBool aIsPredictive) = 0;
	};
	

/**
* This class is a base class implementation for MPtiCore. It contains empty base implemenations
* for core API methods and static methods for creating and listing PtiEngine core objects.
*/
class CPtiCore : public CBase, public MPtiCore
	{
	//
	// Plugin household methods
	//
	public:
 		/**
		* Creates in instance of core object for given implemenation uid.
		*
		* @param aCoreUid An ecom implementation uid for core object to be created.
		* @return Pointer to new core object instance.
		*/
		IMPORT_C static CPtiCore* CreateCoreL(TUid aCoreUid);
		
		/**
		* Lists all the available PtiEngine core onject implemenatations.
		*
		* @return Pointer to a list cantaining implementation uids for available core plugins.
		*/
		IMPORT_C static CArrayFix<TInt>* ListCoresLC();

	public: 
		IMPORT_C ~CPtiCore();

	//
	// 	General methods.
	//
	public:
		IMPORT_C TInt SetCurrentInputSequence(TPtrC8 aInput);
		IMPORT_C TInt Convert(TPtiCharConversion aType,
							  TAny* aInput,
							  TInt aInputLength,
							  TAny* aOutput);
		IMPORT_C TInt GetSpelling(TUint16 aInput,
			                      TDes& aOutput,
								  TPtiSpelling aType);
		IMPORT_C TInt SetExternalKeyMapL(TPtiEngineInputMode aMode,
			                             TPtiKey aKey,
									     TDesC& aKeyMap,
										 TPtiTextCase aCase);
		IMPORT_C TInt CommitCurrentWord();		
		IMPORT_C TPtrC GetCurrentWord() const;

	//
	// Predictive latin API
	//
	public:
		IMPORT_C TInt NumberOfCandidates();
		IMPORT_C TInt GetCandidateListL(CDesCArray& aList);
		IMPORT_C TInt GetNextWordCandidateListL(CDesCArray& aList);
		IMPORT_C TInt GetFirstCandidate(TDes& aResult);
		IMPORT_C TInt GetNextCandidate(TDes& aResult);
		IMPORT_C TInt GetPreviousCandidate(TDes& aResult);
	
	//
	// User dictionary API
	//
	public:
		IMPORT_C TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict);
		IMPORT_C TInt RemoveUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict);
                IMPORT_C TInt NumberOfEntriesInUserDictionary(CPtiUserDictionary* aDict);
		IMPORT_C TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult, CPtiUserDictionary* aDict);
		IMPORT_C CPtiUserDictionary* CreateEmptyUserDictionaryL(TInt aMaxSize);
		IMPORT_C TInt AttachUserDictionary(CPtiUserDictionary* aDict);
		IMPORT_C TBool DetachUserDictionary(CPtiUserDictionary* aDict);		

	//
	// Chinese API
	//
	public:
		IMPORT_C TPtrC GetCandidatePage();
		IMPORT_C TBool NextCandidatePage();
		IMPORT_C TBool PreviousCandidatePage();
		IMPORT_C TBool MoreCandidatePages();
		IMPORT_C void SetCandidatePageLength(TInt aLength);
		IMPORT_C TPtrC GetPhoneticSpelling(TInt aIndex) const; 
		IMPORT_C TInt PhoneticSpellingCount() const;	
	        IMPORT_C TBool SelectPhoneticSpelling(TInt aIndex);
	        IMPORT_C TInt SelectedPhoneticSpelling() const; 
		IMPORT_C TBool ToneMark(TText& aToneMark) const;
		IMPORT_C TBool IsToneMarkValidForSpelling();
		IMPORT_C TBool SetPredictiveChineseChar(const TDesC& aChar);
		IMPORT_C TBool SetToneMark(TInt aToneMark);
 
	//
	// Japanese API
	//
	public:
		IMPORT_C TPtrC ReadingTextL();
		IMPORT_C MPtiEngineCompositionDataInterface* CompositionData();

	//
	// Chinese API
	//			
	public:	
                IMPORT_C HBufC* GetCandidatesByInputString(const TDesC& aInputString, 
                                                         RPointerArray<HBufC>& aList, 
                                                         const TBool aIsPredictive);			

	private:
		inline void SetDestructorKeyId(TInt aDtorKeyId);

	private:
		TInt iDtorKeyId;
		TInt Reserved_1;
	};


inline void CPtiCore::SetDestructorKeyId(TInt aDtorKeyId)
	{
	iDtorKeyId = aDtorKeyId;
	}

#endif _PTI_CORE_H

// End of file