Modifying Keyboard Layouts

FOLDER: LAYOUTS

TYPE: Keyboard Layout source for My-T-Soft

SOURCE: INCLUDED

LANGUAGE: ASM (Assembler files)

IDE: Text editor / NASM

The Keyboard Macro File (KMF) - (e.g KYBD0001.KMF) controls the display & operation of the particular layout for My-T-Soft (My-T-Touch/My-T-Pen), etc.

The layout itself is a binary file, which is generated from an ASM (e.g. ASeMbler). The reason for this is the file layout structure - it is a set of offsets & links, so that all of the data can be variable length. Over time, certain areas have become fixed, while other areas are changed to create the different layouts.

The following documents and provides an overview to the sections within the ASM file. Before getting into all the detail, here is a quick example of modifying one of the files:

Quick Example

You want to change the # symbol to a + symbol in the normal US 101 layout. Edit KEYBRD01.ASM with your favorite text editor, find the LBL000: section, find the # symbol (e.g. LBL003: DB '#',0)

And change it to LBL003: DB '+',0

Save the file

Now rebuild the KMF file:

nasmw -f bin KEYBRD01.ASM -o KYBD0001.KMF

Overwrite the existing KYBD0001.KMF in \Program Files\[ProductDir], and when this layout is used (e.g. Keyboard=1 in the INI file), the shift-3 key will show a + symbol instead of the # symbol.

A few notes on the example:

In general, it is recommended that you preserve the existing files (unless there is a fundamental problem that you are trying to resolve), and use numbers in the 3000 range (e.g. KYBD3001.KMF). You should also modify the layout name in the ENDDATA at the end of the file (or with LAYOUT_NAME in those that have the LAYOUT_NAME define), so there is a unique entry in the Keyboard layout selection in Setup.

Modifying KMF Source files (ASM files)

A quick lesson in assembler syntax:

The EQUs are equates, or macro replacements (similar to #define in C) These should not be touched.

DB means Define Byte (or create a single Byte of data based on the following human readable entry)

DW means Define Word (or double byte, 16-bits)

DD means Define Double word (or 32-bit value)

A label is a non-reserved word followed by a colon, e.g. KEY000:

Text can be represented with single-quotes, e.g. This is some text,0 (always end text with a null terminating byte, in case it us used as a string internally!) Decimal values are OK, but hex is used often. To represent hexadecimal, use a leading 0 and a trailing H, e.g. 020H is 2x16+0, or 32 decimal - these are all the same when compiled to binary:

DB 32 ;this is a decimal 32, or a byte with a decimal value of 32 will be placed into the file

DB 020H ; hexadecimal representation of 32 decimal, e.g. a 2 in the 16s place and a 0 in the ones place

DB ;this is a text - the character for the space is decimal 32

ASM File Overview

For all practical purposes, these are the 12 areas to be familiar with:

1) The header (after the equates (EQU is like #define in assembler)). This is followed by a long listing of offsets, handled as fixed length data objects, with various offsets into this table kept in the header.

2) The KEY scan codes, e.g. KEY000:

3) The Label pool,e.g. LBL000:

4) The IDKeys section KMF001: (normal display)

5) The IDShiftKeys section KMF002: (Shifted display)

6) The IDShiftAltGrKeys section KMF003: (Shift AltGr display)

7) The IDAltGrKeys section KMF004: (AltGr display)

8) (* NOT RELEVANT IN ALL LAYOUTS!) The IDKeysCAPS section KMF005: (normal display - CAPS overrides)

9) (* NOT RELEVANT IN ALL LAYOUTS!) The IDShiftKeysCAPS section KMF006: (Shifted display - CAPS overrides)

10) (* NOT RELEVANT IN ALL LAYOUTS!) The IDShiftAltGrKeysCAPS section KMF007: (Shift AltGr display - CAPS overrides)

11) (* NOT RELEVANT IN ALL LAYOUTS!) The IDAltGrKeysCAPS section KMF008: (AltGr display - CAPS overrides)

12) The Layout Name (ENDDATA)

In most layouts, only the labels need to change (and in some international layouts, occasionally the KEY scan codes may require some changes).

This is how the file is laid out:

Header

