Keyboard.mapKeypress()
Overview
Overrides the default key mapping using a system level key press and key state to output a Velocity key code. This can also be used if a key is not mapped in the Velocity Client (if it shows an empty Key Value in the Client's key test mode). To see if a key is mapped by the Velocity Client, enable the key test mode using a Global Settings project and then access it in the Client menu.
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
/* Map the right control key as the 5250 send key
*/
Keyboard.mapKeypress(114, KeyState.ctrlRight, KeyState.ctrlRight, 0x000A);Example 2
/* 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
/* 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
/* 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);