Keys, Virtual Keys and Virtual Character Keys

A rule is made up of three parts:

context + keystroke > output

The keystroke part of the rule may contain a Unicode character representing the value on the key cap of the base keyboard, a virtual key, a virtual character key, or one of the following statements:

any() statement

Matches on an array of characters

outs() statement

Outputs an array of characters

Only a single character, statement, virtual character key or virtual key is allowed in the keystroke part of the rule.

Four ways to express a keystroke

The meaning of the keystroke part is affected by the &mnemoniclayout system store value. If this store is not present, or its value is 0, then the keyboard is said to be positional. If the store value is 1, then the keyboard is mnemonic.

For hardware keyboards, the keystroke part of a rule can be expressed in four different ways:

With a character code, in a positional keyboard.

The key definition references the value on the key cap of a US English hardware keyboard. Caps Lock and Shift are accounted for (see issue #5460 for how to use this correctly with KeymanWeb, using &CasedKeys).

c matches NCAPS SHIFT C01 (aka NCAPS SHIFT K_A on US keyboard)
c also matches CAPS C01.
+ 'A' >

With a virtual key, in a positional keyboard.

The key definition references a key by its exact location on a US English hardware keyboard, or by an ISO9995 code. More info

c matches SHIFT C01 (aka SHIFT K_A on US keyboard)
c caps lock is ignored, unless you define &CasedKeys
+ [SHIFT K_A] >

c C01 is an alias for K_A
+ [SHIFT C01] >

c Explicitly specify Caps Lock with NCAPS and CAPS
+ [NCAPS SHIFT K_A] >
+ [CAPS K_A] >

With a character code, in a mnemonic keyboard.

This matches the key and modifier state that generates this character on the user's base keyboard, accounting for any modifier that might be used to generate the character, including Caps Lock.

c matches CAPS+D01 or SHIFT+D01 on US English
c matches CAPS+C01 or SHIFT+C01 on French AZERTY
+ 'Q' >

c matches SHIFT+K_LBRKT (D11) on US English
c matches AltGr+E04 on French AZERTY
+ '{' >

With a virtual character key, in a mnemonic keyboard.

This matches the key that generates this character on the user's base keyboard, along with the specified modifier. More info

c matches SHIFT+c on user's base keyboard (i.e. SHIFT B03 on US)
+ [SHIFT 'c'] >

c matches SHIFT+key that generates comma, i.e. SHIFT B08 on US
c which means '<' on US English but on French (SHIFT B07) means '?'
+ [SHIFT ','] >

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.

Virtual keys are only 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, nor in the output of the rule (note: Keyman for Windows did unofficially support output of virtual keys until version 14.0, but it never worked reliably).

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.

The Right Alt key has traditionally been used on European keyboards as an additional modifier 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 some 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.

Cased Keys

The &CasedKeys system store lets you define a set of keys on the keyboard that are affected by Caps Lock state. When present, the compiler will rewrite rules that contain the affected keys to avoid having to repeat rules. For example, you may have the following rules:

store(&CasedKeys) [K_A]
+ [K_A] > 'α'
+ [SHIFT K_A] > 'Α'

These would be replaced by the compiler with:

store(&CasedKeys) [K_A]
+ [NCAPS K_A] > 'α'
+ [SHIFT CAPS K_A] > 'α'
+ [CAPS K_A] > 'Α'
+ [SHIFT NCAPS K_A] > 'Α'

The presence of this store also ensures that Caps Lock is handled correctly for KeymanWeb keyboards (see #5460).

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 key-code ]

Key Codes

Key codes can start with K_, T_, U_ or can be an ISO9995 code.

K_xxxx codes

These are 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 the key is pressed or touched. The standard key names are listed below. Typically, you would use only the "common" virtual key codes.

T_xxxx codes

These are 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. These keys are only valid for touch layouts.

U_####[_....] codes

These are used as a shortcut for a key that will output a string of Unicode values, if no rule matches the key. (In Keyman 14 and earlier, only a single Unicode value was permitted.) This is similar to the overloaded behaviour for K_ ids. Thus #### must be valid Unicode codepoint values, in the range 0020-10FFFF, with sequences separated by _. E.g. U_0259 would generate a schwa if no rule matches. It is still valid to have a rule such as + [U_0259] > .... These codes are only valid for touch layouts. Note: For characters outside the BMP, use Unicode codepoints, not surrogate pairs (e.g. use U_10000, never U_D800_DC00).

ISO9995 codes

These codes refer to keys by position on a standard 101-105 key keyboard. See the tables below for the mappings that Keyman recognises. For example, C02 is equivalent to K_S.

Shift Codes

The possible shift codes are:

Using Right Alt / AltGr

A caveat for using RALT: When using many European keyboards, Windows internally translates the Right Alt (or AltGr) key to LCTRL+RALT. Along with Keyman's option to treat Control+Alt in the same manner as Right Alt, this means that you should avoid using more than one of the following shift combinations in the same keyboard:

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.

Virtual Key Visual Layout

Notes:

• This layout shows US English "QWERTY", with a few of the variations for French "AZERTY" and German "QWERTZ". It does not show variations for punctuation and some additional alphabetic letters, just to maintain clarity.
• The keys shown in blue are not present on all keyboards:
  • Left hand blue key [K_oE2] / [B00] is found on European layouts, among others.
  • Right hand blue key [K_?C1] / [B11] is found on Brazilian Portuguese ABNT layout.

Common virtual key codes

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

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

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:

Examples

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

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

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. The key code is always required, and a default code will usually be generated automatically by Keyman Developer.

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. Additionally, if the key code matches the pattern U_xxxx_yyyy... (where xxxx and yyyy are 4 to 6-digit hex strings), then the Unicode characters U+xxxx and U+yyyy will be output. U_xxxx_yyyy requires store(&VERSION) '15.0'.

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: