Mobile Keyboard tutorial

A page based on this tutorial has been added to the Keyman help system. Keyman help version.

On the Keyman Developer site, there is a series of tutorials on developing keyboards. In my opinion, what is missing is a tutorial on mobile keyboards that adds a few characters to a standard western keyboard. If you have some experience designing keyboards for desktops and laptops, the interface for designing mobile keyboards looks deceptively similar. But the additional steps needed to make a mobile layout work may not be obvious. This tutorial attempts to walk you through the process.

The Quick French tutorial shows how to create a simple desktop keyboard for typing accented characters used in French and other European languages. It is possible to create a touch screen format of that keyboard, but it is probably unnecessary. The default keyboards in both Android and iOS devices have a way to type these accented characters. Press and hold on a vowel (or some consonants), and a popup menu will give you a choice of accents to put on that letter.

For this tutorial we will demonstrate something usable for the Fulfulde language cluster spoken across many Sahelian countries of Africa. Fulfulde is usually written using the Latin alphabet, but there are a few characters added to the usual list of alphabetical characters. So this is a useful example for any language wanting to add a few characters to the standard Latin keyboard. Here are the characters we are going to add, together with their Unicode values.

ɓ   U+0253              Ɓ    U+0181
ɗ U+0257              Ɗ U+018A
ŋ U+014B              Ŋ U+014A
ƴ U+01B4              Ƴ U+01B3

Designing the layout

Here we will likely want to proceed differently than with the desktop keyboard. A common approach for a desktop keyboard is to create a deadkey. The keyboards I have used for Fulfulde (going back to decades ago) used the  slash key as the deadkey. /b gave ɓ, /d gave ɗ, and so on.

It would be possible to use deadkey logic on touch screens, but your mobile device users will find these rules annoying. Instead of two keys they would probably have to press four, since the standard alphabetical keyboard on most touch devices does not have the slash key. They would have to press the key to switch to the numeric keyboard, then press slash, then press the key to go back to the alphabetical keyboard, then the letter. What touch screen users would appreciate is something that uses the great feature of touch screens, the long press or press and hold on a letter, to see analogous letters. So we’ll set up a touch screen keyboard that lets you press and hold ‘d’ to see the two hooked d characters, press and hold ‘b’ to see the hooked b characters, and so on.

Creating a touchscreen keyboard

Setting up your Keyman Project

Be sure to follow the following naming conventions when setting up your project:

  1. Create a folder on your hard drive for your Keyman files
  2. In that folder, create a folder for this project, named after the language.  Use all lowercase letters for compatibility with other platforms.
  3. Now create a project in keyman developer with the same name as the new folder, and save the project inside the folder.

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.

Add touch to an existing keyboard or create a new keyboard?

You can add a touchscreen keyboard to an existing desktop keyboard, or you can create a new touchscreen keyboard from scratch. Because Keyman is targeting multiplatform keyboards, you should be aware that there will be cross-over between both mobile and desktop keyboards. Your mobile device can have an external keyboard, and in the same way, your laptop computer can have a keyboard on its touchscreen. So the Keyman strategy is to alwasy bundle touch keyboards with the typing keyboards to make them work on multiple platforms.

If creating a new keyboard, you click the New icon in the Keyman developer toolbar (or select File > New from the menu), and specify the file name for your keyboard. We recommend a name using only lowercase letters, numbers and underscore. I’ll choose “mobile_fulfulde.kmn’.


Adding the Required Metadata

After creating the file, Keyman developer will ask you to name the keyboard. This name can include spaces and upper case letters if desired. I’ll name this one “Fulfulde for Mobile”.


The first thing you need to do is to tell Keyman developer this keyboard will include some kind of mobile device.  You do this in the Targets list just below the keyboard name. I’ll select “mobile” in the list, (towards the end). You see in the picture above that Keyman developer checked the “windows” box by default, I can uncheck that or leave it checked if I am going to add a Windows keyboard to this set.  Image

This will include all mobile devices, both android and iOS, both phones and tablets. It is possible if needed to select android only or iOS only if needed, and to develop a different keyboard layout for tablets than for phones, but for this example, with only a few characters needed to be added to the default keyboards, there is no need for that kind of complexity.

(If you are adding a mobile layout to an existing keyboard file, you would open that file in Keyman Developer, go to the Targets box and check “mobile” or whatever mobile targets you wanted to specify, then follow along from here).

Adding the Touch-Optimized Feature

The next step is to add the touch-optimised feature to our keyboard setup. If you scroll to the bottom of the details tab, there is the list of features to add. I’ll click the Add button and choose “Touch-Optimised Keyboard.”


Choosing a Touch Layout Template

Keyman Developer asks me to choose one of three templates for the mobile layout.

But I’m going to make this keyboard simple, and just have one layout for both tablets and phones. So beside the platform box, I am going to click the “Del” box,  to delete the tablet layout. When there is only one mobile layout, Keyman developer will compile that layout for all mobile devices. (I could also have chosen to delete the phone layout and done my layout design in the tablet layout).

Adding Longpress Characters

Now I can start adding characters. I’ll click on the “y” key in the layout, then I’ll look for the “add longpress popup” button at the lower right. Image

I click that, and Keyman developer adds a new key below the keyboard layout.Image First,

Adding the Key Image

I need to put something in the keycap image for my new key. I’ll click inside the empty box of the new key, then I’ll go look for my y with hook character in the character map to the right. If I type “y hook” in the search box, Keyman Developer shows the character I’m looking for.Image

If I double click on the lower case y with hook, that adds the character to the keycap box of my new key. Image

Adding the Output

