Contents

• Purpose
  • Constraints
  • Classification and release information
  • Emulator support
• API Description
  • Use Case
  • PtiEngine design
  • User dictionary
  • Observer
  • Language databases
• Using the PtiEngine API
  • Initializing PtiEngine
    • Multitapping
    • Predictive
    • Numeric
    • Pinyin
    • Stroke
    • Zhuyin
    • Pinyin phrase
    • Zhuyin phrase
    • CangJie
    • QWERTY
    • Chinese QWERTY
    • Japanese input modes
  • Entering text in Latin multitapping mode
  • Entering text in Latin predictive mode
  • Querying and activating installed languages
  • Numeric language
  • Changing Input modes and Text cases
  • User dictionary
  • Keymappings
• Glossary
  • Abbreviations
  • Definitions

Constraints

None.

Classification and release information

This API is an SDK API and was first published in S60 3rd Edition.

Emulator support

This API is fully supported in the WINS/WINSCW emulator environment.

Use Case

With PtiEngine API, typical use cases are

• Initializing PtiEngine

• Entering text in Latin multitapping mode.

• Entering text in Latin predictive mode.

• Querying and activating installed languages.

• Numeric language

• Changing input modes and text cases.

• User dictionary

• Keymappings

PtiEngine design

The class CPtiEngine implements the PtiEngine client side API. It is a thin wrapper class and acts only as an API front-end CPtiEngine is the main class for PtiEngine API. The client application creates an instance of this class when it wants to use PtiEngine API. The CPtiEngine class has the following responsibilities:

• Maintain the language list

• Forward the API function calls to the correct core object depending on the selected input mode and language

• Maintain the list of active user dictionaries (see next chapter) and secondary core related data files

• Below figure shows the main classes of PtiEngine API. The figure shows logical relations. In the PtiEngine API, most objects are accessible via M mixin classes. In the plug-in API, C or T counterpart of the corresponding M mixin classes are used.

• CPtiEngine

User dictionary

Typically third party text input engines are delivered with a language databases containing a list of the most frequently used words for each language. These default language databases are usually optimized to be as small as possible, which also means that the number of words in them is more or less limited. There are always words (such as names, abbreviations, etc.) that are related to a specific user and cannot be included into the default language databases by the engine vendor. Prediction engines typically support some kind of user dictionary mechanism for expanding default language databases. The PtiEngine user dictionary is a set of words that can be dynamically attached to the default language database. Once a user dictionary is attached, its entries are available as candidates in prediction result data in a same way as the entries from the default language databases. Some prediction engines allow several user dictionaries to be attached simultaneously.

PtiEngine API supports two kinds of user dictionaries: default and additional. The default user dictionary is something that a core object automatically loads and sets up when an instance of PtiEngine is created. The client application does not need to know the filename or the location for the default user dictionary file. Additional user dictionaries can be attached independently using the CPtiEngine->AttachUserDictionary() method. In that case the client application must know the full name of the user dictionary file. There can be as many additional user dictionaries as the core object allows (it is possible that none are allowed), but only one default dictionary per core object.

The client does not know the location of the default dictionary and if client wants to create an additional dictionary, add it to the core, then client would know the location of the dictionary that is added.

• CPtiEngine->AttachUserDictionary()

Observer

PtiEngine observer is used for indicating the client application when multitapping timer expires, last item in prediction candidate list is reached, first item in prediction candidate list is reached. If the client application needs to observe PtiEngine, it must inherit the MPtiObserver interface class and call the CPtiEngine->SetObserver() method.

• CPtiEngine->SetObserver()
• MPtiObserver

Language databases

Core (third party text input engine) objects may implement their language data in any format they wish, PtiEngine also provides a wrapper class for scanning, loading and accessing language data. It is recommended that a core object uses MPtiLanguageDatabase interface instead of implementing its own. Language database, The default implementation is provided in the class CPtiLanguageDatabase . The core object language database implementation should inherit from latter.

• CPtiLanguageDatabase
• MPtiLanguageDatabase

Initializing PtiEngine

Predictive Text Input Engine is created and initialized by using the following method:

             
              static CPtiEngine* NewL(TBool aUseDefaultUserDictionary = EFalse)
             
            

