The imlib.cpp library module
imlib.cpp, included in the development kit, contains a set of useful functions for interfacing to Keyman.
PrepIM
BOOL PrepIM(void);
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.
IMDefWindowProc
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.
Keyman Imports
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);
KMGetContext
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.
KMSetOutput
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:
while(backlen-- > 0) KMQueueAction(QIT_BACK, 0);
while(*buf) KMQueueAction(QIT_CHAR, *buf++);
KMQueueAction
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).
| itemType code | Description |
|---|---|
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. |
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). |
KMHideIM
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.
KMDisplayIM
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 set to FALSE.
KMGetKeyboardPath
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.
KMGetActiveKeyboard
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().
KMSendDebugString
BOOL WINAPI KMSendDebugString(PSTR str);
This function outputs the string str to the Keyman debug window or debug log file (usually %USERPROFILE%\Desktop\keymanlog\system*.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.
Limitations
- Clicks outside the window will cancel the IM and lose context.
- Switching applications will cancel the IM and lose context.
