&displayMap store

---

Summary

The &displayMap store specifies a mapping file for on screen keyboard display data, used at compile time to transform text on the key caps to an alternate encoding.

Syntax

store(&displayMap) 'KbdXxxx.json'

Description

The &displayMap store specifies a mapping file, relative to the keyboard source file, which provides data for remapping the touch layout and visual keyboard key caps. This file has no impact on output from the keyboard; it is used only for on screen keycap presentation.

The primary purpose of this file is to provide a pathway for consistent display of diacritics and other unattached marks which may be displayed on either type of on screen keyboard, by use of a special font with formatted glyphs in the Private Use Area. This makes it possible to guarantee consistent display across all platforms, as rendering of unattached marks is somewhat platform-specific and font-specific.

This file can be generated by kmc analyze osk-char-use command, or hand crafted. The compiler uses only the str and pua values in the file, although there may be additional data in the file provided for reference purposes. The file should have the following structure (in this example, mapping the Unicode values U+17BB U+17C7 (ុះ) to the Private Use Area code U+F19F):

{
  "map": [
    {
      "pua": "F19F",
      "str": "ុះ"
    },
    ...
  ]
}

• The pua field must be a single hex value, by convention in the PUA range starting at U+F100.
• The str field contains the codepoints that will be mapped to the PUA code; if U+25CC (◌, dotted circle) is specified on a key cap, it will be stripped before matching in the &displayMap, so U+25CC should not be included in str.
• Other fields are documented in the schema reference for displayMap in the Keyman source.

&displayMap fonts and files are intended to be shared across multiple keyboards that work with the same script. kmc analyze osk-char-use can scan multiple keyboards at once when generating the file.

An unsupported tool, ttkbdfont.py, can be used to generate a Kbd font. The font may need some manual editing as insertion of dotted circle (U+25CC) as a base may not always be possible automatically, and combined marks may not render as a cluster in some scenarios. The open source tool FontForge is suitable for making these kinds of minor adjustments to the generated font.

Using &displayMap means that the design-time model for the On Screen Keyboard and Touch Layout can continue to use the correct Unicode values on the keycaps, making the transformation to PUA characters only in the compilation process.

Font selection

• The Kbd font associated with the &displayMap should be added to the keyboard's package and selected in the package 'Keyboard Font' field (OSKFont property in the .kps XML source).
• There is no need to add the font also to the list in the Keyboard Font / Web Fonts dialog box (WebOSKFonts property in the .kps XML source).
• The .kvks file and .keyman-touch-layout file can also reference fonts. These fonts are used only at design time, so they should be any font that supports the script, and should not be the &displayMap Kbd font, because the transform to use the &displayMap Kbd font is done during the compilation of the keyboard and package.

Standard conventions for use of displayMaps

In the Keyman keyboards repository, the PUA range used should start at U+F100.

&displayMap JSON files should be named Kbd<script>.json where <script> is a 4 letter script subtag, for example KbdKhmr.json, and the corresponding font is named KbdKhmr.ttf (with face name KbdKhmr). These fonts are intended only for use in visual keyboards and touch layouts and generally will not be suitable for any other use. An optional suffix to a font may be included, if appropriate, for example, KbdArab-Nastaliq.ttf (face name KbdArab-Nastaliq).

Example

store(&displayMap) '../../../common/fonts/kbd/KbdKhmr.json'

Platforms

The &displayMap store is used only in the compile process and the results are applicable on all platforms.

Windows	macOS	Linux	Desktop web	Mobile web	iOS	Android
✔	✔	✔	✔	✔	✔	✔

Version history

• Version 17.0: This functionality was added to Keyman Developer 17.0. The compiled keyboards can be used with earlier versions of Keyman; it is not necessary to target version 17 or later (via store(&version)) in the keyboard .kmn source file in order to make use of &displayMap in the keyboard.

See Also

• &visualKeyboard store
• &layoutFile store
• More background on the need for &displayMap can be found in issue #9031.