When this method is called, it creates an instance of the CPtiEngine class, initializes the default core object and connects it to the CPtiEngine object. The default core object scans available multitapping and QWERTY resource files, updates the language list and prepares to handle multitapping, QWERTY and numeric input modes. Then it does the ECom plug-in query for other available core objects and initializes the found plug-ins in a similar way.

The Boolean parameter aUseDefaultUserDictionary specifies whether core objects are instructed to load and attach their default user dictionaries. This parameter applies to all core objects for the whole lifetime of the CPtiEngine instance.

After this method is successfully called, PtiEngine is ready to be used but at this point there is not an active language yet, so most of the PtiEngine API methods would return an error value (usually KErrNoActiveLanguage ). The client application must call the method

             
              TInt ActivateLanguageL(TInt aEpocLanguageID, TPtiEngineInputMode aMode = EPtiEngineInputModeNone)
             
            

to activate one of the available languages. PtiEngine is set to the aMode input mode. Available input modes are explained in the following sections.

             
                  CPtiEngine* eng = CPtiEngine::NewL( ETrue );
              

                  CleanupStack::PushL( eng );
              

                  
              

                  //Active english input with multitapping mode
              

                  eng->ActivateLanguageL(ELangEnglish,EPtiEngineMultitapping);
              

                  .......
              

                  eng->CloseCurrentLanguageL();//close the language
              

                  
              

                  CleanupStack::Pop(eng);
              

                  delete eng;    
             
            

• CPtiEngine
• KErrNoActiveLanguage
• aMode
• aUseDefaultUserDictionary

Entering text in Latin multitapping mode

The multitapping input mode ( EPtiEngineMultitapping ) implements the basic multitapping input for ITU-T keyboard. This is the traditional text input mode, where the user may need to press one key several times to input the requested character. The basic use case for inputting one character is presented in next figure .

The below code fragment shows how to input text "dog" to PtiEngine using multitapping input mode.

             
                 CPtiEngine* eng = CPtiEngine::NewL();
              

                 CleanupStack::PushL(eng);
              

                 
              

                 ....
              

                 eng->ActivateLanguageL(ELangEnglish, EPtiEngineMultitapping);
              

                 eng->AppendKeyPress(EPtiKey3);
              

                 eng->AppendKeyPress(EPtiKey6);
              

                 eng->AppendKeyPress(EPtiKey6);
              

                 eng->AppendKeyPress(EPtiKey6);
              

                 eng->AppendKeyPress(EPtiKey4);
              

                 TBuf<100> temp;
              

                 temp.Copy(eng->CurrentWord()); // At this point temp would contain word "dog"
              

                 ....
              

                 
              

                 eng->CloseCurrentLanguageL();
              

                 
              

                 CleanupStack::Pop(eng);
              

                 delete eng;
             
            

• EPtiEngineMultitapping

Entering text in Latin predictive mode

The predictive input mode ( EPtiEngineMultitapping ) implements the predictive text input. In this input, instead of cycling through characters bound to keys, the user presses each key only once and Predictive Text Input Engine tries to guess which word the user is inputting. Usually Predictive Text Input Engine returns several candidates for each input sequence. The basic use case for entering one key and returning the topmost candidate for it is presented in next figure.

The below code fragment shows how to input text "this" to PtiEgine using predictive input mode.

             
                 CPtiEngine* eng = CPtiEngine::NewL();
              

                  CleanupStack::PushL(eng);
              

                  
              

                  ....
              

                  eng->ActivateLanguageL(ELangEnglish, EPtiEnginePredictive);
              

                  eng->AppendKeyPress(EPtiKey8);
              

                  eng->AppendKeyPress(EPtiKey4);
              

                 eng->AppendKeyPress(EPtiKey4);
              

                 eng->AppendKeyPress(EPtiKey7);
              

                 TBuf<100> temp; 
              

                 temp.Copy(eng->CurrentWord()); // At this point temp would contain(depending on the underlying engine) word "this". 
              

                 temp.Copy(eng->NextCandidate()); // Move on to next candidate. 
              

                 eng->CommitCurrentWord(); // Tell engine that current word was accepted.
              

                 ....
              

                 eng->CloseCurrentLanguageL();
              

                  
              

                 CleanupStack::Pop(eng);
              

                 delete eng;
             
            

