The keys.ttkeyboard file must be in UTF-8 format.
All lines in the keys.ttkeyboard file must end in a line feed or a carriage return/line
feed pair. All settings are case-sensitive.
The default keys.ttkeyboard files are available for download:
Identifiers
These settings identify specific keyboard layouts and set off comments.
| Setting |
Description |
| + |
Name keyboard layout and begin section. Also ends previous keyboard
layout if one is present.
Adding .P or .L to the end of the name limits display of the layout to portrait
or landscape mode respectively.
With that exception, a period in the name identifies the layout as subordinate
to another layout with the same name, but without the dot extension. It also prevents the layout name from being
displayed in TinyTERM. For example, +PC English.L.shift is a
subordinate layout of +PC English.L.
+3270 Landscape |
| # |
Comment line. These can be inserted anywhere in the keys.ttkeyboard file.
# Default layout in landscape mode |
General Settings
These settings can be placed anywhere in the keys.ttkeyboard file, preceded with a
dash. They will affect all lines below them, until a new instance of the setting
is found.
| Setting |
Description |
|
| fontSize |
Maximum font size in points of main key labels. The label size will be
reduced automatically to fit the key if needed.
-fontSize 30 |
|
| keyboardHeight |
Sets the height of the keyboard layout. The value is in pixels on first-
and second-generation iPads. On the new iPad with Retina display, this value is
half the number of pixels the layout will use. Defaults to 350
-keyboardHeight 264 |
| keyboardWidth |
Sets the width of the layout. Uses the same pixel values as
keyboardHeight. Defaults to the full screen width.
-keyboardWidth 130 |
| keyHeight |
Changes the default height of the keys, relative to a base value of 1.
keyHeight can be specified to the second decimal place, as
in the example below. It cannot be set to a specific number of pixels.
Default key height in pixels is calculated instead, based on the number of
key rows, the spacing and margin settings, iPad
orientation, and individual keys not using the default keyHeight value.
-keyHeight 1.44 |
| labelPosition |
Sets vertical position and horizontal justification of the main key label.
See image at right for the available values. Note that 0, 3 and 6 left-justify the
text; 2, 5 and 8 right-justify it; and 1, 4 and 7 center the label. Defaults to 4.
This option is only available on iPad.
-labelPosition 5 |
 |
