doc/vkb-format-v3

   1 vkb format for OS2007/OS2008/Maemo5
   2
   3 - released into public domain (Permission is granted, free of charge, to any
   4   person obtaining a copy of this file, to deal with the file without
   5   restriction, including without limitation the right to use, copy, modify,
   6   merge, publish, distribute, sublicense, and/or sell copies of it. The file
   7   is provided "as is", without warranty of any kind.)
   8 - this is the third version of the document
   9 - changelog:
  10   - v1: initial version based on reverse engineering of vkb files
  11   - v2: revised using the excellent work by Kimmo Jukarainen,
  12     http://idoru.metadreams.net/~kimju/src/maemo/decode_vkb/
  13   - v3: added 0x80 key flag
  14
  15 - multibyte fields are little endian
  16 - everything is utf-8 encoded
  17 - all numbers in the "description" column are written in hexadecimal
  18 - some (all?) length fields can be zero
  19 - strings are denoted as 1+n and are encoded as:
  20         bytes   description
  21         1       length of the next field, in bytes
  22         n       the string (utf-8 encoded)
  23
  24 GLOBAL HEADER
  25 bytes   description
  26 1       version (01)
  27 1       number of sections (02 for normal and thumb kbd, 01 for special kbd)
  28 1+n     descriptive (human-visible) name of the locale
  29 1+n     locale name (e.g. en_GB)
  30 1+n     locale name of a word completion dictionary
  31 1       number of screen modes supported by this keyboard (02)
  32 n       types of individual screen modes (1 byte each; types are:
  33         0 = normal, 1 = thumb, 2 = rotated) (00 01)
  34 1       number of key sizes (05)
  35 ...     KEY SIZE
  36 ...     KEY SIZE
  37         (default key sizes are:
  38         23 23 1a 00 00  32 23 1a 00 00  37 23 1a 00 00  48 37 29 00 00  8f 37 29 00 00
  39         that's: 00 normal key, 01 longer key used on the right side of odd
  40         rows, 02 more longer key used on the left side of odd rows, 03 big
  41         key used in thumb kbd, 04 double width big key used in thumb kbd)
  42         (for special kbd, default key sizes are: 23 23 1a 00 00)
  43 2       absolute offset in the file of the first section
  44 2       absolute offset in the file of the second section
  45         ...
  46 20      zeros
  47 ...     SECTION
  48 ...     SECTION
  49
  50 KEY SIZE
  51 bytes   description
  52 1       width of a key (in pixels? rather seems to be percentage or something)
  53 1       height of a key
  54 1       offset of a text (from the top of the key to the bottom of the text)
  55         - i.e. baseline
  56 1       left padding (extra value, not included in the width)
  57 1       top padding (extra value, not included in the height)
  58
  59 SECTION HEADER
  60 bytes   description
  61 1       type of the section (00 normal kbd, 01 special kbd, 04 thumb kbd;
  62         other values: 03 large kbd, 05-07 east language kbds, 08 stroke kbd)
  63 1       number of layouts (02 for normal kbd, 04 for thumb kbd, 06 for special kbd)
  64 1       numeric kbd (00); the meaning of this field is unclear
  65 1       default key size (00 for normal kbd, 03 for thumb kbd, 00 for special kbd)
  66 ...     LAYOUT
  67 ...     LAYOUT
  68
  69 LAYOUT HEADER
  70 bytes   description
  71 1       layout type (00 lowercase, 01 uppercase, 02 neither - i.e. special chars)
  72         notes:
  73         - in a special kbd, even tabs with letters are of the 02 type
  74         - it seems to be hard-coded that the first two layouts in a special
  75           kbd have the shift key disabled
  76 1       corresponding other case layout number, counted from 0; ff for
  77         a single case layout
  78 1+n     name of the layout (in normal kbd should be empty; in thumb kbd
  79         should be 3 utf-8 chars; in special kbd corresponding lower/upper
  80         layouts should have the same name)
  81 1       number of sublayouts (normal kbd has 2 sublayouts, thumb kbd and
  82         special kbd have 1 sublayout)
  83 ...     SUBLAYOUT
  84 ...     SUBLAYOUT
  85
  86 SUBLAYOUT HEADER
  87 bytes   description
  88 1       number of keys in the sublayout
  89 1       number of rows of the sublayout
  90 1       left margin (in pixels?) (9 for numeric kbd)
  91 1       top margin
  92 1       bottom margin
  93 1       right margin (seems that setting of margins affects also other
  94         sublayout margins in some strange way)
  95 n       number of keys in individual rows (1 byte for each row)
  96 ...     KEY
  97 ...     KEY
  98
  99 KEY
 100 bytes   description
 101 1       key type (00 normal key, 01 sliding key, 02 modifier key, 04 multiple key)
 102 ...     these fields depend on the key type (KEY_NORMAL, KEY_SLIDING, etc.)
 103
 104 KEY_NORMAL
 105 bytes   description
 106 1 or 2  FIELD_KEY_FLAGS
 107 1+n     letter
 108 1       key size
 109
 110 KEY_SLIDING
 111 bytes   description
 112 1 or 2  FIELD_KEY_FLAGS
 113 1       number of keys on the sliding key | 0x80
 114 1+n     letter
 115 1+n     letter
 116         ...
 117 1       key size
 118
 119 KEY_MODIFIER
 120 ?
 121
 122 KEY_MULTIPLE
 123 bytes   description
 124 1       number of keys
 125 ...     KEY
 126 ...     KEY
 127
 128 FIELD_KEY_FLAGS
 129 bytes   description
 130 1       key flags (bitfield)
 131         bits:   0 (0x01)        alpha
 132                 1 (0x02)        numeric
 133                 2 (0x04)        hexa
 134                 3 (0x08)        telephone
 135                 4 (0x10)        special
 136                 5 (0x20)        dead
 137                 6 (0x40)        whitespace
 138                 7 (0x80)        next byte is continuation of the flags
 139 1       present only if the previous field contains 0x80 flag:
 140         more key flags (bitfield?)
 141         bits:   2 (0x04)        draw tab face over the key
 142                 3 (0x08)        draw backspace face over the key
 143                 4 (0x10)        draw shift face over the key