Creating Keyboard Layout in Mac OS X

Xah Lee, 2007-12-30, 2010-06-21

This page tells you how to modify Mac OS X's keybinding. You can define your own keyboard shortcuts for cursor movement and editing commands. You can also define 【⌥ Opt+‹letter›】 key to insert your favorite set of accented letter or math symbols. (€ £ ¥ ← ↑ ↓ → 「」 α β λ § ♠ ♣ ♥ ♦ See: Sample Unicode Characters.)

Key Config File

You need to create a file at 〔~/Library/KeyBindings/DefaultKeyBinding.dict〕. Create the “KeyBindings” dir if you don't already have it.

The 〔DefaultKeyBinding.dict〕 file is just a text file, and must be encoded in utf-8. (if you don't know what that means, just don't use any special characters such as “curly quotes” or math symbols ∑ α β λ etc in this file.)

The file's content should be key and action pairs, like this:

/* this is comment */
{
keycode1 = actionCode1;
keycode2 = actionCode2;
…
}

The keycodes are strings that represent key presses, such as pressing the b key, F2 key, 【⌘ Cmd+b】, 【Ctrl+b】, 【⌘ Cmd+⌥ Opt+b】, or the 2 on number pad.

The actionCode represents what to do. Actions may be inserting a character, or text, or moving the cursor to the beginning of line, or page up, or copy and pasting, etc. (The available actions are predefined in OS X)

Simple Example

Create a file at 〔~/Library/KeyBindings/DefaultKeyBinding.dict〕, and put the following content.

/* my keybindings */

{
/* insert Unicode character with Option key down*/
"~a" = ("insertText:", "\U03B1"); /* greek alpha */
"~;" = ("insertText:", "\U2665"); /* heart symbol */

/* move cursor with i j k l keys while Ctrl key down */
"^i" = ("moveUp:");
"^k" = ("moveDown:");
"^j" = ("moveLeft:");
"^l" = ("moveRight:");
}

With the above, pressing 【⌥ Opt+a】 will insert “α”, pressing 【⌥ Opt+;】 will insert “♥”. Holding down Ctrl and pressing any of

     i
   j k l

will move the cursor.

Restart a Cocoa application and the new keybinding will take effect in that application. Only applications that uses Cocoa Text System will support this. For example, you can launch TextEdit to test your changes.

Note: the default keybinding config file used by the system is a XML file at: 〔/System/Library/Frameworks/AppKit.framework/Resources/StandardKeyBinding.dict〕.

Key Syntax

You can define keys with any of ⌘ Cmd, ⌥ Opt, Ctrl, Shift keys held down, or any combination of them.

For the syntax, see: OS X Keybinding Key Syntax.

Action Code

For each key definition, you need a action code. Action can be inserting a character, a string, moving the cursor by character, word, line, or page up/down, or open file, create new file, ….

For a list of action codes you can use, see: OS X Keybinding Action Code.

Sample File and Misc

Here's a example of defining the Home/End keys to move to the beginning/end of line.

{
"\UF729" = "moveToBeginningOfLine:"; /* home key */
"\UF72B" = "moveToEndOfLine:"; /* end key */
}

Here's example file for inserting Unicode characters with the Opt key. osx_keybinding_dict_unicode_example.txt.

Here's a example of ErgoEmacs Keybinding, one for QWERTY layout and one for Dvorak Keyboard Layout:

You can look at Xcode's keybinding file at 〔/Developer/Applications/Xcode.app/Contents/Resources/PBKeyBinding.dict〕. You can view it here: osx_keybinding_xcode.dict.txt.

Emacs Keybinding

Mac OS X by default support emacs's basic keybindings. They are:

Key	Action
【`Ctrl`+`f`】	move forward
【`Ctrl`+`b`】	move backward
【`Ctrl`+`n`】	move down a line
【`Ctrl`+`p`】	move up a line
【`Ctrl`+`a`】	beginning of line
【`Ctrl`+`e`】	end of line
【`Ctrl`+`k`】	delete current position to end of line
【`Ctrl`+`y`】	paste

You can add more of emacs's

Key	Action
【`Ctrl`+`f`】	move forward
【`Ctrl`+`space`】	set mark
【`Ctrl`+`w`】	cut
【`Ctrl`+`x` `Ctrl`+`x`】	Swap cursor position to last mark

However, i don't recommend it. Emacs's shortcut set is very inefficient and ergonomically painful. See: Why Emacs's Keyboard Shortcuts are Painful. If you like a efficient keybinding for text editing, you might try: ErgoEmacs Keybinding.

Problems

See: Problems of Mac OS X's Keybinding Scheme DefaultKeyBinding.dict.

References and Resources

Here are some references and related sites.

Apple Doc. Text System Defaults and Key Bindings @ Source developer.apple.com
Apple Doc. NSResponder Class Reference @ Source developer.apple.com
Customizing the Cocoa Text System (2006-03) By Jacob Rus. @ Source www.hcs.harvard.edu
Mac OS X Key Bindings (2005-04, 2007-05) By Llew Mason. @ Source www.lsmason.com

Technical Note TN2056: Installable Keyboard Layouts @ Source developer.apple.com