| layout |
Sets the position of the keyboard layout:
| 0 |
| main (default) |
| 1 |
| horizontal across top of main keyboard |
| 2 |
| vertical on right edge of screen |
| 3 |
| horizontal on bottom edge of screen (with external keyboard) |
| 4 |
| vertical on right edge of screen (with external keyboard) |
-layout 1
|
| lineJustification |
Sets the justification for rows of keys:
| 0 |
| center (default) |
| 1 |
| left justify |
| 2 |
| right justify |
-lineJustify 1
|
| margin |
Minimum number of pixels on each edge – top, bottom, left and
right – of the keyboard.
-margin 3 |
|
| orientation |
Used only within layouts. Determines whether the
layout displays in portrait, landscape or both modes:
| 0 |
| both (default) |
| 1 |
| portrait |
| 2 |
| landscape |
-orientation 1
|
| shiftFontSize |
Maximum font size in points of shiftLabel text. As with
fontSize, shift labels will be reduced to fit if needed. This option is only available on iPad.
-shiftFontSize 16 |
|
| shiftLabelPosition |
Starting position of the shiftLabel text. Uses the same values as
labelPosition. Defaults to 0. This option is only available on iPad.
-shiftLabelPosition 1 |
|
| size |
Changes the default width of keys, relative to a base value of 1.
size can be specified to the second decimal place. It cannot be
set to a specific number of pixels. Default key size in pixels
is calculated instead, based on the number of keys in the widest row, the
spacing and margin settings, iPad orientation,
and any individual keys not using the default size value.
-size 1.5 |
| spacing |
Minimum number of pixels between keys
-spacing 2 |
|
Key Options
When a key is defined within square brackets [ ], options may be added to
the definition, set off by two semicolons. Many of the general settings can also be
applied to individual keys, and so are repeated below with key-specific examples.
Options are all case-sensitive.
When a semicolon is desired as a displayed character inside the brackets, such as
for a label or shiftLabel, separate it from the double semicolons by a
space:
[; ;;shiftLabel=:]
| Option |
Description |
| \ |
Escape character. Used for special characters
that have other uses without the \. Square brackets are not required for
this option.
\\ |
| blank |
When set to 1, prevents the key from being drawn. Used for creating
space between visible keys in addition to that specified by the spacing
attribute. Blank keys are treated as any others by general attributes.
[BLANK;;blank=1] |
| capsKey |
When set to 1, causes the key to act as a Caps Lock key,
regardless of other settings.
[Caps;;capsKey=1] |
| hideKey |
When set to 1, causes the key to hide the keyboard when tapped. Also
replaces any text with a keyboard graphic. The keyboard can be restored by
tapping the keyboard button in the title bar.
[HIDE;;hideKey=1] |
| fontSize |
Sets the font size for the primary label of the key.
[Clear;;keyChar=1148;;fontSize=15] |
| keyChar |
Assigns a specific value to a key. Available values are
listed below.
[Enter;;keyChar=13] |
| keyHeight |
Changes the height of the individual key, relative to a base value of 1.
keyHeight can be specified to the second decimal place. Keys
taller than the default for the row expand into the next row down.
When making single a key taller than 1, free the space in the row below by
creating a key there with the blank option.
[New Line;;keyHeight=2;;keyChar=1153] |
| keyString |
Assigns a multi-character string to a key.
This allows you to create custom key mappings with multi-byte
sequences on a single keystroke.
[Login;;keyString=username] |
| labelPosition |
Sets vertical position and horizontal justification of the main key label.
Defaults to 4. This option is only available on iPad.
[,;;labelPosition=7] |
| printScreen |
When set to 1, this key will print the current emulator screen to the
currently selected printer. Defaults to 0.
[PrtScr;;printScreen=1] |
| shiftFontSize |
Sets the font size for the shiftLabel of this key.
This option is only available on iPad.
[2;;shiftLabel=@;;shiftFontSize=12] |
| shiftId |
Changes the identity of a shift key. By default, the ID for a given
shiftTo or shiftLock key is the layout it refers to. This option
overrides that behavior, giving the key a unique ID.
[Ctrl;;shiftTo=PC English.L;;shiftId=PC English.L.ctrl] |
| shiftLabelPosition |
Sets vertical position and horizontal justification of the
shiftLabel. Defaults to 0.
[3;;shiftLabel=#;;shiftLabelPosition=2] |
| shiftLabel |
Displays the character as secondary on the keyboard key. Most often used
to show what character will be typed when the shift key is held. There is
no way to display more than two labels on a key. This option is only available on iPad.
[3;;shiftLabel=#] |
| shiftLock |
Used without shiftTo, takes a keyboard layout name. The selected layout
will replace the current layout.
[Fn;;shiftLock=3270 Portrait.function] |
Used with shiftTo, takes a numeric value that determines how the
key works. Also requires a shiftId label to identify the layout to return to.
| 0 |
| Hold-shift: hold key down for shift characters |
| 1 |
| Lock-shift: switch to another layout until tapped again |
| 2 |
| Single-shift: tap to shift.
On typing a shift character, revert to original layout. |
| 3 |
| Double-shift: hold to shift temporarily, or double-tap to lock-shift. |
| 4 |
| Single-shift with double-shift: tap once to shift as with 2 above,
or double-tap to lock-shift as 3 above. (default) |
[Shift;;shiftTo=PC English.L.shift;;shiftLock=0] |
| shiftTo |
Selects a keyboard layout to switch to. Uses the shiftLock value
to determine whether or not it needs to be held.
[Shift;;shiftTo=3270 Portrait.shift] |
| size |
Changes the width of the individual key, relative to a base value of 1.
size can be specified to the second decimal place.
[Q;;size=1.45] |
Special Characters
The following characters are created with the escape character \.
| Character |
Value |
Character |
Value |
| \b |
backspace (hex 08) |
\\ |
backslash (hex 5c) |
| \[ |
left square bracket (hex 5b) |
\] |
right square bracket (hex 5d) |
| \r |
carriage return (hex 0d) |
\x |
UTF-8 hexadecimal number; e.g., \x000d for carriage return |
| \t |
horizontal tab (hex 09) |
\0 |
octal constant; e.g., \011 for horizontal tab |
| \xf700 |
up arrow key ↑ |
\xf701 |
down arrow key ↓ |
| \xf702 |
left arrow key ← |
\xf703 |
right arrow key → |
| \xf704-\xf717 |
function keys F1-F20 |
\xf72b |
End key |
Special characters may be used in combination with the keyString
option to create complex sequences:
[PartNum;;keyString=015-249\tsku015249\xf70d]
keyChar Values
The following values may be assigned to keys, using the keyChar
option. Not all available values are listed. Standard Unicode values may be used
as well for a wide range of characters.
| Value |
Keyboard Key |
Value |
Keyboard Key |
| 0-255 |
Equivalent ASCII character1 |
61747 |
Ctrl-Page Down |
| 63236-63255 |
Function keys F1-F20 |
61748 |
Ctrl-⌫ |
| 63232 |
Up ↑ |
61749 |
Ctrl-Enter |
| 63233 |
Down ↓ |
61750 |
Ctrl-Esc |
| 63234 |
Left ← |
61751 |
Ctrl-Keypad - |
| 63235 |
Right → |
61752 |
Ctrl-Keypad + |
| 63273 |
Home |
61753 |
Ctrl-Keypad * |
| 61721-61730 |
Numeric Keypad 0-9 |
61754 |
Keypad * |
| 61731 |
Keypad - |
61755 |
Keypad + |
| 61732 |
Keypad , |
61756 |
Keypad / |
| 61733 |
Keypad . |
61757 |
Num Lock |
| 61734 |
Keypad Enter |
61758 |
Scroll Lock |
| 61735 |
Page Down |
61759 |
⌫ |
| 61736 |
Page Up |
61760 |
Ctrl-↑ |
| 61737 |
Ctrl-Home |
61761 |
Ctrl-↓ |
| 63275 |
End |
61762 |
Ctrl-Insert |
| 61739 |
Ctrl-End |
61763 |
Ctrl-Delete |
| 61740 |
Insert |
61766 |
Ctrl-Tab |
| 61741 |
Delete |
61767 |
Ctrl-Keypad / |
| 61742 |
Ctrl-→ |
61768 |
Ctrl-Keypad Enter |
| 61743 |
Ctrl-← |
61769-61788 |
Shift-F1 to Shift-F20 |
| 61744 |
Ctrl-Print Screen |
61789-61808 |
Ctrl-F1 to Ctrl-F202 |
| 61745 |
Shift-Tab |
61809-61828 |
Alt-F1 to Alt-F20 |
| 61746 |
Ctrl-Page Up |
61829-61848 |
Ctrl-Shift-F1 to Ctrl-Shift-F20 |
1If Host UTF8 Support is turned off,
ASCII values are interpreted through the currently selected code page.
2Ctrl-F5 (key value 353) is also used for the VT220/VT320
Help key. Ctrl-F6 (key value 354) is also used for the VT220/VT320 Do key.
Putting It All Together
As seen above, there are a variety of options for defining keyboard keys in
ViewML. Combined, they can create just about any key
design needed. Here are three examples from the
sample keyboard layout. They all use
these default values:
-labelPosition 4
-keyHeight 1.19
-fontSize 15
[K;;keyString=k;;size=1.45]
The first argument (here K) is always the key label. keyString
causes the key to send a lower-case k. Without it, the key would send the
label instead, upper-case K. Labeling like this gives an appearance
like that of a physical keyboard.
The last argument, size, is used to widen the key. The larger size
makes the key easier to type on, and leaves less blank space to either side of the
keyboard. Note also that the K is centered, thanks to the default argument
-labelPosition 4.
[Enter;;keyChar=13;;fontSize=11;;labelPosition=6;;size=1.9]
This key uses keyChar instead of keyString to send a
non-printable ASCII 13, which is the carriage return ^M. (It's converted to an
EBCDIC enter in transmission.) The
fontSize argument makes the label text smaller than the default point
size 15.
labelPosition=6 overrides the default value to left-justify the label string in the lower left
corner of the key. And size makes the key even wider than the K
key described above.
-keyHeight 1
[7;;shiftLabel=Home;;shiftLabelPosition=6]
This key was drawn from a layout section that uses a different keyHeight
than the default listed above. It also shows a more complex labeling scheme,
with the shiftLabelPosition argument moving the shift label to the
lower left.
[Shift;;size=1.34;;shiftTo=PC English.L;;
shiftId=PC English.L.shift;;labelPosition=6;;fontSize=11]
This particular key comes from a shifted layout, rather than a main one. shiftTo
shows which lahyout will be displayed when this key is tapped. shiftId gives
this key a unique identifier, so that it properly uses the default shiftLock
behavior.
Note also that in an actual keys.ttkeyboard file, this key definition would be on one
line. It's broken in two here for ease of reading.
