
How to define keyboard mappings in DOS versions
===============================================
(by Marcin Grzegorczyk)

The key mapping file ttdpatch.kbd contains a list of 4-byte entries.  
Each entry has the following format:

 <scan-code> <shift-mask> <shift-stat> <char>

	scan-code   The 'scan code' of a key, i.e. the code received 
	            from the keyboard.  A list of scan codes can be 
	            found in the Ralf Brown's Interrupt List, in the 
	            description of INT 09 (IRQ1 - KEYBOARD DATA READY). 
	            Extended keys have 0x80 added to the scan code.
	shift-mask  Mask of shift states:
	             bit 0 = Shift pressed (left or right)
	             bit 1 = Ctrl pressed (left or right)
	             bit 2 = Alt pressed (left or right)
	             bit 3 = NumLock active
	             bit 4 = right Shift pressed
	             bit 5 = right Ctrl pressed
	             bit 6 = right Alt pressed
	             bit 7 = CapsLock active
	shift-stat  Expected shift states.  Only bits that are set in 
	            shift-mask do matter, other bits must be clear.
	char        The character code (extended ASCII)

If <scan-code>=0 it's an end mark, everything after the end mark is 
reserved for future use.  You do not have to put such an explicit end 
mark in the file, though.

Currently the size limit of the key mapping file is 32KB.  If the file 
is larger only the first 32KB will be read.

A key matches an entry if its scan code is equal to <scan-code> and for 
each bit set in <shift-mask> the current state of the corresponding 
shift key matches the corresponding bit in <shift-stat>.  If a key 
matches, it is mapped to the charcter code <char> and further entries 
are not checked.

If the bit 7 in <shift-mask> is set, the entry is checked only if a 
text input field is currently active.  This makes it possible to remap 
keys like Z or C (which also work as hotkeys) so that when CapsLock is 
active, they're entered into text input fields as uppercase letters but 
retain their hotkey meaning when there's no text input field active.  
To define a key mapping that will work only in text input fields 
regardless of the CapsLock state, define two mappings, one for CapsLock 
turned off and the other for CapsLock turned on.

As mentioned above, if a bit is clear in <shift-mask> the corresponding 
bit in <shift-stat> must be also clear, otherwise the entry cannot 
possibly match.  Don't put such 'impossible' combinations in key 
mapping files, they are reserved for future use.


Special considerations for character codes
------------------------------------------

The <char> codes and code ranges available in TTD are (in hex):

	00      no character (has special meaning, see below)
 	08      Backspace (erase the last character in an input field, 
	        if any; otherwise close all windows)
	0D      Enter (accept the current text input, if any)
	1B      Escape (reject text input field, if any)
	20..7A  US-ASCII subrange (curly braces, vertical bar 
	        and tilde are NOT available)
	7B..87  Special non-characters, see below
	99..FF  Extended characters, mostly from ISO-8859-1
	        (99..9E are currently blank and zero-width)

The following character codes (the so-called hotkeys) will trigger TTD 
functions when no text input field is present:

	20      (space) - dismiss a message/news window, if any
	31..34  ('1' to '4') - railway or road construction tools
	63      ('c') - center view on mouse cursor
	7A      ('z') - center and zoom view on mouse cursor
	E0      "Quit to DOS" window
	E1..EC  Same as function keys F1..F12
	F1..FC  Same as function keys Shift-F1..Shift-F12

When a text input fields is active, all character codes not in the 
range 7B..87 and other than 00 are treated as characters, not hotkeys.  
This makes it possible to input any character, including those that 
normally function as hotkeys, into a text field.

Characters in the range 01..1F are passed to text input fields but 
ignored there, unless they have a special meaning (see the list of 
code ranges above).  A recommended way to make a key combination 'dead' 
is to map it to the character code 13 (hex).


Special considerations for key combinations
-------------------------------------------

Some keys and key combinations are handled specially in TTD (a list is 
given later in this section).  Remapping them can affect their special 
meaning in various ways.

If a key combination that is handled specially in TTD is remapped via 
the keyboard mapping file to a character code other than 00 and not in 
the range 7B..87, it will retain its special meaning only when there 
is no active text input field.  This makes it possible to use such 
combinations to enter characters without triggering unwanted side 
effects.

Key combinations mapped to the character code 00 always retain their 
special handling, if any.  This is useful to prevent specially handled 
combinations from generating spurious characters in text input fields.

Key combinations mapped to a character in the range 7B..87 always lose 
their special meaning, if any.  This, combined with TTDPatch's new 
hotkey lists, makes it possible to define hotkeys that work even when 
a text input field is active.

If the enhanced keyboard handler is active, keys Insert and Home can 
emulate mouse buttons *only* when left or right Alt key is pressed, 
even if no key mappings are defined.  (Normally, i.e. without the 
enhanced keyboard handler, they emulate mouse buttons even without the 
Alt key.)

If you remap any of the following combinations to a character code 
other than 00, it will lose its special meaning when a text input field 
is active:

arrow keys	(scroll the main view)
Shift + arrow keys	(scroll the main view faster)
Alt + arrow keys	(move the mouse cursor)
Alt + Insert	(emulate mouse left button)
Alt + Home	(emulate mouse right button)
left Ctrl + S	(screenshot)
left Ctrl + G	(giant screenshot)

Note: Both numpad ('white') and extended ('gray') arrow keys work the 
same in TTD, so you can e.g. remap only the numpad keys and have the 
others still work as normal.

If you remap any of the following combinations, it will lose its 
special meaning when a text input field is active, *and* will not work 
at all (or will work differently) if it is mapped to a different 
character than the default:

function keys, with or without Shift
	(see "Special considerations for character codes" 
	for default mappings)
Ctrl + C (default E0)

