KeyboardLayout file

A keyboard layout is required to use the Keyboard control. This is written in JSON format and can be individually created or customized. The TwinCAT HMI implements a numpad and a layout for a German and English keyboard as standard. These layouts can be customized directly. Alternatively, you can also add a new keyboard layout from a larger choice. This can be done via the context menu in the Solution Explorer.

JSON Sample Keyboard:

Sample:

{
    "useIndirectInput": false,
    "hasNumPad": true,
    "displayName": "Numpad",
    "localeName": null,
    "layouts": []
}

Key

Description

Example value

useIndirectInput

Specifies whether an input field is to be used as indirect input.

true | false

showHintsInIndirectInputTextbox

Specifies whether notes are to be displayed in the indirect input. (Only in connection with "useIndirectInput")

true | false

hasNumPad

Indicates whether a numpad is available. (Only evaluated in engineering)

true | false

displayName

Specifies the display name of the keyboard. (Only evaluated in engineering)

""

localeName

Indicates the language of the keyboard. (ISO)

null | "de-DE" | "en-US" | …

Script

Not used

""

layouts

Specifies the individual keys on the keyboard.

See "JSON sample layouts"

JSON Sample Layouts:

Sample:

{
    "name": "default",
    "dimensions": {
        "width": 230,
        "height": 230
    },
    "keys": []
}

Key

Description

Example values

name

Specifies the name of a keyboard area.

""

dimensions

Specifies the size of the area in px in which the keys are placed.

{
    "width": 230,
    "height": 230
}

keys

Indicates which keys are available.

See "JSON Sample Keys"

JSON Sample Keys:

The "Key" has different structures that are derived from a base class.

Sample:

{
    "geometry": {
        "left": 0,
        "top": 0,
        "width": 21.73913043478261,
        "height": 21.73913043478261
    },
    "code": "Numpad1",
    "key": "1",
    "location": "numpad",
    "labels": [
        {
            "type": "text",
            "text": "1"
        }
    ]
}

Key base class:

Key

Description

Example values

geometry

Indicates where the key is located and how large it is.

{
    "left": 0,
    "top": 0,
    "width": 22,
    "height": 22
}

type

Indicates the function of the key. You can choose between different functions. See the tables below.

"character" | "modifier" | "action" | "edit" | "layout-switch" | "indirect-input" | "input-hints"

labels

Specifies which label is displayed on the key. This can be a simple text, an SVG line or an image.

Depending on the "type" selected, corresponding additional information must also be entered.

[
    {
        "type": "text" | "svg" | "image",
        "position": "",
        "visible": [
            ""
        ],
        "hidden": [
            ""
        ]
    }
]

Additional:

Type = Text:
"text": ""

Type = SVG:
"svg": {
    "dimensions": {
        "width": 40,
        "height": 40
    },
    "path": "M5 5 L15 15 L5 15 Z"
}

Type = Image:

"image": {
    "dimensions": {
        "width": 40,
        "height": 40
    },
    "source": ""
}

StandardKeyDefinition:

Key

Description

Example values

mode

Specifies how the key should respond.

Normal = write when pressed.

Sticky = change between two values. A long press activates the lock.

Toggle = switch between two states.

"normal" | "sticky" | "toggle"

code

Indicates which physical key it corresponds to on the keyboard. There is no code for actions. In this case, it is recommended to use the same name as in the "key".

"Numpad1"

key

Specifies the value of the key.

Character:

"a"

Modifier:

"Meta" | "Insert" | "Shift" | "Control" | "Alt" | "CapsLock" | "NumLock"

Actions:
"ArrowLeft" | "ArrowRight" | "ArrowUp" | "ArrowDown" | "Home" | "End" | "SelectAll"

Edit:

"Backspace" | "Delete" | "PlusMinus"

composition

Indicates whether the key has a composition.

[ "" ]

shiftKey

Specifies the value of the key when Shift is activated.

"A"

shiftType

Indicates the function of the key. You can choose between different functions.

"character" | "modifier" | "action" | "edit"

shiftComposition

Indicates whether the key has a composition.

[ "" ]

ctrlKey

Specifies the value of the key when Ctrl is activated.

""

ctrlType

Indicates the function of the key. You can choose between different functions.

"character" | "modifier" | "action" | "edit"

ctrlComposition

Indicates whether the key has a composition.

[ "" ]

shiftCtrlKey

Specifies the value of the key when Shift and Ctrl are activated.

""

shiftCtrlType

Indicates the function of the key. You can choose between different functions.

"character" | "modifier" | "action" | "edit"

shiftCtrlComposition

Indicates whether the key has a composition.

[ "" ]

altKey

Specifies the value of the key when Alt is activated.

""

altType

Indicates the function of the key. You can choose between different functions.

"character" | "modifier" | "action" | "edit"

altComposition

Indicates whether the key has a composition.

[ "" ]

ctrlAltKey

Specifies the value of the key when Ctrl and Alt are activated.

""

ctrlAltType

Indicates the function of the key. You can choose between different functions.

"character" | "modifier" | "action" | "edit"

ctrlAltComposition

Indicates whether the key has a composition.

[ "" ]

shiftCtrlAltKey

Specifies the value of the key when Shift, Ctrl and Alt are activated.

""

shiftCtrlAltType

Indicates the function of the key. You can choose between different functions.

"character" | "modifier" | "action" | "edit"

shiftCtrlAltComposition

Indicates whether the key has a composition.