• EPtiEngineMultitapping

Querying and activating installed languages

PtiEngine can query for the list of installed languages and can activate any of the installed languages with a particular input mode. The client application must call the method

             
              TInt ActivateLanguageL(TInt aEpocLanguageID, TPtiEngineInputMode aMode = EPtiEngineInputModeNone)
             
            

to activate one of the available languages. If ActivateLanguageL is called without passing any TPtiEngineInputMode (default mode is EPtiEngineInputModeNone ), client has to call SetInputMode separately to set the desired input mode.

             
                  CPtiEngine* eng = CPtiEngine::NewL( ETrue );
              

                  CleanupStack::PushL( eng );
              

                  
              

                  if ( eng->NumberOfLanguages() )
              

                      {
              

                      RArray<TInt> languages;
              

                    eng->GetAvailableLanguagesL( languages );
              

                     ........
              

                      
              

                      // see if finnish language is there in list of available input languages and if "yes", activate finnish input. 
              

                     for(TInt i=0;i<languages.Count();i++)
              

                          {
              

                          if(languages[i] ==ELangFinnish)
              

                              {
              

                              eng->ActivateLanguageL(ELangFinnish,EPtiEngineMultitapping);
              

                              ........
              

                              eng->CloseCurrentLanguageL();
              

                              }
              

                          }   
              

                      languages.Close();
              

                        }
              

                  
              

                CleanupStack::Pop(eng);
              

                delete eng;
             
            

• ActivateLanguageL
• EPtiEngineInputModeNone
• SetInputMode
• TPtiEngineInputMode

Numeric language

When Predictive Text Input Engine is initialized, it creates a special language object called numeric language and adds it to the list of available languages. The numeric language is for those clients who wish to use the numeric input mode without activating a real language. The numeric language implements only one input mode, EPtiEngineNumeric . The numeric language is excluded from the list of available languages returned by the GetAvailableLangugesL method. It is also excluded from the value returned by the NumberOfLanguages method. However it is possible to get access to the numeric language via the GetLanguage method. The numeric language has the language code ELangNumeric and can be activated as follows:

             
                 CPtiEngine* eng = CPtiEngine::NewL();
              

                 CleanupStack::PushL(eng);
              

                 
              

                 ....
              

                 eng->ActivateLanguageL(ELangNumeric, EPtiEngineNumeric);
              

                 eng->AppendKeyPress(EPtiKey8);
              

                 eng->AppendKeyPress(EPtiKey4);
              

                 eng->AppendKeyPress(EPtiKey2);
              

                 eng->AppendKeyPress(EPtiKey7);
              

                 TBuf<100> temp; 
              

                 temp.Copy(eng->CurrentWord());// At this point the temp will contain "8427"
              

                  
              

                 eng->CloseCurrentLanguageL();
              

                  
              

                 CleanupStack::Pop(eng);
              

                 delete eng;
             
            

• ELangNumeric
• EPtiEngineNumeric
• GetAvailableLangugesL
• GetLanguage
• NumberOfLanguages

Changing Input modes and Text cases

The client can change the input mode when ever there is a need for specific input mode. For example, if the user wants to activate the multitapping predictive mode, that can be done using the following method.

             
              CPtiEngine::SetInputMode(TPtiEngineInputMode aMode);
              

              

              //Here aMode can be one of the modes found in enum TPtiEngineInputMode of PtiDefs.h
             
            

