Keyboard Layout
On-Screen Keyboard Layouts
Create your own language layout using XML or modify the built-in layout for your project. This page is a reference guide for using the On-Screen Keyboard.
Operating Principle
Before configuring your custom keyboard layouts, you need to determine how the on-screen keyboard will behave on your page. This is managed by the Keyboard Mode setting located in the Advanced Panel section of the Page and has three different options:
- Disabled: The on-screen keyboard is completely turned off for this page. The operator must use a physical keyboard or the operating system’s built-in on-screen keyboard to enter text or numeric values.
- Active: The on-screen keyboard is permanently enabled. In Runtime, when the operator clicks on an input field, the keyboard automatically becomes visible.
- UserSelectable: This mode leaves the keyboard usage preference to the operator. Whenever the user enters or refreshes the page, a small window appears in the top right corner of the screen asking whether they want the keyboard to be Active or Passive for that session.
Note: The “On Screen Keyboard” setting located in your project’s Setup menu is only for the Screens environment and triggers the operating system’s built-in keyboard. It should not be confused with the custom XML keyboard structure you prepared for Pages.
The Language setting entered in the Advanced section of the Page determines the keyboard’s initial language when the page opens. The operator can change the language using the 🌐 key on the keyboard. When a new page is loaded, the initial language is selected again based on the Page language. The built-in language layouts are located in the KeyboardLayouts folder at the C:\Program Files\Fultek\Wise SCADA path.
If you want to use your own keyboard layouts, you must create a folder named KeyboardLayouts inside your project folder and place your files there. When the system runs, it checks your project first; if it finds this folder, it completely ignores the standard installation files and uses only the keyboards in your project. If this folder does not exist in your project, it defaults to using the keyboards in the installation folder. The creator of the project folder writes the languages they want to display into index.xml and places the corresponding XML files in the same folder.
If the XML file of a layout defined in index.xml is missing or corrupted, its name will remain in the menu; however, an error will be displayed when selected by the user. If index.xml itself cannot be parsed as XML, the language list cannot be displayed and an error appears.
index.xml Each layout is a menu item. id corresponds to the id.xml file in the same folder. name is displayed in the menu. locale is matched with the Page language; for example, tr is Turkish. Identifiers must start with a Latin letter; can be up to 64 characters long; and must contain only ASCII letters, numbers, _, or -.
XML
<?xml version="1.0" encoding="utf-8"?>
<keyboardLayouts version="1">
<layout id="english" name="English" locale="en" />
<layout id="turkish" name="Türkçe" locale="tr" />
</keyboardLayouts>To add a new language to the project, ensure the XML file name and the keyboard id value are identical, then add a layout row into index.xml. To modify the keys of an existing language, copy the built-in layout to the project and edit the project’s XML.
Language XML
XML
<?xml version="1.0" encoding="utf-8"?>
<keyboard version="1" id="english" name="English" locale="en" direction="ltr">
<layer name="default">
<row>
<key output="`" />
<key output="1" />
<key output="2" />
<key output="3" />
<key output="4" />
<key output="5" />
<key output="6" />
<key output="7" />
<key output="8" />
<key output="9" />
<key output="0" />
<key output="-" />
<key output="=" />
<key role="backspace" />
</row>
<row>
<key role="tab" />
<key output="q" />
<key output="w" />
<key output="e" />
<key output="r" />
<key output="t" />
<key output="y" />
<key output="u" />
<key output="i" />
<key output="o" />
<key output="p" />
<key output="[" />
<key output="]" />
<key output="\" />
</row>
<row>
<key role="caps" />
<key output="a" />
<key output="s" />
<key output="d" />
<key output="f" />
<key output="g" />
<key output="h" />
<key output="j" />
<key output="k" />
<key output="l" />
<key output=";" />
<key output="'" />
</row>
<row>
<key role="shift" />
<key output="z" />
<key output="x" />
<key output="c" />
<key output="v" />
<key output="b" />
<key output="n" />
<key output="m" />
<key output="," />
<key output="." />
<key output="/" />
</row>
<row>
<key role="language" />
<key role="at" />
<key role="space" />
<key role="cancel" />
<key role="submit" />
</row>
</layer>
<layer name="shift">
<row>
<key output="~" />
<key output="!" />
<key output="@" />
<key output="#" />
<key output="$" />
<key output="%" />
<key output="^" />
<key output="&" />
<key output="*" />
<key output="(" />
<key output=")" />
<key output="_" />
<key output="+" />
<key role="backspace" />
</row>
<row>
<key role="tab" />
<key output="Q" />
<key output="W" />
<key output="E" />
<key output="R" />
<key output="T" />
<key output="Y" />
<key output="U" />
<key output="I" />
<key output="O" />
<key output="P" />
<key output="{" />
<key output="}" />
<key output="|" />
</row>
<row>
<key role="caps" />
<key output="A" />
<key output="S" />
<key output="D" />
<key output="F" />
<key output="G" />
<key output="H" />
<key output="J" />
<key output="K" />
<key output="L" />
<key output=":" />
<key output=""" />
</row>
<row>
<key role="shift" />
<key output="Z" />
<key output="X" />
<key output="C" />
<key output="V" />
<key output="B" />
<key output="N" />
<key output="M" />
<key output="<" />
<key output=">" />
<key output="?" />
</row>
<row>
<key role="language" />
<key role="at" />
<key role="space" />
<key role="cancel" />
<key role="submit" />
</row>
</layer>
</keyboard>The example above shows a complete and usable keyboard layout prepared for the english.xml file. The id value (in this example “english”), the file name, and the record in index.xml must match perfectly. The direction property can only be ltr (left-to-right) or rtl (right-to-left). The default and shift layers are mandatory. While the Shift key changes the layer for a single character input, the Caps key continuously locks the Shift layer. The keys appear on the screen in the exact row and order they are written in the XML.
output is the Unicode character that will be written to the text field when the key is pressed. The label property is optional; it is used if you want a different text to appear on the key than the character it outputs. Additionally, to avoid breaking the XML structure, escape characters such as < for <, > for >, & for &, and " for ” are used for special characters, as seen in the shift layer.
Function Keys
When defining special keys on the keyboard, you must use the role attribute instead of the output we use for letters. JavaScript or an external program cannot be executed from within the XML file; only the following fixed roles can be assigned:
- language: Opens the language selection menu.
- shift / caps: Switches to the Shift layer.
- backspace: Deletes the last typed character.
- space / tab / at: Inserts a Space, Tab, and @ character, respectively.
- submit / cancel: Accepts the input (Enter) or cancels the operation.
Customized Key Layout
The keyboard infrastructure features a flexible design that allows you to freely add new keys to existing rows. Wide function keys located at the beginning or end of rows (such as Tab, Caps, Shift, Backspace) dynamically adjust their sizes based on the number of existing keys in that row.
Because of this, when you want to add an extra new character key to any row (for example, if you add a + key right after the Caps key in the XML code), the wide keys automatically shrink to make room for this new character. You do not need to calculate extra width, spacing, or alignment settings; the system seamlessly incorporates your newly added key into the row and automatically adjusts the layout itself.
XML
<row>
<key role="caps" />
<key output="+" /> <!-- Newly added key to the row -->
<key output="a" />
<key output="s" />
</row>Accent Rules (Dead Keys)
XML
<deadKeys>
<dead key="´" mark="́" />
<dead key="^" mark="̂" />
</deadKeys>The use of this section is optional. It is used in some languages to add hats (circumflexes) or accents to letters (e.g., French or Turkish circumflex letters).
- How Does It Work? When the user presses the ^ key first, followed by the a key, the system combines these two inputs and types â (Unicode NFC format) on the screen.
- Definition Rule: The key value here must be exactly the same as the output value of the key you defined within the layer. If the pressed letter is not suitable for combining with the accent (e.g., ^ and x), the system types these two characters separately.
- Design Tip: If the accent mark looks too small or unclear when standing alone on the keyboard key, you can display the mark with a dotted circle (for example: ◌̂ ) by using the key’s label attribute.
Input Methods and Scope
The initial/medial/final forms of Arabic and Persian letters are determined by the browser’s text rendering. Do not duplicate each form as a separate key in the XML. Chinese Pinyin candidate lists, Japanese kanji conversions, and Korean syllable formations cannot be achieved simply by adding key XMLs: they require a separate input engine and dictionary. Chinese candidate selection is not supported in this version; Latin keys in a Chinese XML do not imply standalone Chinese typing support.
Refresh the Page after making changes. When modifying a built-in XML, select the same language and test all necessary letters, the Shift layer, deletion, and input submission with real examples. The operation of the keyboard does not require a connection to this documentation site.