1 /*

     2 * Copyright (c) 2003 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0""

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:               Predective text input engine hwr recognizer interface.

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 

    23 

    24 

    25 

    26 

    27 

    28 

    29 

    30 

    31 

    32 #ifndef _PTI_HWRRECOGNIZER_H

    33 #define _PTI_HWRRECOGNIZER_H

    34 

    35 // INCLUDES

    36 #include "PtiMHwrRecognizer.h"

    37  

    38 // internal definition

    39 enum TUdmType

    40     {

    41     EUdmSymbol = 1,

    42     EUdmShortcut,

    43     EUdmMax

    44     };

    45  struct THwrUdmRange

    46     {

    47     TInt iScript;

    48     TInt iRange;

    49     };

    50 class CTruiPtiEngine;

    51 

    52 

    53 

    54 

    55 /**

    56 * CHwrRecognizer class.

    57 * Interface definiton for Hwr.

    58 */

    59 class CHwrRecognizer : 

    60     public CBase,

    61     public MPtiHwrRecognizer

    62     {

    63 public:

    64     /**

    65      * Two phase constructor, create instance of implementation by 

    66      * implementation uid.

    67      *

    68      * @param aImpId The given implementation uid

    69      */

    70     IMPORT_C static CHwrRecognizer* NewL(TInt aImpId);

    71     

    72     /**

    73      * Two phase constructor, create instance of implementation by

    74      * given language.

    75      *

    76      * @param aLanguage The language should be support by implementation instance

    77      * @param aHwrImplUid Carray the implementation uid on return

    78      */

    79     IMPORT_C static CHwrRecognizer* NewL(const TLanguage aLanguage, TUid& aHwrImplUid);

    80     

    81     /**

    82      * Destructor

    83      */

    84     IMPORT_C virtual ~CHwrRecognizer();

    85 

    86     /**

    87      * Get implementation uid list by supplied resolution parameters

    88      *

    89      * @param aMatch Resolution parameters

    90      * @param aImpIdList The array carry the implementation uid list

    91      * @return None

    92      */

    93     IMPORT_C static void ListImplementationsL(const TLanguage aLanguage, RArray<TUid>& aImpIdList);

    94     

    95     /**

    96      * Get supported language list

    97      *

    98      * @param aResult Carry the supported language list on return

    99      * @return None

   100      */

   101     IMPORT_C static void ListAvailableLanguagesL(RArray<TInt>& aResult);

   102     

   103     /**

   104      * Get supported language list of given hwr implementation instance specified by given 

   105      * implementation uid

   106      *

   107      * @param aImpId The given implementation uid

   108      * @param aResult Carry the supported language list on return

   109      * @return None

   110      */

   111     IMPORT_C static void ListGivenAvailableLanguagesL(TUid aImpId, RArray<TInt>& aResult);

   112     

   113     // from MPtiHwrRecognizer

   114     /**

   115      * Set Hwr to given recognition range

   116      *

   117      * @param aRange Given recognition range

   118      * @return KErrNone means successfully, otherwise system wide error codes

   119      */

   120     IMPORT_C TInt SetRange(const TRecognitionRange& aRange);

   121 

   122     /**

   123      * Get current recognition range of hwr engine

   124      *

   125      * @return Current recognition range

   126      */

   127     IMPORT_C TRecognitionRange GetRange();

   128 

   129     /**

   130      * Appends an auxiliary range

   131      *

   132      * @param aRange The auxiliary range to be appended

   133      * @return KErrNone means successfully, otherwise system wide error codes

   134      */

   135     IMPORT_C TInt AddAuxiliaryRange (const TRecognitionRange& aRange);

   136     

   137     /**

   138      * Remove all auxiliary recognition ranges

   139      *

   140      * @return None

   141      */

   142     IMPORT_C void RemoveAllAuxRange ();

   143     

   144     /**

   145      * Remove an specified auxiliary recognition range.

   146      *

   147      * @param aIndex The index of auxiliary range to be deleted

   148      * @return KErrNone means successfully, otherwise system wide error codes

   149      */

   150     IMPORT_C TInt RemoveAuxiliaryRange (TInt aIndex);

   151     

   152     /**

   153      * Set the number of primary candidate candidates the HWR engine should 

   154      * return each time

   155      *

   156      * @param aNumber The number of primary candidates that HWR engine should 

   157      * return each time

   158      * @return KErrNone means successfully, otherwise means aNumber is illegal

   159      */

   160     IMPORT_C TInt SetCandidateNum(TInt aNumber);

   161 

   162     /**

   163      * Retrieve the current primary candidate number need to be returned 

   164      * each time

   165      *

   166      * @return The number of primary candidate characters which engine returns 

   167      * each time

   168      */

   169     IMPORT_C TInt GetCandidateNum() const;

   170     

   171     /**

   172      * Get the stroke end mark 

   173      *

   174      * @return Current stroke end mark

   175      */

   176     IMPORT_C TPoint StrokeEndMark () const;

   177     

   178     /**

   179      * Get the character candidates from the HWR engine based on the input strokes 

   180      *

   181      * @param aTraceData The array of pen trace points, each stroke is ended by 

   182      * stroke end mark

   183      * @param aResult Candidate buffer array

   184      * @return KErrOutOfMem if out of memory, otherwise number of the primary 

   185      * candidate in the candidate list

   186      */

   187     IMPORT_C TInt Recognize(const RArray<TPoint>& aTraceData, RPointerArray<HBufC>& aResult);

   188 

   189     /**

   190      * Tell the HWR engine about the size of the writing area used to 

   191      * input character 

   192      *

   193      * @param aSize The size of writing area

   194      * @return KErrNone means operation succeed, otherwise system wide error codes

   195      */

   196     IMPORT_C TInt SetInputAreaSize(TSize& aSize);

   197 

   198     /**

   199      * Retrieve an ASCII string that describes the version information 

   200      * of the current HWR engine

   201      *

   202      * @param aVersion Contains the engine version string on return

   203      * @return KErrNone means operation succeed, otherwise system wide error codes

   204      */

   205     IMPORT_C TInt GetEngineVersion(TDes& aVersion);

   206     

   207     /**

   208      * Retrieve an ASCII string that describes the version information 

   209      * of the basic recognition dictionary

   210      *

   211      * @param aVersion Contains recognition dictionary version string on return

   212      * @return KErrNone means operation succeed, otherwise system wide error codes

   213      */

   214     IMPORT_C TInt GetDictVersion(TDes& aVersion);

   215 

   216     /**

   217      * Enable or disable word recognition

   218      *

   219      * @param aFlag The word recognition flag, ETrue if enable word recognition, 

   220      * otherwise EFalse

   221      * @return None

   222      */

   223     IMPORT_C void EnableWordRecognition(const TBool aFlag);

   224     

   225     /**

   226      * Specify whether small case or upper case letter will be the first one 

   227      * in candidate list when the first two letters are the same if case is ignored

   228      * 

   229      * @param aOrder EUpperFirst if user wants upper case letter in the first, 

   230      * otherwise ELowerFirst

   231      * @return None

   232      */

   233     IMPORT_C void SetFirstLetterOrder (const TLatinLetterOrder aOrder);

   234 

   235     /**

   236      * Set number mode

   237      * 

   238      * @param aNumberMode Given number mode

   239      * @return None

   240      */

   241     IMPORT_C void SetNumberMode(const TAknEditorNumericKeymap aNumberMode);

   242 

   243     /**

   244      * Set position of HWR top guideline

   245      * 

   246      * @param aPos Position to be set

   247      * @return None

   248      */

   249     IMPORT_C void GetTopGuideLinePos(TInt& aPos);

   250 

   251     /**

   252      * Set position of HWR bottom guideline

   253      * 

   254      * @param aPos Position to be set

   255      * @return None

   256      */

   257     IMPORT_C void GetBottomGuideLinePos(TInt& aPos);

   258     

   259     /**

   260      * Set permitted recognized character set

   261      * 

   262      * @param aPos Position to be set

   263      * @return None

   264      */

   265     IMPORT_C void SetPermittedSymbolSet(const TDesC& aSymbolSet);

   266     

   267     /**

   268      * Get the character candidates from the HWR engine based on the input strokes 

   269      *

   270      * @param aTraceData The array of pen trace points, each stroke is ended by 

   271      * stroke end mark

   272      * @param aResult Candidate buffer array

   273      * @param aCharSet The small charset that primary range candidate should come from

   274      * @return KErrOutOfMem if out of memory, otherwise number of the primary 

   275      * candidate in the candidate list

   276      */

   277     IMPORT_C TInt RecognizeWithCharSet(const RArray<TPoint>& aTraceData, RPointerArray<HBufC>& aResult, const TDesC& aCharSet);

   278     

   279     /**

   280      * Set the number of each secondary candidates the HWR engine should 

   281      * return each time

   282      *

   283      * @param aNumber The number of each secondary candidates that HWR engine should 

   284      * return each time

   285      * @return KErrNone means successfully, otherwise means aNumber is illegal

   286      */

   287     IMPORT_C TInt SetAuxCandidateNum(TInt aNumber);

   288     

   289     /**

   290      * Retrieve the current each secondary candidate number need to be returned 

   291      * each time

   292      *

   293      * @return The number of secondary candidate characters which engine returns 

   294      * each time

   295      */

   296     IMPORT_C TInt GetAuxCandidateNum() const;

   297     

   298     /**

   299      * Retrieve MTruiEngine interface pointer if the derived engine support UDM feature.

   300      *

   301      * @return The pointer of MTruiEngine if success.

   302      */

   303     IMPORT_C MTruiEngine* QueryUdmInterfaceL();

   304     

   305     /**

   306      * Tell the engine that a new MCR session has been started.

   307      *

   308      * @return None.

   309      */

   310     IMPORT_C void McrBeginSessionL();

   311     

   312         /**

   313      * Get the character candidates from the HWR engine based on the input strokes by MCR

   314      *

   315      * @param aTraceData The array of pen trace points, each stroke is ended by 

   316      * stroke end mark

   317      * @param aResult Candidate buffer array

   318      * @return KErrOutOfMem if out of memory, otherwise number of the primary 

   319      * candidate in the candidate list

   320      */

   321     IMPORT_C void McrAddStrokesL(const RArray<TPoint>& aTraceData, RPointerArray<HBufC>& aResult);

   322     

   323     

   324     /**

   325      * Tell the engine that a new MCR session need to be ended, return the last result.

   326      *

   327      * @return None.

   328      */

   329     IMPORT_C void McrEndSessionL( RPointerArray<HBufC>& aResult );

   330 

   331     /**

   332      * Check wether the new symbol model is valid.

   333      *

   334      * @param aSymbolName The name of the symbol name.

   335      * @param aStrokes Store the strokes for the model.

   336      * @param aScriptType The script that the model shall belongs to  . 

   337      * @param aSimilarSymbol Store the characters recognized by aStrokes

   338      * @return KErrNone if the model is accpeted by the engine, otherwise err codes

   339      */

   340     IMPORT_C virtual TInt SymbolModelValid(  const TDesC& aSymbolName, const RArray<TPoint>& aStrokes, THwrUdmRange aScriptType, TDes& aSimilarSymbol );

   341     /**

   342      * Tell the engine whether to use dictionary when doing reconition.

   343      * @param aFlag ETrue to enable recognition dictionary, and EFalse to diable.

   344      * @return KErrNone means operation succeed, otherwise system wide error codes

   345      */

   346     IMPORT_C TInt EnableRecognitionDictionary(const TBool aFlag);  

   347     /**

   348      * Tell the HWR engine about the size of the touch screen 

   349      * 

   350      *

   351      * @param aSize The size of touch screen

   352      * @return KErrNone means operation succeed, otherwise system wide error codes

   353      */  

   354     IMPORT_C TInt SetScreenSize(TSize& aSize);       

   355     /**

   356      * Tell the HWR engine whether guideline is on.

   357      * 

   358      *

   359      * @param aFlag ETrue to enable guideline, and EFalse to diable.

   360      * @return KErrNone means operation succeed, otherwise system wide error codes

   361      */  

   362     IMPORT_C TInt EnableGuideline(const TBool aFlag);    

   363 protected:

   364     

   365     /**

   366      * Retrieve whether the derived engine support UDM feature.

   367      *

   368      * @return ETrue if support.

   369      */

   370     IMPORT_C virtual  TBool IsSupportUdm() const;

   371     

   372     /**

   373      * Load the aType models to memory.

   374      *

   375      * @param aType Shall set with the value TUdmType 

   376      * @return none

   377      */

   378     IMPORT_C   void LoadUdmL( TUdmType aType );

   379     

   380     /**

   381      * Free the momory of the aType models

   382      *

   383      * @param aType Shall set with the value TUdmType 

   384      * @return none

   385      */

   386     IMPORT_C   void UnLoadUdmL( TUdmType aType );

   387     

   388     /**

   389      * Get the filterd models by THwrUdmRange, return the indexes.

   390      *

   391      * @param aType Shall set with the value TUdmType 

   392      * @param aList Store the indexes that fulfil the aRange

   393      * @param aRange Sepcifiy the rules that the modles shall belong to.

   394      * @return none

   395      */

   396     IMPORT_C   void GetModelIndexListL(TUdmType aType, RArray<TInt>& aList, const THwrUdmRange& aRange );

   397     

   398     /**

   399      * Get the filterd models by THwrUdmRange, return the indexes.

   400      *

   401      * @param aType Shall set with the value TUdmType 

   402      * @param aIndex The index of the model.

   403      * @param aSymbolName Sepcifiy the rules that the modles shall belong to.

   404      * @param aModel Store the strokes for the model.

   405      * @param aHelpLine Store the helpline. 

   406      * @param aBaseLine Store the baseline.

   407      * @return none

   408      */

   409     IMPORT_C   void GetSymbolModelL(TUdmType aType, TInt aIndex, TPtrC& aSymbolName,RArray<TPoint>& aModel, TInt& aHelpLine, TInt& aBaseLine );

   410     

   411 private:

   412 

   413     /**

   414      * Utitlity function, parse a string to range values

   415      * 

   416      * @param aRangeData The string to convert

   417      * @param aLowerValue The lower bound value.

   418      * @param aUpperValue The upper bound value.

   419      * @param aRadix The number system representation for the integer

   420      * @since S60 v3.2

   421      *

   422      * @return None

   423      */

   424     void static GetRanges(const TDesC8& aRangeData, TInt& aLowerValue, TInt& aUpperValue);

   425     

   426     /**

   427      * Utitlity function, extract the languages and append them to array

   428      * 

   429      * @param aImplementationData The string to extract.

   430      * @param aResult The result array that need to append.

   431      * @since S60 v3.2

   432      *

   433      * @return None.

   434      */

   435     void static AppendMatchedLanguagesL(const TDesC8& aImplementationData, RArray<TInt>& aResult);

   436     

   437     /**

   438      * Utitlity function, indicates whether the value is included

   439      * in a string.

   440      * 

   441      * @param aImplementationData The string to test.

   442      * @param aValue The value to test.

   443      * @since S60 v3.2

   444      *

   445      * @return ETrue if match, otherwise EFalse.

   446      */

   447     TBool static Match(const TDesC8& aImplementationData, TInt aValue);

   448 

   449 private:

   450 

   451     /**

   452      * instance identifier key

   453      */

   454     TUid iDtor_ID_Key;

   455     

   456     CTruiPtiEngine* iUdmEngine;

   457     

   458     

   459     };

   460     

   461 /**

   462  * This class declares the hwr recognizer

   463  * Purpose of this class is to save some information of active hwr recognizer

   464  *

   465  * @since S60 v4.0

   466  */  

   467 class CPtiHwrRecognizer : public CBase

   468     {

   469 public: // data

   470 

   471     /**

   472      * Destructor

   473      */

   474     ~CPtiHwrRecognizer();

   475 

   476     /**

   477      * The pointer points to current active hwr implementation

   478      */

   479     CHwrRecognizer* iHwrRecognizer;

   480             

   481     /**

   482      * The languages list that current active hwr implementation supports

   483      */

   484     RArray<TInt> iHwrLanguagesList;

   485 	    

   486     /**

   487      * The implementation uid of current active hwr implementation

   488      */

   489     TUid iHwrImpId;

   490     };

   491 

   492 #endif //  _PTI_HWRRECOGNIZER_H