UNIX Keyboard Reference

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

bgColor Background color for the keyboard layout. Uses hexadecimal RGB values preceded by the # sign; e.g., #000000 for black.
-bgColor #7d8038
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
keyBgColor Default background color for all keys in the layout. Uses hexadecimal RGB values preceded by the # sign.
-keyBgColor #141413
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
keyFgColor Default color for the text on all keys in the layout. Uses hexadecimal RGB values preceded by the # sign.
-keyFgColor #6fede1
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
selKeyBgColor Background color for keys when the key is pressed or locked. Uses hexadecimal RGB values preceded by the # sign.
-selKeyBgColor #121414
selKeyFgColor Text color for keys when the key is pressed or locked. Uses hexadecimal RGB values preceded by the # sign.
-selKeyFgColor #6fed78
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 for the display character, and use the hexadecimal value \x003b as the keyChar for the value sent:

[; ;;keyChar=\x003b;;shiftLabel=:]
  Option   Description

\ Escape character. Used for special characters that have other uses without the \. Square brackets are not required for this option.
\\
bgColor Sets the background color for the key. Uses hexadecimal RGB values preceded by the # sign.
[Caps;;capsKey=1;;bgColor=#a1b2c3]
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]
fgColor Sets the text color for the key. Uses hexadecimal RGB values preceded by the # sign.
[Esc;;keyChar=27;;fgColor=#3cb2a1]
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]
labelMaxWidth Sets maximum width in pixels of the main key label. Text will wrap if longer than that width. Used in conjunction with labelVerticalOffset.
[Caps Lock;;capsKey=1;;size=1.64;;fontSize=11;;labelVerticalOffset=1;;labelMaxWidth=50]
labelPosition Sets vertical position and horizontal justification of the main key label. Defaults to 4. This option is only available on iPad.
[,;;labelPosition=7]
labelVerticalOffset Sets number of pixels for top and bottom margins of key. Used in conjunction with labelVerticalOffset.
[Caps Lock;;capsKey=1;;size=1.64;;fontSize=11;;labelVerticalOffset=1;;labelMaxWidth=50]
printScreen When set to 1, this key will print the current emulator screen to the currently selected printer. Defaults to 0.
[PrtScr;;printScreen=1]
scanBarcode When set to 1, causes the key to trigger a camera scan when tapped.
[Scan;;scanBarcode=1]
selBgColor Sets the background color for the key when pressed or locked. Uses hexadecimal RGB values preceded by the # sign.
[shift;;size=1.3;;shiftTo=QWERTY.P.shift;;selKeyBgColor=#e4e5ed]
selFgColor Sets the text color for the font when the key is pressed or locked. Uses hexadecimal RGB values preceded by the # sign.
[Ctrl;;shiftTo=AZERTY.L;;selKeyFgColor=#1ff514]
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
    61903 Next Session

1If Host UTF8 Support is turned off, ASCII values are interpreted through the currently selected code page.

2Ctrl-F5 (key value 61793) is also used for the VT220/VT320 Help key. Ctrl-F6 (key value 61794) 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 TinyTERM. Combined, they can create just about any key design needed. Here are four examples. The first three are from the sample keyboard layout. All four 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.


[Caps Lock;;capsKey=1;;size=1.64;;fontSize=11;;selKeyBgColor=#e4e5ed;;selKeyFgColor=#1ff514;;
labelVerticalOffset=1;;labelMaxWidth=50]

This particular key has colors and word wrap enabled. capsKey=1 turns on capital letters. size makes the key wider than standard. fontSize shrinks the font. selKeyBgColor sets the key background color when it is pressed, like in this image. selKeyFgColor does the same for the font. labelVerticalOffset puts a one-pixel margin at the top of the key. labelMaxWidth is the maximum width in pixels of a single line of text on the key. If the text is wider than this, it will automatically wrap, preferring to break the line at a space.

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.


iOS User Guide Table of Contents