Creating and editing keyboard XML

OKGO keyboards are defined using a grid of keys across the screen. We tell OKGO where to put each key using XML.

OKGO supports anything that Optikey supports except for "look to scroll" functionality. Extensive documentation can be found at https://github.com/Optikey/Optikey/wiki/Creating-and-Using-Dynamic-Keyboards, but this page will highlight the key things you need to know to build or edit a keyboard for a game

Basic XML structure

<Keyboard>

    <!-- name that appears in OKGO keyboard selection screen (optional, can contain newline character) -->
    <Name>My Demo\nKeyboard</Name>

    <!-- Keyboard size + position (recommended) -->
    <WindowState>Floating</WindowState> <!-- Floating or Docked -->
    <Position>Bottom</Position>     <!-- TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight --> 
    <Width>80%</Width>  
    <Height>40%</Height>  

    <!-- Keyboard styling (optional) -->
    <BackgroundColor>Red</BackgroundColor> <!-- Colour of keyboard where there aren't keys or "Transparent" -->
    <Opacity>0.5</Opacity>                 <!-- How opaque/transparent the keyboard is, 0 = invisible 1 = fully opaque -->

    <!-- Grid definition (essential) -->
    <Grid>
        <Rows>2</Rows>
        <Cols>6</Cols>
    </Grid>

    <!-- Key group definitions - optional way to change properties of some keys together -->
    <KeyGroup Name="AcceleratingKeys" LockOnTime="100" CompletionTimes="100%, 80%, 60%, 40%" KeyDisabledOpacity=".5" />
    <KeyGroup Name="FastKeys" LockOnTime="100" CompletionTimes="1%, 100%" KeyDisabledOpacity=".5" />
    <KeyGroup Name="OrangeKeys" BackgroundColor="orange" ForegroundColor="green"/>

    <Content>
       <!-- List of all keys - can be listed in order without row/column definitions -->
       <DynamicKey>
            <Label>Move</Label>
            <Action>LeftJoystick</Action>
        </DynamicKey>

        <DynamicKey>
            <Label>X</Label>
            <KeyGroup>FastKeys</KeyGroup>
            <KeyPress>XBoxX</KeyPress>
        </DynamicKey>

        <DynamicKey>
            <Label>Y</Label>
            <KeyGroup>OrangeKeys</KeyGroup>
            <KeyToggle>XBoxY</KeyToggle>
        </DynamicKey>

       <!-- ... or with explicit row/column positions on each one, and optional width/height -->
       <DynamicKey Col="4" Row="0" Width="2"  Height="2">
            <Label>Back</Label>
            <Action>BackFromKeyboard</Action>
        </DynamicKey>

    </Content>
</Keyboard>

This XML produces a keyboard that looks like this:

XML parts

The main structure of a keyboard XML file is:

• keyboard properties, including a definition of the grid
• optional keygroups, which can be used to change the behaviour of a group of keys together
• a list of keys, each containing properties and a list of actions.

Keyboard properties

Here is a comprehensive list of all properties and how to use them

General properties

Size + position

Appearance

Key definitions

See What can a DynamicKey do? for full details of what keys are capable of

KeyGroup definitions

You may optionally define key groups with certain properties, to override the default styling or behaviour of on or more keys. The name of the keygroup can be used in a key definition to associate a key with a key group.

Keygroups can be used for styling, for example any keys assigned this keygroup will have an orange background and green foreground.

    <KeyGroup Name="OrangeKeys" BackgroundColor="orange" ForegroundColor="green"/>

They can also be used to change dwelling behaviour, for instance any keys assigned this keygroup will trigger as soon as you look at them (and then trigger a second time after a full dwell has elapsed)

    <KeyGroup Name="FastKeys" CompletionTimes="1%, 100%" />

This keygroup will use a full dwell time initially, but if you keep looking at it it will repeat with a quicker dwell each time - useful for scrolling down a list with arrow keys, for example:

    <KeyGroup Name="AcceleratingKeys" CompletionTimes="100%, 80%, 60%, 40%, 25%, 25%"  />    

More information about all the properties that can be set in a key group are found at Creating-and-Using-Dynamic-Keyboards