Skip to content

Creating and Using Dynamic Keyboards

Julius edited this page Mar 6, 2019 · 4 revisions

Table of Contents

About Dynamic Keyboards

In addition to the many built-in keyboard layouts, OptiKey supports the ability to define your own keyboards. These keyboards are defined in an XML source file and support most, but not all, of the functionality available in the built-in keyboards.

There are 2 primary ways to use dynamic keyboards: choose a keyboard file that someone else has already written, or write your own. Some existing keyboard files are included with OptiKey and can be found in your OptiKey installation folder inside the directory Resources\DynamicKeyboards. The full path may vary depending on your version of Windows and choices you made during installation, but will generally be something like C:\Program Files (x86)\OptiKey\Resources\DynamicKeyboards. You can also view available keyboard files inside of the OptiKey repository here.

Setup With the Sample BigHackerKeyboard XML File

To provide some context and examples of what type of XML keyboard layouts are available, we will first focus on the BigHackerKeyboard example.

You can find the XML source for this keyboard either at the link above or in the DynamicKeyboards folder discussed in the previous section.

Enabling custom keyboards at runtime

In order to enable this keyboard, we need to either choose the Custom Keyboard option as our startup keyboard and specify the path to the keyboard XML file or choose the list of Dynamic Keyboards as our startup keyboard and specify a directory where our custom XML keyboard files can be installed (literally copied). The configuration panel (or Management Console / Settings) can be accessed by right clicking on the OptiKey keyboard and selecting the first option from the resulting popup menu. An example of where to locate these key startup keyboard settings in the console is shown below:

If you have followed these instructions and the keyboard is too large or too small for your screen, then you may need to adjust the Height value in the XML file (see section "Skeleton of the XML Keyboard Files" below). Since the meaning of Height varies depending on screen resolution, a value that works for one user may not work for another.

We are now ready to write software and hack source code with OptiKey!

About BigHackerKeyboard and the purpose of this wiki page

Recently Anna Kirkpatrick and myself collaborated on modifying Custom and Dynamic keyboards for use with OptiKey. These customizable keyboards are specified in specially coded XML files and can be loaded dynamically (or on-the-fly). It turned out that for the most part the functionality to load custom keyboard files dynamically at runtime was already present through the work of K. McNaught on her excellent EyeMine software; it was just undocumented and thus difficult for end users to understand.

Our motivations were slightly different than with the EyeMine software, which used these custom keyboards to create an eye gaze interface for MineCraft. Instead we noticed how difficult it was to write computer programming language source code with the default alphabetical and numeric keyboards in OptiKey (e.g., imagine how many key presses are necessary to type "if(!flag) {" using this scheme!). While Anna has contributed some additions to the OptiKey source code related to improving support for XML keyboard layouts, our primary contribution has been in documenting these features.

Anna's BigHackerKeyboard layout makes use of tabulations of character frequencies in the Sage source code to find the optimal placements for the individual characters within the big keyboard. Notably, since it is easiest to hit the centermost keys with eye tracking software, she has carefully and methodically assembled a keyboard layout which optimizes the user's experience by placing the most common keys near the center of the screen. In addition to making many symbols more accessible, this layout may provide a speed or ease-of-use advantage when compared to QWERTY-based layouts.

Next we will consider the key components of more general purpose XML keyboards like this one so that users can customize their own specialized and preferred keyboard layouts.

Writing your own Custom Keyboards

Skeleton of the XML Keyboard Files

In this section we will explore the necessary components of the dynamic XML keyboard files so users can write and/or edit their own variations of the previous example. First, using the BigHackerKeyboard as our model, we have the following options in the preamble of the file:

   <Name>Big Hacker Keyboard</Name>
   <!-- ... Individual Key Definitions Go Here ... -->

HideFromKeyboardMenu controls whether or not this keyboard will be listed in the dynamic keyboard selection menu. You may wish to set this equal to False for smaller utility-type keyboards.

ShowOutputPanel determines whether or not the word completion suggestions and text output panel are shown at the top of the keyboard. Setting this to False can be useful to free up screen space when these features are not needed.

Note that the Height specifies the height of the keyboard as a function of your screen dimensions and resolution. Even when using an existing keyboard, you may need to adjust the Height value to find a size that works well for your screen. Similarly, if using a different screen resolution for any reason, Height may need to be manually adjusted.

Next, we come to the key entries. Generally speaking there are three distinct types of keys which we can include in our custom keyboards: TextKeys, ActionKeys, and the navigation facing ChangeKeyboardKeys. We provide a few representative examples of each below.


