The Keyman keyboard language has two basic types of keyboard layout: positional and mnemonic. In this blog post, I describe the differences between these two types of keyboard layouts, along with notes on now to develop the two layout types.

The Keyman keyboard language has two basic types of keyboard layout: positional and mnemonic. In this blog post, I describe the differences between these two types of keyboard layouts, along with notes on now to develop the two layout types. But first, for those who have trouble with the word mnemonic:

For this blog post, I’ll use Greek as an example keyboard layout, because the similarities between Greek and Latin letters are familiar to many, and will help in explaining the principles of mnemonic layouts. The same concepts apply to more dissimilar scripts such as Tamil, Lao or Korean.

Positional layouts

So what is a mnemonic layout? Well, I’m actually going to start by defining a positional layout. I think it is important to understand Keyman’s basic keyboard layout model, and the nuances of that model, before moving on to the more complex mnemonic layout model.

A positional layout, in Keyman terms, is a Keyman keyboard that defines its rules according to the position of keys on a physical keyboard. With a positional layout, Keyman does not care what is printed on the key cap of each key; it only cares where on the keyboard that key is. We sometimes call positional layouts “typewriter layouts”, in reference to the fixed layout of a typewriter.

Here is an example Keyman Greek positional keyboard layout running on various Windows base layouts:

Greek Positional on English (US) system layout

Greek Positional on English (UK) system layout

Greek Positional on French (France) system layout

Greek Positional on Swedish system layout

Greek Positional on Thai system layout

