Hacking the TTouchKeyboard Part IV

Hacking the TTouchKeyboard Part I
Hacking the TTouchKeyboard Part II
Hacking the TTouchKeyboard Part III
Hacking the TTouchKeyboard Part IV
Hacking the TTouchKeyboard Part V (not published yet)

Here is a quick off the top of my head documentation for the XML layout that is used by the keyboard compiler. If something doesn't behave as expected drop me a line with a comment or email so I can get it fixed.


This describes the schema and the attributes for the keyboard layout XML file.

<keyboard keyboardtype="Standard" keyboardname="Standard101" width=768" height="228" maxwidth="0" maxheight="0" minwidth="0" minheight="0">

keyboardtype - this allows multiple keyboard layouts to contribute to an overall keyboard type. For instance, for Standard we have the Standard101, Standard102 and Standard 106 keyboard layouts. Each one specifies a different layout for the Standard keyboard layout depending on the keyboard's language. This becomes the value of the TTouchKeyboard.KeyboardLayout property.

keyboardname - this is only used for humans to distinguish which keyboard layout is being used.

width - this is the default width of the keyboard layout.

height - is the default height of the keyboard layout.

maxwidth - is the maxwidth constraint of the keyboard layout.

minwidth - is the minwidth constraint of the keyboard layout.

maxheight - is the maxheight constraint of the keyboard layout.

minheight - is the minheight constraint of the keyboard layout.


<language languagename="en" />

languagename - specifies the two letter language code for the languages that this keyboard layout applies. When the system is searching for a keyboard layout for the current keyboard language it starts from the last keyboard layout registered, to allow developers to override the defaults, once a keyboardtype and language are found that keyboard layout is used.


<row topmargin="0" bottommargin="2">

topmargin - this is the padding between the key rows.

bottommargin - this is the padding between the key rows.


<key scancode="1" vk="200" caption="Esc" width="65" stretch="True" modifiername="fn" imageindex="3" toggle="True" mapscancode="42" mapvk="0" margin="5" doubletall="True" groupindex="1" combokeys="vk:12;vk:12;scancode:24;scancode:24">

scancode - this is the Scan Code that is sent to the active window. The default value is 0. A valid scan code is greater than zero. Any value greater than zero will be sent as a key. If the value is 0 then it is key that does not have a scan code. Any key that does not have a scan code and or a vk is not a real key. If the value is less than 0 then it is also a fake key. This is useful for modifier keys.

vk - Same as scancode above only for the vk. It is important to note that either one or both can be provided. If one isn't provided then the other will be determined by the OS.

caption - this is the key caption to display.

imageindex - this is a image that is displayed. -1 is the default which means the key caption is text. tab=0, shift=1, enter=2, backspace=3, up=4, down=5, left=6, right=7.

width - this is how wide the key is. Since the keyboard is flow layout from the upper left hand following to the right and down it just gets the next available location. The width and height of the key will be the hit test area. The button will be drawn inside this region offset by the margins.

height - Set the height of the key. The only valid value here is double the height of the row. Only one tall key is valid per row and only on the right hand side.

leftmargin - is the margin to the left of the key.

rightmargin - is the margin to the right of the key.

stretch - in flow layout when resizing setting the stretch to True will tell the resize function to allow this key to take up all available space. Keys that are not stretch keys must have their appropriate proportions no matter the size of the keyboard while keys that are stretch keys will take up the available space.

toggle - if a key is a toggle key then it can be pressed and stay's down. A second press will release the key and draw it normally.

groupindex - toggle keys can be in a group. If two ore more keys are in the same group only one of them can be toggled at a time. When pressing a toggle key all the other toggle keys in the same group will be drawn normally while the newly pressed key will be pressed.

combokeys - there are times when it is handy to generate a key sequence. The format is vk:# or scancode:# separated by a semicolon. The first time the vk or scancode is encountered it will trigger a down, the second occurrence it will be an up.

mapscancode, mapvk - keys like the left and right shift keys or left and right ctrl keys have different scan codes and vks, so to show the same state on these keys one can provide an alternate vk or scancode values.

modifiername - this tells the keyboard that this is a modifier key. When this key is toggled and a key has a modifier attribute then the key can change it's caption, scancode, vk and imageindex.

publishedname - this is the name of the key caption override that is displayed in the object inspector under the CaptionOverrides property. This caption will override any and all captions for this key. Note that the developer can provide keyboard locale specific overrides programatically.


<language languagename="fr" scancode="100" vk="2" imageindex="1" caption="AltGr" />

languagename - specifies a language override for the key. If the keyboard language is fr then the scancode, vk, imageindex and caption will overridden with the values provided.


<modifier scancode="44" vk="0" scancode="20" vk="20" imageindex="2" caption="foo" modifiername="caps">

modifiername - specifies an override for the key. If the modifier is toggled then the scancode, vk, imageindex and caption will overridden with the values provided.


<language languagename="fr" scancode="100" vk="2" imageindex="1" caption="AltGr" />
</modifier>
</key>
</row> </keyboard>