A TextKey is a key that is associated with a text character or string of text which is generated when the OptiKey application signals that the key has been pressed. The fields for the TextKey entries in the Keys section of the keyboard are mostly straightforward to parse by their descriptive names. Note that both Row and Col counts start from 0.

Notice that the Text field, which signifies the text generated by OptiKey on key press, can be a string or a special reserved HTML entity such as &gt; or &#xx; where xx is the ascii code of the character. The Label contains the text to be displayed on the key. If different text should be displayed when the shift key is held down, then ShiftUpLabel and ShiftDownLabel should be specified instead. If all three of Label, ShiftUpLabel, and ShiftDownLabel are set, then only ShiftUpLabel and ShiftDownLabel will be used.

In place of a Label, you may instead specify a Symbol to be displayed on the key. If both a Symbol and a Label are specified for the same key, then the default behavior is to display the symbol until the user looks at the key. While the gaze remains on the key, the label will be displayed instead. A list of keywords that can be used to specify the Symbol icons are found in this source file. Common other icon keywords used in constructing the BigHackerKeyboard from above include: TabIcon, EnterIcon, BackOneIcon, LeftArrowKeyIcon, RightArrowKeyIcon, DownArrowKeyIcon, UpArrowKeyIcon, and MenuIcon, among others found in the default OptiKey keyboards.



Much as in the EyeMine source this functionality was originally written to support, an ActionKey associates a specific action with a keypress. Valid actions are listed in this source file. Common actions include: ArrowUp/Down/Left/Right, Escape, LeftCtrl, LeftAlt, LeftShift, BackOne, MenuKeyboard, and LeftWin. Some example ActionKey entries are given below:


To get to the built-in menu which provides a list of all Dynamic / Custom Keyboards that can be loaded at runtime we use the Action titled DynamicKeyboard:


When you press on this key, it brings up a keyboard menu resembling the following screenshot output of our installed OptiKey keyboard selections:

Currently once you exit the Dynamic / Custom Keyboards selection in favor of one of the built-in OptiKey keyboards, i.e., navigating via a custom key with the one of the Actions Alpha1Keyboard, Alpha2Keyboard, CommuniKateKeyboard, ConversationAlpha1Keyboard, ConversationAlpha2Keyboard, ConversationCommuniKateKeyboard, ConversationNumericAndSymbolsKeyboard, Currencies1Keyboard, Currencies2Keyboard, Diacritic1Keyboard, Diacritic2Keyboard, Diacritic3Keyboard, LanguageKeyboard, MouseKeyboard, NumericAndSymbols1Keyboard, NumericAndSymbols2Keyboard, NumericAndSymbols3Keyboard, PhysicalKeysKeyboard, SizeAndPositionKeyboard, or WebBrowsingKeyboard, be cautious in that you may not be able to get back to the selection of Dynamic / Custom Keyboard layouts without a restart of OptiKey. The core OptiKey developers are aware of this problem and are working on a sane way to fix it for all users -- including those who do not use the custom XML keyboard layouts at all during runtime of the application.

To get to the main keyboard menu, you can also include the following key specification in your custom keyboard:


After pressing this key, a screen resembling the following keyboard will be displayed:


These keys are navigational entries used within the OptiKey layout to change between different dynamically loaded keyboards. It happens that users can navigate to the stock, hardcoded OptiKey keyboards such as Alpha1 or Currency1 after loading a dynamic keyboard at startup by specifying an appropriate ActionKey from the FunctionKeys enum in the OptiKey source linked in the last section. On the other hand, ChangeKeyboardKeys are used to navigate directly to another XML keyboard in the directory setup in the configurations console (Settings). If we have another XML keyboard file named HackerKeyboardSymbols2.xml in our keyboards directory, then the following key specification will allow us to load it on-the-fly from our first keyboard:


The ReturnToThisKeyboard determines the behavior of the back button (when the destination keyboard contains a back key). If set to True, then pressing the back key on the destination keyboard will bring the user back to this keyboard. Otherwise, the current keyboard will be skipped, and the back button will return the user to the keyboard accessed before this one. The False option is useful when constructing multiple keyboards with large keys that are meant to function conceptually as a single keyboard. In this use case, arrows at the edges of the keyboard allow the user to "scroll" to the next block of keys. This approach is used frequently in the EyeMine project.

Clone this wiki locally
You can’t perform that action at this time.