williamr@2: /*
williamr@2: * Copyright (c) 2003-2005 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:               Predective text input engine core interface.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef _PTI_CORE_H
williamr@2: #define _PTI_CORE_H
williamr@2: 
williamr@2: // INCLUDES
williamr@2: #include <badesca.h> 
williamr@2: #include "PtiDefs.h"
williamr@2: #include "PtiLanguage.h"
williamr@2: #include "PtiUserDictionary.h"
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class CPtiEngine;
williamr@2: class MPtiEngineCompositionDataInterface;
williamr@2: class MPtiUserDictionaryEntry;
williamr@2: 
williamr@2: // CONSTANTS
williamr@2: const TInt KDefaultCoresGran = 3;
williamr@2: 
williamr@2: /**
williamr@2: * This is abstract base class of all PtiEngine core objects. A PtiEngine core object implements set of
williamr@2: * input modes and input related services for a set of languages. This class defines core side
williamr@2: * PtiEngine API.
williamr@2: */
williamr@2: class MPtiCore
williamr@2: 	{
williamr@2: 	//
williamr@2: 	// General API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		/**
williamr@2: 		* Initialized core object. This method is called by PtiEngine framework when core object
williamr@2: 		* is loaded.		
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @param aOwner Pointer to onwing PtiEngine framework instance.
williamr@2: 		* @param aTextBuffer A pointer to PtiEngine main text buffer.
williamr@2: 		* @param aLanguageList A language list to be filled with language bindings to this core
williamr@2: 		*                      onbject
williamr@2: 		* @param aUseDefautUserDictionary A boolean value indicating whether default user dictionary shoulkd be used
williamr@2: 		*                                 (in case this core object supports user dictionaries).
williamr@2: 		*/	
williamr@2: 		virtual void InitializeL(CPtiEngine* aOwner, TDes* aTextBuffer, CArrayPtrFlat<CPtiCoreLanguage>* aLanguageList, TBool aUseDefautUserDictionary) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Removes languages associated to this core object from given language list. Languages
williamr@2: 		* not associated to this core abject are not touched.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @param aLanguageList A language list to be cleaned.
williamr@2: 		*/
williamr@2: 		virtual void DropLanguages(CArrayPtrFlat<CPtiCoreLanguage>* aLanguageList) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Opens resources for given language and itinialized them.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @param aLanguage Symbian OS language code a language to be initialized.
williamr@2: 		* @return KErrNone or a system wide error code.
williamr@2: 		*/
williamr@2: 		virtual TInt OpenLanguageL(CPtiCoreLanguage *aLanguage) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Closes currently activate language and frees resources associated to it.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @return KErrNone of system wide error ocde.
williamr@2: 		*/
williamr@2: 		virtual TInt CloseLanguageL() = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Returns the contents of text buffer.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @return A constant pointer to text buffer.
williamr@2: 		*/	
williamr@2: 		virtual TPtrC GetCurrentWord() const = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Commits current word. Commiting means that user has added current
williamr@2: 		* word as part of text. Frequency information and other related attributes
williamr@2: 		* can then be updated.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @return KErrNone or a system wide error code.
williamr@2: 		*/
williamr@2: 		virtual TInt CommitCurrentWord() = 0;		
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Returns a pointer core info structure. Core info struct contains useful 
williamr@2: 		* information about core object and its features.
williamr@2: 		*
williamr@2: 		*/				
williamr@2: 		virtual MPtiCoreInfo* GetCoreInfo() = 0;
williamr@2: 				
williamr@2: 		/**
williamr@2: 		* Turns reoreding feature on or off. Reordering means that prediction engine
williamr@2: 		* maintains frequency information for used words and modifys the order of candidate list
williamr@2: 		* based on that information. This feature may not be supported by all prediction engines.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @param aStatus New status for reorderinf feature.
williamr@2: 		* @return KErrNone or a system wide error code.
williamr@2: 		*/
williamr@2: 		virtual TInt SetReordering(TBool aStatus) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* This is the single most important core API method, most of the text input functionality
williamr@2: 		* will be utilize this method. Call to this method indicates core object that a key was
williamr@2: 		* pressed and it should act accordingly and fill the output buffer.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @param aKey Enum value for pressed key.
williamr@2: 		*/
williamr@2: 		virtual void AppendKeyPress(TPtiKey aKey) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Indicates core object that it should perform 'delete key press'-operation.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		*/
williamr@2: 		virtual void DeleteKeyPress() = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Call to this method notifys core object that input buffer was cleared.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		*/
williamr@2: 		virtual void ClearBuffer() = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Sets current input sequence. The end result of this operation must be same as 
williamr@2: 		* if user had entered keys in input array as individual key presses.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @param aInput An array containing sequence of key presses (type TPtiKey).
williamr@2: 		* @return KErrNone or a system wide error code.
williamr@2: 		*/
williamr@2: 		virtual TInt SetCurrentInputSequence(TPtrC8 aInput) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Converts given string from one character set to another. Possible conversion types
williamr@2: 		* are defined in PtiDefs.h
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @param aType        Conversion type.
williamr@2: 		* @param aInput       Pointer to input string to be converted.
williamr@2: 		* @param aInputLength Length of input buffer.
williamr@2: 		* @param aOutput      pointer to output buffer.
williamr@2: 		* @return KErrNone or a system wide error code.
williamr@2: 		*/
williamr@2: 		virtual TInt Convert(TPtiCharConversion aType,
williamr@2: 							 TAny* aInput,
williamr@2: 							 TInt aInputLength,
williamr@2: 							 TAny* aOutput) = 0;
williamr@2: 
williamr@2: 		/**
williamr@2: 		* Re-defines keymappings for given key / input mode / case combination. Previous 
williamr@2: 		* keymapping will be deleted and new mappings will be used instead.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @param aMode Input mode for new key mapping.
williamr@2: 		* @param aKey  A key to be replaced.
williamr@2: 		* @param aKeyMap New keymapping data for aKey.
williamr@2: 		* @param aCase   Text case to be replaced.
williamr@2: 		* @return KErrNone or system wide error code.
williamr@2: 		*/
williamr@2: 		virtual TInt SetExternalKeyMapL(TPtiEngineInputMode aMode,
williamr@2: 			                            TPtiKey aKey,
williamr@2: 									    TDesC& aKeyMap,
williamr@2: 										TPtiTextCase aCase) = 0;
williamr@2: 		/**
williamr@2: 		* Returns alternate spelling for given unicode characters. Possible conversion
williamr@2: 		* types are defined in header PtiDefs.h.
williamr@2: 		*										
williamr@2: 		* @sinec 2.6
williamr@2: 		* @aInput A character to be converted.
williamr@2: 		* @aOutput Resulting alternate spelling will be stored here.
williamr@2: 		* @aType   Spelling conversion type.
williamr@2: 		* @return  KErrNone or system wide error code.
williamr@2: 		*/								
williamr@2: 		virtual TInt GetSpelling(TUint16 aInput, TDes& aOutput, TPtiSpelling aType) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Cancels all on-going core obejct timner activity.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @return KErrNone or system wide error code.
williamr@2: 		*/
williamr@2: 		virtual TInt CancelTimerActivity() = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* A generic command handling method for extending PtiEngine API without adding
williamr@2: 		* new base class methods. It is recommended to use this only in force major
williamr@2: 		* situations, where there is no other way.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @param aCommand A Command id value. Platform wide command ids are defined in PtiDefs.h.
williamr@2: 		* @param aParams  TAny pointer for passing any required parameters.
williamr@2: 		* @return An integer containing possible return value related to command.
williamr@2: 		*/
williamr@2: 		virtual TInt HandleCommandL(TPtiEngineCommand aCommand, TAny* aParams) = 0;
williamr@2: 
williamr@2: 	//
williamr@2: 	// Predictive latin API
williamr@2: 	//  
williamr@2: 	public:    
williamr@2: 	    /**
williamr@2: 	    * Returns number of candidates for currently entered key sequence.
williamr@2: 	    *
williamr@2: 	    * @since 2.6
williamr@2: 	    * @return Number of prediction candidates for currently entered key sequence.
williamr@2: 	    */
williamr@2: 		virtual TInt NumberOfCandidates() = 0;
williamr@2: 		
williamr@2: 		/**		
williamr@2: 		* Returns a list of candidate words for currently entered key sequence.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		* @param aList A list to be filled with candidate words.
williamr@2: 		* @return Number of candidate works in aList.
williamr@2: 		*/
williamr@2: 		virtual TInt GetCandidateListL(CDesCArray& aList) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Returns next word candidate list. Next word candidates are words
williamr@2: 		* potentially related to currently selected candidate. Next word prediction
williamr@2: 		* feature must supported by the engine and turned on.
williamr@2: 		*
williamr@2: 		* @since 2.6
williamr@2: 		*/
williamr@2: 		virtual TInt GetNextWordCandidateListL(CDesCArray& aList) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Returns first word in list of candidate words for current input sequence.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @param aResult A descriptor where resulting word will be stored.
williamr@2: 		* @return KErrnNone or system wide error code.
williamr@2: 		*/		
williamr@2: 		virtual TInt GetFirstCandidate(TDes& aResult) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Returns next word in list of candidate words for current input sequence.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @param aResult A descriptor where resulting word will be stored.
williamr@2: 		* @return KErrnNone or system wide error code.
williamr@2: 		*/						
williamr@2: 		virtual TInt GetNextCandidate(TDes& aResult) = 0;
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Returns previous word in list of candidate words for current input sequence.
williamr@2: 		* 
williamr@2: 		* @since 2.6
williamr@2: 		* @param aResult A descriptor where resulting word will be stored.
williamr@2: 		* @return KErrnNone or system wide error code.
williamr@2: 		*/								
williamr@2: 		virtual TInt GetPreviousCandidate(TDes& aResult) = 0;
williamr@2: 	
williamr@2: 	//
williamr@2: 	// User dictionary API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		virtual TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict) = 0;
williamr@2: 		virtual TInt RemoveUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict) = 0;
williamr@2:         virtual TInt NumberOfEntriesInUserDictionary(CPtiUserDictionary* aDict) = 0;
williamr@2: 		virtual TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult, CPtiUserDictionary* aDict) = 0;
williamr@2: 		virtual CPtiUserDictionary* CreateEmptyUserDictionaryL(TInt aMaxSize) = 0;
williamr@2: 		virtual TInt AttachUserDictionary(CPtiUserDictionary* aDict) = 0;
williamr@2: 		virtual TBool DetachUserDictionary(CPtiUserDictionary* aDict) = 0;		
williamr@2: 
williamr@2: 	//
williamr@2: 	// Chinese API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		virtual TPtrC GetCandidatePage() = 0;
williamr@2: 		virtual TBool NextCandidatePage() = 0;
williamr@2: 		virtual TBool PreviousCandidatePage() = 0;
williamr@2: 		virtual TBool MoreCandidatePages() = 0;
williamr@2: 		virtual void SetCandidatePageLength(TInt aLength) = 0;
williamr@2: 		virtual TPtrC GetPhoneticSpelling(TInt aIndex) const = 0; 
williamr@2: 		virtual TInt PhoneticSpellingCount() const = 0;	
williamr@2: 	    virtual TBool SelectPhoneticSpelling(TInt aIndex) = 0;
williamr@2: 	    virtual TInt SelectedPhoneticSpelling() const = 0; 
williamr@2: 		virtual TBool ToneMark(TText& aToneMark) const = 0;
williamr@2: 		virtual TBool IsToneMarkValidForSpelling() = 0;
williamr@2: 		virtual TBool SetPredictiveChineseChar(const TDesC& aChar) = 0;
williamr@2: 		virtual TBool SetToneMark(TInt aToneMark) = 0;
williamr@2: 
williamr@2: 
williamr@2:    	//
williamr@2: 	// Japanese API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		virtual TPtrC ReadingTextL() = 0;
williamr@2: 		virtual MPtiEngineCompositionDataInterface* CompositionData() = 0;
williamr@2: 
williamr@2: 	//
williamr@2: 	// Chinese API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 	        virtual HBufC* GetCandidatesByInputString(const TDesC& aInputString, 
williamr@2:                                                         RPointerArray<HBufC>& aList, 
williamr@2:                                                         const TBool aIsPredictive) = 0;
williamr@2: 	};
williamr@2: 	
williamr@2: 
williamr@2: /**
williamr@2: * This class is a base class implementation for MPtiCore. It contains empty base implemenations
williamr@2: * for core API methods and static methods for creating and listing PtiEngine core objects.
williamr@2: */
williamr@2: class CPtiCore : public CBase, public MPtiCore
williamr@2: 	{
williamr@2: 	//
williamr@2: 	// Plugin household methods
williamr@2: 	//
williamr@2: 	public:
williamr@2:  		/**
williamr@2: 		* Creates in instance of core object for given implemenation uid.
williamr@2: 		*
williamr@2: 		* @param aCoreUid An ecom implementation uid for core object to be created.
williamr@2: 		* @return Pointer to new core object instance.
williamr@2: 		*/
williamr@2: 		IMPORT_C static CPtiCore* CreateCoreL(TUid aCoreUid);
williamr@2: 		
williamr@2: 		/**
williamr@2: 		* Lists all the available PtiEngine core onject implemenatations.
williamr@2: 		*
williamr@2: 		* @return Pointer to a list cantaining implementation uids for available core plugins.
williamr@2: 		*/
williamr@2: 		IMPORT_C static CArrayFix<TInt>* ListCoresLC();
williamr@2: 
williamr@2: 	public: 
williamr@2: 		IMPORT_C ~CPtiCore();
williamr@2: 
williamr@2: 	//
williamr@2: 	// 	General methods.
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		IMPORT_C TInt SetCurrentInputSequence(TPtrC8 aInput);
williamr@2: 		IMPORT_C TInt Convert(TPtiCharConversion aType,
williamr@2: 							  TAny* aInput,
williamr@2: 							  TInt aInputLength,
williamr@2: 							  TAny* aOutput);
williamr@2: 		IMPORT_C TInt GetSpelling(TUint16 aInput,
williamr@2: 			                      TDes& aOutput,
williamr@2: 								  TPtiSpelling aType);
williamr@2: 		IMPORT_C TInt SetExternalKeyMapL(TPtiEngineInputMode aMode,
williamr@2: 			                             TPtiKey aKey,
williamr@2: 									     TDesC& aKeyMap,
williamr@2: 										 TPtiTextCase aCase);
williamr@2: 		IMPORT_C TInt CommitCurrentWord();		
williamr@2: 		IMPORT_C TPtrC GetCurrentWord() const;
williamr@2: 
williamr@2: 	//
williamr@2: 	// Predictive latin API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		IMPORT_C TInt NumberOfCandidates();
williamr@2: 		IMPORT_C TInt GetCandidateListL(CDesCArray& aList);
williamr@2: 		IMPORT_C TInt GetNextWordCandidateListL(CDesCArray& aList);
williamr@2: 		IMPORT_C TInt GetFirstCandidate(TDes& aResult);
williamr@2: 		IMPORT_C TInt GetNextCandidate(TDes& aResult);
williamr@2: 		IMPORT_C TInt GetPreviousCandidate(TDes& aResult);
williamr@2: 	
williamr@2: 	//
williamr@2: 	// User dictionary API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		IMPORT_C TInt AddUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict);
williamr@2: 		IMPORT_C TInt RemoveUserDictionaryEntry(MPtiUserDictionaryEntry& aEntry, CPtiUserDictionary* aDict);
williamr@2:                 IMPORT_C TInt NumberOfEntriesInUserDictionary(CPtiUserDictionary* aDict);
williamr@2: 		IMPORT_C TInt GetUserDictionaryEntry(TInt aIndex, MPtiUserDictionaryEntry& aResult, CPtiUserDictionary* aDict);
williamr@2: 		IMPORT_C CPtiUserDictionary* CreateEmptyUserDictionaryL(TInt aMaxSize);
williamr@2: 		IMPORT_C TInt AttachUserDictionary(CPtiUserDictionary* aDict);
williamr@2: 		IMPORT_C TBool DetachUserDictionary(CPtiUserDictionary* aDict);		
williamr@2: 
williamr@2: 	//
williamr@2: 	// Chinese API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		IMPORT_C TPtrC GetCandidatePage();
williamr@2: 		IMPORT_C TBool NextCandidatePage();
williamr@2: 		IMPORT_C TBool PreviousCandidatePage();
williamr@2: 		IMPORT_C TBool MoreCandidatePages();
williamr@2: 		IMPORT_C void SetCandidatePageLength(TInt aLength);
williamr@2: 		IMPORT_C TPtrC GetPhoneticSpelling(TInt aIndex) const; 
williamr@2: 		IMPORT_C TInt PhoneticSpellingCount() const;	
williamr@2: 	        IMPORT_C TBool SelectPhoneticSpelling(TInt aIndex);
williamr@2: 	        IMPORT_C TInt SelectedPhoneticSpelling() const; 
williamr@2: 		IMPORT_C TBool ToneMark(TText& aToneMark) const;
williamr@2: 		IMPORT_C TBool IsToneMarkValidForSpelling();
williamr@2: 		IMPORT_C TBool SetPredictiveChineseChar(const TDesC& aChar);
williamr@2: 		IMPORT_C TBool SetToneMark(TInt aToneMark);
williamr@2:  
williamr@2: 	//
williamr@2: 	// Japanese API
williamr@2: 	//
williamr@2: 	public:
williamr@2: 		IMPORT_C TPtrC ReadingTextL();
williamr@2: 		IMPORT_C MPtiEngineCompositionDataInterface* CompositionData();
williamr@2: 
williamr@2: 	//
williamr@2: 	// Chinese API
williamr@2: 	//			
williamr@2: 	public:	
williamr@2:                 IMPORT_C HBufC* GetCandidatesByInputString(const TDesC& aInputString, 
williamr@2:                                                          RPointerArray<HBufC>& aList, 
williamr@2:                                                          const TBool aIsPredictive);			
williamr@2: 
williamr@2: 	private:
williamr@2: 		inline void SetDestructorKeyId(TInt aDtorKeyId);
williamr@2: 
williamr@2: 	private:
williamr@2: 		TInt iDtorKeyId;
williamr@2: 		TInt Reserved_1;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: inline void CPtiCore::SetDestructorKeyId(TInt aDtorKeyId)
williamr@2: 	{
williamr@2: 	iDtorKeyId = aDtorKeyId;
williamr@2: 	}
williamr@2: 
williamr@2: #endif _PTI_CORE_H
williamr@2: 
williamr@2: // End of file
williamr@2: 
williamr@2: