Documentation on XML Definition File (On-Screen Keyboard)

The XML definition file of on-screen keyboard layouts defines all elements that can be pressed on an on-screen keyboard as well as the functions that will be carried out when the elements are being pressed.

Although creating your own on-screen keyboard layout is possible, it should not be taken lightly. Please understand that we cannot offer you any support with creating your own on-screen keyboard layouts!

 

Notes on Screen Resolution

The on-screen keyboard layouts we provide are intended to be used with a screen resolution of 1024x768 pixels.

Should you wish to use a different resolution, SiteKiosk will automatically change all values accordingly, i.e. the jpegs along with the other values will be extrapolated. This is why our skins will also work flawlessly when used, for example, with resolutions under 800x600.

When you create your own on-screen keyboard layout, begin by using a resolution of 1024x768 in order to ensure best quality.

 

General Structure of the XML Definition File

In order to grasp the overall picture, it is often easiest to take an in-depth look at the finished file of an on-screen keyboard layout. The layout "TX-82 Scroll Bars (English)" represents an elementary on-screen keyboard. Download this layout and take a closer look at the "tx-82_english_scroll.xml" located in the folder SKINS\TX-82\ENGLISHSCROLL.

<keydef name="TX-82 Scroll Bars (English)"> <subkeydef name="1024-small" type="small" language="9" docked="-1" forcewinkeyboard="1"> <dockrect x1="0" y1="0" x2="1024" y2="52" /> <hotspot x="0" y="0" /> <shape mode="xor"> <rect x1="12" y1="5" x2="162" y2="50" /> <rect x1="12" y1="5" x2="162" y2="50" /> <rect x1="12" y1="5" x2="162" y2="50" mode="add"/> ... </shape> <language id="9" target="TX-82 Scroll Bars (English)\\docked, big" /> <jpeg type="normal"> skins\tx-82\englishscroll\qwerty0001.jpg</jpeg> <jpeg type="pressed"> skins\tx-82\englishscroll\qwerty0002.jpg</jpeg> <sound id="0">wavs\key_click.wav</sound> <dockbackground type="2" filename="background.png"/> <nondragarea mode="or"> <rect x1="12" y1="5" x2="162" y2="50" /> ... </nondragarea> <nonshiftkeys> <key sound="5" type="5" vkey="0" char="+" shift="0"> <shape mode="xor"> <rect x1="" y1="" x2="" y2="" mode="or" /> <ellipse x1="" y1="" x2="" y2="" mode="or" /> <roundrect x1="" y1="" x2="" y2="" widthellipse="" heightellipse="" mode="or" /> <polygon mode="or" polymode="alternate"> <point x="322" y="2"/> <point x="486" y="2"/> <point x="486" y="53"/> </polygon> ... </shape> </key> <key sound="2" type="2" vkey="0" target="docked, small"> ... </key> <key sound="2" type="16" vkey="0" target=" http://www.sitekiosk.com/"> ... </key> <key sound="17" type="2" vkey="0" target="docked, small"> ... </key> <macro sound="0"> <shape> ... </shape> <mkey char="h"/> <mkey char="t"/> <mkey char="t"/> <mkey char="p"/> <mkey char=":"/> <mkey char="/"/> <mkey char="/"/> </macro> </nonshiftkeys> <keyswithoutshift> <key type=0 char='a'> ... </key> ... </keyswithoutshift> <keyswithshift> <key type=0 char='A'> ... </key> ... </keyswithshift> </subkeydef> </keydef>

 

Documentation of Elements and Attributes

KEYDEF
Every keyboard layout is divided up into a keydef key defining array and several subkeydef arrays. The subkeydef sections describe the keys for the different states of the keyboard, e.g. minimized (small) or maximized (big).

<keydef name="TX-82 Scroll Bars (English)"> <subkeydef ..."> ... </subkeydef> </keydef>

The single attribute of the keydef array is "NAME", which defines the keyboard's name. The content of the attribute will be displayed in the SiteKiosk configuration tool. The attribute "NAME" has to be unequivocal throughout all existing layouts.

SUBKEYDEF


<subkeydef name="1024-small" type="small" language="9" docked="-1" forcewinkeyboard="1">

1. NAME
   The attribute "name" assigns an unequivocal name to a sub layout. You will need this name in order to embed keys that allow the changing of keyboards while the system is running because in that case the system will refer back to NAME.
2. TYPE
   The "type" attribute determines whether a keyboard definition is designed for a large (maximized) keyboard ("big") or for a small (minimized) keyboard. This serves the primary purpose of enabling SiteKiosk to determine at run time whether the keyboard has already been pulled in or whether it still has to be pulled in at a specific moment (e.g. when a new window is opened).
   Switching over automatically from a maximized keyboard to a minimized keyboard or vice versa will only be possible if a "type 2" key (toggle key) is available. If you switch over automatically, all "type 2" entries will be perused, and the first layout that is found will be selected.
   
   Important:
   The definition has to be given completely both for small and big, which means that some keys being visible both in SMALL and BIG will have to be defined twice.
3. LANGUAGE
   The attribute "language" determines for which language the current layout has been defined. This is important with regard to an automatic change of the language because this will help you to recognize if the currently loaded layout is maybe already defined for the language you have selected. Use 0 (for all languages) if you plan to create a keyboard that is able to switch between all languages that have been configured under Windows.
4. DOCKED
   The attribute "docked" determines whether the keyboard is supposed to be docked. This means that in contrast to FLOAT, SiteKiosk will reduce the size of the browser window so far that either the entire keyboard will be located outside of the browser area or that the area not defined in "dockrect" will still overlap the browser area.
   The use of a DOCKED keyboard ensures that the keyboard will not overlap the browser window. In contrast, a FLOATED keyboard is located on the browser surface and will therefore overlap the browser window.
5. FORCEWINKEYBOARD
   When you switch to another keyboard (language), the attribute "forcewinkeyboard" (bool) will determine whether the system is also supposed to switch over to the corresponding keyboard layout (adjustable under CONTROL PANEL/KEYBOARD/LANGUAGE). If, for example, a keyboard with the settings for French is loaded, the regular Windows keyboard settings will be altered to French as well.

DOCKRECT

<dockrect x1="0" y1="0" x2="1024" y2="58"/>

Whenever a keyboard is docked, "dockrect" will define which part of the keyboard will be allowed to overlap the browser window. This part also represents the "visible" part of the minimized keyboard. In this part you will usually embed buttons like "pop up keyboard" and the scroll buttons. In the code example, the keyboard being 1024 pixels wide will stick out by 58 pixels.
In this case, the keyboard will be cut off below the "dockrect", while the part above the "dockrect" will overlap the browser window. Should the "dockrect" be missing, the browser size will be reduced up to the point at which the keyboard will no longer overlap the browser window.
The "dockrect's" attributes are "x1" and "y1" for the upper left-hand corner and "x2" and "y2" for the lower right-hand corner. These values will be specified as keyboard coordinates. The "dockrect" also defines the area the centered keyboard is supposed to cover. The system will always try to move the keyboard to a position in which the "dockrect" will be located in the middle of the screen.

DOCKBACKGROUND
This element defines what the background of the docked keyboard is supposed to look like by allowing you to select a color, an image or a resource.
If "type" is "1", a color will be defined as a decimal number in the attribute "color". This number will determine the background color.
If "type" is "2", a file has to be specified in the attribute "filename" which is supposed to be displayed as tiles in the background.

PAINTING
This element is optional but required if you want to create a keyboard that can automatically switch between all keyboard languages that have been configured under Windows. In that case the image files do not contain characters, these are rendered based on the selected language using the painting values for color (pressed and unpressed state), font family etc.

<painting color-up="0" color-down="16777215" font-family="Tahoma" font-weight="600" font-size="-22"/>

Example: Excerpt from the file natural.xml. A language independent keyboard layout.

Additional possible attributes are resolution-x and resolution-y. They can be used to determine the screen resolution under which the keyboard will be displayed in its original size. If the values are missing, SiteKiosk uses 1600x1200. The keyboard will be scaled under bigger or smaller resolutions.

<painting resolution-x="1024" resolution-y="768"/>

Example: Starting resolution for keyboard scaling.

LANGUAGESELECTOR
This element is only required if you want to create a keyboard that can automatically switch between all keyboard languages that have been configured under Windows. This element displays the available languages and can be expanded using the key type 19 (see below). The following code example includes optional image elements. If they are not provided the language will only be represented by a text description. imagerect and textrect define the positions for the image and text areas of the element.

<languageselector font-family="Arial" font-weight="600" font-size="-12" check-image="skins\provisio\languages\check.ico"> <imagerect x1="135" y1="222" x2="157" y2="236" /> <textrect x1="161" y1="222" x2="181" y2="236" /> <image id="1">skins\provisio\languages\jpg\sa.jpg</image> <image id="2049">skins\provisio\languages\jpg\iq.jpg</image> </languageselector>

Example: Excerpt from the file natural.xml. A language independent keyboard layout.

HOTSPOT

<hotspot x="0" y="0"/>

The "hotspot" contains the attributes "x" and "y". By means of these attributes you can specify a point which will be located at the same spot of the screen whenever a different keyboard is selected. Thus, if you have a similar image for two different keyboards, you should place the "hotspot" for both keyboards in the same location in order to prevent the keyboards from bouncing around. If you do not specify a "hotspot", the system will automatically define the point (x=0, y=0) as the "hotspot".
If the desired layout is a docked layout, the "hotspot" will not have an influence on the desired position of the keyboard.

SHAPE
A shape element provides the outline for a complete keyboard layout (example 1) or for a single key (example 2).

<shape> <rect x1="0" y1="0" x2="1024" y2="58"/> </shape>

Example 1: Determines that the JPEG will be 1024 pixels wide and that 58 pixels of the upper rim of the graphic will be visible.

<key sound="5" type="5" vkey="0"> <shape> <polygon> <point x="322" y="2"/> <point x="486" y="2"/> <point x="486" y="53"/> <point x="322" y="53"/> <point x="322" y="2"/> </polygon> </shape> </key>

Example 2: Defines the key "scroll up" (Type 5). Both the position and the size of the key will be specified by the polygon values on the JPEG (Polygon). When the key is clicked on/pressed, the sound with the ID 5 will be played back and the function "scroll up" will be carried out.

shape itself has a "mode" as its attributes which determines how the individual sub elements (child elements) defining the final shape will be composed. You can choose the following values as "mode": "or" (default), "and", "xor", and "diff". Every child element itself can, in turn, have a "mode" which will overwrite the "mode" attribute of the parent "shape". The child elements will be joined together from the bottom up to form the complete shape.

NONDRAGAREA
Here you can define an area in which the user will not have the possibility to move the keyboard around by dragging (touching the keyboard with his or her finger or with the mouse). The element "nondragarea" is built the same way as the element "shape".

KEY
See item 6 for an example.
The "key" element consists of several attributes of which not every single one has to be specified.
The "sound" attribute indicates which sound is to be played back when the key is pressed. You have to specify the corresponding SOUND ID here.
The attribute "vkey" allows you to determine which virtual keystroke is supposed to be simulated. Please read this note as well as the Window-API documentation for further information.
The attribute "scancode" allows you to use scancodes to determine which virtual keystroke is supposed to be simulated. Please read the Window-API documentation for further information.
You use "shift" to determine whether, prior to pressing the key, the keystroke "shift" is to be simulated as well. However, in most cases the attribute "char" will suffice because in this attribute you only have to specify the desired sign in order to simulate the complete necessary keystroke for the corresponding keys (including Shift, Ctrl, and Alt).
Under "target" you can assign a specific URL or a certain keyboard layout to a key. The desired "target" will then be displayed as soon as the key is pressed. In order to call a keyboard layout you have to enter the name of the keyboard you specified under "subkeydef".
The element KEY can have different TYPE attributes determining the corresponding type of key.

1. Type 0:
   This key is a regular key. In this case, the key to press is composed and simulated in the same way as is the case with the "mkey".
2. Type 1:
   This key is the Capslock key. It switches over to the internal Shift status in SiteKiosk. Whenever the user clicks on the keyboard with the internal status being set to "shift", all "nonshiftkeys" as well as all "keyswithshift" will be checked, and a keystroke will be simulated accordingly. If the status is not set to shift, all the keys defined in "nonshiftkeys" and "keyswithoutshift" will be checked. You need to combine type="1" with vkey="16" to get the Capslock key functionality.
3. Type 2:
   This key is there for changing the size of the keyboard. The key should only occur once, and it should load a keyboard which is "small" rather than one which is "big" or vice versa. The layout to be loaded is defined in the attribute "target" and is built the same way as the target in the "language" element. In order to switch between languages or to change the layout altogether, you will have to use type 17.
4. Type 3:
   This key simulates the scrolling of the content of all frames to the left.
5. Type 4:
   This key simulates the scrolling of the content of all frames to the right.
6. Type 5:
   This key simulates the scrolling of the content of all frames to the top.
7. Type 6:
   This key simulates the scrolling of the content of all frames to the bottom.
8. Type 7:
   This type must not be used (reserved).
9. Type 8:
   This key simulates a click on the Back button.
10. Type 9:
    This key simulates a click on the Forward button.
11. Type 10:
    This key simulates a click on the Stop button.
12. Type 11:
    This key simulates a click on the Refresh button.
13. Type 12:
    This key simulates a click on the Start Page button.
