[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

General Programming Concepts: Writing and Debugging Programs

Programming Input Methods

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:


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 (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 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.

Input Method Management

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.

IM Keymap Management

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.

Key Event Processing

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.

Input Method Structures

The major structures used by the input method are:

IMFepRec Contains the front end information.
IMObjectRec Contains the common part of input method objects.
IMCallback Registers callback subroutines to the IMFep.
IMTextInfo Contains information about the text area, primarily the pre-editing string.
IMAuxInfo Defines the contents of the auxiliary area and the type of processing requested.
IMIndicatorInfo Indicates the current value of the indicators.
IMSTR Designates strings that are not null-terminated.
IMSTRATT Designates strings that are not null-terminated and their attributes.

Related Information

Chapter 16, National Language Support .

The IMClose subroutine, IMCreate subroutine, IMDestroy subroutine, IMInitialize subroutine, IMInitializeKeymap subroutine, IMloctl subroutine, IMFilter subroutine, IMLookupString subroutine, IMProcessAuxiliary subroutine, IMQueryLanguage subroutine.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]