Fixed Table of offsets into actual data

Actual data

This file structure allows variable actual data, while the reference (or offset/pointer) to it is always in the same location. By keeping the raw data in Assembler form, it can be edited fairly easily by humans (once you become familiar with the areas & the implementation). Because the format is compact in its binary form, does not need to be changed that often, the format has stuck.

ASM File Details

Here are the details on the sections:

######################################################################

### (1) HEADER EXCERPT ###################################################

The first 32 bytes are a header

Note the KeyLabelOffset coded here, and used in the Key Label "lookup" below

DB 'MK77' ;signature, subject to change BYTE 0,1,2,3

DB 32 ;Length of header (32) BYTE 4

DD OFFSET ENDDATA ;File Pointer to next entry (5 bytes) BYTE 5,6,7,8,9

DB 0

DD 65536 ;File ID BYTE 10,11,12,13

DW 0 ;Reserved BYTE 14,15

DW 0 ;ScancodeOffset BYTE 16,17

DW 256 ;QuickHelpOffset BYTE 18,19

DW 476 ;BaseMacroOffset BYTE 20,21

DW 542 ;KeyLabelOffset BYTE 22,23

DW 772 ;MacroPanelOffset BYTE 24,25 ;Base KMF look up tables

DW 0 ;PanelKeyOffset BYTE 26,27

DW 0 ;Char Set BYTE 28,29

DW 0 ;Attributes BYTE 30,31

The Char Set (28/29), and Attributes (30,31) are the only items that should be changed. The Char Set matches the ANSI code page, as defined by Microsoft The relevant ones are documented in the My-T-Soft help under Fonts.

The Attributes are bits that signify certain internal operation.

Low Byte is bits for specific handling

Internal Header #defines:

#define KMFHDR_TRACKALTGR 0x0001

#define KMFHDR_NOLOWERCASEDISPLAY 0x0002 (NOT USED ANYMORE)

/* Asian Keyboards */

#define KMFHDR_CODEPAGEINENDDATA 0x0004

/* Localized KMF files / keys over 104 (ScaleAFont) 1.78*/

#define KMFHDR_LOCALIZEDKMFFILE 0x0008

/* Weird handling (in code) - Use 16 values in low nybble of high byte */

#define KMFHDR_HEBREWHANDLING 0x0100

#define KMFHDR_FRENCHHANDLING 0x0200 (Old, could use CAPSTABLES)

#define KMFHDR_MULTIBYTEHANDLING 0x0400

#define KMFHDR_CAPSTABLES 0x0800

######################################################################

### KEY EXCERPT ######################################################

The KEY entries are the actual scan codes

This is the scan code pool (lookup table) for the KMF000 entries below

KEY000: DW 0001BH

KEY001: DW 00070H

KEY002: DW 00071H

KEY003: DW 00072H

######################################################################

### Label Pool -LBL EXCERPT ##########################################

These are the labels used on the displayed keys

This is the Label pool (lookup table) for the different keyboard states KMF001, KMF002, KMF003, KMF004

e.g. Regular, Shifted, Shift Alt-Gr, and Alt-Gr

LBL000: DB '~',0

LBL001: DB '!',0

LBL002: DB '@',0

LBL003: DB '#',0

LBL004: DB '$',0

SPECIAL LABEL NOTES:

Use Unicode character - 255,'U',D1,D2,D3,D4 where D1-D4 is hex "text" representation, e.g. DB 255,'U','0','6','D','E' - or use Unicode value 06DEH, (or 0x06de) (or unicode value 1758 (in decimal))

Also DB 0xFF,'U','0','6','D','E'

Note the ending 0 is not assumed or required, but ALL 4 Unicode hex digits are required!

The unicode character makes the most sense with KMFHDR_CODEPAGEINENDDATA, as these characters most likely will require a special code page for the WideCharToMultiByte to pull them up & display correctly. In general, this really isn't the unicode character, as the code page limits what will really be displayed.

Use Multiple Unicode characters - 255,'M',D1,D2,D3,D4,D1,D2,D3,D4,0 or 255,'M',D1,D2,D3,D4,D1,D2,D3,D4,D1,D2,D3,D4,0

