Keyboard Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com

On this page

Virtual Keys and Virtual Character Keys

With ordinary rules, you can match any key that produces a character. However, sometimes you may want to match other keys, for example Backspace, or Ctrl- or Alt-combinations. In order to match keys like these you need to use virtual keys.

Every key on the keyboard is identified by a virtual key code. Virtual keys are identified by square brackets [ ] containing a combination of zero or more shift-key codes and a virtual key code.

Using virtual keys

Virtual keys are used in the key section of a rule. Virtual keys are not valid in the context of a rule, as the context consists solely of characters. As virtual keys can only be output on a few platforms, they should not be used in the output section of a rule.

A typical use of virtual keys is to make rules to recognise non-character keys, such as Backspace or Tab; for example:

+ [K_TAB] > "You pressed Tab"

Virtual keys are also commonly used to recognise Ctrl or Alt key combinations, like this:

+ [CTRL ALT K_A] > "You pressed Ctrl+Alt+A"

While Keyman virtual keys are closely related to the Windows virtual keys, there are differences, and the two cannot be used completely interchangeably. Most of the following discussion relates to physical keyboards.

The key codes refer to the actual key at the given position on a standard US-English keyboard. When used with a non US-English keyboard driver (selected through Control Panel/Keyboards), differences can arise, and this use is not recommended.

The Right-Alt key has traditionally been used on European keyboards as an additional shift state, usually known as AltGr. The end user of Keyman keyboards can select an option to emulate Right-Alt with Ctrl+Alt, as Right-Alt is not available on many notebook keyboards. Thus, it is wise to avoid using Ctrl+Alt combinations and Right-Alt combinations in the same keyboard.

Additionally, it is useful to keep in mind that when this emulation is active, it is not possible to recognise the Ctrl+Right Alt combination, as this is overridden by Ctrl+Alt (producing Right-Alt). This can have ramifications in keyboards such as German, which makes use of the Ctrl+AltGr combination.

Virtual Keys vs Virtual Character Keys: Keyman 6.0 introduced a new feature known as mnemonic layouts. This feature requires that the "white" alphabet/numeric/punctuation keys in the primary section of the keyboard are referenced by the character on the key cap rather than the key position (as with non-mnemonic layouts). However, all other keys on the keyboard should be referenced as normal.

It is important to remember that you can choose any character that appears on a given keycap, not just the unshifted character. For instance, if you use ['A'], you will be matching the unshifted A key; you must still explicitly state the shift state for the key.

Reference

The general format for a virtual character key is:

[ shift-codes 'c' ]

where 'c' is any character on the keyboard. This can include characters on European keyboards.

The general format for a virtual key is:

[ shift-codes K_key ]

The possible shift codes are:

Shift Key Code
Either shift key SHIFT
Either control key CTRL
Left control key LCTRL
Right control key (not found on all keyboards) RCTRL
Either alt key ALT
Left alt key LALT
Right alt key or AltGr on European keyboards (not found on all keyboards) RALT
Caps Lock on CAPS
Caps Lock off NCAPS

Using Right Alt / AltGr

