---
title: "Workstation Keyboard Layouts"
---

# Workstation Keyboard Layouts

> [Perspective Workstation](launchers-and-workstation/perspective-workstation/perspective-workstation.md) includes a built-in on-screen keyboard for touchscreen HMIs, panel PCs, and other workstations that don't have a physical keyboard. When a user selects an input component in a running Session, such as a Text Field, the on-screen keyboard opens so the user can enter text by touch.

The keys, labels, and languages on the on-screen keyboard come from keyboard layouts that you configure using the **Touchscreen Keyboard Layouts** editor. Layouts use a common JSON structure and are stored on the Gateway, so the same layouts are shared across all projects. Ignition includes several default layouts, and you can create your own, import and export layouts as JSON files, and preview a layout before you save it.

## Workstation Keyboard Layouts Editor

To open the Touchscreen Keyboard Layouts editor, select **Tools > Workstation Keyboard Layouts** in the Designer.

![Designer Tools menu with the Workstation Keyboard Layouts option highlighted.](images/workstation-keyboard-layouts-menu.png)

The editor has two sections:

* **Keyboard Layouts**: Lists the available keyboard layouts. Use the **Add** ![Add icon](images/add.png), **Duplicate** ![Duplicate icon](images/duplicate.png), and **Remove** ![Remove icon](images/remove.png) icons to manage layouts, and the **Export Schema** ![Export Schema icon](images/export-schema.png) icon to save the keyboard layout JSON schema.
* **Keyboard Definition**: Shows the properties of the selected layout. Use the **Export** ![Export icon](images/export.png), **Import** ![Import icon](images/import.png), and **Preview** ![Preview icon](images/preview.png) icons on the right side of this section to export, import, or preview a layout.

Select a layout in the Keyboard Layouts list to view its definition. Click **OK** to save your changes, or **Cancel** to discard them.

![Touchscreen Keyboard Layouts editor with the en_us layout selected and its Keyboard Definition properties shown.](images/workstation-keyboard-layouts-editor.png)

### Default Keyboard Layouts

The keyboard layouts described in the table below are included by default.

| Layout | Description |
|--------|-------------|
| en_us | English keyboard layout. |
| en_us_compat | English keyboard layout kept for compatibility with the legacy layout. |
| de_qwertz | German QWERTZ keyboard layout. |
| es_qwerty | Spanish QWERTY keyboard layout. |
| fr_azerty | French AZERTY keyboard layout. |
| it_qwerty | Italian QWERTY keyboard layout. |

The en_us and en_us_compat layouts are built in and can't be edited or removed. To customize one of them, select it and click the **Duplicate** ![Duplicate icon](images/duplicate.png) icon, then edit the copy. The international layouts can be edited, or removed with the **Remove** ![Remove icon](images/remove.png) icon if your system doesn't need them.

### Keyboard Definition Properties

| Property | Description |
|----------|-------------|
| alias | The 2-3 character string that appears on the keyboard's language selector key to identify this layout, such as `EN`. |
| id | The fixed UUID for the keyboard layout. IDs are generated automatically and are used to track layouts as they're updated on the Gateway. |
| labels | Localized strings for the text on system keys. Available labels are `BACKSPACE`, `CANCEL`, `SHIFT`, `SPACE`, and `SUBMIT`. |
| name | The name of the keyboard layout, as it appears in the Keyboard Layouts list. |
| rows | An array of keyboard rows. Each row is an array of keys, and each key can be defined in any of the following ways:A string literal that creates a system key at that location: `"BACKSPACE"`, `"SUBMIT"`, `"SHIFT"`, `"CANCEL"`, `"CAPSLOCK"`, or `"NUMERIC_LAYOUT"`.An object with at least a `lowercase` member, such as `{ "lowercase": "a" }`. Add an `uppercase` member to define the character used when Shift or Caps Lock is active. To add accent options that appear on long press, use the full object pattern: `{ "lowercase": { "character": "e", "accents": ["ê", "é", "è", "ë", "ė"] }, "uppercase": { "character": "E", "accents": ["Ê", "É", "È", "Ë", "Ė"] } }`.An alias, so the typed character can differ from the key's label: `{ "character": "\t", "alias": "Tab" }`. |
| supportedLanguages | An array of IETF language tags for the languages this layout supports, such as `en`. When the keyboard opens, Ignition looks for a layout that supports the user's locale, and falls back to the English layout if none is found. |
| title | The name presented to the user when selecting this layout, such as `English`. |

