IImePad and IImePadApplet
Microsoft Corporation
August 2003
Summary: This document describes the interface definitions needed to implement IImePad, IImePadApplet (both COM-based interfaces of the Microsoft Input Method Editor), and IImeSpecifyApplets. (17 printed pages)
Contents
Overview
IImePad
IImePadApplet
IImeSpecifyApplets
Overview
IImePad and IImePadApplet are both COM-based interfaces of the Microsoft Input Method Editor (IME). IImePad provides the architecture for non-hardware keyboard input methods, such as a software keyboard and HW recognition. IImePad manages the IImePadApplet and serves as a go-between for other IME components and the IImePadApplet. The request to input a composition string from IImePadApplet is transferred to other Microsoft IME components through IImePad.
IImePadApplet is one interface for ImePad's "applet," which is implemented as a DLL module. The applet provides IImePadApplet interface as an inproc (inprocess) server. Users can implement multiple IImePadApplet interfaces in one DLL.
To specify and emulate the IImePadApplet interface in the applet DLL, the applet must also provide the IImeSpecifyApplets interface. All interfaces are defined in imepad.h.
This document describes the interface definitions needed to implement IImePad, IImePadApplet, and IImeSpecifyApplets.
IImePad
The IImePad interface specifies methods that handle several requests from IImePadApplet. Only one method Request() is provided; IImePadApplet can request several methods with RequestId.
| IUnknown Methods | Description |
|---|---|
| QueryInterface | Returns pointers to supported interface. |
| AddRef | Increment reference count. |
| Release | Decrement reference count. |
| IImePad methods | Description |
|---|---|
| Request (see below) | Request several methods with request-id. |
IImePad::Request
The Request() is called by IImePadApplet; the request handles a composition string, and other requests.
HRESULT Request(
IImePadApplet *pIImePadApplet,
INT reqId,
WPARAM wParam,
LPARAM lParam
);
| Parameter | Meaning |
|---|---|
| pIImePadApplet | [in] Sets self applet Interface pointer. |
| reqId | [in] Specifies IMEPAD's Request Id. |
| wParam | [in/out] Specifies additional Request Id-specific information. |
| lParam | [in/out] Specifies additional Request Id-specific information. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
Note This request method is similar to Win32API's SendMessage(). It sets the Request Id and Request Id-related wParam, lParam values.
RequestID
IMEPADREQ_INSERTSTRING
The applet can use to insert a string to the application as a composition string.
wParam = (WPARAM)lpwstr;
lParam = 0;
| Parameter | Meaning |
|---|---|
| lpwstr | Value of wParam; point to the null-terminated string to be added to the application. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_SENDCONTROL
The applet can use IMEPADREQ_SENDCONTROL to control composition of the string, caret, etc in the application.
wParam = (WPARAM)ctrl;
lParam = 0;
| Value | Meaning |
|---|---|
| ctrl | Value of wParam; specifies the control value that requests IME to process the composition string and caret position. |
| IMEPADCTRL_CONVERTALL | Convert all composition string. |
| IMEPADCTRL_DETERMINALL | Determine all composition string. |
| IMEPADCTRL_DETERMINCHAR | Determine specified count's composition string char. |
| IMEPADCTRL_CLEARALL | Clear all composition string. |
| IMEPADCTRL_CARETLEFT | Move character caret to the left. |
| IMEPADCTRL_CARETRIGHT | Move character caret to the right. |
| IMEPADCTRL_CARETTOP | Move character caret to the top of composition string. |
| IMEPADCTRL_CARETBOTTOM | Move character caret to the end of composition string. |
| IMEPADCTRL_CARETBACKSPACE | Delete composition string's character before caret. (Like BACKSPACE key.) |
| IMEPADCTRL_CARETDELETE | Delete composition string's character after caret. (Like DELETE key.) |
| IMEPADCTRL_PHRASEDELETE | Delete composition string's phrase. |
| IMEPADCTRL_INSERTSPACE | Insert space character. Full width or half width depening on IME configuration. |
| IMEPADCTRL_INSERTFULLSPACE | Insert full width space. |
| IMEPADCTRL_INSERTHALFSPACE | Insert half width space. |
| IMEPADCTRL_ONIME | Set IME ON. |
| IMEPADCTRL_OFFIME | Set IME OFF. |
| IMEPADCTRL_ONPRECONVERSION | Set pre-conversion ON. |
| IMEPADCTRL_OFFPRECONVERSION | Set pre-conversion OFF. |
| IMEPADCTRL_PHONETICCANDIDATE | Open IME's candidate. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETCOMPOSITIONSTRING
The applet can use IMEPADREQ_GETCOMPOSTIONSTRING to add the composition string to the application.
wParam = (WPARAM)lpwstr;
lParam = (LPARAM)nMaxCount;
| Parameter | Meaning |
|---|---|
| lpwstr | Value of wParam; point to the buffer that is to receive the current composition string text. |
| nMaxCount | Value of lParam; specify the maximum number of characters to be copied, including the terminating null character |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_SETAPPLETSIZE
The applet can use IMEPADREQ_SETAPPLETSIZE to set a new applet window size.
wParam = MAKEWPARAM(width, height);
lParam = no use
| Parameter | Meaning |
|---|---|
| width | LOWORD of wParam; set the new applet width. |
| Height | HIWORD of wParam; set the new applet height. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_SETAPPLETDATA
The applet can use IMEPADREQ_SETAPPLETDATA to set its original data. It is saved to the registry and can be retrieved with IMEPADREQ_GETAPPLETDATA.
wParam = (WPARAM)(PBYTE)pByte;
lParam = (LPARAM)(INT)size;
| Parameter | Meaning |
|---|---|
| pByte | Value of wParam; set the address you want to write to the registry. You can get this data with IMEPADREQ_GETAPPLETDATA. |
| Size | Value of lParam; specify the data size of pByte. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETAPPLETDATA
The applet can use IMEPADREQ_GETAPPLETDATA to get its original data.
wParam = (WPARAM)(PBYTE)pByte
lParam = (LPARMA)(INT)size;
| Parameter | Meaning |
|---|---|
| pByte | Value of wParam; set the buffer address that receives the applet's specified data. |
| Size | Value of lParam; specify the buffer size. |
IMEPADREQ_GETCOMPOSITIONSTRINGINFO
The applet can use to get current composition string information.
wParam = (WPARAM)(LPIMECOMPOSITIONSTRINGINFO)lpImeCompInfo.
lParam = 0; //no use.
Structure
typedef struct tagIMECOMPOSITIONSTRINGINFO {
INT iCompStrLen;
INT iCaretPos;
INT iEditStart;
INT iEditLen;
INT iTargetStart;
INT iTargetLen;
}IMECOMPOSITIONSTRINGINFO, *LPIMECOMPOSITIONSTRINGINFO;
| Value | Description |
|---|---|
| iCompStrLen | The length of a composition string. |
| iCaretPos | The caret position in a composition string. |
| iEditStart | The starting position in a composition string that the applet can edit. |
| iEditLen | The length of a string the applet can edit from iEditStart. |
| iTargetStart | The starting position in a non-determined composition string. |
| iTargetLen | The length of a non-determined composition string from iTargetStart. |
| Parameter | Meaning |
|---|---|
| lpImeCompInfo | Value of wParam; specify IMECOMPOSITIONSTRINGINFO structure's address that receives the composition info. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_CHANGESTRING
The applet can use IMEPADREQ_CHANGESTRING to change the composition string.
wParam = (WPARAM)(LPWSTR)lpwstr;
lParam = MAKELPARAM(wStartPos, wLength);
| Parameter | Meaning |
|---|---|
| lpwstr | Value of wParam; set NULL terminated string. |
| wStartPos | LOWORD of lParam; set composition string start position to change. |
| wLength | HIWORD of lParam; length of composition string to change. wStartPos and wStartPos+wLength must be between iEditStart and iEditStart+iEditLen as returned by IMEPADREQ_COMPOSITIONSTRINGINFO. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
Note IMEPADREQ_CHANGESTRING is different from IMEPADEQ_CHANGESTRING in its return value and ability to set the Far East Id.
IMEPADREQ_DELETESTRING
The applet can use IMEPADREQ_DELETESTRING to delete the composition string.
wParam = MAKEWPARAM(wStartPos, wLength);
lParam = 0; //not used.
| Parameter | Meaning |
|---|---|
| wStartPos | LOWORD of wParam. Position in composition string to delete. |
| wLength | HIWORD of wParam. Length of composition string to delete. wStartPos and wStartPos+wLength must be between iEditStart and iEditStart+iEditLen as returned by IMEPADREQ_COMPOSITIONSTRINGINFO. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETAPPLHWND
The applet can use IMEPADREQ_GETAPPLHWND to get the application window handle.
wParam = (WPARAM)(HWND *)pHwnd;
lParam : Not used
| Parameter | Meaning |
|---|---|
| pHwnd | Value of wParam; specify the HWND handle address to get the application window handle. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_FORCEIMEPADWINDOWSHOW
The applet can use IMEPADREQ_FORCEIMPADWINDOWSHOW to keep the ImePad window visible**.**
wParam = (BOOL)fShow
lParam : not used
Note In normal case, IImePad UI is activated if IME's context is active. If the applet wants to keep ImePad UI visible (for example, when the applet invokes the Property Dialog, etc.), it can keep the ImePad UI visible with this request.
IMEPADREQ_POSTMODALNOTIFY
If the applet calls a Request with IMEPADREQ_POSTMODALNOTIFY, ImePad calls the applet's Notify() asynchronously with a specific notification Id and user data.
wParam = (WPARAM)notifyCode
lParam = (LPARAM)dwUserData;
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETDEFAULTUILANG
The applet can get the recommended (default) ImePad applet UI Language with IMEPADREQ_GETDEFAULTUILANG.
wParam = (LANGID *)pLangID;
lParam = 0; not used
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETCURRENTUILANG
The applet can get the current ImePad window's UI (Menu, Dialog) and UI Language with IMEPADREQ_GETDEFAULTUILANG.
wParam = (LANGID *)pLangID;
lParam = 0; not used
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETAPPLETUISTYLE
The applet can use IMEPADREQ_GETAPPLETUISTYLE to get the self applet's UI style (IPWS_XXXX combination).
wParam = (WPARAM)(DWORD *)pdwStyle;
lParam = 0; not used.
For detailed UI style information, see IImePadApplet::CreateUI.
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_SETAPPLETUISTYLE
The applet can use IMEPADREQ_SETAPPLETUISTYLE to set a self applet's UI style (IPWS_XXXX combination).
wParam = (WPARAM)(DWORD)dwStyle;
lParam = 0; not used.
For detailed UI style information, see IImePadApplet::CreateUI.
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_ISAPPLETACTIVE
The applet can use IMEPADREQ_ISAPPLETACTIVE to set a self applet as activated or NOT.
wParam = (WPARAM)(BOOL *)pfActive;
lParam = 0; not used.
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_ISIMEPADWINDOWVISIBLE
The applet can use IMEPADREQ_ISIMEPADWINDOWVISIBLE to set ImePad as visible or NOT.
wParam = (WPARAM)(BOOL *)pfVisible;
lParam = 0; not used.
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_SETAPPLETMINMAXSIZE
The applet can use IMEPADREQ_SETAPPLETMINMAXSIZE to set the minimum and maximum applet size.
wParam = MAKEWPARAM(width, height); // Applet's width & height
lParam = (LPARAM)(BOOL)fMax; // Set Max size or Min size.
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETCONVERSIONSTATUS
The applet can use IMEPADREQ_GETCONVERSIONSTATUS to get the current application IME's conversion status. For a complete list of conversion and sentence modes, see the SDK's header file IMM.H.
wParam = (WPARAM)(DWORD *)pdwConversionMode; //conversion mode.
lParam = (LPARAM)(DWORD *)pdwSentenceMode; //sentence mode.
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETVERSION
The applet can use IMEPADREQ_GETVERSION to get IImePad's version information.
wParam = (WPARAM)(DWORD *)pdwVerMS;
lParam = (LPARAM)(DWORD *)pdwVerLS;
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IMEPADREQ_GETCURRENTIMEINFO
The applet can use IMEPADREQ_GETCURRENTIMEINFO to get the IME information that invoked ImePad.
wParam = (WPARAM)(DWORD *)pdwImeLangID; //Retrieve IME's LangID
lParam = (LPARAM)(DWORD *)pdwImeInputID; //Retrieve IME's Input Id.
Note Only when the IME is TC (Traditional Chinese) may the input Id be 0 (IME is for BOPOMOFO), or 1 (IME is for CHANGJIE). Otherwise, the input Id is always 0.
IImePadApplet
The IImePadApplet interface specifies methods called from IImePad, the create window, and several notifications.
| IUnknown Method | Description |
|---|---|
| QueryInterface | Returns pointers to supported interface. |
| AddRef | Increment reference count. |
| Release | Decrement reference count. |
| IImePadApplet methods | Description |
|---|---|
| Initialize | Initialize the applet. |
| Terminate | Terminate the applet. |
| GetAppletConfig | Get applet configuration data. |
| CreateUI | Called to create applet window. |
| Notify | Send notification. |
IImePadApplet::Initialize
The Initialize() method is called from IImePad to initialize IImePadApplet.
HRESULT Initialize(
IUnknown *pIUnknown //IUnknown pointer to query IImePad
);
| Parameter | Meaning |
|---|---|
| pIUnknown | [in] address of IUnknown interface. IImePadApplet can get IImePad interface pointer with using QueryInterface(). |
Note When the ImePad user interface is created, IImePad calls this method and sets the IImePad interface pointer as an argument. The applet can use this pointer to call the pIImePad->Request() method.
IImePadApplet::Terminate
The Terminate() method is called from IImePad to terminate IImePadApplet.
HRESULT Terminate(VOID);
Note IImePad calls this method when finish to use IImePadApplet.
IImePadApplet::GetAppletConfig
The GetAppletConfig() is called from IImePad to get IImePadApplet's configuration data.
HRESULT GetAppletConfig(
LPIMEAPPLETCFG lpCfg
);
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
Note This method is called from IImePad to get the applet's specific data. This method can be called before the calling Initialize () method. The LPIMEAPPLETCFG data definition is described below.
Structure
typedef struct tagAPPLETCFG {
DWORD dwConfig;
WCHAR wchTitle[MAX_APPLETTITLE];
WCHAR wchTitleFontFace[MAX_FONTFACE];
DWORD dwCharSet;
INT iCategory;
HICON hIcon;
LANGID langID;
WORD dummy;
LPARAM lReserved1;
}IMEAPPLETCFG, *LPIMEAPPLETCFG;
.gif)
.gif)
IImePadApplet::CreateUI
The CreateUI() is called from IImePad to get the applet's window handle, style, size. The applet can set its window style, sizing policy.
HRESULT CreateUI(
HWND hwndParent,
LPIMEAPPLETUI lpAppletUI
);
| Parameter | Meaning |
|---|---|
| hwndParent | [in] Window handle of IImePad GUI. The applet can create the window as its child window. |
| lpAppletUI | [in] Address of IMEAPPLETUI structure. The applet can set its window style. |
Structure
typedef struct tagIMEAPPLETUI {
HWND hwnd;
DWORD dwStyle;
INT width;
INT height;
INT minWidth;
INT minHeight;
INT maxWidth;
INT maxHeight;
LPARAM lReserved1;
LPARAM lReserved2;
}IMEAPPLETUI, *LPIMEAPPLETUI;
.gif)
.gif)
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
IImePadApplet::Notify
The Notify() is called from IImePad to notify some kind of information with notify code, imepadif_notifycode.
IUnknown *pIUnknown, //Pointer of IUnknown to get IImePad interface pointer
INT notify, //notify code
WPARAM wParam, //first parameter
LPARAM lParam //second parameter
);
| Parameter | Meaning |
|---|---|
| IUnknown *pIUnknown | [in] Pointer of IUnknown interface. To get IImePad interface pointer, use QueryInterface(). |
| INT notify | [in] Notify code. |
| WPARAM wParam | [in/out] Specifies additional notify Id specific information. |
| LPARAM lParam | [in/out] Specifies additional notify Id specific information. |
| Return Value | Meaning |
|---|---|
| S_OK | Success |
| S_FALSE | Error |
Notify Code
IMEPN_ACTIVATE
lpwstr1 = (LPWSTR)wParam;
lpwstr2 = (LPWSTR)lParam;
IMEPN_ACTIVATE is called when the IImePadApplet Window has activated. wParam, lParam may be the point string of the Japanese phonetic characters, or the converted string pointer if the applet was activated by Microsoft IME. Normally, these value are NULL, so if the applet uses wParam and lParam as a string, it must check to see whether or not the pointer is NULL.
IMEPN_INACTIVATE
wParam=0;
lParam=0;
IMEPN_INACTIVATE is called when the IImePadApplet Window is deactivated.
IMEPN_CONFIG
wParam = 0;
lParam = 0;
IMEPN_CONFIG notification indicates the user select the "Property" menu in the IImePad GUI. This can trigger the IImePadApplet to show the applet a specific configuration dialog.
IImeSpecifyApplets
The IImeSpecifyApplets' interface specifies methods called from IImePad to emulate IImePadApplet's interface.
| IUnknown Method | Description |
|---|---|
| QueryInterface | Returns pointers to the supported interface. |
| AddRef | Increment reference count. |
| Release | Decrement reference count. |
| IImePadApplet methods | Description |
|---|---|
| GetAppletIIDList (see below) | Return IImePadApplet's interface Id List. |
IImeSpecifyApplet::GetAppletIIDList
The GetAppletIIDList() is called from IImePad to enumerate how many of IImePadApplet's interfaces are implemented.
HRESULT GetAppletIIDList(
REFIID refiid, //IImePadApplet IID
LPAPPLETIIDLIST lpIIDList //address of APPLETIIDLIST
);
| Parameter | Meaning |
|---|---|
| refiid | [in] IID of IImePadApplet. This IID is defined in IMEPAD.H as IID_IImePadApplet. This is for IImePadApplet's future enhancement. |
| lpIIDList | [in/out] Address of APPLETIIDLIST. Sets the applet's IID list and count. |
Structure
typedef struct tagAPPLETIDLIST {
INT count;
IID *pIIDList;
}APPLETIDLIST, *LPAPPLETIDLIST;
| Value | Meaning |
|---|---|
| count | Set the IID count implemented in this applet. |
| pIIDList | Set the IID List. This must be allocated with CoTaskMemAlloc(). |
Note This method is called from IImePad to emulate the number of IImePadApplet interfaces implemented in this applet DLL module. The applet must compare refiid and IID_ImePadApplet as defined in IMEPAD.H, and if refiid is the same as the IID_IImePadApplet compiled with IMEPAD.H, then the applet can set the IID list to pIIDList. It should also be noted that IImePadApplet might be enhanced in the future. If this occurs, IID_IImePadApplet will be changed.