Changing Wine key mappings on Mac OS X

Source: https://palant.de/2014/02/14/crazy-hacks-changing-wine-key-mappings-on-mac-os-x

Remap CMD keys on wine (MacOS)

One of the biggest quirks of using a Mac is its keyboard — in addition to the usual Control (⌃) and Alt a.k.a. Option (⌥) keys you also have the Command (⌘) key. Unlike on Windows or Linux, the Control key is rarely used at all, the only really important shortcut key being Control-Tab. Instead, most shortcut keys use Command as modifier. So as a Mac user you quickly learn to press Command for pretty much any key combination.

This works well as long as you stick to native OS X applications. As soon as you run Windows applications via Wine however you get into trouble: in order to map Mac keys to Windows keys Wine associates the Control key with Control. Consequently, in Wine you have to for example press Control-C to copy text instead of Command-C. You also have to remember that all other shortcut keys use Control instead of Command which is very annoying.

Given that the best key mapping is a matter of taste, one would expect Wine to be configurable as far as key mappings go. Yet pretty much everything you find on that topic tells you to change Xorg key mappings. This works if you are on Linux or using an old Wine version that requires Xorg. However, current Wine versions have a Mac Driver that allows them to run on OS X natively, without the awkward detour through Xorg. And other than these outdated advises I could only find a question on apple.stackexchange.org — unanswered of course (I answered it in the meantime).

Given the lack of documentation, studying the source code is the only option. The important function here is macdrv_compute_keyboard_layout() that does various things trying to guess the best keyboard mapping — yet none of the steps appear to be configurable (yes, I filed a change request). There is also a hardcoded mapping table called default_map that is uses as a fallback and that’s exactly what is being used for the modifier keys. This means, in order change the mapping of modifier keys one has to modify that table in the compiled binary (that would be /Applications/Wine.app/Contents/Resources/lib/wine/winemac.drv.soon my computer).

Warning: Perform the following steps at your own risk and keep a backup of the original file. Note that you will have to redo this procedure whenever Wine is updated.

The mapping for the two Command keys is defined by the following lines:

{ VK_RMENU,                 0x38 | 0x100,   TRUE },     /* kVK_RightCommand */
{ VK_LMENU,                 0x38,           TRUE },     /* kVK_Command */

For the binary representation of these lines one has to keep in mind that WORD (type of the first two fields) is a two byte integer whereas BOOL (type of the last field) is a four byte integer. You will also need to consult the list of Windows virtual key codes (VK_RMENU has the value A5 and VK_LMENU the value A4). The second field is a key scan code defining the physical key being pressed. So the compiled binary should contain the following byte sequences:

A5 00 38 01 01 00 00 00
A4 00 38 00 01 00 00 00

Any hex editor should be able to open the binary and find these bytes, in my case they were located at hexadecimal offset 62770. In order to change the mapping to VK_RCONTROL and VK_LCONTROL one could change these bytes to:

A3 00 1d 01 01 00 00 00
A2 00 1d 00 01 00 00 00

Now whenever you press the Command key it will be interpreted as Control by the Windows application rather than Alt. But you will no longer have anything mapping to Alt. One option would be to change the mapping of the Control key but I prefer to keep it mapped to Control in order for Control-Tab to work in Windows applications. The other option is to map the Option key to Alt, normally it is unmapped.

All unmapped keys are represented by eight zeroes so you will have to find the corresponding entry by position relative to other keys — three and six entries behind the left Command key for the left and right Option key respectively. You can put the original values for the Command keys there. This will work for combinations like Alt-F4 yet menu shortcuts like Alt-F won’t work — on OS X most combinations involving letters and the Option key are used to enter special characters. Still, you can press Alt to enter the menu and cursor keys to navigate which is a lot more than you can usually do with OS X menus.

Of course, there are more options — e.g. you could leave the left Command key mapped to Alt. Choose your poison, and in time Wine developers will hopefully make this post obsolete.

Resources & References

• http://apple.stackexchange.com/questions/108214/keyboard-shortcut-using-mac-driver-in-wine
• http://ridiculousfish.com/hexfiend/

Other options with Karabiner private.xml

As of 2016, Dec, Karabiner does not work with Sierra

<?xml version="1.0"?>
<root>
  <appdef>
    <appname>PLAYONMAC</appname>
    <equal>org.pqrs.unknownapp.wine</equal>
  </appdef>

  <item>
    <name>Enable at only PlayOnMac</name>
    <item>
      <name>Swap left command key and left control key in PlayOnMac</name>
      <identifier>private.appdef</identifier>
      <only>PLAYONMAC</only>
      <autogen>__KeyToKey__ KeyCode::COMMAND_L, KeyCode::CONTROL_L</autogen>
      <autogen>__KeyToKey__ KeyCode::CONTROL_L, KeyCode::COMMAND_L</autogen>
    </item>
  </item>
</root>