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 ImmGetContextfunction. 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 ImmNotifyIMEfunction notifies the IME about changes to the input context. Once you are finished with the context, you must release it by using the ImmReleaseContextfunction.

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 ImmCreateContextfunction. To assign an input context to a window, use the ImmAssociateContextfunction. ImmAssociateContextreturns 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 ImmDestroyContextto 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. ImmAssociateContextis 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 ImmCreateIMCCfunction. 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 ImmGetIMCCSizeand ImmReSizeIMCCfunctions. Use ImmDestroyIMCCto free the memory of an IMC component.

To obtain a handle to an input context, an IME calls the ImmLockIMCfunction. To obtain a handle to an IMC component that is a member of an input context, an IME calls the ImmLockIMCCfunction. 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 ImmGetIMCLockCountand ImmGetIMCCLockCountfunctions. To release a handle and decrement the lock count, use the ImmUnlockIMCor ImmUnlockIMCCfunction.

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.

See Also