### Keyboard

The Keyboard menu lets you select between Logical Layout (the default), Physical Layout and Typing Layout. There is also Experimental Logical Layout which is (hopefully) temporary. It is identical to Logical Layout except for a slight difference in handling shift key state to work better with a custom CP/M BIOS.

Enable ghosting for a truly authentic experience. Due to the way the keyboard matrix works on the Model 1, 3 and 4 it is possible for a 4th key to appear pressed when 3 others are down. For example, if you press and hold `F`, `G` and `O` in that order you will see `FGN` on screen as those keys ghost with `N`. On the Color Computer `O`, `G`, `N` will result in `OGF` showing up.

#### Logical Layout

Logical Layout means that what you see on the key is what gets sent to the TRS-80. This is as you would expect but there are two things to keep in mind. None of the TRS-80 Models sport the full variety of keys on a modern PC. The Model 2 comes closest where the Model 1,3,4 machines lack even square brackets, curly braces and many others. They did, however, have some keys which have no analogue on the PC. Both had a `BREAK` key for interrupting programs. Models 1,3,4 had `CLEAR` to clear the screen. The Model 2 had `HOLD` to pause display. The Model 4 and 4P have a CAPS key for switching between upper and lower-case input.

To Get | Model 1,3,4 Press | Model 2 Press | Color Computer
--- | --- | --- | ---
`BREAK` | `Esc, Pause/Break, End` | `ctl-C, Pause/Break, End` | `Esc, Pause/Break, End`
`CLEAR` | `Home, \` | n/a | `Home`
`CAPS` | `CapsLock, PageUp` | n/a | `CapsLock`
`HOLD` | n/a | `ctl-shift-@, Scroll Lock` | n/a

Model 2, 12, 16, 6000 and Tandy 10 have a soft capslock option activated with the `-ks` option or the Keyboard → Soft Capslock. It acts like capslock without using the real capslock key. It can save a lot of trouble switching between the emulator another other applications. It is remembered as a preference and will be activated automatically if you run TRSDOS on the Model 2 or 12 as it requires that all commands use upper case.

#### Physical Layout

With Physical Layout the emulator is set up so TRS-80 keys are activated by PC keys in roughly the same relative position on the keyboard. Most of the symbols on your keyboard will correspond to the same key on the TRS-80. The letters, numbers, arrow keys and Enter will do what you expect and `!#$%;<>,.` are in the same spot, otherwise:

To Get |  | Press
--- | --- | ---
``` |  | `shift [`
`@` |  | `[`
`&` |  | `shift 6`
`*` |  | `shift -`
`(` |  | `shift 8`
`)` |  | `shift 9`
`-` |  | `=`
`+` |  | `shift ;`
`=` |  | `shift =`
`:` |  | `-`
`'` |  | `shift 7`
`"` |  | `shift 2`
`Left` |  | `], Left`
`Right` |  | `\, Right`
`Up` |  | ``, Up`
`Down` |  | `Tab, Down`
`Break` |  | `Backspace, Esc, Pause/Break, End`
`Clear` |  | `', Home`
`Caps` |  | `CapsLock, PageUp`

Physical Layout is generally only needed for games where a key activated at a different position can make the game unplayable. Note that the Model 2 does not support Physical Layout.

#### Typing Layout

Typing layout is optimized for regular keyboard input like inputting BASIC programs or word processing. Other layouts try to report all the keys held down in the host keyboard to the TRS-80. That works well with games where keys can be held down for long periods to move or control a video game player. But it is of no help in typing text. In fact, sophisticated keyboard input routines on the TRS-80 side will support N-key rollover to compensate for the multiple keys held down that come from a fast typist.

Like Logical layout, Typing layout will attempt to input keys as they appear on your keyboard. It also massages the keyboard input so that only one normal key is held down at a time. If a shift or control key is needed it will ensure those modifier keys are down before the regular key and only go back up after the regular key is released. In addition the key is held down for a fixed amount of time which is long enough for even large key-bounce delays to recognize it. If the key is held down longer the auto-repeats from the host system will be sent as key presses. As such, even TRS-80 programs that don't support auto-repeat will have that feature.

Keys are also buffered allowing type-ahead even if the TRS-80 is not polling the keyboard fast enough to keep up.

Typing layout is not recommended for games (though the automatic key repeat may be a rapid fire cheat in some games). It is quite helpful for Model 1 and 3 Level 1 BASIC, TRSDOS 2.3 on the Model 1 and CP/M on the Model 1, 3 and 4.

#### Special Keys

`F9` will pause and resume the emulation. You can hold `F12` to make the TRS-80 run faster. Pressing `shift-F12` will keep it in fast (turbo) mode without having to hold `F12`. Tapping `F12` will put the emulator back to normal speed. The `-turbo` command line option has the same effect.

In turbo mode keyboard input can get very difficult with characters repeated frequently. trs80gp addresses this by dropping out of turbo mode whenever a key is pressed. This automated return to normal speed can be turned on or off by Keyboard → Auto De-Turbo menu.

The Typing keyboard layout usually works better in Turbo mode as there is no problem with repeats generated by the TRS-80. Try using that layout in turbo mode with Auto De-Turbo turned off.

`Ctrl-Alt-C` and `Ctrl-Insert` and `Ctrl-Alt-V` and `Shift-Insert` are shortcuts for "Copy" and "Paste" respectively.

Use `F11` to save a screenshot and `Shift-F11` to save a cleanshot which is a screenshot without any beam drop-outs that appear as they do on the real Model I.

`Alt-F5` activates the machine's reset button. The Model I's reset button is not a hard reset and will not reboot the machine in the case of an especially bad crash. In that case use `Ctrl-Alt-F5` to do a warm restart to reboot the emulated Model I or File → Warm Restart. `Shift-Ctrl-Alt-F5` or File → Cold Restart is the same as a warm restart but it also re-initializes all RAM.

`Alt-Enter` will toggle between windowed and full screen mode.

`Alt-F4` is the standard Windows shortcut to exit the program which may not be familiar to Wine users. For that matter `Alt` by itself will move focus to the menu where you can use the keyboard to navigate and `Alt-F`, `Alt-E` will active the `File`, `Edit` and `View` menus respectively and so on for other top-level menus.

#### Software Keyboard

In unusual circumstances you may need to use the Keyboard → Software Keyboard... in order to press several keys at once. Most PC keyboards can only show 3 or 4 keys held down at once but some TRS-80 games have easter eggs that require holding down as many as 8 keys. The software keyboard makes this easy as each keyboard button stays pressed when clicked and only releases when clicked again. Or if the corresponding PC key is released.

If nothing else it is laid out the same as the original TRS-80 keyboard so you can see the idea behind Physical Layout mode. And the buttons go up and down as you type. Put the software keyboard window underneath the main one and you'll feel like you're on a real TRS-80. Minutes of fun.

The software keyboard also has an orange reset button. There's also a "RAM Badge" showing how much memory is installed. Incidentally, the Model 1 and Model 4P didn't have RAM badges and the reset key was in a different location.

#### Automatic Input (aka Pasting)

Keyboard input can be pasted into the emulator with the Edit → Paste menu entry, "`-i`" command line flags, `Ctrl-Alt-V` or `Shift-Insert` keyboard shortcuts, or Edit → Paste Macro N menu entries. How it is passed to the emulator depends on the Paste Mode which defaults to "OS Injection". The mode can be changed with Edit → Paste Mode or on the command line with `-icmd [ input mode ]` as in the table below:

Paste Mode | Command | What it Does | When to Use
--- | --- | --- | ---
Inject into OS | input char | Hooks into the standard ROM or DOS routines for keyboard input. | Robust, fast and supported by built-in DOSes and BASIC. Can input characters that can't normally be typed. Won't work at all on unsuppored DOSes like CP/M on the Model 4 or any program like games with custom keyboard scanning routines.
Typing | input key | Characters are translated to individual key presses in the same way as the `Typing` keyboard layout. | Best for word processors or operating systems not supported by "Inject" mode. Delays may be needed if the program takes extra time on some input (e.g., after ENTER). Can be OK for games but a single key down at a time is often too limiting. Not all characters can be typed and programs will use different key chords for special characters like square brackets or curly braces. In short, pased input may be lost because it cannot be translated into keystrokes or due to timing difficulties.
Toggle | input toggle | Like "Typing" but each character toggles the up/down state of the key it translates into. Allows for many keys to be pressed at once and how long each are held down. | Generally needed for games where two keys down at once are needed for diagonal movement. Or other programs where key "chords" are required. The need to repeat characters for press and release of keys means that text simply copied from elsewhere won't work when pasted into the emulator.

Automated input is a convenient way to "fast-type" a BASIC program or run a series of TRS-DOS commands.

For example, the following command will go into BASIC, set the top of memory to 60000 and then input and run a short BASIC program.

        trs80gp -i "BASIC\r\r60000\r10 ?7*5\rRUN\r"

Note on the Model 2 that trs80gp sends the input to the keyboard hardware and TRS-DOS clears the buffer before reading each command leading to most input being lost (hence the `-iw` option).

On the Model 2 we must wait for the "Date" prompt to appear thus making the exercise a bit more complicated:

        trs80gp -m2 -iw Date -iy "%m/%d/%Y\r%h.%i.%s\rBASIC\r10 ?7*5\rRUN\r"

The contents of entire files can be sent using `-if filename` or the Edit → Paste File.. menu.

The emulator automatically goes into turbo mode when processing input fed in from the command line or pasted directly into it. The speed boost is nice when pasting in BASIC source listing or other large input. It can be turned off with the `-iatx` on the command line or put on explicitly with `-iat`. Or use the Edit → Auto Turbo menu entry.

##### Input Translation

Input sent with `-i` will interpret the usual C-style backslash escapes. Unlike C, you'll use `\r` much more than `\n` since TRS-80's most often use carriage return (character 13) to end a line.

Escape | Output | Character #
--- | --- | ---
\a | beep | 7
\b | backspace | 8
\e | escape | 27
\f | form-feed | 12
\n | newline | 10
\r | carriage return | 13
\t | tab | 9
\v | vertical tab | 11
\`ooo` | octal value (1, 2 or 3 digits) | `ooo` in octal
\x`hh` | hexadecimal value (1 or 2 digits) | `hh` in hexadecimal

Pasted input, pasted files or files sent via `-if` have line endings converted to make host input more compatible with what a TRS-80 expects. CR followed by LF is replaced with CR. Otherwise LF is replaced with CR. This handles both Windows style text with CR+LF as a line ending and Unix style with NL as the line ending.

Input fed in with `-ifr` is not translated at all.

##### OS Inject Mode

Since the characters are fed to keyboard input routines you can enter graphics characters and other data that normally can't be typed in with a real keyboard. Consider this a handy way to put graphics characters inside string literals in BASIC. Normally that requires magic incantations of `VARPTR` and has been the subject of countless 80 Microcomputer magazine articles.

If the TRS-80 is not calling the standard keyboard input routine then trs80gp will time-out and give up trying to send input after about one minute. Specifically, 3600 frames which is one minute at 60 Hz and one minute and 12 seconds at 50 Hz. Mind you, the emulator automatically switches to turbo mode during automated input so the real time will be less. The timeout value can be changed with the `-itime N` option or disabled entirely with `-itime 0`.

A few of the options such as `-id N` (wait N frames) and any which generate screenshots (`-is`, `-ic`), exit the emulator (`-ix`) or write to files (`-it`, `-im`) do not wait for keyboard polling and can be used to grab screenshots of games. Generally they are of most use in writing the automated tests used by trs80gp's authors. The `-showframe` option is useful for screenshots as it shows the current emulator frame in the title bar. Thus you needn't guess how many frames to wait before a program is ready for its screenshot.

The `-ik` will explicitly set individual keys in the keyboard matrix. This can be used to control games and other programs which do not use the standard ROM or DOS keyboard input routines. But you do need to know they keyboard matrix layout and carefully time the input make the whole exercise rather tedious. A better facility for entering input to games and other uncooperative programs is being considered.

##### Typing Mode

This mode uses the same emulator mechanism as the keybord "Typing" layout to translate characters into keystrokes that are sent one at a time to the emulator. Not supported by machines which do not have keyboard matrix emulation like the Model 2 line, DT-1 and Tandy 10.

Unlike the OS Injection they keys are not held back until the program scans the keyboard matrix. Keyboard input can thus be lost if the steady rate the keys are fed to the emulator is too fast for the current program. In those cases you will need to add delays with `-id` or use `-iw` to wait until the program is known to be looking for keyboard input again.

Each key press and release happens over several frames so there is normally no need to delay when sending a line of text.

##### Toggle Mode

The most tedious mode to use as every character ultimately is repeated to trigger the press and release of each key. Here the software keyboard can be of great help as it reflects any keyboard input and will indicate if any keys are "stuck" down because you missed sending a second character to pull the key back up.

There is no delay between each key up and down in toggle mode. Even typing "ABC" will require delays between the down key press and up. For example:

trs80gp -m1 -icmd [ input toggle ] -iw READY -i A -id 4 -i A -id 1 -i B -id 4 -i B -id 1 -i C -id 4 -i C

Awkward, but it is much easier than issuing `-ik` to directly control the keyboard matrix. Toggle mode will consume characters until a nul is reached which will induce a single frame delay. The above command can be written equivalently as:

trs80gp -m1 -icmd [ input toggle ] -iw READY -i "A\0\0\0\0A\0B\0\0\0\0B\0C\0\0\0\0C"

#### Paste Macros

The Edit → Define Macro... menu allows you to create up to 10 paste shortcuts. The strings entered can be pasted either through the Edit → Paste Macro 0 though 9 menu entires or by pressing Alt-0 through Alt-9 (Command+0 through Command+9 on Mac). Each macro is automatically saved and there is a different set of macros for each TRS-80 model.

Macros can also be defined on the command line with `-imac0 string` through `-imac9 string`.

The mechanism is exactly the same as other automatic input so you can use `\` escapes to enter control and graphics characters. This is particularly useful for Xenix's virtual console feature where entering `\xFC` followed by `0` though 9 will switch to that console. For example, to have Alt-4 switch to console 4 set up the macro to send `\xFC\x34` or `\xFC4` (\x hex escapes consume at most 2 digits). Also, like `-iy`, "%" substitutions for date and time can be used.