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_MHWRRECOGNIZER_H

    33 #define _PTI_MHWRRECOGNIZER_H

    34 

    35 // INCLUDES

    36 #include <badesca.h>

    37 #include <PtiDefs.h>

    38 #include <eikon.hrh>

    39 

    40 // public sdk

    41 enum TPtiHwrScriptType

    42     {

    43     EPtiHwrScriptBegin = ELangMaximum,

    44     EPtiHwrScriptLatin,

    45     EPtiHwrScriptCyrillic,

    46     EPtiHwrScriptGreek,

    47     EPtiHwrScriptHebrew,

    48     EPtiHwrScriptArabic,

    49     EPtiHwrScriptAny = ELangMaximum + 200   

    50     };

    51 

    52 enum TPtiHwrRange

    53     {

    54     EPtiHwrRangeLanguage = 1,

    55     EPtiHwrRangeSymbol,

    56     EPtiHwrRangeNumber,

    57     EPtiHwrRangeAny = EPtiHwrRangeLanguage + 100

    58     };   

    59     

    60     

    61 /**

    62  *  MTruiEngine class.

    63  *  The interface between HWR engine and TrainUI application

    64  */

    65 class MTruiEngine

    66     {

    67 public:

    68     /**

    69      * Set current trained character's Language Script

    70      *

    71      * @param aLanguageScript current trained character's Language Script

    72      */

    73     virtual void SetLanguageScriptL( TInt aLanguageScript ) = 0;

    74     

    75     /**

    76      * Check if character has model

    77      *

    78      * @param aChar The character which is checked

    79      * @return TBool True means this character has model

    80      *               False means this character doesn't has model yet

    81      */

    82     virtual TBool CharacterModelExist( const TDesC& aChar ) = 0;

    83     

    84     /**

    85      * Get character model

    86      *

    87      * @param aChar Get this character's model

    88      * @param aModel Array of points where the character's model is stored.

    89      * @return TInt Error value. If no error occurred, KErrNone is returned

    90      */

    91     virtual void GetCharacterModelL( const TDesC& aChar,

    92                                     RArray<TPoint>& aModel ) = 0;

    93     

    94     /**

    95      * Set character model

    96      *

    97      * @param aChar Set model to this character

    98      * @param aModel Array of points where the character's model is stored.

    99      * @aSubRange Shall set the value to TPtiHwrRange.

   100      * @aSimilarChar if not accepted by engine, store the conflict char

   101      * @return TInt Error value. If no error occurred, KErrNone is returned

   102      */

   103     virtual void SetCharacterModelL( const TDesC& aChar,

   104                                     RArray<TPoint>& aModel , TInt aSubRange, TDes& aSimilarChar ) = 0;

   105     

   106     /**

   107      * Delete character model

   108      *

   109      * @param aChar Delete this character's model

   110      * @return TInt Error value. If no error occurred, KErrNone is returned

   111      */

   112     virtual TInt DeleteCharacterModel( const TDesC& aChar ) = 0;   

   113     

   114     /**

   115      * Get text list of all the shortcuts

   116      *

   117      * @param aShortcutTextList The text list.

   118      * @return TInt Error value. If no error occurred, KErrNone is returned

   119      */

   120     virtual void GetShortcutTextListL( RPointerArray<HBufC>& aShortcutTextList ) = 0;

   121     

   122     /**

   123      * Check if shortcut has model

   124      *

   125      * @param aText The shortcut which is checked

   126      * @return TBool True means this shortcut has model

   127      *               False means this shortcut doesn't has model yet

   128      */

   129     virtual TBool CheckShortcutModel( const TDesC& aText ) = 0;

   130     

   131     /**

   132      * Get trails assigned to the specified shortcut.

   133      * 

   134      * @param aText The specified shortcut text

   135      * @param aModel Trails of the shortcut.

   136      * @param aUnicode The assigned preset text if it is a preset shortcut,

   137      *        otherwise, it is 0;     

   138      */

   139     virtual void GetShortcutModelL( const TDesC& aText, 

   140                             RArray<TPoint>& aModel, TUint& aUnicode ) = 0;

   141     

   142     /**

   143      * Set Shortcut model

   144      *

   145      * @param aText Set model to this Shortcut

   146      * @param aModel Array of points where the Shortcut's model is stored.

   147      * @param aSimilarText Store the conflict text if exist.

   148      * @return void.

   149      */

   150     virtual void SetShortcutModelL( const TDesC& aText,

   151                               RArray<TPoint>& aModel, TDes& aSimilarText ) = 0;

   152     

   153     /**

   154      * Delete Shortcut model

   155      *

   156      * @param aText Delete this Shortcut's model

   157      * @return TInt Error value. If no error occurred, KErrNone is returned

   158      */

   159     virtual TInt DeleteShortcutModel( const TDesC& aText ) = 0;

   160     

   161     /**

   162      * Change the text of an existing shortcut

   163      *

   164      * @param aOldText The text of an existing shortcut

   165      * @param aNewText The new text of the shortcut

   166      * @return none

   167      */

   168     virtual void ChangeShortcutTextL( const TDesC& aOldText,

   169                                      const TDesC& aNewText ) = 0;

   170 

   171 

   172     /**

   173      * Get guiding line pos

   174      * 

   175      * @aSize The are

   176      * @param aTop The vertical coordinate of top guiding line

   177      * @param aBottom The vertical coordinate of bottom guiding line

   178      * @return TInt Error value. If no error occurred, KErrNone is returned

   179      */

   180     virtual TInt GetGuidingLinePos( const TSize& aSize, TInt& aTop , TInt&  aBottom) = 0; 

   181 

   182     /**

   183      * Get the number of the maximum of shortcuts

   184      *

   185      * @return TInt The number of the maximum of shortcuts

   186      */

   187     virtual TInt MaxShortCutLength() = 0; 

   188 

   189     /**

   190      * Save preset shortcuts.

   191      * 

   192      * @param aUnicode The assigned preset text.

   193      * @param aShortcut The shortcut to be save.

   194      */

   195     virtual void SavePresetShortcutL( TUint aUnicode, const TDesC& aShortcut ) = 0;

   196     

   197     /**

   198      * Return all unicodes of preset text stored in PTI engine

   199      * 

   200      * @param aPresets All preset text's unicodes are stored in this array.     

   201      */

   202     virtual void GetAllPresetSymbolsL( RArray<TUint>& aPresets ) = 0;  

   203     

   204     /**

   205      * Get trails assigned to a preset text.

   206      * 

   207      * @param aUnicode The unicode of the preset text.

   208      * @param aModel Store trails of the preset text.

   209      * @param aShortcut Indicate whether the preset text has been assigned to a shortcut text.

   210      *        If KNullDesC, it is not in use.

   211      */

   212     virtual void GetPresetSymbolByUnicodeL( TUint aUnicode, RArray<TPoint>& aModel, TDes& aShortcut ) = 0;  

   213     };

   214     

   215     

   216 /**

   217 * MHwrRecognizer class.

   218 * Interface definiton for Hwr.

   219 */

   220 class MPtiHwrRecognizer

   221     {

   222 public:

   223     // pure hwr interface

   224     /**

   225      * Set Hwr to given recognition range

   226      *

   227      * @param aRange Given recognition range

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

   229      */

   230     virtual TInt SetRange(const TRecognitionRange& aRange) = 0;

   231 

   232     /**

   233      * Get current recognition range of hwr engine

   234      *

   235      * @return Current recognition range

   236      */

   237     virtual TRecognitionRange GetRange() = 0;

   238 

   239     /**

   240      * Appends an auxiliary range

   241      *

   242      * @param aRange The auxiliary range to be appended

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

   244      */

   245     virtual TInt AddAuxiliaryRange (const TRecognitionRange& aRange) = 0;

   246     

   247     /**

   248      * Remove all auxiliary recognition ranges

   249      *

   250      * @return None

   251      */

   252     virtual void RemoveAllAuxRange () = 0;

   253     

   254     /**

   255      * Remove an specified auxiliary recognition range.

   256      *

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

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

   259      */

   260     virtual TInt RemoveAuxiliaryRange (TInt aIndex) = 0;

   261     

   262     /**

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

   264      * return each time

   265      *

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

   267      * return each time

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

   269      */

   270     virtual TInt SetCandidateNum(TInt aNumber) = 0;

   271 

   272     /**

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

   274      * each time

   275      *

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

   277      * each time

   278      */

   279     virtual TInt GetCandidateNum() const = 0;

   280     

   281     /**

   282      * Get the stroke end mark 

   283      *

   284      * @return Current stroke end mark

   285      */

   286     virtual TPoint StrokeEndMark() const = 0;

   287     

   288     /**

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

   290      *

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

   292      * stroke end mark

   293      * @param aResult Candidate buffer array

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

   295      * candidate in the candidate list

   296      */

   297     virtual TInt Recognize(const RArray<TPoint>& aTraceData, RPointerArray<HBufC>& aResult) = 0;

   298 

   299     /**

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

   301      * input character 

   302      *

   303      * @param aSize The size of writing area

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

   305      */

   306     virtual TInt SetInputAreaSize(TSize& aSize) = 0;

   307 

   308     /**

   309      * Retrieve an ASCII string that describes the version information 

   310      * of the current HWR engine

   311      *

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

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

   314      */

   315     virtual TInt GetEngineVersion(TDes& aVersion) = 0;

   316     

   317     /**

   318      * Retrieve an ASCII string that describes the version information 

   319      * of the basic recognition dictionary

   320      *

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

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

   323      */

   324     virtual TInt GetDictVersion(TDes& aVersion) = 0;

   325 

   326     /**

   327      * Enable or disable word recognition

   328      *

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

   330      * otherwise EFalse

   331      * @return None

   332      */

   333     virtual void EnableWordRecognition(const TBool aFlag) = 0;

   334     

   335     /**

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

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

   338      * 

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

   340      * otherwise ELowerFirst

   341      * @return None

   342      */

   343     virtual void SetFirstLetterOrder (const TLatinLetterOrder aOrder) = 0;

   344 

   345     /**

   346      * Set number mode

   347      * 

   348      * @param aNumberMode Given number mode

   349      * @return None

   350      */

   351     virtual void SetNumberMode(const TAknEditorNumericKeymap aNumberMode) = 0;

   352     

   353     /**

   354      * Set position of HWR top guideline

   355      * 

   356      * @param aPos Position to be set

   357      * @return None

   358      */

   359     virtual void GetTopGuideLinePos(TInt& aPos) = 0;

   360 

   361     /**

   362      * Set position of HWR bottom guideline

   363      * 

   364      * @param aPos Position to be set

   365      * @return None

   366      */

   367     virtual void GetBottomGuideLinePos(TInt& aPos) = 0;

   368     

   369     /**

   370      * Set permitted recognized character set

   371      * 

   372      * @param aSymbolSet Permitted recognized character set

   373      * @return None

   374      */

   375     virtual void SetPermittedSymbolSet(const TDesC& aSymbolSet) = 0;    

   376 

   377     /**

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

   379      *

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

   381      * stroke end mark

   382      * @param aResult Candidate buffer array

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

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

   385      * candidate in the candidate list

   386      */

   387     virtual TInt RecognizeWithCharSet(const RArray<TPoint>& aTraceData, RPointerArray<HBufC>& aResult, const TDesC& aCharSet) = 0;

   388     

   389     /**

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

   391      * return each time

   392      *

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

   394      * return each time

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

   396      */

   397     virtual TInt SetAuxCandidateNum(TInt aNumber) = 0;

   398     

   399     /**

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

   401      * each time

   402      *

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

   404      * each time

   405      */

   406     virtual TInt GetAuxCandidateNum() const = 0;

   407     

   408     /**

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

   410      *

   411      * @return The pointer of MTruiEngine if success.

   412      */

   413     virtual MTruiEngine* QueryUdmInterfaceL()  = 0;

   414     

   415     /**

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

   417      *

   418      * @return None.

   419      */

   420     virtual void McrBeginSessionL() = 0;

   421     

   422         /**

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

   424      *

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

   426      * stroke end mark

   427      * @param aResult Candidate buffer array

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

   429      * candidate in the candidate list

   430      */

   431     virtual void McrAddStrokesL(const RArray<TPoint>& aTraceData, RPointerArray<HBufC>& aResult) = 0;

   432     

   433     /**

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

   435      *

   436      * @return None.

   437      */

   438     virtual void McrEndSessionL( RPointerArray<HBufC>& aResult ) = 0;

   439     /**

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

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

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

   443      */

   444     virtual TInt EnableRecognitionDictionary(const TBool aFlag) = 0;

   445     /**

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

   447      * 

   448      *

   449      * @param aSize The size of touch screen

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

   451      */  

   452     virtual TInt SetScreenSize(TSize& aSize) = 0;   

   453     /**

   454      * Tell the HWR engine whether guideline is on.

   455      * 

   456      *

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

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

   459      */  

   460     virtual TInt EnableGuideline(const TBool aFlag) = 0;    

   461     };

   462 

   463     

   464 #endif  //_PTI_MHWRRECOGNIZER_H