Layout Specifications
Touch-screen layouts for KeymanWeb 10 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) |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| (layout specification) |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| layer |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| row |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| key |
|
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 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 |
| ||||||||||||||
| 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 |
