Key Maps
What is it?
Since WebSSH 33.51, a key map changes what the special keys send: the arrows, Home, End, Page Up, Page Down, Insert, Delete, Backspace, Esc, Tab, Enter and F1 to F12. A key map is chosen per server and applies to the hardware keyboard and to the keyboard accessory bar alike.
When do you need it?
A modern terminal sends ANSI escape sequences for its cursor keys: the up arrow sends ESC [ A. Some programs do not understand them:
- vintage systems: terminals of the 1970s had no cursor keys, so CP/M editors, WordStar, Turbo Pascal and many monitors move the cursor with control characters (the "WordStar diamond":
Ctrl + E,Ctrl + X,Ctrl + S,Ctrl + D) - line editors and dumb consoles that only know the Emacs keys (
Ctrl + P,Ctrl + N,Ctrl + B,Ctrl + F) - appliances whose menus expect a specific byte for a function key
With a key map the arrow keys send what the program expects. The original control combinations keep working: the key map only adds a more comfortable way to send them.
Choose the key map of a server
- Edit the connection and open Terminal Settings
- Tap Key Map and choose one
The key map is applied every time a terminal opens on that server, on every connection type (SSH, Mosh, Telnet, raw connection). The other servers are untouched.
Presets
| Key | WordStar / CP/M | Emacs |
|---|---|---|
| ↑ | Ctrl + E |
Ctrl + P |
| ↓ | Ctrl + X |
Ctrl + N |
| ← | Ctrl + S |
Ctrl + B |
| → | Ctrl + D |
Ctrl + F |
| Home | Ctrl + Q S |
Ctrl + A |
| End | Ctrl + Q D |
Ctrl + E |
| Page Up | Ctrl + R |
Esc v |
| Page Down | Ctrl + C |
Ctrl + V |
| Insert | Ctrl + V |
|
| Delete | Ctrl + G |
Ctrl + D |
A preset cannot be modified. To start from one, duplicate it (long press or right click > Duplicate) and edit the copy.
Create your own key map
Open Settings > Terminal > Key Maps and tap the add button. The editor draws the keys a key map can change. Tap a key — or press it on your hardware keyboard — and choose what it sends:
| Choice | The key sends |
|---|---|
| Default | Its usual sequence: the key is not remapped |
| Control Character | One control character, from ^@ (0x00) to ^_ (0x1F), or ^? (0x7F) |
| Another Key | The usual sequence of another key, for example Home sending what the up arrow sends |
| Custom Sequence | Any sequence of up to 64 characters, see below |
A remapped key shows what it sends under its legend. Keys without anything under their legend keep their usual sequence.
Custom sequences
| You type | Sent |
|---|---|
<ctrl-x> |
The control character of x: <ctrl-e> is 0x05 |
<esc> |
Escape, 0x1B |
<tab> |
Tab, 0x09 |
\xNN |
The character whose hexadecimal code is NN, from 00 to 7F |
\\ |
A backslash |
| Anything else | Itself |
For example <esc>OP is what F1 usually sends, and <ctrl-q>S is the WordStar "beginning of line". The bytes that will be sent are shown in hexadecimal under the field as you type.
7-bit characters only
A custom sequence accepts characters from 0x00 to 0x7F. What a character above 0x7F becomes on the wire depends on the remote character set of the server, so it cannot be a fixed byte.
Switch during a session
The same server may run programs that expect different keys. The key map can be changed for the open session without touching the server's setting:
| Platform | How |
|---|---|
| iPhone / iPad | Tap the "…" ellipsis button, then Key Map and choose a key map or None |
| Mac | Right click the terminal or click the "…" ellipsis button, then Key Map |
| Keyboard accessory bar | Add the {KEYMAP} key to your layout, see Keyboard Accessory View Customisation. It turns the key map of the session on and off and stays lit while keys are remapped |
While a key map is active, the "…" ellipsis button of the terminal shows a badge. Open it and look at Key Map to see which one.
Good to know
- Modifiers are left alone:
Shift,AltorCtrlheld with an arrow key send what they sent before. On a hardware keyboardCtrl+ arrow stands forPage Up,Page Down,HomeandEnd, and follows the key map of those keys. - Only typed keys are remapped: pasted text, snippets, the Compose Bar and the password paste are sent as they are. Paste Slowly does not slow a remapped key down.
- Another Key follows the arrow keys mode of the connection.
- Broadcast Input: with split panes and Broadcast Input on, the other panes receive what the remapped key sent.
- iCloud: your key maps and the choice made for each server follow iCloud sync. If a key map is deleted, the servers that used it go back to no key map.
-
Key Maps require WebSSH 33.5 or later and WebSSH PRO. ↩