Per IME Interface

WM_MSIME_xxx messages

Introduction

These features are avaialble for applications in format of Per IME interface.

Notes on Sub-Classing

In order for IME to be able to receive these messages sent to an IME UI window, MS-IME needs to subclass it by the following procedure:

When IME creates a new instance of UI related window (toolbar, candidate, composition etc..), look for the parent window whose class name is "IME" and replace its WndProc with IME's own message filter (which has an ability to filter out those 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 IME context of an application. A message may be associated with a function id (or request id) to further distinguish different functions of the message, and with a data structure for the function.

LRESULT SendMessage

Parameters:

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 pointer to structure defined for this function id.

Message list

Message Description

WM_MSIME_SERVICE Application can get various information from MS-IME via this

WM_MSIME_UIREADY IME sends this when a 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 initialization the per-IME interfaces. The application can choose which methods does it use.

WM_MSIME_SERVICE (The application sends to IME default UI window)

SendMessage with WM_MSIME_SERVICE message are used to obtain various information from MS-IME.

Message id WM_MSIME_SERVICE

Version 1

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)

Note 1: IME will initialize MS-IME interfaces when the application sends WM_MSIME_SERVICE to the IME. Application must send this message before using other MS-IME interfaces.

Note 2: Application must send WM_MSIME_SERVICE to the IME after the application window is shown.

Note 3: The timing of a IME default UI window creation is different in each operationg systems. Even if the application window was created, it does not mean that a IME default UI window is exist already. You can use WM_MSIME_UIREADY message if you won't care of this.

WM_MSIME_UIREADY (IME sends to the application window)

IME sends a WM_MSIME_UIREADY message when a IME is ready to receive per-IME messages. If the application uses MSIME per-IME interfaces, it needs to handle this message.

Message id WM_MSIME_UIREADY

Explanations:

Wparam IME Identification

VERSION_ID_JAPANESE

VERSION_ID_KOREAN

VERSION_ID_CHINESE_TRADITIONAL

VERSION_ID_CHINESE_SIMPLIFIED

VERSION_ID_IMEJP98

lParam Reserved ( 0 )

Return Value TRUE if the application uses per-IME interfaces. FALSE, otherwise.

Note : IME will send this message when IME UI window was created or an new Input Context was created.

Re-Conversion

WM_MSIME_RECONVERTREQUEST

SendMessage with WM_MSIME_RECONVERTREQUEST and FID_RECONVERT_VERSION function tells if 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.

WM_MSIME_RECONVERT

IME will use hIMC->hWnd to get the window handle of the application, and call SendMessage() to that window with the following message id.

Those messages require RECONVERTSTRING parameter. Please see IMM/IME API document in MSDN for the details.

Message id WM_MSIME_RECONVERT

IME uses this function to get information on string to be re-converted from the application.

Function id (wParam) IMR_RECONVERTSTRING

Data Structure (lParam) lParam will be a pointer to RECONVERTSTRING. Application fills this structure with information on string to be re-converted.

Return Value If application filled this structure, return size of this structure, otherwise return zero.

IME uses this function to notify application that 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 string to be re-converted.

Return Value If application accepts the re-conversion string, return non-zero, otherwise return zero.

WM_MSIME_RECONVERTREQUEST

Application uses ImmGetDefaultIMEWnd() to obtain the window handle of the default UI window of IME.

Message id WM_MSIME_RECONVERTREQUEST

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 internal version (VERSION_RECONVERSION).

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 following message id.

Message id WM_MSIME_DOCUMENTFEED

IME uses this function to get information on string to be re-converted from the application.

Function id (wParam) VERSION_DOCUMENTFEED

Data structure (lParam) lparam will be a pointer to RECONVERTSTRING. Application fills this structure with information on string to be re-converted.

Return Value If application filled this structure, return size of this structure, otherwise return 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 following message id.

Those message requires IMECHARPOS structure. Please see IMM/IME API document in MSDN for the details.

Message id WM_MSIME_QUERYPOSITION

Version 1

Explanations:

wParam VERSION_QUERYPOSITION

lParam lParam will be a pointer to IMECHARPOS structure. Application fills this structure.

Return Value non-zero value if succeeded. Returns 0 if fail.

Mode Bias

WM_MSIME_MODEBIAS

Application can specify modes not defined in IMM to increase conversion hitrate.

Message id WM_MSIME_MODEBIAS

Version 1

Explanations:

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 succeeded. Returns 0 if fail.

MODEBIAS-GETVALUE
current bias value.

BiasMode:

MODEBIASMODE_DEFAULT reset a mode bias setting