This works very similar to above (with same issues with code pages) The internal logic always assumes at least 2 characters (e.g. if there was only 1, use the 'U' above, not the 'M'!).

The third character is optional, and the check for the ending 0 (null value) is used to see if only 2 (or if there is a third). Internally, the M is changed to a U and the code falls through into the handling for U automatically. The characters 2 and 3 may have spacing issues, depending on the actual character. Although this was implemented & tested, it does not fully handle the spacing for the 2nd (or 3rd) characters. In general, this shouldn't be used, but was left in the code in case it needed to be improved at a later time.

Override character length as 1 - 255,'1',C1,[C2,][C3,][C...,]0, this allows multiple characters to be used, but the font size will be used internally as if only 1 character is used.

If the KMFHDR_CAPSTABLES attribute is used (0800H), there is also an "override" label available. By specifying a 3 character entry, e.g. 0FFH,0FFH,0BDH, (or 255,255,[some other char value]), this type of entry will use the third character without any modification (since some of the internal caps logic says if it is a 1 character label, use AnsiUpper/AnsiLower if LowerCaseDisplay=1 in the INI) This forced upper/lower case change for single character displays can cause some issues on international layouts, and if it affects a normal or shifted state (e.g. KMF001/KMF002), using a label with the 3 character override (leading 255,255/0FFH,0FFH) will allow selection of the unmodified character value for display.

######################################################################

### IDKeys - KMF EXCERPT #############################################

IDKeys

This is the regular layout

Note the 542 offset to refer to the LBL pool

KMF001: DW 542+21 ;Esc

DW 542+22 ;F1

DW 542+23 ;F2

######################################################################

### IDShiftKeys - KMF EXCERPT ########################################

IDShiftKeys

This is the shifted layout

0 means no change from the regular, rather than no display

The 542 offset is used to refer to the LBL pool

KMF002: DW 0 ;Esc

DW 0 ;F1

DW 0 ;F2

######################################################################

### IDShiftAltGrKeys - KMF EXCERPT ###################################

IDShiftAltGrKeys

This is the shifted Alt-Gr layout

0 means no display

The 542 offset is used to refer to the LBL pool

KMF003: DW 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ;20

DW 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ;20

######################################################################

### IDAltGrKeys - KMF EXCERPT ########################################

IDAltGrKeys

This is the Alt-Gr layout

0 means no display

The 542 offset is used to refer to the LBL pool

KMF004: DW 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ;20

DW 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ;20

######################################################################

### CAPS SECTION - SIMILAR TO ABOVE###################################

0 means no change from the current display, rather than no display

KMF005 is CAPS override to KMF001

KMF006 is CAPS override to KMF002

KMF007 is CAPS override to KMF003

KMF008 is CAPS override to KMF004

As overrides, they should be 0, unless the CAPS state for that key label is wrong. If it is wrong, then you need to specify the correct label, e.g. 542+123 - the internal logic, says if this is not 0, then lookup the specified label & use that rather than what would have been displayed.

######################################################################

### Layout Name (ENDDATA) ############################################

ENDDATA:

DB '104 United States Standard',0

_TEXT ENDS

Building KMF Files from ASM files

This section defines how to build the asm files

These examples are for the Borland Turbo Assembler (i.e. TASM), used by IMG. These notes are for IMGs developers only - see below for using NASM.

This is for 101 layouts (%1 = 23 for example):

TASM KEYBRD%1

TLINK /3/x/t KEYBRD%1,KYBD00%1.KMF

DEL KEYBRD%1.OBJ

This is for 104 layouts (%1 = 123 for example):

TASM KYBD0%1

TLINK /3/x/t KYBD0%1,KYBD0%1.KMF

DEL KYBD0%1.OBJ

The layouts included in the Developers Kit have been modified slightly to work with nasm (GPL assembler). The included zip nasm-0.98.39-win32.zip was downloaded on April 27, 2007 from http://nasm.sourceforge.net - (you may wish to go there and obtain the latest stable version). The COPYING file describes the license for this software. The modified KMF layout ASM files contain a %include nasm.inc to bypass & ignore certain entries from the original TASM source files.

File: nasm.inc

%idefine offset

%idefine _TEXT

%idefine SEGMENT

%idefine PUBLIC

