Contributions to DoubleCommand
Background
DoubleCommand is a keyboard key re-mapping program for Mac OS X written by Michael Baltaks. It enables you to modify the operating system’s interpretation of keystrokes in ways that are unachievable by customization of System Preferences. As of May, 2007, DoubleCommand is one of the few third-party applications of its kind that is open source, actively maintained, and works on the latest release of OS X.
Motivation
I became interested in DoubleCommand when I encountered a usability problem with the 82-key Déck Keyboard. The common complaint about this keyboard among Mac users is the placement of the Command key at the extreme top-right position of the board. This makes key chords very difficult to type, especially when they combine Command with Option, Control, or Shift.
The obvious solution to this dilemma is to swap the position of the Command key with the tilde (~) key. However, there was no application that could perform this feat on current versions of Mac OS X (10.4 as of this writing). Through some research, it appeared the difficulty stemmed from the fundamental way in which the OS viewed the functionality of the two keys: Command is a “modifier” key, while tilde is a “character generating” key. While adjusting the mappings of same-type keys is trivial, converting a key of one type to behave as the other could not be performed.
To solve the usability problem with the 82-key Déck Keyboard on Mac OS X, additional functionality would have to be developed. DoubleCommand was chosen as the platform for developing this feature as it is open source, well maintained, and has clean internal structure amenable to modification.
Implementation
Two additional classes were developed and integrated into DoubleCommand:
There is one KeyboardRemapper instance for each keyboard that is hooked by DoubleCommand for keystroke re-mapping. The KeyboardRemapper can apply any number of key modifications, each of which can modify its target key in one of the following ways.
- Mute the key, so that it will not generate events.
- Behave the same as some other key with respect to impact on modifier flags (e.g., caps-lock, shift) and generation of characters (including keystroke repetition if the key is held down).
- Translate the keycode it would normally send so that a different keycode is associated with the events the key generates.
For example, to make the tilde key act like the Command key requires two modifications: (1) it should behave like the Command key (i.e., as a modifier), and (2) it should send the keycode associated with the Command key. To complete the swap, a similar set of two alterations are performed to make the Command key act like tilde.
KeyboardRemapper is implemented by wrapping (subclassing) IOHIKeyboardMapper and altering method parameters before passing them to the keyboard’s original IOHIKeyboardMapper instance. In some cases, adjusting values of the IOHIKeyboardMapper instance’s internal data is necessary as well. It is worth noting that if the input device source code provided by Apple was not freely available, the feature provided by this project would have been much more difficult to implement.
KeyBehaviorManager is responsible for managing several KeyboardRemapper instances (one for each hooked keyboard), and is the primary interface to the newly incorporated functionality. DoubleCommand passes the user’s preferences to the KeyBehaviorManager, which then configures its KeyboardRemapper instances accordingly.
Results
The changes were successfully implemented in DoubleCommand. The program now has a powerful generic interface for altering key behavior. Other parts of the program are still essential, as a number of features provided require stateful key filters and macro expansion (KeyboardRemapper is a stateless filter).
An additional benefit to the approach of wrapping IOHIKeyboardMapper is the keyboard hook is not detached when the user returns to the login screen (i.e., locks the workstation). Prior to the development of this project, key re-mappings applied by DoubleCommand would fail to operate after the user locked the computer.
Michael Baltaks was gracious to accept the changes to his program and check them in to the main branch of DoubleCommand. Though his program does not directly support swapping the Command and tilde keys (as was the goal of this project), the base functionality is now provided. It is now trivial to implement a generic key re-mapper to provide the user with the ability to customize the application to fit their needs.
Download
Below is a custom version of DoubleCommand, with support for the 82-key Déck Keyboard. Namely, it provides an option for swapping the position of the Command and tilde keys in software (you have to swap the keycaps in hardware). The package is in its 3rd release, and is built upon version 1.6b3 of DoubleCommand.
- Universal Binary
- Source (available on request)