&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 atU+F100
. - The
str
field contains the codepoints that will be mapped to the PUA code; ifU+25CC
(◌, dotted circle) is specified on a key cap, it will be stripped before matching in the&displayMap
, soU+25CC
should not be included instr
. - 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.
The Kbd font associated with the &displayMap
should be added to the keyboard's
package and selected in the package 'Keyboard Font' field.
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 |
---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
See Also
&visualKeyboard
store&layoutFile
store- More background on the need for
&displayMap
can be found in issue #9031.
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.