The imlib.cpp library module
imlib.cpp, included in the development kit, contains a set of useful functions for interfacing to Keyman.
PrepIM initialises the Keyman32 imports. You should not call any of the Keyman imports without calling PrepIM first. If PrepIM fails, you should exit without doing any processing.
BOOL IMDefWindowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam, LRESULT *lResult);
IMDefWindowProc should be called from an IMC window procedure (see section titled Input Method Composition windows). If it returns TRUE you should return the value stored in lResult without any further processing. IMDefWindowProc mostly manages window activation and movement.
The DLL can call Keyman functions to interact with Keyman and the target application. It should not attempt to directly control the application as Keyman will be doing this. You should never call any of the functions here from the KeymanIMConfigure callback.
You can use PrepIM(), declared in imlib.cpp to get access to the the Keyman functions. When using imlib.cpp, the functions are declared as pointers, so you need to dereference them to call them in C (e.g. for KMGetContext, call (*KMGetcontext)(buf,len);
BOOL WINAPI KMGetContext(PWSTR buf, DWORD len);
KMGetContext returns the last len-1 UTF-16 codepoints of the context stack. If there are not enough characters in the context stack, it will return as many as it can. On success, the buf variable will be null terminated.
The context stack can contain a special code for deadkeys. See KMQueueAction for a way to output a deadkey. The code sequence for a deadkey is (3 words):
UC_SENTINEL, CODE_DEADKEY, deadkeyID
UC_SENTINEL is 0xFFFF; CODE_DEADKEY is 0x0008; deadkeyID can be any value from 0x0001 to 0xFFFE.
NoteChanges in 8.0.333.0: a potential buffer overflow has been corrected. The size of the buffer pointed to by buf should be len+1 WCHARs to allow for terminating null. Keyman now counts supplementary plane characters as 2 UTF-16 codepoints rather than as a single codepoint. Keyman no longer returns partial deadkey code sequences.
BOOL WINAPI KMSetOutput(PWSTR buf, DWORD backlen);
KMSetOutput is a wrapper for KMQueueAction. It simplifies the process of deleting contextual characters and outputting a new string. The results will not be output to the screen until the current function returns. If called within the context of an IMC window, the results will not be output to the screen until the window posts the wm_keymanim_close message.
buf is a pointer to a null-terminated string of characters to output. backlen is the number of characters to backspace from the current context before displaying buf.
This function modifies the context returned from KMGetContext, even if the output is not yet on the screen.
Internally, this function does the following code:
while(backlen-- > 0) KMQueueAction(QIT_BACK, 0);
while(*buf) KMQueueAction(QIT_CHAR, *buf++);
BOOL WINAPI KMQueueAction(int itemType, DWORD dwData);
KMQueueAction lets you send any Keyman action to a target application. This can be virtual keys, characters, shift keys up and down, deadkeys, beeps, or backspaces (a special case of virtual keys).
|QIT_VKEYDOWN||Simulate any key press on the keyboard; dwData is the virtual key code|
|QIT_VKEYUP||Simulate any key release on the keyboard; dwData is the virtual key code|
|QIT_VSHIFTDOWN||Simulate pressing a set of shift keys. dwData can be a combination of the following flags: LCTRLFLAG, RCTRLFLAG, LALTFLAG, RALTFLAG, K_SHIFTFLAG, K_CTRLFLAG, K_ALTFLAG|
|QIT_VSHIFTUP||Release the shift state, dwData is the same as the previous flags.|
|QIT_CHAR||dwdata is any WCHAR. For an ANSI window, zero-pad an 8-bit character.|
|QIT_DEADKEY||dwData is any value from 0x0001 to 0xFFFE. This can be matched in the context with KMGetContext.|
|QIT_BELL||dwData should be zero (0).|
|QIT_BACK||dwData should be zero (0).|
BOOL WINAPI KMHideIM(HWND hwndIM);
KMHideIM hides the IMC window referred to by hwndIM and ensures that Keyman processes input from the keyboard through the correct method. You should call this rather than hiding the window manually with ShowWindow(hwnd, SW_HIDE); or post the message wm_keymanim_close to hide the window.
BOOL WINAPI KMDisplayIM(HWND hwndIM, BOOL FCaptureAll);
KMDisplayIM displays the IMC window referred to by hwndIM. It does not do any movement of the window. If the FCaptureAll flag is set, all keyboard input (character-generating keys only) will be redirected to the IMC window until the message wm_keymanim_close is posted, KMHideIM is called, or KMDisplayIM with FCaptureAll is set to false.
BOOL WINAPI KMGetKeyboardPath(PSTR keyboardname, PWSTR dir, DWORD length);
This function returns the full path to the keyboard referred to by keyboardname. The buffer dir should be 260 characters long.
BOOL WINAPI KMGetActiveKeyboard(PSTR keyboardname, DWORD length);
This function can be called while processing to determine which is the active keyboard. Alternatively, use the callbacks KeymanIMActivate and KeymanIMDeactivate.
BOOL WINAPI KMSendDebugString(PSTR str);
This function outputs the string str to the Keyman debug window or debug log file (usually c:\keyman.log).
The Input Method Composition window
The IMC window can be shown or hidden at any time that the associated keyboard is active. This means that you can have an IMC window permanently open or open at appropriate times.
The keyboard IMSample included with Keyman is a good example of manipulating the IMC display.
The window should be created invisible, most probaly as a popup window. The window can use KMGetContext, KMSetOutput at any time, but output will not be put to the screen until it has posted (not sent) wm_keymanim_close to itself.
PostMessage(hwnd, wm_keymanim_close, (WPARAM) FSuccess, (LPARAM) FActuallyClose);
Keyman will manage the window display, focus, and message loop. The window procedure should set the position and size appropriately.
Keyman will recognise this window and any child windows to be part of the IM and will not attempt to process any input that goes through the window.
The IMC window must not take focus at any time.
Clicks outside the window will cancel the IM and lose context.
Switching applications will cancel the IM and lose context.