Keyboard emulation
==================

E-UAE emulates an Amiga keyboard layout by a straightforward mapping - where
possible - of host keys to Amiga keys. In general, the alphanumeric keys,
function keys, numbers, punctuation, cursor keys, numeric keypad, etc.
should work as expected (that is, the symbol on the key cap should be
produced in AmigaOS when the key is pressed). There are some difficulties,
however, particularly with international keyboard layouts, and we shall discuss
these in a moment.

In addition, the following keys are mapped to the Amiga keys and Help key:

Left Super		Left Amiga
Right Super		Right Amiga
PageDown		Left Amiga
PageUp			Right Amiga
Menu key		Right Amiga
Insert			Help

"Super" keys mean Windows keys on a PC keyboard, Option keys on a Mac
keyboard, etc. Note that most Mac keyboards don't differentiate between left
and right Option keys, and both will produce a Left Amiga.

Currently, E-UAE's keyboard mapping is not user-configurable. This will be
addressed in a future release.


International keyboards
=======================

If you are using E-UAE built with the X11 or SDL graphics drivers then you
need to set the kbd_lang= option to specify your keyboard layout (you also
need to pick an appropriate keyboard driver in AmigaOS).

Supported layouts currently include:

de - German
dk - Danish
es - Spanish
us - USA (default)
se -
fr - French
it - Italian

Pick the layout that best fits your keyboard (e.g. use 'us' for British
keyboards).

Support for some layouts is currently poor - for example, numeric and
punctuation keys are interchanged on the French layout - and SDL poorly
supports international keys.

A partial solution with SDL is to use E-UAE's raw key mapping (see below).


Command key sequences
=====================

The following key combinations invoke UAE commands or functions:

F12 + Q                 Quit UAE
F12 + R                 Reset UAE (warm reset)
F12 + Left Shift + R    Reset UAE (cold reset)
F12 + D                 Open built-in debugger/monitor

F12 + S                 Toggle between windowed display and full-screen mode
                        (if supported by the graphics driver).
F12 + G                 Toggle mouse-grab mode (in windowed mode)
F12 + M                 Toggle mouse mode.
F12 + I (or             Toggle display inhibit (Amiga screenmodes, not P96)
Scroll Lock)
F12 + A                 Cycle through audio interpolation modes
                        (interpolation works with 16-bit audio only)

F12 + Numpad Plus       Increase frame-skip rate
F12 + Numpad Minus      Decrease frame-skip rate

F12 + F1                Open dialog to insert floppy image in drive 0
F12 + F2                Open dialog to insert floppy image in drive 1
F12 + F3                Open dialog to insert floppy image in drive 2
F12 + F4                Open dialog to insert floppy image in drive 3
F12 + Left Shift + F1   Eject floppy image in drive 0
F12 + Left Shift + F2   Eject floppy image in drive 1
F12 + Left Shift + F3   Eject floppy image in drive 2
F12 + Left Shift + F4   Eject floppy image in drive 3

F12 + F                 Emulates freeze button of Action Replay cartridge
                        (if you have a cartridge ROM loaded).

On Mac OS X, use F11 rather than F12 in the key sequences above (reason: F12
is used by Finder on OS X to eject a CD. On OS 10.3, I believe F11 may be
used by Expose, so you may need to change your Expose settings.) On AmigaOS,
use CTRL+Left Alt instead of F12 (reason: most Amigas don't have F12 keys).


Raw key mapping
===============

When emulating an Amiga keyboard in UAE, the tricky thing is how to translate
key-presses on the host to virtual key-presses on the emulated Amiga.
Traditionally, when running UAE on Unix systems using X or SDL, UAE maps
host key symbols (cooked keys) to raw Amiga key-presses. This approach has a
number of problems, especially with international keyboards. This is mainly
due to the number of translations involved in this process and the fact that
it requires that apples be converted into oranges, back into apples and then
into oranges again for a key-press on the host keyboard to eventually end up
on your virtual Amiga screen.

When mapping cooked keys, what happens is this. You press a key. Ignoring
the really low-level stuff, your host operating system receives a raw scan
code denoting which key on the keyboard is pressed (this scan code
identifies the position of the key on the keyboard, not the symbol that is
painted on the key cap). Your OS then translates this to a key symbol using
your keymap settings to produce (if your keymap is correct) a value which
actually does correspond to the symbol painted on the physical key on your
keyboard.

If E-UAE tries to work with this translated key symbol, it then has to
somehow convert that back into a raw scan code appropriate to if that key
were pressed on an Amiga keyboard (and then AmigaOS will use its keymap
settings to translate it into a key symbol again). This requires that UAE
know about international keyboard layouts, and requires the graphics system
to report unique events for all host keys (SDL does not completely support
some international layouts, for example).

One solution is for UAE to instead ask the host operating system for the raw
scan code corresponding to a key-press and map that to a raw Amiga scan code.
This is potentially easier and more accurate, since we are now converting
like to like, apples to apples, raw key-presses to raw key-presses. The
problem now is, instead of having to support different international
keyboard layouts, UAE has to understand different keyboard types (e.g.,
standard PC104/5 keyboards, Mac keyboards, Sun keyboards) and - more
annoyingly - the different raw scan codes that different operating systems
assign to what are logically or even physically identical keys.

The upshot of all this is that raw key-mapping is currently optionally
supported when UAE is built against libSDL for Linux (when running on
XFree86 on a PC or a Mac), on BeOS and on OS X. As I said above, raw
key-mapping better supports international keyboards, so is recommended for
most users, although its not terribly well tested and some problems may
exist. One such problem is that the command-key sequences listed above will
work as if you had a US keyboard rather than whatever international flavour
of keyboard you actually have. I'll fix this eventually.

Raw key-mapping with SDL is enabled with the config option:

sdl.map_raw_keys=true

Note that the AmigaOS version of E-UAE and the BeOS version when built with
native BeOS graphics support both always do raw key mapping, so no comparable
config options is supported or required in these situations. Note also,
however, that the command-key problem described above is exhibited in both
cases.
