Keyboard.tbl

From SpareMiNT Wiki

The format of the keyboard.tbl file was originally defined by Atari when they released MultiTOS. The current format is an extension of this.

First of all - the keyboard itself doesn't know anything about characters, layout or languages. Every key has it's own unique code (scancode) in the range from 0 to 127, these are the same regardless of your computer's nationality. Converting these scancodes to the characters that are printed on the keycaps is the task of the operating system. To do this it use a set of tables, and keyboard.tbl is nothing but a set of translation tables which does exactly this.

[edit] The file format

The keyboard.tbl is a binary file, so when I refer to null or zero, I mean ASCII value 0, not the character "0".

[edit] Header

The first two bytes will always contain the hexadecimal value 2772. Byte three is zero, and byte four is the AKP code of keyboard language.

[edit] Standard tables

The next 384 bytes (3x128) consists of three tables. This is indexed by scancode, so the character at position 2 (and remember that we start counting at zero!) is the character that will be returned when the key with scancode 2 is pressed.

Unshifted 

No Shift- or Alternate-keys are pressed, Caps Lock off.

Shifted 

Either Shift-key is pressed, no Alternate-key and Caps Lock off.

Caps Lock 

Caps Lock on and no Alternate-key. Shift is disregarded.

[edit] Alternate tables

The following three tables defines the characters returned when the Alternate-key is pressed. These tables differs from the standard tables in that they are not of a fixed size. They consist of pairs of bytes, where the first byte is the scancode and the second byte is the character this scancode translates no. A single null/zero terminates each table. If any or all of these tables are empty they will consist of just a single null/zero.

Alternate 

No Shift-keys pressed, Caps Lock off.

Alternate Shifted 

Either Shift-key pressed, Caps Lock off.

Alternate Caps Lock 

Caps Lock on.

NB! To complicate things the Alternate tables doesn't use the original keyboard scancodes, but a translated scancode set called VDI scancodes. The only difference is that the scancodes between 2 and 13 (the top row of the keyboard) is replaced with scancodes 120 to 131.

[edit] AltGr table

On the Milan or under Aranym it's also possible to use the AltGr key as a modifier. The AltGr-table works identically to the normal Alternate-tables, except that it use keyboard scancodes and not VDI scancodes. If you don't use this feature, just put a null/zero here.

[edit] Deadkeys

The deadkeys-table is also variable in length and is terminated by a single null/zero. However, unlike the other tables there are no scancodes involved. The purpose of this table is to compose accented characters from an accent and a base character. So every entry in this table consists of three bytes: The ASCII value of the accent, the ASCII value of the base character and finally the ASCII value of the accented character. To be of any use, all the used accents and base characters must be available from the keyboard.

[edit] How to create and edit

It's quite possible to create this file from scratch using a hex-editor. There are simpler ways though.

[edit] mktbl

This simple tool is included in the FreeMiNT distribution. It's a command line tool which translates a source-file to a keyboard.tbl binary file. This source-file is in plain text and can be edited with any text-editor.

Sample source-file:

; German keyboard, AKP code 1
;
; Unshifted
 
dc.w	$2772
dc.w	$0001
 
dc.b	$00,$1b,'1','2','3','4','5','6'
dc.b	'7','8','9','0','�',$27,$08,$09
dc.b	'q','w','e','r','t','z','u','i'
dc.b	'o','p','�','+',$0d,$00,'a','s'
dc.b	'd','f','g','h','j','k','l','�'
dc.b	'�','#',$00,'~','y','x','c','v'
dc.b	'b','n','m',',','.','-',$00,$00
dc.b	$00,' ',$00,$00,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
dc.b	$00,$00,'-',$00,$00,$00,'+',$00
dc.b	$00,$00,$00,$7f,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
dc.b	'<',$00,$00,'(',')','/','*','7'
dc.b	'8','9','4','5','6','1','2','3'
dc.b	'0','.',$0d,$00,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
 
; Shifted
 
dc.b	$00,$1b,'!','"',$dd,'$','%','&'
dc.b	'/','(',')','=','?',$60,$08,$09
dc.b	'Q','W','E','R','T','Z','U','I'
dc.b	'O','P','�','*',$0d,$00,'A','S'
dc.b	'D','F','G','H','J','K','L','�'
dc.b	'�','^',$00,'|','Y','X','C','V'
dc.b	'B','N','M',';',':','_',$00,$00
dc.b	$00,' ',$00,$00,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,'7'
dc.b	'8',$00,'-','4',$00,'6','+',$00
dc.b	'2',$00,'0',$7f,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
dc.b	'>',$00,$00,'(',')','/','*','7'
dc.b	'8','9','4','5','6','1','2','3'
dc.b	'0','.',$0d,$00,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
 
; Caps
 
dc.b	$00,$1b,'1','2','3','4','5','6'
dc.b	'7','8','9','0','�',$27,$08,$09
dc.b	'Q','W','E','R','T','Z','U','I'
dc.b	'O','P','�','+',$0d,$00,'A','S'
dc.b	'D','F','G','H','J','K','L','�'
dc.b	'�','#',$00,'~','Y','X','C','V'
dc.b	'B','N','M',',','.','-',$00,$00
dc.b	$00,' ',$00,$00,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
dc.b	$00,$00,'-',$00,$00,$00,'+',$00
dc.b	$00,$00,$00,$7f,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
dc.b	'<',$00,$00,'(',')','/','*','7'
dc.b	'8','9','4','5','6','1','2','3'
dc.b	'0','.',$0d,$00,$00,$00,$00,$00
dc.b	$00,$00,$00,$00,$00,$00,$00,$00
 
; Alternate
 
dc.b	$1a,'@',$27,'[',$28,']',$00
 
; Alternate shifted
 
dc.b	$1a,$5c,$27,'{',$28,'}',$00
 
; Alternate Caps
 
dc.b	$1a,'@',$27,'[',$28,']',$00

[edit] Other tools

At the moment the only other tool that's capable of creating and editing keyboard.tbl is KeyEdit. It has a GEM-based interface and is very easy to use, but does not yet support deadkeys.