MODEBIASMODE_FILENAME filename

MODEBIASMODE_READING RESERVED (reading recommended)

MODEBIASMODE_DIGIT RESERVED (ANSI-Digit Recommended Mode)

Comment: MODEBIASMODE_READING and MODEBIASMODE_DIGIT are not supported in IME98A, but reserved for feature usage.

Invoke IMEPad

WM_MSIME_SHOWIMEPAD

Invoke IMEPad from the application.

Message id WM_MSIME_SHOEIMEPAD

Explanations:

wParam Applet selection option.

SHOWIMEPAD_DEFAULT - Invoke IMEPad with default applet.

SHOWIMEPAD_CATEGORY - Invoke IMEPad with specified applet

SHOWIMEPAD_GUID - Invoke IMEPad with 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 succeeded. Returns 0 if fail.

Mouse Operation on Composition String

WM_MSIME_MOUSE

Message id WM_MSIME_MOUSE

Version 1

Today's IME was already providing mouse operation in several window components like candidate window, status(mode) window, composition window and so on however it was not possible to do same mouse operation pdone by an IME for composition text if the application does TrueInline. From with IMEs which provide this interface, application will be able to support operation on composition string using mouse even in TrueInline mode.

When the mouse is on the composition string area, we want to eat 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 those message, application will SendMessage a message called WM_IME_MOUSE to IME window.

Explanations:

wParam Mouse operation code.

LOBYTE(LOWORD(wParam))

IMEMOUSE_VERSION

IMEMOUSE_NONE

IMEMOUSE_LDOWN

IMEMOUSE_RDOWN

IMEMOUSE_MDOWN

IMEMOUSE_WUP

IMEMOUSE_WDOWN

HIBYTE(LOWORD(wParam))

Mouse Position.

HIWORD(wParam)

Clicked position

For more detail, see Parameters (*1).

lParam Input Context handle.(HIMC)

Return Value Returns 1 if IME handled this message. IMEMOUSERET_NOTHANDLED if IME did not handled this message..

Parameters (*1)

Low word of wParam of the message should always be indicating mouse button status at that time regardless of the kinds of message application is trying to process. High word of wParam of the message always contains the location of the mouse in offset from the beginning of the composition string. The character offset should be in character count, not in bytes. lParam always contains current HIMC associated to focused window. From WM_IME_MOUSE message IME will be able to tell all the mouse action. So it'll change mouse cursor shape, and do designed composition string operation action triggered by the message.

wParam

HIGHWORD : (OFFSET) Contains offset information relative to the beginning of the composition string. Type of this value is short (so this is signed value). Negative range is reserved for future. Offset value should indicate edge of each character. So for instance, offset 0 is a position of left edge of first character. Offset 1 is a position between first and second character. Area where we should have the same offset value is last half of previous character to first half of next character.

LOWBYTE of LOWWORD : (BUTTON STATE) used as bit field indicating mouse button status. We have IMEMOUSE_LBUTTON, IMEMOUSE_MBUTTON and IMEMOUSE_RBUTTON Defined so they should be set whenever those buttons are down. When the wheel is rolling, IMEMOUSE_WUP and IMEMOUSE_WDOWN should be set accordingly. IMEMOUSE_WUP is for when user is rolling wheel to head of the mouse and IMEMOUSE_WDOWN is the other way. Client application can also set IMEMOUSE_VERSION to query which version of mouse operation current IME supports.

Lower 3 bits HIGHTBYTE of LOWWORD : (POSITIONING) Used to describe detailed mouse cursor position information. Client can describe detailed mouse cursor positioning with this field. 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 dimension in which text flows. I.E. if the text flow is horizontal, the calicuration should be done using X coordinate. All the divisions are supposed to be done as integer operations.

lParam

Always contains current HIMC.

Return value

zero if the message is not handled by IME. Non-zero if handled. Note IME will always want to handle all mouse events on composition string if it supports mouse operation. If an IME don't know how to respond to one particular mouse event, it should still, eat the message and do nothing. Otherwise, client application might determine the composition string or do something else as a response to that unhandled mouse event.

NOTE

Double clicks

Application should always translate all dobule click message as mouse button down. This way, IME will be able to do doubleclick behavior even if application window doesn't support double click(a window without CS_DBLCLKS).

Mouse cursor

While mouse cursor is over the composition string and IME supports mouse operation, IME could change mouse cursor using SetCursor(). So, application will need to restore mouse cursor when it came out from the composition area. Also, application should not try to hide the cursor when mouse operation is working.

Mouse message optimization

