* How to create a keyboard layout overlay for VirtualKB.
========================================================

The overlay file has a very simple and basic format.  The format
allows the fast parsing of keyboard overlay layouts; of course
it can be done better but this has worked for all the layouts I
have implemented.

IMPORTANT: Please create and test the overlay files in the Palm
emulator because the keyboard does not check for errors in the
layout definition.

You should create a palm database with the following resources:

1) A bitmap id 100 containing the keyboard layout (letters lower
case).

2) A bitmap id 101 containing the shifted keyboard layout (letters
upper case, numbers and punctuation shifted).

3) A bitmap id 102 containing the caps-locked keyboard layout
(letters upper case).

4) A bitmap id 103 containing the caps-locked shifted layout
(letters lower case, numbers and  punctuation shifted).

5) A bitmap id 104 containing the numeric keypad layout (it shows
when you tap 123).

   * The bitmaps must not be taller than 5 standard font text lines
   (or 60 pixels aprox.).

   * All the alphabetic keyboard layout bitmaps should be the
   same size.

6) A string id 100 containing the number of standard font text
lines the resources 1)-4) are going to span.

7) A string id 101 containing the number of text lines the resource 5)
is going to span.

   * The strings in the example below indicate that the bitmaps
   are going to be 50 pixels tall aprox.

8) A string id 200 containing the scan definitions for the alphabetic
keypad (resources 1)-4))

9) A string id 201 containing the scan definitions for the numeric
keypad (resource 5))

   * A scan definitions string consists of a series of characters
   that are understood as input characters, control characters,
   or key geometry numbers.

   * The first character in the scan definition string tells the
   number of areas (keys) that follow.

   * Each area defines a key.  The format for an area is:

   <topleftx><toplefty><width><height><area-type>[<columns><rows>][characters]|
   <topleftx><toplefty><width><height><area-type>[<length><\001>][characters]

   - topleftx is the distance from the top of the bitmap to where
   the area begins.
   - toplefty is the distance from the left of the bitmap to where
   the area begins.
   - width is the width of the area !
   - height is the height of the area !
   - length is used when you are creating a type e area (see below).
   - characters are the characters that this key sends.
   - the area types can be:

       a An area divided into rows and columns to use for shift
       affected characters.

        example: "\156\045\062\012a\005\00167890&@()=" The first 4
        characters define the bounds of the key.  The following
        character tells this is an a type area, so the 2 following
        characters specify that this area divides into 5 columns and
        1 row.  The remaining characters specify what to enter for
        each cell: row 1, column 1, enter 6 ...  row 1, column 5,
        enter 0, but if shift pressed: row 1, column 1, enter &
        ... row 1, column 5, enter =.

       b An area divided into rows and columns used for alphabetic
       characters.

	example: "\001\014\140\044b\006\003fhaolmuretspwdincy" This is
	a b type area, so the 2 characters following b specify that
	this area divides into 6 columns and 3 rows.  The remaining
	characters specify what to enter for each cell: row 1,
	column 1, enter f ...  row 2 column 2, enter r ... row 3,
	column 6, enter y.

       c An area for a single shift affected key.

	example: "\174\015\011\013c-+" This c type area enters - if
	not shifted or + if shifted.

       f An area for a single shift-caps affected key.

	example: "\174\015\011\013f-+" This f type area enters - if
	not shifted or + if shifted or in caps mode.

       d An area for a single alphabetic key.

	example: "\162\015\011\013dm" This d type area enters m, and
	is affected by caps lock and shift.

       e An area for multiple character input.

	example: "\036\030\023\013e\003\000()\034" This e type area
	enters a length 3 string (please always enter the \000
	character after the length character). You can enter any
	string, an idea could be if, do, while keys, etc.

       p The area is a caps lock key.

	example: "\001\015\016\013p" This p area defines a caps lock key
	somewhere into the layout bitmap.  You can define multiple
	caps lock areas.

       s The area is a shift key.

	example: "\001\031\021\013s" This s area defines a shift key
	somewhere into the layout bitmap.  You can define multiple
	shift areas.

   * Please remember that you can't enter a zero character value
   into the definition strings, that means there is a mandatory 1
   pixel margin around the overlay bitmap.

   * The a or b type areas leave a 1 pixel margin between rows
   and columns.

* Creator, type and name of the database.

As the program is now implemented, only one layout at a time can be
loaded into the handheld.  In the following commands, you can see
the creator should be 'D-KB' (Should have changed for VirtualKB),
the type should be 'VKBO' (virtual keyboard overlay), and the name
should be "d-kb-overlay".

   pilrc compact/compact.rcp
   build-prc -o compact.pdb -t 'VKBO' -c 'D-KB' -n "d-kb-overlay"
   *.bin

* Example overlay .rcp file.

Here is the .rcp file I used for the compact.pdb layout.  The .bmp
files are 160x48 pixels in this case.  I used octal representation
for the key geometry characters.

BITMAP ID 100  "compact/compact.bmp"
BITMAP ID 101  "compact/compacts.bmp"
BITMAP ID 102  "compact/compactc.bmp"
BITMAP ID 103  "compact/compactsc.bmp"
BITMAP ID 104  "compact/vnum.bmp"

STRING ID 100 "4"
STRING ID 101 "4"
STRING ID 200
"\021"\
"\001\001\013\013c\t\t"\
"\015\001\170\013b\012\001qwertyuiop"\
"\205\001\011\013c'\""\
"\217\001\030\013c\b\b"\
"\001\015\016\013p"\
"\020\015\154\013b\011\001asdfghjkl"\
"\174\015\011\013c-+"\
"\206\015\011\013c/*"\
"\220\015\027\013c\n\n"\
"\001\031\021\013s"\
"\023\031\124\013b\007\001zxcvbnm"\
"\220\031\030\013s"\
"\147\031\050\013a\004\001,.!~;:?_"\
"\001\045\010\012c1<"\
"\012\045\050\012a\004\0012345>#$%"\
"\062\045\073\012c  "\
"\156\045\062\012a\005\00167890&@()="

STRING ID 201
"\030"\
"\062\001\074\012a\003\001789789"\
"\062\014\074\044a\003\0034561230.,4561230.,"\
"\001\001\010\012c\242\242"\
"\012\001\050\012a\004\001$\200\243\245$\200\243\245"\
"\001\014\010\013c\\\\"\
"\012\014\023\013e\003\001[]\034"\
"\036\014\023\013e\003\001{}\034"\
"\001\030\010\013c<<"\
"\012\030\011\013c>>"\
"\024\030\011\013c=="\
"\036\030\023\013e\003\001()\034"\
"\001\044\010\013c\260\260"\
"\012\044\050\013a\004\001@~&#@~&#"\
"\156\001\011\012c--"\
"\170\001\023\012c++"\
"\214\001\023\012c\b\b"\
"\156\014\011\013c//"\
"\170\014\011\013c**"\
"\202\014\011\013c::"\
"\214\014\023\013c\t\t"\
"\156\030\062\013a\005\001\274\275\276|^\274\275\276|^"\
"\156\044\023\013c\n\n"\
"\202\044\023\013c  "\
"\226\044\011\013c%%"
