[Home] [Purchase] [Download] [Manual] [Acknowledgements] [Sitemap] [Release Notes] [FAQ]

Up ] New ] Open ] Save ] Save As ] Delete keyboard layout ] Generate Layout Install Package ] Import KBE file ] Export KBE file ] Import KLC file ] [ Import Mac .keylayout file ] Register Layout DLL file ] Manage language bar list ] Restoring custom layouts lost during a Windows 10 upgrade ]

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.

KbdEdit import from Mac .bundle KbdEdit import from individual Mac .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.

Resources dir in an Ukelele DMG installation image

KbdEdit navigating to Ukelele keybouard bundles directory

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
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"/>

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?"/>

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

Copyright © KbdSoft 2007-2022