Setting the Input Context

In order to get or set IME status information, composition strings, or window positions, your application needs to send an input context handle to most API calls. Calling ImmGetContext will retrieve the default input context the system has created and associated with all the windows of a particular thread. After you are finished with the input context, you need to release it by calling ImmReleaseContext. Be forewarned that the system's default input context is a shared resource; any changes you make to it will affect other windows in the same thread. To avoid this, you can create a custom input context. Changes you make to a custom input context will affect only those windows you associate with it.

Before you associate a window with a custom input context, it's a good idea to save the window's default input context. You might need it later—for example, if you destroy your custom input context and need to restore the default.

To create an input context, call ImmCreateContext. To associate this context with a window, call ImmAssociateContext. After you have associated an input context with a window, the system will automatically provide the input context whenever the window gets the focus. The system generates a WM_IME_SETCONTEXT message; the input context is contained in the lParam. If you make changes to the input context, you should call ImmNotifyIME so that the IME can remain synchronized. To destroy the custom input context before you terminate your application, you must call ImmDestroyContext.

Applications that are fully IME-aware should handle most WM_IME messages, which tell the application that something has changed and that the application should query the system to get updated information. For example, the IME generates WM_IME messages when an IME user interface window moves, when the user turns the IME on or off, or when the user sends a string to the application. The table below lists some of these messages and the functions your application should call in response to them. For more detailed information, consult the FULLIME example that ships with the Far East Windows 95 PDK, and Appendixes N and O in this book.

Functions for Processing WM_IME Messages
WM_IME Message Submessage Function for Processing Message
WM_IME_OPENCANDIDATE   ImmGetCandidateListCount
WM_IME_CHANGECANDIDATE   ImmGetCandidateListCount
WM_IME_COMPOSITION   ImmGetCompositionString
WM_IME_COMPOSITIONFULL   SendMessage, with WM_IME_CONTROL and IME_SETCOMPOSITION WINDOW
WM_IME_SETCONTEXT   ImmIsUIMessage
WM_IME_NOTIFY IMN_CHANGECANDIDATE ImmGetCandidateListCount,
    ImmGetCandidateList
  IMN_GUIDELINE ImmGetGuideline
  IMN_OPENCANDIDATE ImmGetCandidateListCount,
    ImmGetCandidateList
  IMN_OPENSTATUSWINDOW ImmGetConversionStatus
  IMN_SETCOMPOSITIONFONT ImmGetCompositionFont
  IMN_SETCOMPOSITIONWINDOW ImmGetCompositionWindow
  IMN_SETCONVERSIONMODE ImmGetConversionStatus
  IMN_SETOPENSTATUS ImmGetOpenStatus
  IMN_SETSENTENCEMODE ImmGetConversionStatus
  IMN_SETSTATUSWINDOWPOS ImmGetStatusWindowPos
  IMN_SETCANDIDATEPOS ImmGetCandidateWindow