Keyboard Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com

Other versions
Version 6.0

On this page

(image: Keyman icon) DLL Interface for Keyman

DLL exports

The DLL is called from Keyman with LoadLibrary. All functions are then found with GetProcAddress. You must ensure that the function exports do not have ordinals encoded in the names. The best way to accomplish this in C/C++ is to use a .def file.

DLL group function exports

The function declaration for the DLL group function is:

BOOL WINAPI KeyEvent(HWND hwndFocus, WORD KeyStroke, WCHAR KeyChar, DWORD ShiftFlags);

Note that KeyEvent is a placeholder for any name that you wish to use. You can have multiple exports for Keyman use in a single DLL.

Parameters

ParameterDescription
hwndFocusThe currently focused window. You will probably never have a need to use this.
KeyStrokeThe virtual key code for the current key.
KeyCharThe character code for the current key (based on US English layout). This will be 0 if KeyStroke does not generate a character (e.g. function keys).
ShiftFlagsThe shift state for the current key. See the table in the Notes section for possible shift states.

Notes

The following shift states are possible:

FlagValueDescription
LCTRLFLAG0x0001Left Control flag
RCTRLFLAG0x0002Right Control flag
LALTFLAG0x0004Left Alt flag
RALTFLAG0x0008Right Alt flag
K_SHIFTFLAG0x0010Shift flag
K_CTRLFLAG0x0020Ctrl flag (unused here; see l/r flags)
K_ALTFLAG0x0040Alt flag (unused here; see l/r flags)
CAPITALFLAG0x0100Caps lock on
NUMLOCKFLAG0x0400Num lock on
SCROLLFLAG0x1000Scroll lock on
ISVIRTUALKEY0x4000It is a Virtual Key Sequence

Keyman recognises a number of other exports, if they are defined in the DLL. None of these are required. These functions will be called when a keyboard that references the DLL is manipulated. They will not be called for keyboards that do not reference the DLL.

The following exports are available:

KeymanIMInit

BOOL WINAPI KeymanIMInit(PSTR keyboardname);

KeymanIMInit is called once when the keyboard identified by keyboardname is loaded for a given process. It is called for each process in which the keyboard is loaded.

KeymanIMDestroy

BOOL WINAPI KeymanIMDestroy(PSTR keyboardname);

This is called once when the keyboard identified by keyboardname is unloaded in a given process. It is called when the process exits normally, or when Keyman refreshes its keyboard list after keyboards are added or removed. If the keyboard is subsequently reloaded, KeymanIMInit will be called again.

KeymanIMActivate

BOOL WINAPI KeymanIMActivate(PSTR keyboardname);

This function is called whenever the user or a program activates the keyboard. It is never called before KeymanIMInit (unless KeymanIMInit is not exported). This is an appropriate place to switch on permanently-visible IMC windows. KeymanIMActivate can also be called when switching processes and the target process has a related keyboard already active.

KeymanIMDeactivate

BOOL WINAPI KeymanIMDeactivate(PSTR keyboardname);

This function is called when the user or a program switches off a related keyboard. It is always called before KeymanIMActivate for the next keyboard. It will also be called when the user activates another process, to give the DLL a chance to hide top-most IMC windows.

KeymanIMConfigure

BOOL WINAPI KeymanIMConfigure(PSTR keyboardname, HWND hwndParent);

KeymanIMConfigure is called when the user clicks the Configure button in KMShell to configure the DLL-specific functionality for the keyboard. The appropriate behaviour is to display a dialog box, and save the settings in the registry.

This function is separate from all the other functions. It can be called when there are no keyboards loaded, or even if Keyman itself is not loaded. You should not attempt to call Keyman32.dll from this function.