<info> <desc>Tags and attributes supported by the .onboard layout xml file.</desc> <name>Francesco Fumanti</name> <email>francesco.fumanti@gmx.net</email> <years>2016</years>

This work is licensed under the GNU General Public License version 3 or any later version.

</info>

The following specification is outdated and incomplete. It is nevertheless available here, as it might be helpful when working with layouts.

Layout specification

The following section assumes a basic knowledge about markup languages by the reader. Moreover, I am only going to talk about the main points of the layout specification; you are encouraged to open the layouts shipping with <app>Onboard</app> in order to learn about more details.

A layout consists of one <file>xml</file> file with the `.onboard` extension and one <file>svg</file> file per pane defined in the <file>.onboard</file> file.

The <file>.onboard</file> file specifies what key are on each pane, their properties such as label and action; it does not specify size and the location of each key. These are defined in the <file>svg</file> file corresponding to the pane. The connection between the keys in the <file>.onboard</file> file and in the <file>svg</file> files is made by the ids of the keys: the key in the <file>svg</file> file that has the same id of a key in the <file>.onboard</file> file determines the size and position of the key on the pane.

You can use the application named <app>Inkscape</app> to create or modify the <file>svg</file> files corresponding to the panes. The keys can be rectangles or paths (straight lines or bezier curves) though <app>Onboard</app> only detects clicks quite approximately around curves. Do not forget to set the id of the keys in <app>Inkscape</app> by right clicking on the object and selecting object properties.

Each <pane> tag in the <file>.onboard</file> file has:

<list> <item>

`id = "name"`: the id of the pane

</item> <item>

`filename = "name"`: the name of the corresponding svg file

</item> </list>

Each <key> tag in the <file>.onboard</file> file has:

<list> <item>

`id = "name"`: the id of the key

</item> <item>

`sticky = "true/false"`: whether the key is a latching and locking key; please see

</item> <item>

`label = "name"`: the default label on the key

</item> </list>

Each <key> tag in the <file>.onboard</file> file can also have:

<list> <item>

`cap_label = "name"`: the label for when caps lock or shift is pressed

</item> <item>

`shift_label = "name"`: the label for when only shift is pressed

</item> <item>

`altgr_label = "name"`: the label for when alt gr is pressed

</item> <item>

`altgrNshift_label = "name"`: the label for when alt gr and shift is pressed

</item> <item>

`font_offset_x = "number between 0 and 1"`: the x offset of the label in the key

</item> <item>

`font_offset_y = "number between 0 and 1"`: the y offset of the label in the key

</item> </list>

Each <key> tag in the <file>.onboard</file> file must have exactly one of:

<list> <item>

`char = "character"`: the character written when key pressed

</item> <item>

`keysym = "number"`: the keysym or the physical key being emulated in decimal or hex prefixed by 0x

</item> <item>

`modifier = "name"`: the name of the modifier which key emulates. It is recommended to have the sticky attribute set to true for modifiers. List of modifier names given below.

</item> <item>

`keypress = "name"`: name of emulated keys. List of press names given below.

</item> <item>

`macro = "number"`: the macro aka snippet number starting from 0 that the key corresponds with

</item> <item>

`script = "name"`: he name of the script which is run when key is pressed

</item> </list>

List of modifier names that can be paired with the modifier attribute of key:

<list> <item>

`shift`

</item> <item>

`caps`

</item> <item>

`control`

</item> <item>

`mod1` aka alt

</item> <item>

`mod2`

</item> <item>

`mod3` aka num lock

</item> <item>

`mod4`

</item> <item>

`mod5` aka alt gr

</item> </list>

List of keypress names that can be paired with the keypress attribute of key:

<list> <item>

`space`

</item> <item>

`insert`

</item> <item>

`home`

</item> <item>

`page_up`

</item> <item>

`page_down`

</item> <item>

`end`

</item> <item>

`delete`

</item> <item>

`return`

</item> <item>

`backspace`

</item> </list>

List of group names that can be paired with the group attribute of key:

<list> <item>

`alphanumeric`

</item> <item>

`bottomrow`

</item> <item>

`backspace`

</item> <item>

`misc`

</item> <item>

`shifts`

</item> <item>

`keypadmisc`

</item> <item>

`keypadnumber`

</item> <item>

`keypadoperators`

</item> <item>

`directions`

</item> <item>

`editing`

</item> <item>

`snippets`

</item> <item>

`mousebutton`

</item> <item>

`scripts`

</item> <item>

`fkeys`

</item> </list>