DLL Interface for Keyman
Keyman's multiple group processing is powerful, but sometimes you need to beable to do something a bit more complex, such as a dictionary lookup. Keyman'sDLL interface let you do this. You can call a function in a DLL in the sameway as you call another group. The function can read the context, deadkeys andthe current keystroke, and output characters, deadkeys, virtual keys, beeps andother items.
The DLL interface also allows you to create a popup Input Method Composition (IMC)window. This window allows the user to select visually the characters they arewishing to input. The window can be set to be visible when the keyboard is active,or after an appropriate key sequence. When the window is visible, it can be set tocapture all keyboard input, or be passive.
The DLL should be placed in any of the following locations:
The best option is the first, as you can then include the DLL in a Keyman package for easy installation and uninstallation.
General usage information
DLL functions used in place of groups are called DLL group functions.All strings, apart from keyboard names, are passed as WCHAR, regardless of whetherthe active window is a Unicode window or not. ANSI characters are represented as16-bit WCHAR, with high bits zeroed out.
The DLL will be loaded for each process in which the keyboard is activated. Remember that the DLL will not share memory between these processes by default, so ifyou have large memory requirements, you should use memory mapped files or possiblySHARDATA segments to minimize the memory consumption.
DLL group functions are called in a fairly time-critical environment. It is importantthat you minimise the processing time in these functions. It is essential that youavoid any window focus or activation -- message boxes are definitely out of the question.For debugging purposes, there is a Keyman32.dll function exported for writing to thelogfile (see the section titled Keyman32 imports).
DLLs can handle multiple keyboards at once. The keyboards are identified by a name whichis the filename of the keyboard, minus path and extension. For example, givenc:\keyman\imsample\imsample.kmx, the keyboard name is imsample. These are the same namesthat Keyman uses internally, for example in the registry and directory names.
Parameters for the DLL can be stored in two locations in the registry. They should alwaysbe stored under HKEY_CURRENT_USER, as the user may not have permission to change machine-widesettings, and the settings should not affect other users. The following locations are recommended:HKEY_CURRENT_USER\Software\Tavultesoft\Keyman.0\IMX\
The .kmn interface
Inside a .kmn file, you define the DLL group function interface as follows:
You can use this anywhere where you would place the use statement (except inthe begin statement), with the call statement. For example,
+ 'a' > call(DLLFunction)
A single .kmn file can reference multiple DLL group functions, in a single or multiple DLLs.
|The DLL file|