A caveat for using RALT: When using many European keyboards, Windows internally translates the RALT (or AltGr) key to LCTRL+RALT. Keyman also includes an option to treat CTRL+ALT in the same manner as RALT (this is useful for notebook keyboards that do not have a RALT or AltGr key. Both of these 'features' mean that you should avoid using more than one of the following shift combinations in the same keyboard:

Shift Code
RALT
CTRL ALT
CTRL RALT
LCTRL ALT
LCTRL RALT

Caps Lock

If neither CAPS or NCAPS is specified, then the CAPS LOCK key is ignored. This means that if you do have a rule that uses CAPS, you should make sure that no other rule references that key without NCAPS or CAPS specified. In the following example, the [CAPS K_A] rule will never be matched, because the [K_A] rule does not take CAPS LOCK into account:

+ [K_A] > 'small a'   c WRONG!
+ [CAPS K_A] > 'BIG A'

Instead, you should use:

+ [NCAPS K_A] > 'small a'   c Right!
+ [CAPS K_A] > 'BIG A'

Caps lock is also controlled by Caps lock stores.

Common virtual key codes

The following table lists all of the common virtual key codes:

Key Code Key Name Key Code Key Name
K_SPACE K_oE2 102nd Key (European)
K_A A K_BKSP Backspace
K_B B K_TAB Tab
K_C C K_ENTER Enter
K_D D K_ESC Escape
K_E E K_LEFT Left Arrow
K_F F K_UP Up Arrow
K_G G K_RIGHT Right Arrow
K_H H K_DOWN Down Arrow
K_I I K_PGUP Page Up
K_J J K_PGDN Page Down
K_K K K_HOME Home
K_L L K_END End
K_M M K_INS Insert
K_N N K_DEL Delete
K_O O K_F1 F1
K_P P K_F2 F2
K_Q Q K_F3 F3
K_R R K_F4 F4
K_S S K_F5 F5
K_T T K_F6 F6
K_U U K_F7 F7
K_V V K_F8 F8
K_W W K_F9 F9
K_X X K_F10 F10
K_Y Y K_F11 F11
K_Z Z K_F12 F12
K_1 1 K_KP5 Key Pad 5 (Numlock off)
K_2 2 K_NP0 Number Pad 0
K_3 3 K_NP1 Number Pad 1
K_4 4 K_NP2 Number Pad 2
K_5 5 K_NP3 Number Pad 3
K_6 6 K_NP4 Number Pad 4
K_7 7 K_NP5 Number Pad 5
K_8 8 K_NP6 Number Pad 6
K_9 9 K_NP7 Number Pad 7
K_0 0 K_NP8 Number Pad 8
K_BKQUOTE ` K_NP9 Number Pad 9
K_HYPHEN - K_NPSTAR Number Pad *
K_EQUAL = K_NPPLUS Number Pad +
K_LBRKT [ K_NPMINUS Number Pad -
K_RBRKT ] K_NPDOT Number Pad .
K_BKSLASH \ K_NPSLASH Number Pad /
K_COLON ;
K_QUOTE '
K_COMMA ,
K_PERIOD .
K_SLASH /

The following table lists all of the less common virtual key codes:

Key Code Key Name Key Code Key Name
K_SEL Select K_?96 Unknown Key 96
K_PRINT Print K_?97 Unknown Key 97
K_EXEC Execute K_?98 Unknown Key 98
K_HELP Help K_?99 Unknown Key 99
K_SEPARATOR Separator K_?9A Unknown Key 9A
K_F13 F13 K_?9B Unknown Key 9B
K_F14 F14 K_?9C Unknown Key 9C
K_F15 F15 K_?9D Unknown Key 9D
K_F16 F16 K_?9E Unknown Key 9E
K_F17 F17 K_?9F Unknown Key 9F
K_F18 F18 K_?A0 Unknown Key A0
K_F19 F19 K_?A1 Unknown Key A1
K_F20 F20 K_?A2 Unknown Key A2
K_F21 F21 K_?A3 Unknown Key A3
K_F22 F22 K_?A4 Unknown Key A4
K_F23 F23 K_?A5 Unknown Key A5
K_F24 F24 K_?A6 Unknown Key A6
K_KANJI?15 Kanji Key #1 K_?A7 Unknown Key A7
K_KANJI?16 Kanji Key #2 K_?A8 Unknown Key A8
K_KANJI?17 Kanji Key #3 K_?A9 Unknown Key A9
K_KANJI?18 Kanji Key #4 K_?AA Unknown Key AA
K_KANJI?19 Kanji Key #5 K_?AB Unknown Key AB
K_KANJI?1C Kanji Key #6 K_?AC Unknown Key AC
K_KANJI?1D Kanji Key #7 K_?AD Unknown Key AD
K_KANJI?1E Kanji Key #8 K_?AE Unknown Key AE
K_KANJI?1F Kanji Key #9 K_?AF Unknown Key AF
K_oE0 OEM Key E0 K_?B0 Unknown Key B0
K_oE1 OEM Key E1 K_?B1 Unknown Key B1
K_oE3 OEM Key E3 K_?B2 Unknown Key B2
K_oE4 OEM Key E4 K_?B3 Unknown Key B3
K_oE6 OEM Key E6 K_?B4 Unknown Key B4
K_oE9 OEM Key E9 K_?B5 Unknown Key B5
K_oEA OEM Key EA K_?B6 Unknown Key B6
K_oEB OEM Key EB K_?B7 Unknown Key B7
K_oEC OEM Key EC K_?B8 Unknown Key B8
K_oED OEM Key ED K_?B9 Unknown Key B9
K_oEE OEM Key EE K_?C1 Unknown Key C1
K_oEF OEM Key EF K_?C2 Unknown Key C2
K_oF0 OEM Key F0 K_?C3 Unknown Key C3
K_oF1 OEM Key F1 K_?C4 Unknown Key C4
K_oF2 OEM Key F2 K_?C5 Unknown Key C5
K_oF3 OEM Key F3 K_?C6 Unknown Key C6
K_oF4 OEM Key F4 K_?C7 Unknown Key C7
K_oF5 OEM Key F5 K_?C8 Unknown Key C8
K_?00 Unknown Key 00 K_?C9 Unknown Key C9
K_?05 or K_NPENTER Number Pad ENTER K_?CA Unknown Key CA
K_?06 Unknown Key 06 K_?CB Unknown Key CB
K_?07 Unknown Key 07 K_?CC Unknown Key CC
K_?0A Unknown Key 0A K_?CD Unknown Key CD
K_?0B Unknown Key 0B K_?CE Unknown Key CE
K_?0E Unknown Key 0E K_?CF Unknown Key CF
K_?0F Unknown Key 0F K_?D0 Unknown Key D0
K_?1A Unknown Key 1A K_?D1 Unknown Key D1
K_?3A Unknown Key 3A K_?D2 Unknown Key D2
K_?3B Unknown Key 3B K_?D3 Unknown Key D3
K_?3C Unknown Key 3C K_?D4 Unknown Key D4
K_?3D Unknown Key 3D K_?D5 Unknown Key D5
K_?3E Unknown Key 3E K_?D6 Unknown Key D6
K_?3F Unknown Key 3F K_?D7 Unknown Key D7
K_?40 Unknown Key 40 K_?D8 Unknown Key D8
K_?5B Unknown Key 5B K_?D9 Unknown Key D9
K_?5C Unknown Key 5C K_?DA Unknown Key DA
K_?5D Unknown Key 5D K_oDF Unknown Key DF
K_?5E Unknown Key 5E K_?E5 Unknown Key E5
K_?5F Unknown Key 5F K_?E7 Unknown Key E7
K_?88 Unknown Key 88 K_?E8 Unknown Key E8
K_?89 Unknown Key 89 K_?F6 Unknown Key F6
K_?8A Unknown Key 8A K_?F7 Unknown Key F7
K_?8B Unknown Key 8B K_?F8 Unknown Key F8
K_?8C Unknown Key 8C K_?F9 Unknown Key F9
K_?8D Unknown Key 8D K_?FA Unknown Key FA
K_?8E Unknown Key 8E K_?FB Unknown Key FB
K_?8F Unknown Key 8F K_?FC Unknown Key FC
K_?92 Unknown Key 92 K_?FD Unknown Key FD
K_?94 Unknown Key 94 K_?FE Unknown Key FE
K_?95 Unknown Key 95 K_?FF Unknown Key FF

The following table lists all of the reserved virtual key codes that will not be recognised even if they are on your keyboard, although they are included in Keyman for completeness:

Key Code Key Name
K_SHIFT Shift
K_CONTROL Control
K_ALT Alt
K_CAPS Caps Lock
K_NUMLOCK Num Lock
K_SCROLL Scroll Lock
K_LBUTTON Left Mouse Button
K_MBUTTON Middle Mouse Button
K_RBUTTON Right Mouse Button
K_CANCEL Ctrl+Break
K_PAUSE Pause
K_PRTSCN Print Screen

Examples

c override default bksp behaviour for 'ng'
'ng' + [K_BKSP] > nul

+ [SHIFT CTRL K_A] > 'à'
+ [RALT K_E] > 'è'

Virtual keys should not be used in the output as they will only work on Windows applications and are not portable.

Virtual keys and touch layouts

Touch layouts do not have physical keyboards, so the concept of virtual keys is in some ways less relevant. However, for compatibility and ease of reference, Keyman maintains a mapping between the US English virtual key codes and the characters emitted by these keys. If a touch key is given one of these virtual keys (e.g. K_A), then the corresponding US English character (a) will be emitted, if no rule is provided to override that.

Each touch key must be given an identifying key code which is unique to the key layer. Key codes by and large correspond to the virtual key codes used when creating a keyboard program for a desktop keyboard, and should start with K_, for keys mapped to standard Keyman virtual key names, e.g. K_HYPHEN, and T_ or U_ for user-defined names, e.g. T_ZZZ. If keyboard rules exist matching the key code in context, then the output from the key will be determined by the processing of those rules. It is usually best to include explicit rules to manage the output from each key, but if no rules matching the key code are included in the keyboard program, and the key code matches the pattern U_xxxx (where xxxx is a 4-digit uppercase hex string), then the Unicode character U+xxxx will be output. The key code is always required, and a default code will usually be generated automatically by Keyman Developer 9.

  • K_xxxx is used for a standard Keyman Desktop key name, e.g. K_W, K_ENTER. You cannot make up your own K_xxxx names. Many of the K_ ids have overloaded output behaviour, for instance, if no rule is matched for K_W, Keyman will output 'w' when it is touched. The standard key names are listed above. Typically, you would use only the "common" virtual key codes.

  • T_xxxx is used for any user defined names, e.g. T_SCHWA. If you wanted to use it, T_ENTER would also be valid. If no rule matches it, the key will have no output behaviour.

  • U_#### is used as a shortcut for a key that will output that single Unicode value, if no rule matches it. This is similar to the overloaded behaviour for K_ ids. Thus #### must be a valid hexadecimal value. E.g. U_0259 would generate a schwa if no rule matches. It is still valid to have a rule such as + [U_0259] > ...

Any key can be used to switch keyboard layers (see below), but the following layer-switching key codes have been added for switching to some commonly used secondary layers:

Identifier Value
K_NUMERALS 261
K_SYMBOLS 262
K_CURRENCIES 263
K_SHIFTED 264
K_ALTGR 265