## Adding Custom Keyboard Layouts

You can create a keyboard layout from scratch, or duplicate an existing layout to use as a starting point.

1. In the Touchscreen Keyboard Layouts editor, click the **Add** ![Add icon](images/add.png) icon.

    A new layout named **keyboard_1** is added to the Keyboard Layouts list. The layout name appears in italics with an asterisk until you save it. New layouts start with the alias `KB`, default English labels, the title `Custom Keyboard`, and empty **rows** and **supportedLanguages** arrays.

    ![Touchscreen Keyboard Layouts editor showing a new keyboard_1 layout with empty rows and supportedLanguages arrays.](images/adding-custom-keyboard-layouts.png)

    :::tip
    To start from an existing layout instead, select the layout and click the **Duplicate** ![Duplicate icon](images/duplicate.png) icon.
    :::

2. In the Keyboard Definition section, update the **name**, **alias**, **title**, and **labels** properties as needed.
3. Under **rows**, click **Add Array Element** to add each keyboard row, then add the keys for each row. See [Keyboard Definition Properties](#keyboard-definition-properties) for the supported key formats.
4. Under **supportedLanguages**, click **Add Array Element** and enter a language tag for each language the layout supports.
5. Click the **Preview** ![Preview icon](images/preview.png) icon to check the layout. See [Previewing Keyboard Layouts](#previewing-keyboard-layouts) for details.
6. Click **OK** to save the layout.

## Exporting Keyboard Schemas

The keyboard layout JSON schema describes the structure every keyboard layout follows. Export the schema to validate layouts or autocomplete results when you build layouts in an external JSON editor.

1. In the Touchscreen Keyboard Layouts editor, click the **Export Schema** ![Export Schema icon](images/export-schema.png) icon at the bottom of the Keyboard Layouts section.

    ![Touchscreen Keyboard Layouts editor with the Export Schema icon highlighted.](images/exporting-keyboard-schemas-button.png)

2. In the Save popup, choose a location and click **Save**. The file is saved as **keyboard_schema.json** by default.

    ![Save popup with keyboard_schema.json as the file name and Schema JSON Files as the file type.](images/exporting-keyboard-schemas-save-dialog.png)

## Exporting Keyboard Layouts

Export a keyboard layout to back it up, edit it in an external JSON editor, or move it to another Gateway.

1. In the Touchscreen Keyboard Layouts editor, select the layout you want to export.
2. Click the **Export** ![Export icon](images/export.png) icon.

    ![Touchscreen Keyboard Layouts editor with the en_us layout selected and the Export icon highlighted.](images/exporting-keyboard-layouts-button.png)

3. In the Save popup, choose a location and click **Save**. The file is named after the layout by default, such as **en_us.json**.

    ![Save popup with en_us.json as the file name and Keyboard Layout JSON as the file type.](images/exporting-keyboard-layouts-save-dialog.png)

## Importing Keyboard Layouts

Import a keyboard layout that was exported from another Gateway or built in an external JSON editor. Imported layouts must be JSON files.

1. In the Touchscreen Keyboard Layouts editor, click the **Import** ![Import icon](images/import.png) icon.

    ![Touchscreen Keyboard Layouts editor with the Import icon highlighted.](images/importing-keyboard-layouts-button.png)

2. In the Open popup, select the keyboard layout JSON file and click **Open**.

    ![Open popup filtered to Keyboard Layout JSON files.](images/importing-keyboard-layouts-open-dialog.png)

3. Click **OK** to save the imported layout.

## Previewing Keyboard Layouts

You can preview a keyboard layout in the Designer before you save it. The preview popup includes a text field so you can test the keys, shift behavior, and accent options.

1. In the Touchscreen Keyboard Layouts editor, select the layout you want to preview.
2. Click the **Preview** ![Preview icon](images/preview.png) icon.

    ![Touchscreen Keyboard Layouts editor with the en_us layout selected and the Preview icon highlighted.](images/previewing-keyboard-layouts-button.png)

    The Keyboard Preview popup opens and displays the selected layout.

    ![Keyboard Preview popup for the English layout, with qwerty typed in the preview text field.](images/previewing-keyboard-layouts-window.png)

3. Type in the preview text field to test the layout, and then close it when you're done.

:::note
Long press any key that has accent characters defined to open a popup with the alternate characters. For more information about long press, accent keys, and navigating within the text field, see [Keyboard Layouts](platform/designer/designer-tools/keyboard-layouts/keyboard-layouts.md#using-the-long-press-feature).
:::