Working with Input Contexts

Article
11/18/2015

A version of this page is also available for

4/8/2010

An input context stores information about the status of the Input Method Editor (IME). An input context is an internal structure maintained by the IME. The system creates and assigns a default input context to each thread. Within the thread, this default input context is a shared resource and is associated with each newly created window. Input contexts require considerable system resources, so use them conservatively.

To retrieve or set information in the IME, an application must first obtain a handle to the input context associated with a specified window. To obtain this handle, use the ImmGetContext function. You can use the returned handle in subsequent calls to the IMM functions to retrieve and set IME values, such as the Composition window style, the composition style, and the Status window position. The ImmNotifyIME function notifies the IME about changes to the input context. Once you are finished with the context, you must release it by using the ImmReleaseContext function.

Because the default input context is a shared resource, any changes that you make to it apply to all windows in the thread. However, you can override this default behavior by creating and associating your own input context for one or more windows in the thread. The changes that you make to your own input context apply only to the windows with which it is associated.

To create an input context, use the ImmCreateContext function. To assign an input context to a window, use the ImmAssociateContext function. ImmAssociateContext returns the handle of the previously associated input context. If you have not previously associated an input context with a window, the returned handle is for the default input context. When an application has finished with an input context that it has created, it calls ImmDestroyContext to free the memory that was allocated. It is the responsibility of the application to ensure that the input context being destroyed is not associated with a window. ImmAssociateContext is used to restore the original context of a window.

To create a new input method context (IMC) component that is a member of an input context structure, use the ImmCreateIMCC function. This function returns an IMC component handle and initializes the IMC component with 0s. To retrieve or change the size of the IMC component, use the ImmGetIMCCSize and ImmReSizeIMCC functions. Use ImmDestroyIMCC to free the memory of an IMC component.

To obtain a handle to an input context, an IME calls the ImmLockIMC function. To obtain a handle to an IMC component that is a member of an input context, an IME calls the ImmLockIMCC function. With each call to these functions, the total number of handles, or the lock count, is incremented for the corresponding input context or IMC component. To get the lock count of an input context or IMC component, use the ImmGetIMCLockCount and ImmGetIMCCLockCount functions. To release a handle and decrement the lock count, use the ImmUnlockIMC or ImmUnlockIMCC function.

Once an input context is associated with a window, the system automatically selects that context when the window receives the input focus. The style and other information in the input context affects subsequent keyboard input for that window, and determines the appearance and operation of the IME.

Working with Input Contexts

See Also

Reference

Additional resources