Search:   Help



LyX documentation


Shared groups


Mac /


Categories: Mac
<< | Page list | >>

Swapping the Command and Control keys for LyX on the Mac

The Problem

Early versions of LyX on Mac used to come with a graphical user interface called xforms, which required an X Window server (X11) to be running and lacked the Aqua-like look-and-feel that is now attainable through the Qt interface. However, the Qt libraries with which current versions of LyX/Mac are built put severe constraints on users' ability to customize the modifier key bindings.

Modifier keys are important for users relying heavily on keyboard shortcuts in LyX. The official binaries for LyX/Mac available from the main download page follow Qt's use of "Option" and "Command" (Apple) as modifier keys, leaving the "Control" key non-functional. Two modifier keys (plus the Shift key) are indeed sufficient for LyX, but there are situations when it becomes desirable to break out of this default choice.

This is true especially for users who are accustomed to Emacs, a popular all-purpose editor that has a long history on UNIX-like operating systems. Although LyX offers customized bind files which implement many Emacs key bindings, there is one crucial problem: wherever Emacs users expect to press the Control key, LyX requires them to press the Command key instead. This is extremely confusing for people who use both LyX and Emacs side by side. (The "Escape" key in LyX also functions differently from Emacs, because LyX only uses it as a "cancel" key.)


In LyX 2.0 (starting with alpha 6) or later on Mac OS X, go to Preferences > Editing > Keyboard/Mouse and look for the check box saying "Do not swap Apple and Control Keys." When this box is checked, the Control key acts as Control and the Apple key acts as Meta - i.e., the modifier keys are not swapped. The setting takes effect after relaunching LyX. An exception are the keyboard shortcuts in the Mac-specific LyX nenu: "Preferences", "Hide LyX" and "Quit": they always use the Apple key.

History (included only for reference)

The rest of this page is now obsolete. You may want to browse this section if you're looking for an older version of LyX (<version 2.0), compiled with a fix for the Control-Apple swap issue.

An Initial Solution

On this page, we collect binaries that fix this problem by re-assigning the role of the modifier keys to make the Control key functional again. For versions up to 1.4.2, this was done by compiling the Qt libraries with a small patch. (Instructions for compiling the patched version can be found on the lyx-users mailing list.)

Here are links to binaries for LyX that contain the patch described above:

Most people who use a patched version of LyX also use an operating system-level keyboard mapper like uControl or fkeys to map the Caps Lock key to the Control modifier. The patched versions above do not do this mapping directly.

A Better (?) Solution

A major downside of the original solution is that a patched version of LyX needs to be compiled and distributed separately for every release. It would be much better if a single LyX distribution could be configured for either standard and "swapped" behavior.

An attempt at this is now available as a new patch for Qt 4 (confirmed to work with versions 4.3.4 through 4.4.3; does not work with 4.5.2), which has been used to create patched versions of the LyX binaries:

You can install the patched version just like the official one. To swap the modifier keys, you will need to add a key called QtSwapModifiers to the .GlobalPreferences list in your home directory.

An easy way to do this is to type:

open ~/Library/Preferences/.GlobalPreferences.plist

in a Terminal window. Then, using the Property List Editor, select the Root node, click New Child to add a new key, and call the key QtSwapModifiers. Select the new key, then change its class to Boolean using the pop-up list. Its default value will be Yes. (If you want to turn off swapping, re-edit this file and change the value to No.) Changes will become effective the next time you start LyX.

This new solution has been tested on PPC and Intel Macs running Tiger and Leopard. If you find that it doesn't work as expected, feedback would be greatly appreciated.

At this time there does not appear to be enough critical mass among the LyX/Mac user base to warrant compiling the patch in the regular release. (There was some discussion of this issue on the lyx-devel mailing list.) However, the patch source includes a rudimentary shell script ( that successfully builds the Universal binary on an old PowerPC Mac running OS X 10.4.11. If you're interested in building it yourself (and/or improving the script), this would be a good place to start.

Future Solutions

There is a resolution that doesn't require patching Qt. In looking at the sources of qt-everywhere-opensource-src-4.6.2.tar.gz there is a new ApplicationAttribute constant called Qt::AA_MacDontSwapCtrlAndMeta which can be set by the application. When it is set, the keymapper no longer performs the switch. That means Qt no longer has to be patched, but LyX needs to call setAttribute with this constant when the application loads. On the lyx-devel mailing list, I suggested adding the option to switch Meta and Control directly to the application preferences.

I started testing this approach (noeckel, June 5, 2010), and found it has one additional advantage: the menu shortcuts are now displayed correctly in the GUI (i.e., ^S for save if you use emacs bindings). With the older patches, the shortcuts worked fine but they weren't displayed in the pull-down menus. What I did to compile the test version is:

In the file /src/frontends/qt4/GuiApplication.cpp add the single line



 #ifdef Q_WS_MACX
	// FIXME: Do we need a lyxrc setting for this on Mac? This behaviour
	// seems to be the default case for applications like LyX.

To compile LyX with Qt 4.6.2, you need to set some extra arch flags as described in

The next step is for the LyX developers to add a Preference entry so that this call can be made depending on the user's settings.

For completeness, here are some older discussion items:

  • Would the Qt developers be willing to implement a more general modifier-swapping mechanism? We have logged this request with Trolltech as suggestion 205938. The private version of the task includes a description of the new patch and a link to this page.
  • Is there a clean way to provide a workaround by changing the LyX source code instead of Qt? This may be possible, but it's not clear that enough people are affected by this issue to make that worthwhile.
  • Can OS X itself, or one of the kernel extensions mentioned above, be used to solve the problem? The OS X System Preferences provide customizable modifier keys, even on a per-application basis. But (at least as of Tiger) it is not possible to switch the function of the Control and Command keys for all keyboard shortcuts in LyX. If anyone finds a solution for Leopard or beyond, please post it here.

Votes for continued support for modifier key swapping

  • David Rosenberg ( -- having the modifier key swap is crucial for me. I wouldn't upgrade to 1.6.0 without it. I wouldn't mind compiling myself if there were a short tutorial... Thanks!
  • I've posted the binary for LyX 1.6.1 with the switched modifier keys at LyX 1.6.1 for Intel. This is still compiled with hard-coded key assignments, so there is no variable QtSwapModifiers. The simple reason is that I haven't had time to re-compile Qt with the new approach suggested by Jason Woodard. -- Jens Noeckel (Jan 24, 2009)
    • Sorry for being out of touch, Jens, and thanks for posting the 1.6.1 Intel binary. I produced a Universal binary with the new patch and linked it above. -- JW (Mar 13, 2009)
    • Per David's comment, I included a compilation script in the patch source tarball (see above for link). Unfortunately it's not easy for me to produce a more general tutorial because I'm compiling on an old PPC Mac, which requires a lot of fiddling to produce Universal binaries at all, and then a bunch of weird compiler flags that I seem to have to tweak by trial and error every time. -- JW
    • Just posted a binary for 1.6.4. Unfortunately my PowerBook G4 is now semi-retired, and I do most of my writing on a (gasp!) Windows machine now. So this might be the last one I'm able to do. I will try to make sure the links still work, and hope there's enough information here for anyone who wants to take this forward to do so. -- JW (Sep 5, 2009)


Edit - History - Print - Recent Changes - All Recent Changes - Search
Page last modified on 2014-07-18 22:11 UTC