Now there is still one very important thing I need to do. If you have ever designed desktop keyboards in the layout view, you would think putting the character you want on the keycap is all you need to do. But mobile keys don’t work that way. (Technically there is a difference between a physical keyboard, where pressing a key sends a unique code to the computer, and a virtual keyboard, where tapping a key only registers a tap on an arbitrary part of the screen). In adding a mobile key, we have to enter what the key does, not just add a character to the keycap. To make our new key insert the Unicode character 01B4, I’ll go to the “code” box and change the string to “U_01B4”. (“U_” followed by a Unicode hex value is the code for “insert the character with this Unicode value”).


Now I also want to add the upper case hook y here, so my users won’t have to hold Shift before getting to an upper case y with hook. So I want to add another new key to this longpress popup row. I’ll click on the green triangle with a plus sign to the lower right of my new key, this adds a second new key.



(If I had clicked on the green triangle to the left of my first key, the new key would be added to the left of that key).For this new key, I go through the same steps. I click in the empty box on the new key, then double click the upper case y with hook in the character map to put that in the keycap. I also change the code of this new key to “U_01B3”


Another option for upper case characters

I might also add the upper case character to a longpress character on the upper-case Y key, because some users will press the Shift key then look for the letter to type. To do this, I change the layer at the top of the tablet layout to "shift" from "default".

SimpleTouchKeyboard 15b
Now I click the Y key, and add a longpress character, then add the upper case y with hook to the keycap and add the keycode as shown before. 

SimpleTouchKeyboard 16b

You can design your keyboard either way, with the upper case characters in the same longpress row as the lower case, or in a longpress row off of the shift layer. The rest of this tutorial shows the upper case characters in the same row, but I don't mean to present this as the best way. If you do put upper case characters in the shift layer, you'll have to remember to change the layer back to "default" when you want to add more lowercase letters, then back to "shift" when working on upper case letters. You could put the upper case characters in both places, if you think that best.


Now I’ll add the two d hook characters as a longpress popup for the d key. I click the d key in the layout, click “Add longpress popup”, add the lower case hook d to the keycap and change the code to “U_0257”; then click the plus sign to add a second key, add the upper case hook D to the keycap and change its code to “U_018A”. The end result should look like this:Image

I’ll do the similar step to add two characters as a longpress popup for “b”Image

And two characters as a longpress popup for “n”. (Tip, to search for ŋ in the character map, type “eng”). Image

How Longpress Keys are Shown

When no keys are selected in the keyboard layout, I can still see which ones I have set up longpress popups for, because Keyman developer shows a faint gray line at 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. (Keyboard > Compile Keyboard, or press F7). Hopefully you’ll see it compiled with no error messages:


Errors when Compiling?

You may 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 for the T_new_NNN codes are 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. If your default browser is not Chrome, you will need to pasted the URL into Chrome, since only Chrome can be used to test the mobile keyboard function. It should open with a Keyboard Test Host window with a visual keyboard. This keyboard is the web version--not the mobile keyboard simulator, as it doesn't handle longpress keys.


We need to tell Chrome to simulate a mobile device. First, we turn on Chrome’s web developer tools by pressing F12 or Ctrl-Shift-i. This should bring up a panel to the right.

Image Now at the top left of that right panel, click on the Toggle device button (the image looks like a phone outline with a tablet behind it).


Now the “Keyboard test host” panel should shrink in size, but you must click the curling arrow Image 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. Now click in the yellow box and the mobile keyboard layout should appear below. Your cursor now appears as 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.

and give the package settings file a name. I’ll use the same name as the keyboard.


Assigning the Language Code

One important bit of information to add to the package is the language code. You do this by going to the keyboard tab in the left column, then clicking “Add” below the language tag box.


A dialog comes up where you enter the BCP 47 tag for the language. The BCP 47 system is an international system of language tags, much like the Ethnologue system of three letter tags, except that some languages have only a two letter  tag. If you know the ethnologue code for your language, chances are that is the BCP 47 tag; or if it is not, the dialog box will correct your entry. For instance if I wanted to specify the Hausa language, I’d start entering the ethnologue code hau. Keyman Developer knows Hausa has a two letter tag, so it corrects my entry.


For my example, Fulfulde is not one single language but a language cluster. I need to be specific. I do an ethnologue.com search for Fulfulde, and it shows me several codes; fub, fuv, fuh, fuq. I’ll enter the first one of those, fub,


Tip: If your language has more than one script, it is important to include the script type.  Because Fulfulde has both Latin and Ajami scripts, I will indicate that this is the Latin script.


(as you can see, all I need is four letters for the script tag. “Lati” would work, “Latn” would also work.) I click OK and I should now have a language tag in my table.


Adding Additional Languages

I can add more than one language, so I’ll add in the other three as well. (There are actually more Fulfulde languages than these four, but some of them would also require additional characters).

Please note that in future versions we will be adding predictive typing which will be language specific.  In that case, the keyboard would not work for all of these, just the dialect the dictionary wordlist was created for.



Bulding the Package File

Now I am ready to build my package file. I will click Save again to save the information I have just entered, then I’ll click the Compile tab on the left, then click the Compile Package button.


Hopefully the package will compile without errors. 


Distributing a package file

The KPS package file can be installed by any version of Keyman 10, whether on Windows, Mac, Android or iOS. (Earlier Keyman versions for Android or iOS are pickier, you probably want to upgrade). Distributing it can be tricky, as I said earlier 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.

Contributors to this page: sewhite and dhigby .
Page last modified on Friday May 25, 2018 12:09:38 GMT-0000 by sewhite.


Creative Commons License
All content on this LingTranSoft wiki are by SIL International are licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.