%idefine BYTE NOTHING EQU

%idefine ENDS

To build a KMF file for use with My-T-Soft, you can do the following with the nasm binaries in the nasm-0.98.39-win32.zip file.

nasmw -f bin KEYBRD01.ASM -o KYBD0001.KMF

The binary file can be copied to the \Program Files\[ProductDir] folder, and can be used directly.

There is a BUILD.BAT file that will make the typing a bit easier, e.g. you just specify the number (Build 01 for Keyboard 1, Build 105 for Keyboard 105, etc.). Here is the BUILD.BAT text:

@echo off

if %1XX == XX goto NOGOOD

if exist KEYBRD%1.ASM goto BUILD101

if exist KYBD0%1.ASM goto BUILD104

goto NOMATCH

:BUILD101

nasmw -f bin KEYBRD%1.ASM -o KYBD00%1.KMF

ECHO Built KYBD00%1.KMF

GOTO END

:BUILD104

nasmw -f bin KYBD0%1.ASM -o KYBD0%1.KMF

ECHO Built KYBD0%1.KMF

GOTO END

:NOMATCH

Echo Problem finding an ASM file!!

ECHO "%1"

ECHO See following build specs:

goto NOGOOD

:NOGOOD

ECHO No ASM FILE SPECIFIED! You must specify a specific

ECHO keyboard layout ASM file, e.g.

ECHO build 01[Enter]

ECHO -or-

ECHO build 102[Enter]

goto END

:END

Example & instructions making changes between KMF & testing

Test procedures in XP Pro

Some things to know about keyboards - AltGr, Dead Keys

AltGr - some international layouts provide a whole new mode to access even more characters.

The right-hand Alt key becomes AltGr (which I believe was originally for Alt Graphics), and it creates 2 possible new states - AltGr, and Shift-AltGr.

Dead Key - is an accenting key, used mostly for accent characters. The way this works in practice, is you type the key, and NOTHING shows up !!! (hence, dead key), but when you type the next character that can be accented, e.g. e, you will see �instead of e. Dead Keys (when typed on 2 times, will generate 2 accent characters - this is important when testing, since you can type a key & get nothing, and this could mean 1 of 2 things - it is a blank/not used key, or it is a dead key!)

To test any layout, you must be in the appropriate "Locale" with the correct keyboard layout selected.

For example, in Turkey, there is a Type F/Type Q layout. If you have Type F in My-T-Soft, but Windows thinks it is Type Q, you'll have lots of problems.

This is the best way to test in Windows XP

Load Wordpad

Load the Locale

Set the font fairly large, e.g. 24 or 26

Type with the physical keyboard & My-T-Soft keyboard to verify everything matches.

On All keys, you must press the key 2 or 3 times, to verify it is not a dead key (dead keys will not generate any visible output if only pressed once!)

For reference to layouts, you can try: http://www.microsoft.com/globaldev, then when loaded, on the left-hand column under the GlobalDev Home, find References | Keyboard Layouts. Once at the layout page, you can select from the available layouts - this will load a popup that shows the layout/dead-keys, etc.

Some helpful hints:

Show the locale / internationalization / layout selection bar in a window - if floats towards the top-right

Compare physical keyboard to My-T-Soft results first, e.g. type with the physical keyboard, then type with My-T-Soft - they should match, then verify the display in My-T-Soft matches the results

These are 8 possible states to be aware of:

Normal, Shifted, Caps & Caps-Shifted

If the keyboard supports AltGr, then you have:

Normal, Shifted, Caps, Caps-Shifted, AltGr, Shift-AltGr, Caps-AltGr, Caps-Shift-AltGr

Some advanced notes:

Setting KeyWatch=1 in the INI file, shows you the number of the key internal to My-T-Soft KeyWatch.exe (from Developer's Kit/KEYBOARD folder) shows virtual key/actual results for comparing physical keyboard/My-T-Soft generated keystrokes

Version 1.78 Release 2 - 5/4/2007

Copyright © 1993-2007 by Innovation Management Group, Inc.

All Rights Reserved.

My-T-Mouse, My-T-Pen, My-T-Touch, and My-T-Soft are registered trademarks of Innovation Management Group, Inc.