Export Mac .keylayout file

Feature available only in Premium and Personal editions (not available in Lite and Player editions).

The "Export Mac keylayout file" command is accessed through the File | Export Mac keylayout file... menu item, or through the button (Export Mac keylayout file) on the main toolbar. It exports the current layout in the Mac keylayout format, which allows them to be installed and used on all current versions of Apple Mac OS.

(Note that KbdEdit can also import Mac layouts via the Import Mac .keylayout file command).

Choosing the command opens up the standard "Save As" dialog, where a full path to the saved file can be chosen:

KbdEdit dialog Export keyboard layout to Apple Mac keylayout file

Installing exported layouts on a Mac

Installing the keylayout files on a Mac requires a few manual steps.

Each file you want to use under Mac has to be copied to the ~/Library/Keyboard Layouts/ subdirectory under current user's home directory (represented by tilde ~):

KbdEdit-generated keylayout file in Apple Mac Keyboard Layouts directory

This subdirectory does not exist by default, and will most likely have to be created first. Keep in mind that capitalisation matters under Mac - ~/Library/Keyboard Layouts/ and ~/Library/keyboard layouts/ are two distinct directories, and only the former is correct.

Installing keylayout files in this subdirectory makes them available only to the current user. To make them available system-wide (to all users), they have to be copied to system directory /Library/Keyboard Layouts/.

For the new layouts to be picked up, it is necessary to log out and log back in. The new layouts will appear under the Others language in Keyboard Settings UI:

KbdEdit-generated custom keyboard layout in Apple Mac Keyboard settings UI

Click Add for the desired layouts, and they will appear in the keyboard switcher UI:

KbdEdit-generated custom keyboard layout in Apple Mac Keyboard Layout selection menu

Limitations of Windows-to-Mac conversion

Under the hood, Windows and Mac keyboard layout file formats are quite different, with each supporting unique functionality not found in the other. This means that conversion can be a lossy process, in which some of the features of the original Windows layout are not fully (or at all) replicated on the Mac side.

What is preserved

These functions are fully preserved:

Both single-character and ligature Unicode mappings
Non-BMP characters (codepoints above U+FFFF)
All Caps Lock effects - both in the same as Shift and separate mapping modes, as well as the effect of Caps Lock on AltGr via the CAPLOKALTGR flag.
Dead key transformations, both straight and chained.

Note however that, on the Mac side, only dead transformations that are accessible through current key mappings are retained in the layout. This differs from the Windows format, where dead transformations are kept in the dead table even if they are not mapped to any keys! In practice this means that you may notice a loss of some dead transformations if you export a layout to the keylayout format, and import the same layout back with Import Mac .keylayout file.

Modifiers

Only Shift, AltGR and Ctrl modifier keys are supported reliably. On the Mac side, they are mapped to the Shift, Opt and Ctrl keys respectively (be aware of limitations of Ctrl as a general-purpose modifier key).

If a Windows layout uses the Kana key, either togglable or non-togglable, it will be represented by the Cmd key on the Mac side, but this is unlikely to work as intended, as Cmd is usually reserved for UI shortcuts under Mac.

Windows modifier keys Roya and Loya are not supported.

Each Windows modifier position is accessible via only one modifier combination on the Mac side. This differs from the Mac approach, whereby each modifier position is typically accessible through several different combinations.

Low-level customisations

Most Low-level editor customisations are not supported on the Mac side:

If you change the position of a special key such as an arrow, modifier or function key, these customisations will not be replicated.
Assigning any non-standard function to a character-producing key will make the key completely ineffective under Mac.
On character-producing keys, only the final Unicode mappings matter, and they are determined by the position of the physical key, as Mac does not have the concept of virtual key codes.
It is not possible to distinguish between the left and right Opt key - Mac doesn't have the concept of the AltGr key.
Special NLS functions are not supported.

Maximising Windows / Mac interoperability

Here are a few practical tips to ensure your custom layout remains usable on a Mac:

Limit the layout to essential modifier keys, i.e. to Shift and AltGr only, which faithfully translate to Shift and Opt on Mac.
You can also freely use all CapsLock functions.
Avoid the Ctrl and Kana modifiers.
Even though, in theory, they translate to Ctrl and Cmd on Mac, they are inappropriate as general-purpose modifier combinations.
Don't use the Roya and Loya modifiers at all.
Use chained dead keys to make up for the shortage of modifier positions (few examples: example 1, example 2).
Choose descriptive dead char names. They are used as a base for state names in the generated mac layout, and human-friendly state names make the dead key table much easier to follow understand.
Avoid most low-level modifications, or at least make them in a way that the layout remains useful in their absence.
(on the Mac side, you can achieve the equivalent of some low-level modifications via third-party tools like Karabiner.)

Manual index