Creating Custom Keyboard Layouts

Along with the three default keyboard layouts which are available with KeyboardTest, it is possible to add up to 100 custom keyboards for specialized user requirements.

Adding a keyboard:

1. Create a new keyboard layout file <mylayoutname>.kbl.
This file will contain all the information about all the keys on a keyboard. See the three examples (DellPortInt.kbl, DellPortUS.kbl and AT107.kbl). Kbl files are in csv format. For more information on the structure of .kbl files see Keyboard Layout files below.

2. Create a new bitmap file <mylayoutname>.bmp.
This should be a 700 pixel x 340 pixel x 256 color close up picture of your new keyboard. Again, see the three examples (files DellPortInt.bmp, DellPortUS.bmp & AT107.bmp). The name of this file should be exactly the same as the .kbl file.

3. Make sure both of these files are placed into the KeyboardTest, installation directory. Normally, C:\Program Files\KeyboardTest.

4. On startup, Keyboard Test loads the first 100 .kbl files along with their corresponding bitmaps. These correspond to the selections available through the Keyboard type dropdown menu. A .kbl file with an incorrect format, or a .kbl file without the corresponding .bmp file will be flagged as errors.

Keyboard layout files:

Kbl files are comma separated variable (csv) text files. Each line of the file corresponds to one key. There should be no unnecessary white space. There are 10 mandatory values per line which define each key. These are followed by 11 optional fields that can be specified to define a compound key. A compound key is a single key on the keyboard that generates multiple key presses. For example, a keyboard generates the keys "W","W","W",".", when the compound key "WWW.", is depressed  Thirty compound keys can be defined for each keyboard layout.

Each value must be one of the following.

To define duplicate keys that have the same scancodes, such as a left and a right space bar, simply include the key twice in the keyboard layout, and define different names and positions. There are no specific limits for the number of duplicate keys that are supported. KeyboardTest will match the first entry and then cycle through all duplicate key entries in the keyboard layout file. Note that duplicate COMPOUND keys are not supported. An example of the definition is shown below:

#Duplicate keys

32,57,"LSPACE","false","KTSTATUSUP",0,130,229,86,35

32,57,"RSPACE","false","KTSTATUSUP",0,216,229,86,35

Comments can be added by using a # as the first character in a line (see sample files).

The values in the order they must appear on each line of the .kbl file are as follows.

Windows ScanCode:
Windows scan code for this key (After language translation). This can be in 3 formats, a number, a single character, or a string value denoting a predefined constant (see Windows key codes reference).

If the key being defined is a compound key, the string “COMPOUND” must be used for this field.

If the key being defined is a Mouse button, the strings “LMOUSE”, “MMOUSE” and "RMOUSE" must be used for the left, middle and right mouse buttons, respectively. For example:

#Mouse

"LMOUSE",0,"LMouse","true","KTSTATUSUP",0,619,13,24,27

"MMOUSE",0,"MMouse","true","KTSTATUSUP",0,644,13,7,27

"RMOUSE",0,"RMouse","true","KTSTATUSUP",0,652,13,24,27

OEMCode:
A number value which is the OEM scan code for this key (Before language translation).

If the key being defined is a compound key or a mouse button, the value of 0 must be used for this field.

Name:
A string value denoting the name of the key eg "K", "Tab". This typically is the characters printed on the key.

Extended Status:
A string value. "False" if part of normal keyboard, "True" if part of extended keyboard. Eg Numeric keypad.

If the key being defined is a compound key, modified key or a mouse button, the string “true” must be used for this field.

Status:
A string value denoting the test status of the key.
"KTSTATUSNOTEST" = Don't test this key.
"KTSTATUSUP" = Test this key (Key starts in the up position) .

