WM_MSIME_xxx Messages
August 2003
Microsoft Corporation
Summary: This document describes the SendMessage function, which is used to communicate between IME and the IME context of an application. (16 printed pages)
Contents
Introduction
Service Functions
Re-Conversion
Document Feeding
QueryPosition
Mode Bias
Invoke IMEPad
Mouse Operation on a Composition String
KeyMap and Function-Key Sharing
Introduction
These features are available for applications in the format of Per IME Interfaces.
Notes on Sub-Classing
In order for IME to be able to receive these messages sent to an IME UI window, Microsoft IME needs to subclass it by the following procedure:
When IME creates a new instance of a UI-related window (toolbar, candidate, composition, and so on), look for the parent window whose class name is "IME" and replace its WndProc with IME's own message filter (which has the ability to filter out such messages) using SetWindowLong (hwnd, GWL_WNDPROC, lpfnYourDefIMEWndProc).
Be sure to call the original WndProc from lpfnYourDefIMEWndProc so that regular messages will be processed correctly.
SendMessage API
The SendMessage function is used to communicate between IME and the IME context of an application. A message may be associated with a function ID (or request ID) to further distinguish between different functions of the message, and with a data structure for the function.
LRESULT SendMessage
Parameter | Description |
---|---|
HWND hwnd |
UI window of current IME obtained by ImmGetDefaultIMEWnd() |
UINT msg |
Each interface will have a message ID WM_MSIME_* obtained by RegisterWindowMessage() |
WPARAM wParam |
Function ID of an interface |
LPARAM lParam |
Contains a pointer to structure defined for this function ID |
Message List
Message | Description |
---|---|
WM_MSIME_SERVICE | Application can get a variety of information from Microsoft IME through this |
WM_MSIME_UIREADY | IME sends this when an IME is ready to receive per-IME messages |
WM_MSIME_RECONVERTREQUEST | Reconversion request |
WM_MSIME_RECONVERT | Reconversion |
WM_MSIME_DOCUMENTFEED | Document feeding |
WM_MSIME_QUERYPOSITION | Query position |
WM_MSIME_MODEBIAS | Use extra conversion mode not defined in IMM |
WM_MSIME_SHOWIMEPAD | Control IME Pad |
WM_MSIME_MOUSE | Mouse operation related to IME |
WM_MSIME_KEYMAP | Share key mapping between application and IME |
Service Functions
There are two methods of initializing the per-IME interfaces. The application can choose which method it uses.
WM_MSIME_SERVICE
In this method, the application sends to the IME default UI window. SendMessage with WM_MSIME_SERVICE message are used to obtain a variety of information from Microsoft IME.
Message ID: WM_MSIME_SERVICE
Version 1.0
Explanations:
Wparam: None
LParam: None
Return Value: Non zero value on success, 0 otherwise.
The return value for the Japanese Microsoft IME98 is VERSION_ID_IMEJP98.
#define VERSION_ID_JAPANESE 0x01000000
#define VERSION_ID_KOREAN 0x02000000
#define VERSION_ID_CHINESE_TRADITIONAL 0x04000000
#define VERSION_ID_CHINESE_SIMPLIFIED 0x08000000
#define VERSION_ID_IMEJP98 (VERSION_ID_JAPAN | 0x980)
#define VERSION_ID_IMEJP2000 (VERSION_ID_JAPANESE | 0x98a)
**Note 1 **IME will initialize Microsoft IME interfaces when the application sends WM_MSIME_SERVICE to the IME. The application must send this message before using other Microsoft IME interfaces.
**Note 2 **The application must send WM_MSIME_SERVICE to the IME after the application window is shown.
**Note 3 **The timing of an IME default UI window creation is different in each operating system. Even if the application window was created, it does not mean that an IME default UI window exists already. You can use the WM_MSIME_UIREADY message if this is not a concern.
WM_MSIME_UIREADY
In this method, IME sends to the application window. IME sends a WM_MSIME_UIREADY message when an IME is ready to receive per-IME messages. If the application uses Microsoft IME per-IME interfaces, it needs to handle this message.
Message ID: WM_MSIME_UIREADY
Parameter | Description |
---|---|
wParam | IME Identification:
VERSION_ID_JAPANESE |
lParam | Reserved (0) |
Return Value | TRUE if the application uses per-IME interfaces; FALSE otherwise |
Note IME will send this message when the IME UI window is created or a new Input Context is created.
Re-Conversion
WM_MSIME_RECONVERTREQUEST
SendMessage with WM_MSIME_RECONVERTREQUEST and FID_RECONVERT_VERSION function tells whether this interface is available to the application.
Function ID (wParam): FID_RECONVERT_VERSION
Data Structure (lParam): None
Return Value: Version number of interface; 0 if not supported
Application uses ImmGetDefaultIMEWnd() to obtain the window handle of the default UI window of IME.
Message ID: WM_MSIME_RECONVERTREQUEST
An application uses this function when it wants IME to perform re-conversion on a particular string.
Function ID (wParam): 0 = default. FID_RECONVERT_VERSION = ask version
Data Structure (lParam): Target window handle. IME will send WM_MSIME_RECONVERT message to (HWND)lParam.
Return Value: Return TRUE on success, FALSE otherwise. If wParam is FID_RECONVERT_VERSION, this message returns the internal version (VERSION_RECONVERSION).
WM_MSIME_RECONVERT
IME will use hIMC->hWnd to get the window handle of the application, and call SendMessage() to that window with the message ID: WM_MSIME_RECONVERT. This message requires the RECONVERTSTRING parameter. Please see IMM/IME API document in MSDN for more details.
IME uses the function below to get information on the string to be re-converted from the application:
Function ID (wParam): IMR_RECONVERTSTRING
Data Structure (lParam): lParam will be a pointer to RECONVERTSTRING. The application fills this structure with information on the string to be re-converted.
Return Value: If the application fills this structure, the return value is the return size of this structure, otherwise the return is zero.
IME uses the function below to notify the application that a given re-conversion string will be changed:
Function ID (wParam): IMR_CONFIRMRECONVERTSTRING
Data Structure (lParam): lParam will be a pointer to RECONVERTSTRING. IME may fill this structure with information on the string to be re-converted.
Return Value: If the application accepts the re-conversion string, the return is non-zero, otherwise the return is zero.
Document Feeding
WM_MSIME_DOCUMENTFEED
IME will use GetFocus() to get the window handle of the application, and call SendMessage() to that window with the message ID: WM_MSIME_DOCUMENTFEED. IME uses this function to get information on the string to be re-converted from the application.
Function ID (wParam): VERSION_DOCUMENTFEED
Data structure (lParam): lparam will be a pointer to RECONVERTSTRING. The application fills this structure with information on the string to be re-converted.
Return Value: If the application fills this structure, the return is the return size of this structure, otherwise the return is zero.
QueryPosition
WM_MSIME_QUERYPOSITION
IME will use hIMC->hWnd to get the window handle of the application, and call SendMessage() to that window with the message ID: WM_MSIME_QUERYPOSITION (version 1). These messages require the IMECHARPOS structure. Please see IMM/IME API document in MSDN for more details.
WParam: VERSION_QUERYPOSITION
lParam: lParam will be a pointer to the IMECHARPOS structure. The application fills this structure.
Return Value: Will be a non-zero value if successful; returns 0 if it fails.
Mode Bias
WM_MSIME_MODEBIAS
Applications can specify modes not defined in IMM to increase the conversion hit rate.
Message ID: WM_MSIME_MODEBIAS
Version: 1.0
Parameter | Description |
---|---|
wParam |
Specifies the control code to perform the conversion bias. MODEBIAS-GETVERSION Get version number of this interface (lParam is ignored). MODEBIAS-SETVALUE Set bias value (See BiasMode). MODEBIAS-GETVALUE Get current bias value (lParam is ignored). |
lParam |
See BiasMode |
Return Value | Depends on wParam MODEBIAS-GETVERSION: Version number MODEBIAS-SETVALUE: Non-zero value if successful; returns 0 if fail MODEBIAS-GETVALUE: Current bias value |
BiasMode:
MODEBIASMODE_DEFAULT: Resets a mode bias setting
MODEBIASMODE_FILENAME: Filename
MODEBIASMODE_READING: RESERVED (reading recommended)
MODEBIASMODE_DIGIT: RESERVED (ANSI-digit recommended mode)
Note MODEBIASMODE_READING and MODEBIASMODE_DIGIT are not supported in IME2000, but reserved for feature usage.
Invoke IMEPad
WM_MSIME_SHOWIMEPAD
WM_MSIME_SHOWIMEPAD invokes IMEPad from the application.
Message ID | WM_MSIME_SHOEIMEPAD |
---|---|
wParam |
Applet selection option: SHOWIMEPAD_DEFAULT: Invokes IMEPad with the default applet SHOWIMEPAD_CATEGORY: Invokes IMEPad with the specified applet SHOWIMEPAD_GUID: Invokes IMEPad with the specified applet |
lParam |
Applet selection parameter; a value depends on wParam to be taken. SHOWIMEPAD_DEFAULT: Must be 0 SHOWIMEPAD_CATEGORY: Specifies IMEPad applet category ID (see IMEPad) specification SHOWIMEPAD_GUID: A pointer to IMEPad applet's GUID (see IMEPad) specification |
Return Value | Non-zero value if successful; returns 0 if failed |
Mouse Operation on a Composition String
WM_MSIME_MOUSE
Message ID: WM_MSIME_MOUSE
Version: 1.0
IME has previously provided mouse operation in several window components, such as the candidate window, status (mode) window, composition window, and so on. Yet up until now, it has been impossible to perform the mouse operation performed by an IME for composition text, if the application is in TrueInline mode. Now, however, for IMEs providing this interface, applications will be able to support operations on composition strings using the mouse, even in TrueInline mode.
When the mouse is on the composition string area, we want to consume all the mouse-related messages (WM_MOUSEMOVE, WM_SETCUROSR, WM_L(M/R)BUTTONDOWN, WM_L(M/R)BUTTONUP, WM_L(M/R)BTNDBLCLK. Whenever we get these messages, the application will SendMessage a message called WM_IME_MOUSE to IME window.
Parameter | Description |
---|---|
wParam |
Mouse operation code.
LOBYTE(LOWORD(wParam)) |
lParam |
Input context handle (HIMC) |
Return Value | Returns 1 if IME handled this message; returns IMEMOUSERET_NOTHANDLED if IME did not handled this message |
Parameters (*1)
The "low" word of wParam of the message should always indicate the mouse-button status at that time, regardless of the kinds of messages the application is attempting to process. The "high" word of wParam of the message always contains the location of the mouse relative to the beginning of the composition string (in terms of offset). The character offset should be in character count, not in bytes. lParam always contains the current HIMC, associated to the focused window. From WM_IME_MOUSE message, IME will be able to tell all the mouse action. So it will change the mouse cursor shape, and perform the designed composition string operation action triggered by the message.
HIWORD: (OFFSET) Contains offset information relative to the beginning of the composition string. Type of this value is short (so this is a signed value). The negative range is reserved for the future. Offset value should indicate the edge of each character. For instance: Offset 0 is a position at the left edge of the first character. Offset 1 is a position between the first and second characters. The last half of the previous character to the first half of the next character should have the same offset value.
LOBYTE of LOWORD: (BUTTON STATE) Is used as a bit field, indicating the mouse button status. IMEMOUSE_LBUTTON, IMEMOUSE_MBUTTON, and IMEMOUSE_RBUTTON are all defined so that they should be set whenever those buttons are down. When the wheel rolls, IMEMOUSE_WUP and IMEMOUSE_WDOWN should be set accordingly. IMEMOUSE_WUP is for when the user rolls the wheel forward (towards the front of the mouse), and IMEMOUSE_WDOWN applies when the user rolls the wheel back. The client application can also set IMEMOUSE_VERSION to query which version of mouse operation is currently supported by IME.
Lower 3 bits HIBYTE of LOWORD: (POSITIONING) This is used to describe detailed mouse-cursor position information. The client can describe detailed mouse-cursor positioning with this field. The positioning value is determined by following formula:
Positioning =
Mouse < Edge : (Mouse ? PrevCenter) * 2 / (Edge ? PrevCenter)
Mouse >= Edge: (Mouse - Edge) * 2 / (NextCenter ? Edge) + 2
Mouse: Current mouse cursor position
Edge: Where characters meets
PrevCenter: Center of previous character
NextCenter: Center of next character
All coordinates are the dimensions in which text flows. That is, if the text flow is horizontal, the calculation should be made using the X coordinate. All division should be performed as integer operations.
lParam
Always contains the current HIMC. The return value is zero if the message is not handled by IME, and is non-zero if handled. Note that IME will always handle mouse events on the composition string if it supports mouse operation. If an IME doesn't know how to respond to a particular mouse event, it should still consume the message and do nothing. Otherwise, the client application might determine the composition string or respond in another way to the unhandled mouse event.
Double Clicks
The application should always translate double-click messages as "mouse button down." This way, IME will be able to perform double-click behavior, even if the application window doesn't support double-click behavior (a window without CS_DBLCLKS).
Mouse Cursor
When the mouse cursor is over the composition string, and IME supports mouse operation, IME could change the mouse cursor using SetCursor(). So, the application will need to restore the mouse cursor when it moves from the composition area. Also, the application should not try to hide the cursor when the mouse operation is working.
Mouse Message Optimization
It is important not to generate too many messages to IME. To pass WM_IME_MOUSE to the IME UI window, when the mouse button state has not changed at all and the mouse hasn't moved enough to make wParam of the message different, is redundant. We might get WM_MOUSEMOVE or WM_SETCURSOR for every one pixel of the move of the mouse, whereas we only want to generate the WM_IME_MOUSE when the cursor leaves the character it is on.
Clicking somewhere other than on the composition string should cause a determination of the composition string. This needs to be done by the application.
While the user is dragging any mouse button, the application should capture the mouse so that it will be able to get the mouse event, even when the mouse moves to other windows. The application should cease tracking the drag of the mouse only when the dragging ceases, and while the application is tracking the drag, it should ignore other mouse button or keyboard actions.
Capturing the Mouse
Application should pass appropriate messages whenever there's any change fo the mouse button status or the mouse position (in terms of character offset). The application should call SetCapture() to enable mouse capturing when any mouse button is pressed. Capture may be released at the client application's decision. However, the client application should send extra WM_IME_MOUSE with IMEMOUSE_NONE to notify IME that capturing is released, so that IME will be able to stop dragging.
KeyMap and Function-Key Sharing
WM_MSIME_KEYMAP
This interface allows Microsoft IME and an application to share key mapping. The steps below show how to use this.
Initialization
- (Optional) Call FID_MSIME_VERSION to confirm the interface version.
- Call the FID_KMS_INIT function. All F-keys and space key with any combination of SHIFT and CTRL become available to share by default.
- (Optional) Call FID_KMS_DEL_KEYLIST function if applications want to prevent IME from using some of the function keys. For example, if an application passes F7 key, IME will not handle F7.
- Call the FID_KMS_GETKEYMAP function. IME will return all the key assignments for F-keys and space bar, with all combinations of SHIFT and CTRL, and in all states of the composition string listed below.
Negotiation as a User Types
- Call FID_KMS_NOTIFY when a user creates a selection area in an application. In this state, IME takes special action according to the user's keying (mainly re-conversion for the selected area), if defined. When a selection area is destroyed, call this API again so that IME 's internal state is reset.
- Call FID_KMS_INVOKE with the functionality ID when the user clicks the F-key guide on applications. Send the functionality ID of the F-key in the current state of the composition string. The functionality ID is returned from FID_KMS_GETKEYMAP above.
Termination
- Call FID_KMS_TERM for termination.
Message ID: WM_MSIME_KEYMAP
Interface Version
This function tells if this interface is available to the application.
Function ID: FID_MSIME_VERSION
Data Structure: None
Return Value: Version number of interface; 0 if not supported
Initialization
IME uses the default key list for key-map sharing. If a selection exists in applications and a user hits one of the keys in the list, IME processes this key.
Function ID (wParam): FID_MSIME_INIT
Data structure (lParam): IMEKMSINIT
INT cbSize: Size of this structure
HWND hWnd: (Optional) A window handle that receives notification from IME. If hWnd is NULL, no notification is posted to input context. (But other functionalities of key map sharing are valid.) IME uses this Window handle (which is not NULL) when a user customizes key assignments. IME will send the registered window message RMW_CHGKEYMAP to hWnd, with WPARAM=0(reserved), LPARAM=0(reserved).
Return Value: TRUE on success; otherwise FALSE.
Suppress Key-Map Sharing
IME excludes the key list in key map sharing that applications give through this function. For example, if an application gives VK_F7 (F7 function key) through this API, IME does not handle this key.
The IMEKMSKEY structure is defined below. The function, "Suppress Key-map Sharing" uses only dwStatus and dwVKEY.
Typedef tagIMEKMSKEY {
DWORD dwStatus;
The shift-control combination status—any combination of constants below (defined in IMM.H):
0x0000 (default)
MOD_CONTROL
MOD_SHIFT
Alt key and Win key is not processed by IME.
DWORD dwCompStatus;
Status of the composition status—a combination of the bits below:
IMEKMS_NOCOMPOSITION: No composition string exists. IME is ON.
IMEKMS_COMPOSITION: Composition string exists. IME is ON.
IMEKMS_SELECTION: Selection state is set by FID_KMS_NOTIFY. IME is ON or OFF.
IMEKMS_IMEOFF IME is OFF.
DWORD dwVKEY; VKEY code defined in IMM.H
union {
DWORD dwControl; IME Functionality ID (See 3.6.5)
DWORD dwNotUsed;
}
union {
INT cwchDscr; Size of pwchDscr string in WCHAR
INT iNotUsed;
}
union {
WCHAR *pwchDscr; The pointer to string of short description of this functionality
VOID *pNotUsed;
}
} IMEKMSKEY
Function ID (wParam) | FID_KMS_DEL_KEYLIST |
---|---|
Data Structure (lParam) | IMEKMS |
INT cbSize | Size of this structure |
HIMC hIMC | Handle of input context |
DWORD cKeyList | Number of key list array pKeyList[]. |
IMEKMSKEY *pKeyList | IMEKMSKEY.dwStatus:. Shift-Control combination status. IMEKMSKEY.dwCompStatus:. Composition string status. IMEKMSKEY.dwVKEY:. VKEY code to suppress IME's use of.. . Not used below: IMEKMSKEY.dwNotUsed IMEKMSKEY.iNotUsed IMEKMSKEY.pNotUsed |
Return Value | TRUE on success; otherwise FALSE |
Notify Selection Status
Applications should provide notification of the status of text selection.
Function ID (wParam) | FID_KMS_NOTIFY |
---|---|
Data structure (lParam) | IMEKMSNTFY |
INT cbSize | Size of this structure |
HIMC hIMC | Handle of input context |
BOOL fSelect | TRUE if applications get selection, FALSE if applications lose selection |
Return Value | TRUE on success; otherwise FALSE |
Get Key-Map List
Applications can get the key-map list of IME, which includes the functionality ID, short descriptions, for user's convenience, of each virtual key code. (Shift-Ctrl status is also included.).
Function ID (wParam) | FID_KMS_GETMAP |
---|---|
Data structure (lParam) | IMEKMSKMP |
INT cbSize | Size of this structure |
HIMC hIMC | Handle of input context |
LANGID idLang | Language ID for pwchDscr string |
WORD wVKStart | Starting number of VK_xxx |
WORD wVKEnd | Ending number of VK_xxx |
INT cKeyList | Number of IMEKMSMAP structures in pKeyList[] |
IMEKMSKEY *pKeyList | pkeyList is a block buffer that includes both several structures of IMEKMSKEY and string buffer for pwchDscr. Applications can access IMEKMSKEY by pKeyList [0], pKeyList [1], …, pKeyList [cKeyList-1].
IMEKMSKEY.dwStatus:. *** IMPORTANT ***. |
Return Value | TRUE on success; otherwise FALSE. |
Invoke Functionality
Applications can invoke the IME functionality (dwControl) listed in the Key-Map List that applications got. For this API, hIMC is the most important, by which IME chooses the appropriate input context to apply functionality to.
Functionality IDs are IME-dependent, and are currently not open for applications development. Use only the IDs that were returned to applications through FID_KMS_GETMAP.
Parameter | Description |
---|---|
Function ID (wParam) | FID_KMS_INVOKE |
Data structure (lParam) | IMEKMSINVK |
INT cbSize | Size of this structure |
HIMC hIMC | Handle of input context |
DWORD dwControl | Functionality ID that applications got in KEYMAP list, to invoke the functionality of IME |
Return Value | TRUE on success; otherwise FALSE |
Termination
This function terminates key-map sharing.
Parameter | Description |
---|---|
Function ID (wParam) | FID_MSIME_TERM |
Data structure | None |
Return Value | TRUE on success; otherwise FALSE |