The input method is a programming interface that allows applications to run in an international environment provided through National Language Support (NLS). The input method has the following characteristics:
Refer to the diagram to see the relationship between the input method and the application.
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 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.
The IMInitialize subroutine links the converter function using the load subroutine. The load subroutine is similar to the exec subroutine and links the converter program at run-time. Since the IMInitialize subroutine is called as a library function, it must preserve security for certain programs. When the IMInitialize subroutine is called from a set root ID program, it will ignore the LOCPATH environment variable and search for converters only in the /usr/lib/nls/loc/iconv and /etc/nls/loc/iconv directories.
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. 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 newer 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.
Once 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.
The input method provides the following subroutines for maintenance purposes:
| IMInitialize | Initializes the standard input method for a specified language. Returns a handle to an IMED associated with the locale. The handle is an opaque structure of type IMFep. |
| IMQueryLanguage | Checks whether the specified language is supported. |
| IMCreate | Creates one instance of a particular input method. This subroutine must be called before any key event processing is performed. |
| IMClose | Closes the input method. |
| IMDestroy | Destroys an instance of an input method. |
The input method provides several subroutines to map key events to a string. The mapping is maintained in an imkeymap file located in the LOCPATH directory. The subroutines used for mapping are:
| IMInitializeKeymap | Initializes the imkeymap associated with a specified language. |
| IMFreeKeymap | Frees resources allocated by the IMInitializeKeymap subroutine. |
| IMAIXMapping | Translates a pair of key-symbol and state parameters to a string and returns a pointer to that string. |
| IMSimpleMapping | Translates a pair of key-symbol and state parameters to a string and returns a pointer to that string. |
Input processing begins when you press keys on the keyboard. The application must have created an IMObject before calling these functions:
| IMFilter | Asks the IMED to indicate if a key event is used internally. If the IMED is composing a localized string, it maps the key event to that string. |
| IMLookupString | Maps the key event to a localized string. |
| IMProcessAuxiliary | Notifies the input method of input for an auxiliary area. |
| IMIoctl | Performs a variety of control or query operations on the input method. |
The IMED communicates directly with the user by using the Input Method-Callback (IM-CB) API to access the graphic-dependent functions (callbacks) provided by the application. The application attaches the callbacks, which perform output functions and query information, to the IMObject during initialization. The application still handles all the input.
The set of callback functions that the IMED uses to communicate with a user must be provided by the caller. See "Using Callbacks" for a discussion of the subroutines defined by the IM-CB API.
The major structures used by the input method are:
National Language Support Overview for Programming.
The IMClose subroutine, IMCreate subroutine, IMDestroy subroutine, IMInitialize subroutine, IMInitializeKeymap subroutine, IMloctl subroutine, IMFilter subroutine, IMLookupString subroutine, IMProcessAuxiliary subroutine, IMQueryLanguage subroutine.
