Keyman Developer 12

If you have some experience designing typing keyboards for computers, the interface for designing touch keyboards looks deceptively similar. But the additional steps needed to make a touch layout work are not obvious. This tutorial walks you through the process of creating your first touch keyboard as part of a complete keyboard solution in Keyman Developer.

You will need to have Keyman Desktop and Keyman Developer installed on a Windows computer. Additionally, you may want one or more other devices on which you can test your keyboard.

For this exercise we will use the Fulfulde language cluster spoken across many Sahelian countries of Africa. Fulfulde is usually written using the Latin alphabet, but there are a few additional characters that must be added. They are as follows, together with their Unicode values.

Important differences about touch keyboards

In this tutorial, we distinguish between touch keyboards, which are pressed by fingers on a screen, and typing keyboards which involve tapping real keyboard keys.

Touch keyboard layouts must be treated differently than typing keyboards because they are primarily visual keyboards. Typing keyboards are usually learned by the feel of the keys and the use of muscle memory (where a repeated action becomes automatic), which is why sequences of keys are often used to produce a single character. In addition, for many typing keyboards, the user is expected to memorize a series of keystrokes to produce a desired character. For example, when laying out a typing keyboard you might use the following sequence to produce the letter ɓ:

; + b = ɓ

(that is, typing ";" followed by "b" produces "ɓ"). Users must have a typing guide of some sort to remind them, but this combination is quickly learned. The combination might use a deadkey, where the semicolon (the deadkey) produces no visual output on the screen, but typing "b" produces "ɓ". Or the keyboard might display the semicolon when it is typed, then replace it with "ɓ" when "b" is pressed. Typists will master this quickly and throw away the guide. Experienced typists won't need to look at the hardware keys when they type.

On a touch keyboard, however, there is an understanding that WYTIWYG (What you touch is what you get). That means that the letter ɓ ought to be visible somewhere on the keyboard. We’ll look at the options that we have for touch keyboards later in this document.

Plan beyond the touchscreen

You may think that you only want to create a touch keyboard layout and don’t want to bother with setting up a typing keyboard layout. However, the distinction between a computer and a mobile device is becoming less and less all the time. Often a tablet will be paired with a bluetooth keyboard to enable the user to type faster. The minute this happens, your keyboard will not work as expected. Long press features don’t work on the attached keyboard. That is why when you create a keyboard package in Keyman Developer it is always assumed that you will be producing both and bundling them together.

Creating a Keyman Project

In Keyman Developer, create a new basic project. Select New Project from the Project menu and then choose Basic

This will start a wizard that will walk you through the setup process. Your keyboard will eventually be uploaded to Github to allow easy discovery of your keyboard in the Keyman app. For this reason, the wizard helps you follow the naming structure and language identification that will be required for doing so.

You are asked to name the keyboard and fill out other information.

