Keyboard Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com

Other versions
Version 17.0 (current version)Version 16.0Version 15.0Version 14.0Version 13.0Version 12.0Version 11.0Version 10.0Version 2.0

On this page

Layout Specifications


Touch-screen layouts for KeymanWeb 17 are specified as JSON objects containing a member object for each specified device type. Currently supported device types are tablet and phone. Layouts for desktop computers may also be specified but desktop on-screen keyboard design is normally managed by the standard Keyman Developer on-screen keyboard tool rather than the keyboard layout designer. If the same layout is appropriate for both tablet and phone devices only one need be specified, and will be used for either type of device.

File encoding for manually-created layout files may use either UTF-8 or 7-bit ANSI coding, but must not include a BOM. For easier editing and management without requiring special fonts, embedded Unicode characters with values above 127 may use the \uXXXX notation.

For details of the JSON specification, see The JSON Data Interchange Format(ECMA-404).

Object name or description Object or array element members
(container object)
Name Type Description Required
tablet Object Tablet layout specification No
phone Object Phone layout specification No
desktop Object Desktop OSK layout specification No
(layout specification)
Name Type Description Required
font string Key label default font No
fontsize string Key label default font size (in em) No
layer Object array Array of layer specifications Yes
layer
Name Type Description Required
id string Layer name Yes
row Object array Array of keyboard row specifications Yes
nextlayer string Keyboard layer to display after processing keystroke No
row
Name Type Description Required
id string Row number Yes
key Object array Array of keyboard key specifications Yes
key
Name Type Description Required
id string Key identifier Yes*
text string Text on key No
font string Font name if different from default key label font No
fontsize string Font size if different from default key label font size No
sp number Key style No
width number Key width No
pad number Space before key No
dk number Deadkey (1) or normal key (0 or omitted) No
layer string Modifier key or keys assumed applied when mapping this key No
nextlayer string Name of keyboard layer to be displayed after this key is processed No
sk Object array Array of pop-up key specifications No

Details of key member specifications are given below:

Member name Details
id Each key id must start with >K_ , for keys mapped to standard Keyman virtual key names, e.g. K_HYPHEN , or either U_ or T_ for user-defined names. Keys identified as U_xxxx[_xxxx...] specify one or more Unicode characters in hex format, e.g. U_1363 for the Ethiopic Comma character, and will insert those characters if the key id is not matched by a rule. Other user-defined keys, such as T_ZZZ , will be ignored unless matched by a rule. The key id is required except for key styles 9 or 10 (blank or spacer keys).
text Where a key id is of the form K_XXXX , the text on the key will be the indicated Unicode character if this member is omitted. However, what the keystroke output will depend on any rules that process the keystroke, and may or may not be the same as the key text.
sp
Value Key style
0 Normal key (default)
1 Shift key
2 Active shift key
8 Deadkey
9 Blank key
10 Spacer
font The font for the key label may be specified if it is necessary to use a different font for that key.
fontsize The font size for the key label may be specified (in em units) if necessary.
width By default, each key has a width of 100 units, with rows then scaled to make the widest row fit on the screen. Set the width value if a key should be narrower or wider than the standard width.
pad Space before key, in same units as width (default key width=100 units).
layer Override the default layer type for processing key rules. For example, use 'layer':'shift' in any layer to process a key rule as if it were the shift layer, i.e. as if the Shift key was down.
nextlayer Select the key layer to be displayed after processing the current keystroke. This will usually be used to implement custom layer selection, but can also be used to select a different layer after a deadkey or normal key, and will override any nextlayer value specifed for the entire layer. The layer to be displayed may also be specified using the setlayer() statement in a rule in the keyboard source.
sk Pop-up key specifications are identical to normal key specifications except that they cannot be nested. (Key size and spacing members width and pad are ignored for pop-up keys.)

For many keyboards, it is helpful to associate some keyboard layers with physical keyboard modifier states. This is reflected in the layer name, where a layer name of shift means that when a key in that layer is touched, the keystroke will be processed as if the keyboard Shift key is held.

The special layer names of:
leftalt , rightalt , alt ,
leftctrl , rightctrl , ctrl , ctrlalt ,
leftctrl-leftalt , rightctrl-rightalt , leftctrl-leftalt-shift , rightctrl-rightalt-shift ,
shift , shift-alt , shift-ctrl , shift-ctrl-alt ,
leftalt-shift , rightalt-shift , leftctrl-shift , and rightctrl-shift
each apply the appropriate modifier keys when processing rules unless overridden by a layer value in the key specification. The layer names default , numeric , symbol and currency are also recognized, but no modifier key is applied for keys in these layers.

The following special key identifiers have been added to simplify layer selection:

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

A special font is used to provide easily recognizable key graphics for various special purpose keys. The following key text strings will be recognized and cause the appropriate graphic to be used for the key cap instead of the actual text:

Text string Key purpose
*Shift* Shift key image (inactive)
*Enter* Return
*Tab* Move to next input element in tab order
*BkSp* Backspace
*Menu* Display the language menu
*Hide* Hide the virtual keyboard
*Alt* Alt key caption
*Ctrl* Control key caption
*Caps* Caps Lock caption
*ABC* Select the upper case alphabetic layer
*abc* Return to the default (alphabetic) keyboard layer
*123* Select a numeric keyboard layer
*Symbol* Select a layer with various non-letter symbols
*Currency* Select a layer with currency symbols
*Shifted* Active Shift key image
*AltGr* Select Control + Alt (AltGr) modifier state
*TabLeft* Go back to previous input element in tab order
*LAlt* Select left Alt modifier state
*RAlt* Select right Alt modifier state
*LCtrl* Select left Control modifier state
*RCtrl* Select right Control modifier state
*LAltCtrl* Select left Alt + left Control modifier state
*RAltCtrl* Select right Alt + right Control modifier state
*LAltCtrlShift* Select left Alt + left Control + Shift modifier state
*RAltCtrlShift* Select right Alt + right Control + Shift modifier state
*AltShift* Select Alt + Shift modifier state
*CtrlShift* Select Control + Shift modifier state
*AltCtrlShift* Select Alt + Control + Shift modifier state
*LAltShift* Select left Alt + Shift modifier state
*RAltShift* Select right Alt + Shift modifier state
*LCtrlShift* Select left Control + Shift modifier state
*RCtrlShift* Select right Control + Shift modifier state