[ "" ]

numlockKey

Specifies the value of the key when the numpad is activated.

""

numlockType

Indicates the function of the key. You can choose between different functions.

"character" | "modifier" | "action" | "edit"

numlockComposition

Indicates whether the key has a composition.

[ "" ]

capsLock

Indicates which keys are available under capsLock and what function they have.

{
    "type"
    "key"
    "composition"
    "shiftKey"
    "shiftType"
    "shiftComposition"
    "ctrlKey"
    "ctrlType"
    "ctrlComposition"
    "shiftCtrlKey"
    "shiftCtrlType"
    "shiftCtrlComposition"
    "altKey"
    "altType"
    "altComposition"
    "ctrlAltKey"
    "ctrlAltType"
    "ctrlAltComposition"
    "shiftCtrlAltKey"
    "shiftCtrlAltType"
    "shiftCtrlAltComposition"
    "numlockKey"
    "numlockType"
    "numlockComposition"
}

keyPath

Internal only

-

undefinedKey

Internal only

-

longpressAction

Specifies how the key should behave after a long press. The default value is 'none'.

"none" | "repeat" | "additionalkeys" | "lock"

additionalKeys

Indicates whether there is an additional key. This is coupled with a long press of the key, for example. For example, a long press on "a" selects the umlaut "ä".

See "JSON Sample Keys"

location

Indicates the location of the key. When not in use, "Standard" is used. When using "Ctrl", for example, a distinction is made between left and right.

"standard" | "left" | "right" | "numpad"

ignoreModifiers

Specifies whether the key should ignore modifiers. This is useful for the space bar, for example, as it has no other function.

true | false

LayoutSwitchKeyDefinition: (type = layout-switch)

Key

Description

Example values

layoutName

Specifies the name of the keyboard layout to be switched to. See "JSON sample layouts"

"default"

IndirectInputKeyDefinition: (type = indirect-input)

Key

Description

Example values

component

Indicates whether the button triggers a system function.

"textbox" | "accept" | "cancel"

InputHintsKeyDefinition: (type = input-hints)

Key

Description

Example values

-

-

-

Key samples:

Layout-Switch:

The keyboard can be switched to a second layout via "Layout switch". Here, the name from "JSON Sample Layouts" must be entered in "layoutName".

{
    "geometry": {
        "left": 0,
        "top": 0,
        "width": 20,
        "height": 20
    },
    "type": "layout-switch",
    "layoutName": "default",
    "labels": [
        {
            "text": "ABC",
            "type": "text"
        }
    ]
}

Indirect Input:

An "Accept" button can be created via "Indirect Input", for example. With an indirect keyboard, this writes the value into the selected input field.

{
    "geometry": {
        "left": 0,
        "top": 0,
        "width": 20,
        "height": 20
    },
    "type": "indirect-input",
    "component": "accept",
    "labels": [
        {
            "type": "svg",
            "svg": {
                "path": "M 1 11 L 5 17 L 18 1",
                "dimensions": {
                    "width": 19,
                    "height": 18
                }
            }
        }
    ]
}

Modifier:

A key such as "Shift" or "Ctrl" can be used as a modifier. Here is an example of the left Shift key on the keyboard with "Lock" functionality.

{
   "geometry": {
      "left": 0,
      "top": 0,
      "width": 20,
      "height": 20
   },
   "code": "ShiftLeft",
   "key": "Shift",
   "type": "modifier",
   "mode": "sticky",
   "location": "left",
   "labels": [
      {
         "type": "svg",
         "svg": {
            "dimensions": {
               "width": 14,
               "height": 14
            },
            "path": "M 3.5 13.5 L 3.5 6.5 L 0.5 6.5 L 7 0.5 L 13.5 6.5 L 10.5 6.5 L 10.5 13.5 Z"
         },
         "hidden": [
            "locked"
         ]
      },
      {
         "type": "svg",
         "visible": [
            "locked"
         ],
         "svg": {
            "dimensions": {
               "width": 14,
               "height": 14
            },
            "path": "M 3.5 8.5 L 3.5 6.5 L 0.5 6.5 L 7 0.5 L 13.5 6.5 L 10.5 6.5 L 10.5 8.5 Z M 3.5 13.5 L 3.5 10.5 L 10.5 10.5 L 10.5 13.5 Z"
         }
      }
   ],
   "longpressAction": "lock"
}

Action: (SelectAll)

With Action, a function such as a "SelectAll" or "ArrowUp" can be implemented. The entire text/number of the input field is selected via "SelectAll".

{
    "geometry": {
        "left": 80,
        "top": 40,
        "width": 20,
        "height": 20
    },
    "code": "SelectAll",
    "key": "SelectAll",
    "type": "action",
    "labels": [
        {
            "type": "text",
            "text": "SelectAll"
        }
    ]
}

Character:

The value from the "key" is written to the input field.

{
    "geometry": {
        "left": 80,
        "top": 40,
        "width": 20,
        "height": 20
    },
    "code": "KeyA",
    "key": "a",
    "type": "character",
    "labels": [
        {
            "type": "text",
            "text": "a"
        }
    ]
}

Edit:

The value is changed between a positive and negative value.

{
    "geometry": {
        "left": 80,
        "top": 40,
        "width": 20,
        "height": 20
    },
    "code": "PlusMinus",
    "key": "PlusMinus",
    "type": "edit",
    "labels": [
        {
            "type": "text",
            "text": "+/-"
        }
    ]
}