The Keyboard Name field is designed for a human-readable name for the keyboard, so you can use capital letters here. The Keyboard ID has more restrictions (only underscore and lowercase letters allowed). This name will be used for the project folder, the project file (.kpj) and a number of other files (.kmn, .kps, etc.) in the project. The wizard will try to create a Keyboard ID based on the Keyboard Name that you enter, but you can change it when you select the path. (If you plan to submit your keyboard to the Keyman keyboards repository on Github, the Keyboard ID can't be the same as any exisiting keyboard.)

For the Copyright field you'll need to enter a year (or a range of years, going from the first year the keyboard was published to the present) as well as the name of a person or a legally recognized entity. 

For the target, "any" is selected by default. This is equivalent to checking all the other boxes. We will keep this, since our goal is for this keyboard to work on all platforms.

The wizard will create a folder with the name of the Keyboard ID, and place files in that new folder. By default, the new folder will be in the C:\Users\USER\Documents folder, but you can choose a different path where your keyboard project will be stored.

Adding Language Tags

Click Add… and a dialog comes up where you enter the BCP 47 tag for the language and script. The BCP 47 system uses the two or three letter tag of the Ethnologue code and includes more detail about the script or region if necessary. In this example, Fulfulde is not a single language but a language cluster, but they all share the same special characters. Their language tags are fub, fuv, fuh, fuq, and ffm. Each must be added separately.

After adding all the target languages for the keyboard, we are finished with the project setup and can click OK.

Now you will be able to use this project to organize and create any files for desktop, mobile, web, or other. It also facilitates uploading the files to the Keyman website later on.

Editing the keyboard

On the keyboard tab of your new project page, Keyman has already created a fulfulde.kmn file for you. Click on it to open the file for editing.

The editor page should look like this:

Two features were added by default: the desktop on screen keyboard, and the touch-optimised keyboard. These show up as additional tabs on the left.  If you don't see a tab for On Screen and Touch Layout on the left, then you will need to click the Add button above and add them one at a time.

If you want to add a small icon to identify the keyboard, Keyman will use it in place of its generic icon. Click on the "Add..." button and then select "Icon". Keyman Developer includes a way to edit the icon, or you can edit the icon with another program. For this tutorial we will use the generic icon.

Layout (for typing keyboard)

We want to include a typing keyboard and since this tutorial is focusing on touch, we will simply include the code to paste in with minimal explanation.

On the bottom of the Layout tab, there is a Code tab. This is where the code may be inserted. We will use the semicolon as a context to create 8 of special characters needed, and the sequence j + n to make ɲ. You can see how that works visually by gluing the j and n together. We can do this because n never follows a j. Here are two possible ways to write the code:

Simple

begin Unicode > use(main)

 

group(main) using keys

";" + "b" > "ɓ"

";" + "d" > "ɗ"

";" + "n" > "ŋ"

";" + "y" > "ƴ"

";" + "B" > "Ɓ"

";" + "D" > "Ɗ"

";" + "N" > "Ŋ"

";" + "Y" > "Ƴ"

"j" + "n" > "ɲ"

"j" + "N" > "Ɲ"

 

Advanced (using only three rules)

begin Unicode > use(main)

 

store(basekey) "bdnyBDNY"

store(output_char) "ɓɗŋƴƁƊŊƳ"

 

group(main) using keys

";" + any(basekey) > index(output_char,2)

"j" + "n" > "ɲ"

"j" + "N" > "Ɲ"

Paste the code you prefer into the code editor

On-Screen

The next tab down on the left is for the on screen keyboard. There is nothing interesting about this keyboard because you can’t show the way the semicolon is used to produce characters. So we will simply copy the layout of the underlying keyboard.

You may get a dialog box that says: "Debug Host Keyboard file debughost.kmx must be installed to enable debugging. Install it now?" This debugging feature (which is not covered in this tutorial) is also used to read the keyboard and fill the on-screen layout, so we should install it. Click OK and allow the installer to continue. There should eventually be a dialog indicating that it was installed successfully and then the on-screen keyboard layout will be completed.

Touch layout

At the top of the touch layout area, you can select "phone" or "tablet". These are represented by iPhone and iPad graphical representations, but they will work on Android as well. You can select vertical or horizontal mode as well.

You have the flexibility to have a different number of rows or columns of keys on the tablet and phone layouts, and so Keyman keeps them separate. If you want the exact same key structure on both, then delete one of the two (either "phone" or "tablet") and complete the other. It is a lot of extra work to maintain two identical layouts. Keyman will automatically use "tablet" if "phone" is not present or "phone" if "tablet" is not present. Only if you want to make the "tablet" and "phone" layouts different, would you want to have both.

On the touch layout tab, we can start handling the additional characters. Remembering that all special characters on a touch keyboard must be visible somewhere, there are at least four options to add them to an existing keyboard. In the case of adding a hooked b to a latin keyboard you could:

Let’s look at each of these more closely to decide.

Swap with unused characters

In Fulfulde, the v, z, x letters are not used. So it may seem like a good idea to swap unused letter for the ones they use. However, in our global information age we must include access to a v even if it is not used frequently. The minute the user tries to pull up Vimeo to watch a video, they will be prevented from typing the URL! But since the v would be used quite infrequently, it would be possible to make the v available on the long-press popup for ɓ.

To swap v for ɓ, open the Keyman character map, and then drag the hooked b to the key.

NB: When dragging from the character map, you can get the character, the code or the name. Right-click on the character, select "Insert Mode" from the menu, and pick one of the choices: "Code" (U+0253), "Character" (ɓ) or "Name" ($LATIN_SMALL_LETTER_B_WITH_HOOK).

After the letter appears on the key, hit enter to save it.

All this does is change the character displayed on the key. You’ll notice that the output is listed in the bottom right corner of the key: K_V which is the virtual key name for V. Note that keys on the touch layout with K_ names will use the behavior of the corresponding key in the .kmn file.

To change the output of the key, we need to look at the options below the keyboard when the key is selected:

In the code box, we can replace the K_V and reference the Unicode key value: U_0253. Note that it uses the underscore and not the plus symbol. Now, pressing that key would produce the hooked b. Remembering what we said about the danger of making the letter v inaccessible, we would need to add the v back as a long-press key. If you decide this is the best approach, long-press keys are covered next.

Longpress keys

The other approach in this scenario would be to place the hooked variants on longpress popup keys, such that a long press on b would offer the hooked b.

To do this, you would select the "b" key, and press the "Add longpress popup" button below. This opens another row of options below, starting with a new button. You can drag and drop the hooked b to that button and hit Enter.

You’ll notice that the default code output by longpress keys is an automatically generated T variable. That is because Keyman doesn’t try to guess what you are adding here—there are no defined longpress popup keys for your underlying keyboard. You can output the unicode value directly instead: U_0253.

If you wanted to add more longpress keys to this popup, you would click on the green triangle to the left or right to create a new programmable key on either side. To see what this looks like, click on the period key which has 8 more punctuation keys that pop up.

Additional layers

Touch keyboards have different layers. The most obvious is produced by the shift key, which when pressed, changes the characters produced by all the keys. But mobile keyboards also tend to have a number key layer. Some have a layer of symbols too. If you want, Keyman will allow you to create your own custom layer which can be produced by pressing a designated key of your choice. We won’t take the time to do that now, but we will show you how to work in another layer.

The hooked b also has an uppercase version. This needs to be added after you switch the keyboard to the shift layer. At the top of the window is the Layer selector:

Once the shift layer is selected, you can now edit the shifted keys, and may add a longpress popup key to the uppercase B like shown here:

The Next Layer select box tells the keyboard whether you want to change layers after pressing the key. By default, it is set to (none). If you leave it set to (none), when you type the capital hooked B the keyboard will remain on the shift layer and the next letter typed will also be a capital.

On most phones using Roman scripts, when you press shift and type a letter, the shift state then goes back to lowercase. If you want to have similar functionality on your keyboard, you need to set the Next Layer field to "default" (that is, the lowercase layer) for all the keys on the shift layer. 

Squeeze in another key

If you are designing a tablet-sized keyboard, you can squeeze extra characters in. On a phone-sized keyboard, you could also do this, but then increase the chance of users missing the keys because they are so small. Using the green triangles next to any selected key, you can add extra characters. This is what our keyboard would look like if we just added extra keys for 3 of our 5 special characters:

It just so happens that adding the hooked y, d, and b to each row was consistent. To add the ŋ and the ɲ, we can place them on a longpress n.

How Longpress Keys are Shown

Even when no keys are selected in the keyboard layout, I can still see which ones have longpress popups, because Keyman Developer shows a faint gray line across the top right corner of the key. So you should have a faint diagonal line on your y, d, b, and n keys.

Compiling your Keyboard

Now click Save to save your work, and compile the keyboard, using one of the following methods:

Hopefully you’ll see it compiled with no error messages:

Errors when Compiling?

You might see a warning like:

Warning: line 0  warning 2092: Key "T_new_579" on layer "default", platform "phone", is a custom key but has no corresponding rule in the source.

This shows you forgot to enter the correct keycode for a new key you added. Double-check your longpress popup keys for one with a “T_new_NNN” code (T_new_579 in this example), and add in the desired “U_NNNN” code.

The purpose of the T_new_NNN codes is so that you can write rules for these keys in the same way you do for physical keys.  If you add these key references (which you can customize to anything, like T_Hook_Y_UC) to the code, then you can make rules for them alongside your physical keyboard rules in the kmn coding section. 

You might also see a message like

Error: line 0 error 405A: Key "U+0181" on "phone", layer "default" has an invalid identifier.

This shows you attempted to change the keycode but mistyped the code. I’ve gotten this more than once because I am used to typing U+0181 to refer to a Unicode value, but the correct syntax for a keycode in Keyman Developer is U_0181.

Testing your keyboard

See also the Keyman help page on testing keyboards

The “Test Keyboard” command under the “Keyboard” menu only tests the desktop versions of a keyboard, not the mobile versions. To test a mobile keyboard, you can use the Chrome browser on your Windows computer to simulate a mobile device.

The Build Tab

To do this, go to the Build tab (bottom one in the left column) and in the “Web and Mobile targets” box, click “Test keyboard on web”. Now click  “Open debugger in local browser.”

Testing in Chrome

Your default browser will open with the keyboard.

1. The default web keyboard is displayed

It opens with a Keyboard Test Host window showing a visual keyboard. Don't worry, this is not your touch keyboard, but the web version of your desktop keyboard.

2. Open Chrome's web developer tools

Chrome can simulate a mobile device. Press F12 or Ctrl-Shift-i to open the web developer tools, and a panel will open on the right.

3. Open the Mobile Toolbar

4. Select your test device

As shown above, click on the Toggle device button.  You will get a device selection bar at the top of the screen like this:

Now the “Keyboard test host” panel should shrink in size

5. Refresh the page

You must click the curling arrow  (or press the F5 key) to reload the page in Chrome before you see the mobile keyboard layout. When you see a button saying “Install Keyman for Android” (or “Install Keyman for iOS”), you have gotten to the right setup.

6. Click in the yellow box

Now the mobile keyboard layout should appear below. Your cursor has changed to a gray circle representing the size of a fingertip on a mobile keyboard. You should be able to test the keyboard now. Click on any key to make a simple press of that key, click and hold to make a longpress on a key. (If you're using a touch pad rather than an actual mouse, tap the pad for a simple press and double tap and hold for longpress.)

 

Additional Files

The Keyman Developer "New Project" wizard created several other files for you. These are documentation files designed to help people effectively use this keyboard on a computer with a hardware keyboard. During your testing phase, you don't necessarily need to complete these documentation files, but it is a good idea to complete this user documentation before releasing your keyboard. You will definitely need to complete these files before the keyboard can be submitted to the Keyman keyboards repository.

Another requirement for submission to the Keyman keyboards repository is a "help" subfolder (under the "source" folder) to provide the online help that Keyman provides for web use of the keyboard. 

This tutorial won't be covering these documentation files.

Building the Package File

The new project wizard constructed a "Keyman Package Source" (.kps) file for you. In Keyman Developer, click on the .kpj file (just below the menu and toolbar), then click on the "Packaging" tab along the bottom of the screen, then on the .kps file that is displayed. Review the information in each section (Files, Keyboards, etc).

In the "Files" section, make sure that the .kmx, .js, and .kvk files are referenced from the build folder.

In the "Keyboards" section, verify the BCP 47 code (language tag). 

In the "Details" section, verify the fields listed. (It is possible to include a 140x250 pixel image that is displayed when the keyboard is installed. This file needs to be added to the list in the "Files" section, then referenced as the image file in this section.)

You can skip the "Shortcuts" and "Source" sections. 

In the "Compile" section, after saving any changes made above, click on the "Compile Package" button.

Distributing a package file

When you finalize your keyboard, you should consider making it available in the Keyman keyboards repository, so that anyone with an Internet connection can download the package.

Distributing the keyboard package (.kmp file) via local network

For testing, you can share the .kmp file from Keyman Developer over a network. In the "Compile" section of the "Packaging" tab (mentioned in the last section) you can click on the "Test Package Online" button. You'll get a list of URLs which you can use to get the package from Keyman Developer. Some of these (127.0.0.1:8008, localhost:8008) are only valid on the machine running Keyman Developer, but others (often starting with 192.168 or whatever your local network uses) are valid for testing by any devices on the local network.

Another device (an Android phone, for example) connected to the same network can use that address (including the ":8008" on the end) to get a copy of the .kmp package. When you enter that address in a browser on the device, you are given several choices:

You can use the first choice to install Keyman on your device (assuming you have Internet access). The second choice will install the keyboard that Keyman Developer is serving into Keyman on your device. The third choice brings up a page similar to the following:

Clicking on the link will download the package that Keyman Developer is serving and then install it into Keyman on the device.

Distributing the keyboard package (.kmp file) manually

The Keyman package (.kmp) file can be installed by Keyman (version 10 or later) on any platform, whether on Windows, Mac, Linux, Android or iOS. (Earlier Keyman versions for Android or iOS are pickier, you probably want to upgrade.) Distributing the package can be tricky, since it is a zip type file containing javascript, which is suspect to many email servers. But it can be shared by uploading it to a Google drive, then sending links to the file.

On mobile devices, you may still see the device saying the file type is unrecognized. But if you look for other options you should find a way to install it to Keyman. For example, in iOS, you can click on the three dots at right, then choose “Open in”

 

Then it should give you the option to Copy to Keyman (assuming you have installed the Keyman app).

 

Then you should be able to tap “install” in Keyman to install the keyboard.