14. Type 13:
    This key simulates a click on the Print button.
15. Type 14:
    This key simulates a click on the Search button.
16. Type 15:
    This type must not be used (reserved).
17. Type 16:
    This type performs a browser navigation towards the URL defined in the attribute "target".
18. Type 17:
    This type performs a change of the on-screen keyboard layout to a layout defined in "target". The syntax for the value of this attribute is the same as the one described in connection with the "language" element.
19. Typ 18:
    This type is for internal use.
20. Typ 19:
    This type is used for the language selection when you plan to support all languages that have been configured under Windows and needs to be combined with language="-1". Other language values are currently not supported. -1 means it is for all languages and needs a value of 0 for the language attribute of SUBKEYDEF.
21. Typ 20:
    This type simulates Alt Gr.
22. Typ 21:
    This type simulates the Shift key.
23. Typ 22:
    This type simulates the CTRL key.

Example:

<key sound="2" type="16" vkey="0" target="http://www.sitekiosk.com/"> ... </key>

Note:
You have to use UNICODE with "char" attribute to write special characters! Please note that you can only use characters that are part of the official keyboard layout of the chosen language.


<key sound="0" type="0" char="&#8364;"> <shape> <rect x1="644" y1="151" x2="696" y2="201" /> </shape> </key>

Example: Defines a key for "€".


Defining the KEYBOARD AREAS

<polygon> <point x="322" y="2"/> <point x="486" y="2"/> <point x="486" y="53"/> <point x="322" y="53"/> <point x="322" y="2"/> </polygon>

Example: A polygon can consist of any desired number of points (in this case 5) that are linked together.

By means of the following elements you will be able to define areas on the keyboard that can be pressed or clicked on.

1. RECT:
   "rect" lets you define a rectangle. The attributes are "x1", "y1" for the upper left-hand corner and "x2", "y2" for the lower right-hand corner.
2. ELLIPSE:
   "ellipse" lets you define an elliptic area. The ellipse is specified by a rectangle which touches the ellipse from the inside at four points. Again, the attributes are "x1", "y1" and "x2", "y2".
3. ROUNDRECT:
   This element lets you define a round rectangle. In addition to the coordinates of a rectangle, you can specify with the help of "widthellipse" and "heightellipse" to what degree the rectangle is supposed to be rounded at the corners.
4. POLYGON:
   A polygon defines an area consisting of several points. A polygon can be built by means of two different "polymodes". If the "polymode" is "winding" (default), all the areas with a winding value other than zero will be filled. If the "polymode" is "alternate", all the areas between even and uneven polygon sides will be filled.
5. POINT:
   The attributes of a point are its two coordinates "x" and "y".

LANGUAGE


<keydef name="TX82-Ultra Universal (floating)"> <subkeydef name="ger, docked, small" language="7" type="small" docked="-1" forcewinkeyboard="1"> <dockrect x1="0" y1="22" x2="991" y2="47" /> <hotspot x="0" y="0" /> <language id="7" target="ger, docked, small" /> <language id="9" target="eng, docked, small" /> <language id="12" target="fre, docked, small" /> ... </keydef>

Example: Excerpt from the file tx82_ultra_universal_floating.xml. A trilingual keyboard layout (German, English, French).

This element is not required if you want to create a keyboard that can automatically switch between all keyboard languages that have been configured under Windows, use languageselector instead (see above).
The "language" attribute assigns an additional keyboard layout to a language code. Thus, if an automatic change of the language occurs, all the "language" elements of the current keyboard definition will be searched for the first layout that matches the language code ("id") of the newly selected language. The matching layout will then be loaded.
The keyboard layout that is to be loaded will be specified as "target". This "target" consists of two arrays separated by "\\". The left part contains the definite name that was defined in the related "keydef" array of a different file. The other part contains the name of the "subkeydef". The first part can be left out if the definition is located in the same "keydef" array.

Here are the language IDs:

