Import Mac .keylayout file
The "Import Mac keylayout file" command is accessed through the File | Import
Mac keylayout
file... menu item, or through the button
(Import Mac keylayout file) on the main toolbar.
The command imports Apple Mac OS keyboard layouts, both the standard ones shipped with Mac OS,
and the custom layouts
created with Mac tools like Ukelele.
(If you are interested in learning more about the .keylayout format,
this overview from Github user
lancejpollard is a good
starting point; a
detailed specification is available in
Apple's technical documentation.)
Choosing the keylayout file to import
Mac layouts can be imported from either a Mac
bundle or an individual .keylayout file.
- The Bundle mode imports a layout from a Mac bundle
directory containing multiple layouts; in Ukelele, a layout bundle is created via
the New Keyboard Layout Collection command.
The "..." button is used to select a bundle directory, which
is denoted by the .bundle suffix.
Once a bundle is chosen, the
Choose a layout from the bundle: list will be populated with all layouts
found in it.
- In the Individual .keylayout file mode, the "..." button
chooses a "naked" .keylayout file (the kind that's created via
New Keyboard Layout in Ukelele).
A bundle is merely a collection of .keylayout files under a predefined directory
structure, accompanied by some additional metadata, so technically even bundled
layouts can be imported as individual .keylayout files. This is not recommended
though - bundled layouts should be imported via the "bundle" route, as this
allows KbdEdit to make a better guess with regards to layout metadata like the
intended language.
How to import a standard Mac layout
If you are merely interested in using a standard Mac layout under
Windows, you have to get creative, as MacOS does not
include .keylayout versions of standard keyboards. The easiest way
around this is to borrow layout bundles from an Ukelele installation package:
- On a Mac computer, download the latest Ukelele DMG image
from
Ukelele download page.
- Mount the DMG file as if you were going to install it (there is
no need to actually install the application!)
- You will notice that, in addition to the Ukelele application, the
mounted image also contains a few files and directories (Read Me.rtf,
Resources, Documentation).
The Resources directory is the important one - this is where
the .keylayout bundles are stored.
- Copy the Resources directory from DMG to the Windows
computer where KbdEdit is installed, e.g. via a USB flash drive or a
network share.
- On the Windows computer, start KbdEdit, choose the Import
Mac .keylayout file command, choose the Bundle mode, then
navigate to the Standard Keyboards subdirectory under
Resources.
- Standard Mac layouts are grouped under several
.bundle subdirectories - Central European.bundle, Cyrillic.bundle,
Roman.bundle etc.
E.g. the standard
U.S. layout is located under Roman.bundle.
Choosing the layout Id to import
Some keylayout files implement multiple layouts in
a single file – usually a base layout, and one or more variations of it. The variation to import is chosen in the
Import layout Id
dropdown.
E.g. the standard U.S. Mac layout from Roman.bundle
includes layout Ids 16c and 994. The layouts are mostly
identical, with the
latter having a slightly changed placement of "[", "]" and few
other keys.
Choosing the Caps Lock conversion mode
The Map Apple Caps Lock to dropdown
has two options:
- Caps Lock – a best effort is made to map the Mac
Caps Lock combinations to the Windows
Caps Lock, while using non-togglable
Kana
as a fallback.
This is generally a "lossy" conversion, due to Windows
Caps Lock
limitations ("separate caps" mappings only supporting Base and Shift+Base positions, and
lack of support for ligatures
and
dead
keys).
Any combinations that cannot be perfectly mapped to the Windows Caps Lock
are also mapped to an additional combination where Kana is acting as
a surrogate Caps Lock.
E.g. many Mac layouts have Caps Lock + Option positions – these will
appear as AltGR + Kana on the Windows side, because "separate
caps" mappings are not available for AltGR positions.
If a base+Caps or Shfit+Caps Mac position has a ligature
mapped to it, the ligature will be
truncated to the first character in the imported Windows Caps mapping.
A Mac dead character on a Caps position will be mapped to the same character, but in
its "non-dead" version.
In these two cases, the entire position is also
duplicated as a lossless Kana / Shift+Kana, where the ligature/dead
mappings are preserved.
- Togglable Kana – Windows Caps Lock is not used at all,
and is fully replaced by the lossless
"togglable" Kana.
This perfectly preserves all Mac Caps
Lock mappings, but at the cost of using the non-standard Kana
modifier, which can have side-effects like the Caps Lock light not
reflecting the Kana state, and potentially reduced compatibility in
some apps.
Choosing the physical keyboard type
The Physical keyboard type lets you choose between US and ISO. This only affects
the placement of `~ and §± keys.
The JIS (Japanese) keyboard type is currently not
supported.
Conversion of dead keys
Mac dead key tables (the
<actions> element) are supported within
confines of
the Windows dead key model:
- Dead key chaining is fully supported
- Dead keys producing ligatures is not
supported, as Windows dead keys
only support
single UTF16 code points.
Any ligatures encountered in the Mac dead key table are silently
truncated to their first character.
A heuristic is applied for the common case of two-character ligatures of
non-breaking space (00a0) followed by a combining diacritic (e.g.
combining double grave accent (030f)). In this case, the
non-breaking space is discarded, and the combining diacritic character is
preserved.
- By extension, non-BMP (>0xFFFF) Unicode code
points are not supported either, as on Windows they’re
internally
represented as two-character ligatures of UTF16 surrogate pairs.
- The
<terminators> Mac element is not supported - in the Windows dead
key model, it is not possible to specify a default "to" character to produce
when an undefined "from" character is entered.
Conversion of Mac modifiers
The import tries hard to preserve all modifier
positions found in the original Mac layout, within the Windows
limitation of
max 15 modifier positions supported.
The automatically chosen key combinations may not always be the most
intuitive. For optimal results, some manual tweaking of imported
modifiers may be required, through rearranging of
active modifier combinations followed by
moving
high-level mappings between modifier positions).
A best effort is made to map each Mac modifier key to the most sensible equivalent on the
Windows side:
|
Mac modifier key |
"Best effort" Windows modifier |
| Shift |
Shift |
| Caps Lock |
Caps Lock with non-togglable Kana as a fallback
or
togglable Kana |
| Option |
AltGR |
| Cmd |
Roya |
It would be more intuitive if Mac Cmd key could be represented by the
Windows "Win" key, but unfortunately this
key is not available as a general-purpose modifier, so the exotic "Roya"
modifier is used instead.
Modifier conversion from Mac to Windows is far from straightforward, due to the
much higher flexibility of Mac’s modifier specification:
- A single Mac modifier position (mapIndex within a
<keyMapSelect> element) can generally contain multiple
<modifier> elements i.e. combinations.
- A modifier key specification can include the ? wildcard (e.g. command?), indicating that the position is
not affected by the said modifier key, i.e. the position is selected
whether the key is pressed or not.
- Mac keyboards can distinguish between left/right versions of
some modifiers, or can treat both the same. E.g. Shift is available
as either leftShift, rightShift or anyShift.
In Windows, distinguishing between left/right Shift is not
possible, i.e. only the equivalent of anyShift is supported.
Instead of trying to fully replicate all unique modifier key combinations
for a Mac position, Windows import tries to select the
most representative combination, and ignores the rest. Without this restriction, the
"max 15 modifier positions" limit would be quickly exhausted even for the simplest Mac
layouts.
Where an obvious equivalent key combination cannot be found, or is already
taken, the import defaults to the next unused combination.
As an example, in the standard U.S. Mac keyboard, the
mapIndex="0" position consists of two combinations:
<keyMapSelect mapIndex="0">
<modifier keys="command?"/>
<modifier keys="anyShift? caps? command"/>
</keyMapSelect>
Expanding the ? wildcards yields 5 unique combinations:
- <BASE>
- Cmd
- Cmd (Caps on)
- Shift+Cmd
- Shift+Cmd (Caps on)
In the Windows import, only <BASE> is retained as the
most representative, and the 4 combinations involving Cmd are ignored.
In the same U.S. Mac keyboard, the mapIndex="4" position
includes only one entry:
<keyMapSelect mapIndex="4">
<modifier keys="anyShift caps? anyOption command?"/>
</keyMapSelect>
Which expands to 4 unique combinations:
- Shift+Option
- Shift+Option (Caps on)
- Shift+Option+Cmd
- Shift+Option+Cmd (Caps on)
On the Windows side, these combinations are represented by a single
Shift +
AltrGr position. Manual index |