In the same way client can change the text case between lower and upper when ever there is a need using the method below.

             
              IMPORT_C void CPtiEngine::SetCase(TPtiTextCase  aCase);
              

                  
              

                  //Here aCase could either be EPtiCaseUpper or EPtiCaseLower.
              

                  
              

                 
              

                 //Code fragment on how to change the Text Case:
              

                  
              

                 CPtiEngine* eng = CPtiEngine::NewL();
              

                 CleanupStack::PushL(eng);
              

                 
              

                 ....
              

                 eng->ActivateLanguageL(ELangEnglish, EPtiEngineMultitapping);
              

                 eng->SetCase(EPtiCaseUpper);
              

                 eng->AppendKeyPress(EPtiKey3);
              

                 eng->AppendKeyPress(EPtiKey6);
              

                 eng->AppendKeyPress(EPtiKey6);
              

                 eng->AppendKeyPress(EPtiKey6);
              

                 eng->AppendKeyPress(EPtiKey4);
              

                 TBuf<100> temp;
              

                 temp.Copy(eng->CurrentWord()); // At this point temp would contain word "DOG"
              

                 ....
              

                 
              

                  eng->CloseCurrentLanguageL();
              

                 
              

                 CleanupStack::Pop(eng);
              

                 delete eng;
             
            

User dictionary

The PtiEngine user dictionary is a set of words that can be dynamically attached to the default language database. Once a user dictionary is attached, its entries are available as candidates in prediction result data in a same way as the entries from the default language databases. Some prediction engines allow several user dictionaries to be attached simultaneously. For more details, refer to User dictionary section of API Description. The below code fragment shows how to add a user dictionary to default language database. The support for adding additional user dictionary is entirely depends up on the core that supports that current language and input mode. But each core will have a default dictionary to which words can be added using API AddUserDictionaryEntry , and pointer to default user dictionary for current language can be get by using API DefaultUserDictionary of CPtiEngine .

             
                  CPtiEngine* eng = CPtiEngine::NewL();
              

                
              

                  CleanupStack::PushL(eng);
              

                eng->ActivateLanguageL(ELangEnglish, EPtiEngineMultitapping);
              

                
              

                CDesCArrayFlat* words = new (ELeave) CDesCArrayFlat(5);
              

                CleanupStack::PushL( words );
              

                words->AppendL(_L("lorem"));
              

                words->AppendL(_L("ipsum"));
              

                words->AppendL(_L("dolor"));
              

                 words->AppendL(_L("sit"));
              

                TBuf<50> filename(_L("C:\\data\\TempUDB\\TestUserDictFile.txt"));
              

                
              

                RFs fsSession;
              

                User::LeaveIfError( fsSession.Connect() );
              

                CleanupClosePushL( fsSession );
              

                
              

                RFile file;
              

                CleanupClosePushL(file);
              

                if ( file.Open( fsSession, filename, EFileWrite | EFileShareAny ) != KErrNone )
              

                      {
              

                      file.Create( fsSession, filename, EFileWrite | EFileShareAny );
              

                      }
              

                  
              

                file.Close();
              

                CleanupStack::PopAndDestroy(2); //file , fsSession
              

                
              

                TInt err  = eng->CreateUserDictionaryL(filename, words, EPtiEnginePredictive);
              

                CleanupStack::PopAndDestroy(words);  //words
              

                
              

                // The above call will add the words "lorem",ipsum","dolor",and "sit" to the user dictonary.
              

                if(KErrNone == err)
              

                      {
              

                      MPtiUserDictionary* dict = eng->AttachUserDictionaryL(filename);
              

                  
              

                  //The above call will attach the created user dictonary to the current core.From now onwards ,     the above 4 words will be
              

                  //predicted by the current active core.
              

                  if(dict)
              

                          {
              

                     TFileName msg;
              

                     TPtiUserDictionaryEntry entry(_L("amet"));
              

                     eng->AddUserDictionaryEntry(entry,dict->Id());  //The above call will add "amet" to the user               dictonary ,so it will be predicted from now on.
              

                     //the prediction engine will start predicting the above added words   ....   
              

                     eng->RemoveEntryFromUserDictionary(entry,dict->Id());  //The above call will remove "amet"            from the user dictornary,so it will not be predicted anymore.
              

                     
              

                     eng->DetachUserDictionary(filename);
              

                     //Above call detaches the dictonery from the current core.
              

                     
              

                     }
              

                      
              

                      }
              

                  eng->CloseCurrentLanguageL();
              

                CleanupStack::Pop(eng);
              

                delete eng;
             
            

• AddUserDictionaryEntry
• CPtiEngine
• DefaultUserDictionary

Keymappings