LANG_AFRIKAANS 54 LANG_ALBANIAN 28 LANG_ARABIC 1 LANG_ARMENIAN 43 LANG_ASSAMESE 77 LANG_BULGARIAN 2 LANG_CATALAN 3 LANG_CHINESE 4 LANG_CROATIAN 26 LANG_CZECH 5 LANG_DANISH 6 LANG_DUTCH 19 LANG_ENGLISH 9 LANG_ESTONIAN 37 LANG_FINNISH 11 LANG_FRENCH 12 LANG_FRENCH-BELGIUM 2060 LANG_GERMAN 7 LANG_GREEK 8 LANG_HEBREW 13 LANG_HINDI 57 LANG_HUNGARIAN 14 LANG_ICELANDIC 15 LANG_INDONESIAN 33 LANG_ITALIAN 16 LANG_JAPANESE 17 LANG_KANNADA 75 LANG_KOREAN 18 LANG_LATVIAN 38 LANG_LITHUANIAN 39 LANG_MACEDONIAN 47 LANG_MALAY 62 LANG_MALAYALAM 76 LANG_MARATHI 78 LANG_NORWEGIAN 20 LANG_POLISH 21 LANG_PORTUGUESE 22 LANG_ROMANIAN 24 LANG_RUSSIAN 25 LANG_SERBIAN 26 LANG_SLOVAK 27 LANG_SLOVENIAN 36 LANG_SPANISH 10 LANG_SWEDISH 29 LANG_THAI 30 LANG_TURKISH 31

JPEG

<jpeg type="normal"> skins\tx-82\englishscroll\qwerty0001.jpg</jpeg> <jpeg type="pressed"> skins\tx-82\englishscroll\qwerty0002.jpg</jpeg>

Under "jpeg" you specify the images that are supposed to be loaded for unpressed (image1) and pressed keys (image2), respectively.
The image of the "type" "normal" will be displayed to the user. Of the image "type" "pressed" only that part of the key will be displayed that was pressed. This section refers back to the key definition. If you want your on-screen keyboard to work, you will have to specify both images.

SOUND

<sound id="0">wavs\key_click.wav</sound>

The "id" of the "sound" element defines when a sound is supposed to be played back. You assign the "id" belonging to the desired sound to the attribute "sound" in the "key" or "macro" element. You have to enter the path of the sound file that is to be played back between the opening <sound> and the closing </sound>.

NONSHIFTKEYS
In the "nonshiftkeys" element you can specify all the keystrokes that can be generated on the regular keyboard without the help of the SHIFT KEY. These include, for example, keys like 'a', 'b', '+', '-', '.' or ',' as well as the keys for changing the keyboard layout, scroll keys, etc.

MACRO

<macro sound="8"> <shape> <polygon> <point x="806" y="289"/> <point x="906" y="290"/> <point x="906" y="344"/> <point x="805" y="343"/> <point x="806" y="289"/> </polygon> </shape> <mkey char=";"/> <mkey char="-"/> <mkey char=")"/> </macro>

Example: If enabled, this macro will produce the emoticon ";-)"

A macro's attribute is "sound" which defines as numerical value (id) which of the previously defined sounds is supposed to be played back when this key is pressed.
Apart from that, the "macro" contains a sub element "shape" which defines the area in which the pressing of this key is supposed to be perceived. This "shape" will be defined like above. As child element, a macro can contain any desired number of "mkeys".

1. MKEY:
   As an attribute, the "mkey" can contain "vkey" "press" "char" or "shift". The "vkey" determines which virtual key (see Documentation of Window API) will be simulated by means of this keystroke. With the help of "press," you can determine if a key is supposed to be pressed ("1"), released ("0") or pressed and released ("-1") (default).
   With "shift" you can specify whether the pressing of the Shift key is supposed to be simulated prior to the pressing of the actual key. In most cases, however, the attribute "char" will be sufficient because this attribute will simulate the entire key combination of the corresponding keys together with Shift, CTRL and Alt in order to have the desired character displayed.

KEYSWITHOUTSHIFT and KEYSWITHSHIFT:
Here you can determine which key is supposed to be simulated in case the shift key is not pressed ("keyswithoutshift") or rather pressed ("keyswithshift"). You will only be able to use "key" elements as child elements here.

1. key:
   A "key" contains a "shape" as a child element which, as described above, defines an area in which the pressing of a key will be perceived. A "key" has "sound", "type", "vkey", "char", "shift" or "target" as its attributes. The attribute "sound" defines which sound is supposed to be played back when this key is pressed.

  

1. Converting keyboard layout files from 4.8 (.kbd) to 4.9 (.xml)
   We offer a free download of a converting tool. With the help of this tool you will be able to convert old .kbd files into the new .xml format. You will, of course, still have to revise these files.
2. Virtual Key Codes
   Another free download is provided for the tool virtkeys.exe. This tool allows you to easily find the Virtual Key Codes you will partly need in order to create your own on-screen keyboard layout.
3. Here are, at a glance, the most important VIRTUAL Key Codes:
   
   • ENTER = 13
   • SHIFT LEFT= 16, 160
   • ESC = 27
   • SPACE= 32
   • TAB = 9
   • BACKSPACE= 8