It is important that we do not generate too many messages to IME. The situation which looks clearly redundant to pass WM_IME_MOUSE to the IME UI window is when mouse button state is not changed at all and mouse haven't moved enough to make wParam of the message different. We might get WM_MOUSEMOVE or WM_SETCURSOR for every one pixel of the move of the mouse, we only want to generate the WM_IME_MOUSE when the mouse left the character which was sitting on.

Clicking somewhere except composition string

This should cause determination of the composition string. This needs to be done by application's responsibility.

While dragging

While user is dragging any mouse button, application should capture mouse so that it will be able to get mouse event even the mouse is went to other windows. And it should release it when the dragging over. While application is tracking the drag, it should ignore other mouse button action or keyboard actions.

Capturing mouse

Application should pass appropriate message whenever there's any change about mouse button status or mouse position in character offset is changed. Application should call SetCapture() to enable mouse capturing when any mouse button is pressed down. Capture may be released at client application's decision. However, 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 MS-IME and application to share key mapping.

Below steps show how to use this.

Initialization

(optional) Call FID_MSIME_VERSION to confirm interface version.

Call 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 APPS want to prevent IME from using some of F-keys. E.g., if APPS passes F7 key, IME will not handle F7.

Call FID_KMS_GETKEYMAP function. IME will return all the key assignment for F-keys and space with all combination of SHIFT and CTRL, and in all states of composition string listed below.

Negotiation as user's typing

Call FID_KMS_NOTIFY when a selection area is created in APPS by the user. In this state, IME takes special action by user's keying (mainly re-conversion for 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 functionality ID when the user clicks F-key guide on APPS. Send functionality ID of the F-key in the current state of composition string. Functionality ID is returned from FID_KMS_GETKEYMAP above.

Termination

Call FID_KMS_TERM for termination.

Message id WM_MSIME_KEYMAP

Interface Version

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 default key list for key map sharing. If a selection exists in applications and 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) Window handle which receives notification from IME. If hWnd is NULL, no notification is posted to input context. (But other functionalities of key map sharing is valid.)IME uses this Window handle (which is not NULL) when

a user customizes key assignments. IME will send registered window message RMW_CHGKEYMAP to hWnd, with WPARAM=0(reserved), LPARAM=0(reserved).

Return Value TRUE on success, FALSE otherwise.

Suppress Keymap sharing

IME excludes the key list in key map sharing which apps gives through this function. For example, if apps gives VK_F7 (F7 function key) through this API, IME does not handle this key.
IMEKMSKEY structure is defined as below. The function of "Suppress Keymap Sharing" only use dwStatus and dwVKEY in it.

Typedef tagIMEKMSKEY {
     DWORD dwStatus;

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 composition status. 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 functionalify
          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, FALSE otherwise.

Notify Selection Status

Apps can get the key map list of IME, which includes functionality ID, short descriptions for user's convenience, for each virtual key code. (Shift-Ctrl status is also included.).

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 apps get selection, FALSE if apps lose selection

Return Value TRUE on success, FALSE otherwise.

Get Keymap List

Apps can get the key map list of IME, which includes functionality ID, short descriptions for user's convenience, for 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 which includes both several structures of IMEKMSKEY and string buffer for pwchDscr. Apps can access IMEKMSKEY by pKeyList [0], pKeyList [1], ..., pKeyList [cKeyList-1].
IMEKMSKEY.dwStatus:.
Shift-Control combination status.
IMEKMSKEY.dwCompStatus:.
Composition string status.
.IMEKMSKEY.dwVKEY:.
VKEY code..
IMEKMSKEY.dwControl:.
Functionality ID for IME.
IMEKMSKEY.cwchDscr.
The size of description string in WCHAR.
IMEKMSKEY.pwchDscr.
The pointer to description string of this functionality ID.

*** IMPORTANT ***.
APPS MUST release this buffer after use as below.
GlobalFreePtr( pMap );

Return Value TRUE on success, FALSE otherwise.

Invoke Functionality

Apps can invoke IME functionality (dwControl) listed in Key Map List which apps got. For this API, hIMC is most important with which IME chooses the appropriate input context to apply Functionality to.
Functionality IDs are IME-dependent, and are not open for APPS development now. Use only the IDs which were returned to APPS through FID_KMS_GETMAP.

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 which apps got in KEYMAP list, to invoke the functionality of IME

Return Value TRUE on success, FALSE otherwise

Termination

This function terminates key map sharing.

Function id (wParam) FID_MSIME_TERM

Data structure None

Return Value TRUE on success, FALSE otherwise