Initialization

This section will discuss subroutines used to determine input methods.

You can use the IMQueryLanguage subroutine to determine if an input method is available without initializing it. An application (toolkit) initializes a locale-specific input method by calling the IMInitialize subroutine, which initializes a locale-specific input method editor (IMED). The subroutine uses the LOCPATH environment variable to search for the input method named by the LANG environment variable. The LOCPATH environment variable specifies a set of directory names used to search for input methods.

If the input method is found, the IMInitialize subroutine uses the load subroutine to load the input method and attach the imkeymap file. When the input method is accessed, an object of the type IMFep (input method front-end processor) is returned. The IMFep should be treated as an opaque structure.

Each IMFep inherits the locale's code set when the IMInitialize subroutine is called. Consequently, strings returned by the IMFilter and IMLookupString subroutines are in the locale's code set. Changing the locale after the IMInitialize subroutine is called does not affect the code set of the IMFep.

For each IMFep, the application can use the IMCreate subroutine to create one or more IMObject instances. The IMObject manages its own state and can manage several Input Method Areas (see Input method areas). How each IMObject defines input processing depends on the code set and keyboard associated with the locale. In the simplest case, a single IMObject is needed if the application is managing a single dialog with the user. The input method also supports other user interfaces where the application allows multiple dialogs with the user, and each dialog requires one IMObject.

The difference between an IMFep and IMObject is that the IMFep is a handle that binds the application to the code of the input method, while the IMObject is a handle that represents an instance of a state of an input device, such as a keyboard. The IMFep does not represent a state of the input method. Each IMObject is initialized to a specific input state and is changed according to the sequence of events it receives.

After the IMObject is created, the application can process key events. The application should pass key events to the IMObject using the IMFilter and IMLookupString subroutines. These subroutines are provided to isolate the internal processing of the IMED from the customized key event mapping process.