Keyboard.mapKeypress()

Overview

Overrides the default key mapping using a system level key press and key state to output a Velocity key code.

When the key code is detected, the script checks to see if any of the filter key states (such as Shift or Alt) are in use.

Added in version 2.1.5

Android only

Format

Keyboard.mapKeypress(systemKeyCode, filterKeyState, enabledKeyState, velocityKeyCode);

Parameter Description Type Required Notes
systemKeyCode The key code as defined by the system. Key codes for Android use the KeyEvent.KEYCODE_* values specified in the Android documentation. Integer Required  
filterKeyState The key states that should be checked. Values from KeyState can be combined together. See below for possible Keystate values. Integer Required To map a key regardless of what states are in use, set this to none.
enabledKeyState The key states that must be on or down. Values from Keystate can be combined together. The enabledKeyState should be a subset of states used in filterKeyState. Integer Required To map a key when no states are in use, specify the possible states in the filterKeyState and then set this to none.
velocityKeyCode The Velocity key code that should be produced. A value of 0x0000 will cause the key code to be ignored. A value of 0xFFFF will cause the key code to be bypassed and processed by the system. For a list of Velocity key codes see Keyboard Codes and Commands in the Velocity User Guide. Integer Required  

Remarks

Keypress mappings added first will take precedence.

Each session maintains its own keypress mappings.

The filterKeyState and enabledKeyState parameters are used together and specify which state modes are checked and which states must be on respectively.

If enabledKeyState includes a state that is not included in filterKeyState, then the mapping will never match.

If both the filterKeyState and enabledKeyState parameters are KeyState.none, then the keyboard state is ignored and only the systemKeyCode is used to match.

The option Press and hold number keys to send function keys in Velocity will not work with keys mapped with this function.

Multi-tap keyboards (keyboards with multiple characters on the same key) may not work as expected with this function.

Keys mapped with this function may be processed again in WLEvent.on("Key",...) or WLEvent.onKey().

KeyState object

The KeyState object defines constants representing the shift state of the keyboard. It should be used in the mapKeypress() function. These values are bit flags and can be combined together to represent multiple states. For shift, alt, ctrl, and meta these flags will be on when either the left or right keys are pressed.

Field Description Value
none No shift state. 0x00000000
shift Either of the Shift keys are pressed. 0x00000001
alt Either of the Alt keys are pressed. 0x00000002
sym The Sym state is pressed. 0x00000004
func The Func state is pressed. 0x00000008
altLeft The left Alt key is pressed. 0x00000010
altRight The right Alt key is pressed. 0x00000020
shiftLeft The left Shift is pressed. 0x00000040
shiftRight The right Shift is pressed. 0x00000080
ctrl Either of the Control keys are pressed. 0x00001000
ctrlLeft The left Control key is pressed. 0x00002000
ctrlRight The right Control key is pressed. 0x00004000
meta Either of the meta keys are pressed. 0x00010000
metaLeft The left Meta key is pressed. 0x00020000
metaRight The right Meta key is pressed. 0x00040000
capsLock The caps lock is engaged. 0x00100000
numLock The num lock is engaged. 0x00200000
scrollLock The scroll lock is engaged. 0x00400000

Example 1

Copy
/* Map the right control key as the 5250 send key
 */
Keyboard.mapKeypress(114, KeyState.ctrlRight, KeyState.ctrlRight, 0x000A);

Example 2

Copy
/* Map shift+A as the F3 key. Ctrl, Alt, and Func must not be on.
 */
Keyboard.mapKeypress(29, KeyState.shift | KeyState.ctrl | KeyState.alt | KeyState.func, KeyState.shift, 0xE03D);

Example 3

Copy
/* Map Ctrl+RightArrow as the letter A. Shift, Alt, and Func must not be on.
 */
Keyboard.mapKeypress(0x16, KeyState.shift | KeyState.ctrl | KeyState.alt | KeyState.func, KeyState.ctrl, 0x0041);

Example 4

Copy
/* Ignore the 4 key in any shift state. Will also ignore Shift+4 and the 4 combined with any other state.
 */
Keyboard.mapKeypress(11, KeyState.none, KeyState.none, 0x0000);