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

Message List

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

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

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.

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.

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

1. (Optional) Call FID_MSIME_VERSION to confirm the interface version.
2. 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.
3. (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.
4. 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

1. 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.
2. 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

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

Notify Selection Status

Applications should provide notification of the status of text selection.

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

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.

Termination

This function terminates key-map sharing.