/*
* 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 "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 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