You’ll note that the Greek letters are essentially in the same place on each keyboard, apart from one exception. Now, what appears to be an exception is the backslash (on US) and the extra “102nd” key on European keyboards. The image below shows that the backslash () key cap actually changes to a pound (#) key cap on the UK keyboard, whereas the 102nd key on the UK keyboard has a backslash on its cap.

The answer is that the key identified by K_BKSLASH on the US English keyboard moves down one row and to the left of the Enter key. The 102nd key, despite having a backslash on its cap, is a new key cap with a different keycode of K_oE2. So while this initially may confuse, remembering this single exception is the key to joy with positional layouts! Actually, the backslash key moves around even on US English layouts – sometimes it is next to the backspace, sometimes below!

Programming a positional layout

Because Keyman’s original design was based on US English (as was Windows itself), the positional layout is defined in terms of a US English keyboard, using the names for the keys that logically match the US English keyboard layout, such as K_A, K_SLASH and K_COLON. These names should not be read as having a more literal meaning and could just as easily have been called C01, B10 or C10 (which would be their names in the ISO 9995 keyboard layout standard). However I think that Keyman’s key names, while less precise, are much easier to work with on a practical day-to-day basis! We call these ‘virtual keys’, due to their similarity to Windows’ Virtual Key codes. Don’t rely on them being identical to Windows Virtual Key codes, however, because they aren’t! A couple of examples may be warranted:

+ [K_A] > ‘key to right of caps lock, unshifted’
+ [SHIFT K_A] > ‘key to right of caps lock, shifted’
+ [CTRL ALT K_A] > ‘key to right of caps lock, with ctrl+alt’

The alternative method of defining keys in a Keyman keyboard is to use a single character. Internally, the Keyman keyboard compiler will translate these to the applicable virtual keys. With this model, extra shift states such as Ctrl or Alt cannot be accessed. For example:

+ ‘a’ > ‘key to right of caps lock, unshifted’
+ ‘A’ > ‘key to right of caps lock, shifted’

The Layout tab of the Keyboard Editor works only with Positional Layouts.

Mnemonic layouts

A mnemonic layout, unlike a positional layout, does not care what the physical keyboard is. Instead it reconfigures itself to map to the key caps of the selected Windows base keyboard (usually the same as the hardware keyboard). Taking our Greek keyboard above, and turning it into a mnemonic layout, gives us the following.

Greek Mnemonic on English (US) system layout

Greek Mnemonic on English (UK) system layout

Greek Mnemonic on French (France) system layout

Greek Mnemonic on Swedish system layout

Note how the Alpha α has moved from the 3rd row to the 2nd row on the French layout: that is, it is placed with the letter A on the French keyboard.

The key advantage of a mnemonic layout is that the keyboard developer can create a single keyboard layout that transparently maps onto almost any Latin script layout. Previously, keyboard layouts would need to be redesigned for each base layout that they were to be used with. This leads to a multiplicity of keyboard layouts to support and difficulty for the end user who may not be sure which base layout they use. There are at least 75 different Latin script keyboard layouts included with Windows 7!

A mnemonic layout also relies on the basic idea that the letters A-Z (and a-z), digits 0-9, and all punctuation available on a US English keyboard will somehow be available on any Latin script keyboard. This is true, as far as we are aware, for all Microsoft Latin script keyboard layouts. This means that the mnemonic layout does not translate across scripts, into Thai or Russian physical keyboards, for example. It would certainly be possible to design a mnemonic layout for a Cyrillic base script, which would then work across the various Cyrillic hardware layouts that are available.

Greek Mnemonic on Thai system layout

The example above may clarify the limitation of using a mnemonic layout with a base script keyboard for which it has not been designed. The reality is, however, that the vast majority of the world’s keyboards have access to the Latin alphabet via one method or other. For instance, with Thai, the US English key caps are also printed on nearly all Thai keyboards, so switching to a US English base keyboard is all that is needed to resolve this problem.

There are some additional complexities with mnemonic layouts and on screen keyboards. While Keyman does its best to translate a mnemonic layout for display in an on screen interface, deadkeys can make it difficult to display some aspects accurately across all hardware layouts. It can also be hard to find some of the more buried punctuation on some European layouts.

Planning a Mnemonic Layout

There are a few things it helps to be aware of when developing a mnemonic layout. First is to consider the frequency of access for various keys on the keyboard. For instance, many Greek keyboards use vertical bar (|) to access the iota subscript character <<IOTA SUBSCRIPT>>. The problem here is that vertical bar is not easy to access on many European layouts, being accessible only via AltGr+Shift combination on some layouts.

Next, some punctuation characters are available only via deadkeys in some European layouts. For example, ^ is only available via a deadkey at the top left of a German layout. This means to access this character (and hence the translation for the Keyman keyboard), the user must type ^ <space>, rather than just ^.

The following table provides some hints as to the best characters to use when designing your mnemonic layout. In general, the further down the table, the more likely you are to have usability issues with deadkeys or AltGr on some layouts. Thus use of these characters should be balanced with the frequency of use and their mnemonic utility.

A-Z a-z Alphabetic characters – always easily accessible
0-9 Numerals – always easily accessible
, . ; : / ! ? ( ) – = + Basic punctuation – usually easily accessible
@ # $ % & * _ | < > [ ] { } Additional punctuation – often on AltGr
` ‘ ” ~ ^ Deadkey punctuation – often deadkey-based

Programming a Mnemonic Layout

To tell Keyman that a keyboard layout is mnemonic, you must add the &mnemoniclayout system store:

store(&mnemoniclayout) ‘1’

Once you set this flag, Keyman will no longer use Virtual Keys codes. Instead it will use characters – the characters from the key caps. The Layout mode of the Keyboard Editor will no longer be accessible, and you will need to design your keyboard in Source Mode.

When coding your layout, remember that keys are no longer defined via shift states and key codes. Instead they are defined by the characters on the key caps. For alphabetic keys, the shifted and unshifted letters are not unified: in the unlikely event that ‘a’ and ‘A’ were on separate keys, Keyman could handle this situation.

For most rules, using the character-based rules is sufficient. However, it is still often useful to access extended characters with modifier keys. In most cases, we recommend overloading only the A-Z alphabetic keys with Ctrl+Alt, AltGr or similar modifiers, as many European layouts use AltGr (which Windows maps to Ctrl+Alt) to access additional punctuation. For the greatest compatibility do not use modifiers at all.

To use modifiers, the syntax is similar to the virtual key syntax for positional layouts. The key difference is how the key is identified: instead of using a virtual key code, you can use any of the characters that the key itself would produce. For example, the following rules would both match Ctrl+A:

+ [CTRL ‘a’] > ‘Ctrl A’
+ [CTRL ‘A’] > ‘Ctrl A’

It is important to recognise that the second example above does not match Ctrl+Shift+A. Again, by example:

+ [‘a’] > ‘key that produces an A’
+ [‘A’] > ‘key that produces an A, same as previous rule’

+ [SHIFT ‘a’] > ‘shift + key that produces an A’
+ [SHIFT ‘A’] > ‘shift + key that produces an A, same as previous rule’

The current release of Keyman Developer will warn you if you use the function keys or other non-character keys on your keyboard as virtual keys (e.g. K_F1). Non-character keys are those keys that do not normally produce a character and do not differ from language to language (except perhaps in the name on the key cap). Technically this should still work in Keyman Engine. A future update of Keyman Developer may allow you to use non-character keys on a mnemonic layout.

There are of course additional keys on some keyboards, such as Japanese or Brazilian keyboards. In most cases, it is best to avoid designing a Keyman keyboard that relies on these additional keys, as that restricts the usage of the keyboard to users from that region. The same rule applies to the 102nd key on European layouts, of course!

Software Developers Only

A little side note for Windows developers: Windows’ use of virtual key codes is inconsistent and confusing when it comes to European layouts. The names of the keys shift, logically, in many cases; for instance the VK_Q and VK_A swap places between US QWERTY and French AZERTY layouts. However, the defined virtual key codes for punctuation in many cases change unexpectedly; for example VK_COLON does not produce a ; on a French keyboard! For this reason, Keyman does not use virtual key codes for mapping mnemonic layouts but instead translates the layout based on the Windows keyboard definition itself.

The Future

We are working on the On Screen Keyboard in Keyman Desktop to improve support for mnemonic layouts and keyboard options. A future version of Keyman Engine may include support, via the keyboard options feature, for providing knowledge of the underlying layout to the keyboard layout. This would allow you to optimise access to Iota Subscript, for example, when it is harder to access on a specific system layout.

Categories: Developing Keyboards

2 thoughts on “Developing Mnemonic Layouts for Keyman Desktop”

Yonas Woldehaimanot · August 9, 2011 at 4:35 pm

Nice! That solved my issue!
TITLE: Keyman Desktop 8.0.332.0 Beta Release
BLOG NAME: Typing around the world
DATE: 09/05/2011 03:39:33 PM
Keyman Desktop 8.0.332.0 Beta release addresses two reported issues:

* Keyman Desktop 8.0 is not working with legacy applications that require WM_UNICHAR for Unicode input (regression from 7.1)
* If a non-Latin script keyboard or IME is the default…

Substituted layouts in Text Services Framework | Marc Durdin's Blog · May 9, 2018 at 2:06 pm

[…] we’ve got. So for Keyman Desktop 9, we wrote a mnemonic layout recompiler that recompiles a Keyman mnemonic layout keyboard, merging it with a given Windows system base layout, at keyboard installation time in Keyman […]

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Related Posts

Developing Keyboards

Introducing the Keyman Open Source Keyboard Repository

We have many hundreds of keyboard layouts online at that cover well over a thousand  languages. These keyboard layouts work on Windows, the web, iPhones, iPads and Android phones and tablets. However, most of Read more…


Using Keyman Engine for Android to create a system keyboard

In part 1 of this series, we looked at the steps involved in creating a basic Android app which included a Keyman in-app keyboard. In this post, we’ll work with the second sample included in Read more…