PTI Engine API: API Description

PtiEngine API provides text input services for various languages and input modes, in a unified API. This view of the API is called client API. See details in Section Client API (CPtiEngine).

Text input services are extensible using the plug-in API. Clients wishing to extend text input with new languages and/or input modes will implement and deploy plug-ins. See details in Section Plug-in API (MPtiCore and CPtiCore).

Common utility classes and data structures are used by both the Engine and the plug-ins.

Client API (CPtiEngine)

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.
• Maintain the list of available core object plug-ins.
• Forward the API function calls to correct the core object depending on the selected input mode and language.
• Maintain the list of active user dictionaries and secondary core related data files.

Plug-in API (MPtiCore and CPtiCore)

Concrete implementation of text input services are implemented as MPtiCore-derived objects called core objects. Each core object implements one or more input modes for one or more languages. PtiEngine maintains the list of core objects. Built-in input modes are supported by built-in core objects, while other core objects are deployed in ECom plug-ins. Installed plug-in core objects are automatically loaded by the PtiEngine run-time.

The actual core objects inherit from the class CPtiCore, which contains empty default implementations for the MPtiCore methods.

When PtiEngine loads a new core object, it first asks the core object to initialize itself. At this point the core object must perform several tasks. It has to scan its language resources to find out which languages are available in the device and prepare to activate them when asked. Then it needs to update the language list maintained by PtiEngine. The list is passed to the core object as a parameter for the initialization method and the core abject has to fill the list according to its language and input mode resources. It also has to fill a structure called TPtiCoreInfo. PtiEngine uses this struct for querying the core object input capabilities.

Many of the methods defined in the MPtiCore interface can also be found from the PtiEngine client side API. In many cases the PtiEngine client side API acts only as a wrapper and forwards the function calls to the correct core object depending on the selected language and input mode.

PtiEngine has a built-in core object. Unlike other core objects, it is not dynamically loaded but statically linked to the PtiEngine module. The default core object provides basic multitapping and QWERTY input modes and is always available. A dynamic core object can still implement and override multitapping or QWERTY modes if needed.

User dictionary API (MPtiUserDictionary and CPtiUserDictionary)

Typically third party text input engines are delivered with a language databases containing a list of the most frequently used words for each language. 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 pre-built 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, a core object can use its items as candidates in prediction result data in a same way as it uses 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. 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.

While it is possible for a core object to completely maintain its user dictionary data files by itself, PtiEngine also provides convenience class CPtiUserDictionary. It is recommended that all core objects use this class. That way all user dictionary and other core related data is always stored to a predefined folder. PtiEngine adds an own header field in the beginning of the data file (which is removed when the data is accessed through PtiEngine). The header field contains the core object UID value and CRC checksum for guarding against file corruption.

Observer

The PtiEngine observer is used for indicating the client application that certain things have happened. If the client application needs to observe PtiEngine, it must inherit the MPtiObserver interface class and call the CPtiEngine->SetObserver() method.

Numeric language

When PtiEngine 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:

MyPtiEngineInstance->ActivateLanguageL( ElangNumeric, EPtiEngineNumeric );

Language databases

While core 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 highly recommended that a core object uses that interface instead of implementing its own. Language database API is defined in the interface class MPtiLanguageDatabase and default implementation for its methods are provided in the class CPtiLanguageDatabase. The core object language database implementation should inherit from later.

Character conversions

PtiEngine supports converting character codes from one format to another. The number of available conversion types depends on the available core objects and it is possible that only a small subset of conversion types defined in PtiDefs.h is available. All supported character conversion types are listed in the following table.

Spellings

PtiEngine API has a method for querying alternate spellings for a given character. The number of available spelling types depends on the available core objects and it is possible that only a small subset of spelling types defined in PtiDefs.h is available. Available spelling types can be queried with the method TPtiCoreInfo::Spellings(). All supported spelling types are listed in the following table.

Use cases

PtiEngine provides a feature-rich API. Only the most typical uses cases are listed here.

1. Initializing PtiEngine.
2. Activating language.
3. Closing current language.
4. Setting input mode.
5. Checking language and input mode.
6. Getting current language.
7. Inputting text.
8. Committing the current word.
9. Clearing the current word.
10. Listing available languages.
11. Listing available input modes.
12. Adding / removing entries to user dictionary.

API class structure

Figure 1 shows the main classes of PtiEngine API. Some minor utility structs are omitted for clarity. The figure shows logical relations.

In the client 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.