CPtiKeyMappings class can be used to get the data that is mapped to a particular key ( TPtiKey ) with a particular case ( TPtiTextCase ) and input mode ( TPtiEngineInputMode ). Call the function StartMapping to get the first character that is mapped to the particular key and then call NextKey to get the subsequent mapped characters. We can replace the data that is mapped to a particular key by using the ReplaceKeyMapL function. Next subsequent StartMapping , or NextKey calls for that key returns the newly mapped characters.

             
                  CPtiEngine* eng = CPtiEngine::NewL();
              

                  CleanupStack::PushL(eng);
              

                
              

                  eng->ActivateLanguageL(ELangEnglish, EPtiEngineMultitapping);
              

                
              

                  CPtiKeyMappings * keyMappings = dynamic_cast < CPtiKeyMappings* > (dynamic_cast < CPtiCoreLangua ge* >(eng->CurrentLanguage())->GetKeymappings());
              

                
              

                  TBool isAppend;
              

                  TUint16 key = keyMappings->StartMapping(EPtiKey2,EPtiCaseLower,EPtiEngineMultitapping); // retur    ns the first character that is mapped to EPtiKey2 'a'
              

                  TUint16 key1 = keyMappings->NextKey(EPtiKey2,isAppend,EPtiCaseLower);    // returns the next cha  racter that is mapped to EPtiKey2 'b'
              

                    
              

                  TBuf<20> beforeReplace;
              

                  keyMappings->GetDataForKey(EPtiKey2,beforeReplace,EPtiCaseLower); // gets the first 20 characters     that are mapped to EPtiKey2 for lower case "abc2...."
              

                 
              

                  _LIT(KNewMapLower, "def");
              

                  TBuf<5> lowerMap(KNewMapLower);
              

                  keyMappings->ReplaceKeyMapL(EPtiKey2,lowerMap,EPtiCaseLower); // replaces the data that is mapped    to EPtiKey2 for lower case
              

                    
              

                  TUint16 key2 = keyMappings->StartMapping(EPtiKey2,EPtiCaseLower,EPtiEngineMultitapping);// retur ns the first character that is mapped to EPtiKey2 'd'
              

                  TUint16 key3 = keyMappings->NextKey(EPtiKey2,isAppend,EPtiCaseLower); // returns the first chara cter that is mapped to EPtiKey2 'e'
              

                
              

                  TBuf<20> afterReplace;
              

                  keyMappings->GetDataForKey(EPtiKey2,beforeReplace,EPtiCaseLower);  // gets the first 20 characte  rs that are mapped to EPtiKey2 for lower case "def"
              

                    
              

                  eng->CloseCurrentLanguageL();
              

                  
              

                  eng->ActivateLanguageL(ELangEnglish, EPtiEngineHalfQwerty);
              

                  
              

                  CPtiHalfQwertyKeyMappings * keyHalfQwertyMappings = dynamic_cast< CPtiHalfQwertyKeyMappings*> (d    ynamic_cast< CPtiCoreLanguage* >(eng->CurrentLanguage())->GetHalfQwertyKeymappings());
              

                  
              

                  TUint16 key4 = keyHalfQwertyMappings->StartMapping(EPtiKeyQwertyA,EPtiCaseFnLower,EPtiEngineHalf  Qwerty);
              

                  // returns the first functionalized character that is mapped to EPtiKeyQwertyA '?'
              

                  
              

                  eng->CloseCurrentLanguageL();
              

                  
              

                  CleanupStack::Pop(eng);
              

                  delete eng;
             
            

• CPtiKeyMappings
• NextKey
• ReplaceKeyMapL
• StartMapping
• TPtiEngineInputMode
• TPtiKey
• TPtiTextCase

Abbreviations

FEP	Front End Processor
UI	User Interface

Definitions

PtiEngine	Predictive Text Input Engine
Multitapping	The conventional text input method for mobile phones where often several key presses are required to insert a single character.
Predictive text input	Text input method where the text input software tries to guess the correct words simultaneously when the user is typing them. Its purpose is to decrease the number of required key presses and to make text input faster and easier.
Input sequence	The sequence of key presses. Predictive Text Input Engine may produce several candidate words for a single input sequence.