"KTSTATUSFAIL" = This indicator is specific to compound keys.  It is used to indicate that the defined compound key should be used for automatic testing of failures such as row and column hardware shorts. Specifically, when this status is used to define a compound key, KeyboardTest will check whether the defined keys (specified by up to 10 compound key characters)  are pressed in any order (ie. A hardware short) within the compound key timer limits described below.

Note 1: This compound key will be ignored when testing for the automatic pass condition,

Note 2: This key definition differs to a compound key defined with Status equal to KTSTATUSUP, which matches the keys in the order pressed.

Note 3: This indicator will be ignored when not in batch mode (no automatic failure or pass).

" KTSTATUSNOTESTFAIL" = Don't test this key, but if it is sent by the keyboard then fail the test (for faulty keycodes generated by shorts eg. Keycode of 255). This type of key only has meaning for batch mode testing only.
 

Color:
Number value corresponding to the color to be displayed when the key is pressed down.

Use the following:

0 for Red

1 for Light Blue

2 for Light Purple

3 for White

X, Y:
Number values. The X and Y offset of the key on the keyboard image in pixels, (Top Left corner). Note: Getting these values and the width and height values correct can take some time and trial and error.

Width, Height:
Number values. The Width and Height the key on the keyboard image in pixels.

COMPOUND KEYS - OPTIONAL PARAMETERS:

The following parameters are required to define a compound key.

If the key being defined is not a compound or a modified (see below) key, the Height value (described above) must be the last entry on the line.

If the key being defined is a compound key, the Compound key timer must be specified, followed by the characters (specified as Windows ScanCode decimal numbers). At least one character must be defined for a compound key, up to a maximum of 10. Each parameter must be separated by a ",". For example, to define "WWW.", as a compound key, the following should be included in the .kbl file:

"COMPOUND",0,"WWW.","true","KTSTATUSUP",0,26,95,20,29, 250,87,87,87,190

Where 500 is the Compound key timer (described below), 87 (Hexadecimal 57) is the Scancode for "W" and 190 the Scancode for ".".

If the key being defined is a compound key for testing for failure due to hardware shorts, the Compound key timer must be specified, followed by the characters (specified as Windows ScanCode decimal numbers). At least one character must be defined for a compound key, up to a maximum of 10. Each parameter must be separated by a ",". For example, to define a short between rows 1 and 2, select one key from each row (eg “ESC” and “`”, ie. 27 and 192) and add the following to the .kbl file:

"COMPOUND",0,"Row1-2: Short","true","KTSTATUSFAIL",0,26,118,420,29,200,27,192

Compound key timer:
Number value. The Compound key timer indicates a maximum value (in ms) between characters generated by the keyboard when a compound key is depressed. For example, the maximum time allowed between one "W" and the next "W" being received. If this timer value is exceeded, the key presses will be treated as individual key presses and not a compound key.

Compound key characters - Windows scan codes:
A comma separated list of between 1 and 10 number values. Windows scan code for each of the compound key characters (after language translation), specified as a decimal number (see above example).

MODIFIED KEYS - OPTIONAL PARAMETERS:

Modified Keys are pressed by pressing 2 keys simultaneously. For example, the hash '#' character is typed by pressing the SHIFT key with the '3' key, where the SHIFT key is the modifier key, and the '3' key is the effective key.

The following additional parameters are required to define a modified key.

- Windows Scan code of effective key

- Windows Scan code of modified key

For example, to define the hash '#' key:

"MODIFIED",0,"#","true","KTSTATUSUP",3,187,29,15,15,0,51,16

The 1st parameter must always be "MODIFIED"

The 1st parameter must always be 0

Parameters 3 - 10 are the same as described above.

Parameter 11 must always be 0 since the compound timer value is not applicable.

Parameters 12 and 13 are the Windows scan codes of the effective and modified keys respectively. In the above example, 16 is the Windows scan code for the SHIFT key, and 51 is the Windows scan code for the modified key.

NOTE:
We recommend that the best way to create a custom layout file is to make a copy of one of the three existing sample files and edit the lines as necessary.