Keyboard Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com

Other versions
Version 18.0Version 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 2 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 descriptionObject or array element members
(container object)
NameTypeDescriptionRequired
tabletObjectTablet layout specificationNo
phoneObjectPhone layout specificationNo
desktopObjectDesktop OSK layout specificationNo
(layout specification)
NameTypeDescriptionRequired
fontstringKey label default fontNo
fontsizestringKey label default font size (in em)No
layerObject arrayArray of layer specificationsYes
layer
NameTypeDescriptionRequired
idstringLayer nameYes
rowObject arrayArray of keyboard row specificationsYes
nextlayerstringKeyboard layer to display after processing keystrokeNo
row
NameTypeDescriptionRequired
idstringRow numberYes
keyObject arrayArray of keyboard key specificationsYes
key
NameTypeDescriptionRequired
idstringKey identifierYes*
textstringText on keyNo
fontstringFont name if different from default key label fontNo
fontsizestringFont size if different from default key label font sizeNo
spnumberKey styleNo
widthnumberKey widthNo
padnumberSpace before keyNo
dknumberDeadkey (1) or normal key (0 or omitted) No
layerstringModifier key or keys assumed applied when mapping this keyNo
nextlayerstringName of keyboard layer to be displayed after this key is processedNo
skObject arrayArray of pop-up key specificationsNo

Details of key member specifications are given below:

Member nameDetails
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 specify a Unicode character in hex format, e.g. U_1363 for the Ethiopic Comma character, and will insert that character if 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
ValueKey style
0Normal key (default)
1Shift key
2Active shift key
8Deadkey
9Blank key
10Spacer
fontThe font for the key label may be specified if it is necessary to use a different font for that key.
fontsizeThe 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.
padSpace 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 shift, ctrl, alt, ctrlshift, altshift, ctrlalt and ctrlaltshift 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:

IdentifierValue
K_NUMERALS261
K_SYMBOLS262
K_CURRENCIES263
K_SHIFTED264
K_ALTGR265

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 stringKey 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 right Alt modifier state
*TabLeft*Go back to previous input element in tab order