Unicode Keyboards for Mac OS

by Alex Eulenberg
Created May 3, 2002
Revised April 6, 2013

Create your own custom Unicode keyboard for Mac OS 9 or X!

Enter your layout specification in the box below, choose a Layout Name and Script / Resource ID (see notes on choosing scripts), and submit to get a keyboard layout resource file, and install by following the installation instructions.


Layout Name: Script / Resource ID:
Mac OS X .keylayout (XML) file* (download)
Mac OS X .keylayout (XML) file* (view)
Mac OS X .rsrc (binary resource) file*
Mac OS 9 Keyboard File
Rez Source
Raw Hexadecimal (Resource name and ID will be ignored)

*requires Mac OS X v10.2 or higher
Autodefine unassigned keystrokes with those from the standard keyboard?
Yes, autodefine them all.
Yes, but leave the "option" keystrokes blank.
No, start with a completely blank keyboard.

Layout of the "standard keyboard":
U.S. (QWERTY)
Dvorak
Dvorak / QWERTY command keys
Colemak

Layout specification (may be left blank to generate standard keyboard):


Notes on choosing a Script for your layout

Note: The system software of Mac OS X 10.5 "Leopard" and later does not support the concept of "script". Most if not all applications written to run on Mac OS X 10.5 and later ("Universal" or "Intel-only") support Unicode and make no use of a keyboard layout's script assignment. As a practical matter, choice of script only matters if you are running "Classic" (unavailable as of 10.5 "Leopard") or PowerPC-based (unavailable as of 10.7 "Lion") applications.

Depending on its Resource ID, every keyboard layout is associated with a script. The script determines how to translate the layout's two-byte (0-65535) Unicode character values to one-byte (0-255) character values. These one-byte values are used by non-Unicode-supporting applications (chiefly older "Carbonized" applications such as AppleWorks 6, Microsoft Word X, and just about any "Classic" Mac OS application). These applications use the Script Manager to coordinate the script, character value, and font, as the same character value may represent different letters in different script-specific fonts. Script is ignored by Unicode-supporting applications (all Cocoa applications and most new Carbon applications written for Mac OS X). These applications work with the characters directly as Unicode characters, and font switching is done on a character-by-character basis.

Also, in older versions of Mac OS, the layouts in the keyboard menu would be grouped by script. The keyboard shortcut of command-space would switch to the last selected layout of the next group, while command-option-space would switch to the next layout in the current group. In OS X v10.5 "Leopard" and later, there are no groups. The command-space keyboard shortcut (if activated) simply switches to the previous layout, and command-option-space switches to the next layout in the menu, both regardless of script.

In Mac OS X, installable keyboard layouts may be of one of four scripts: Roman, Cyrillic, Central European, or Unicode. The "Unicode" script essentially means "not for use with Script Manager-based applications".

Roman Script

The Roman script is intended for keyboard layouts containing only letters found in Mac OS's Roman (or "MacRoman") character set. For best compatibility with all applications and operating system versions you should in most cases use the "Roman" script, even if your keyboard includes characters that are outside of this set. The chief advantage of doing this is that the keyboard will always be accessible, even if not all of its characters are.

Cyrillic and Central European

If, however, your keyboard is for Cyrillic or contains Central/East European accented characters, you should choose the Cyrillic or Central European script as appropriate in order to be compatible with Script Manager-based applications. If you want to use this keyboard as your main keyboard in an old version of Mac OS X, however, you will have to turn off "font and keyboard synchronization" (International Preferences, Input Menu "options") to keep it from constantly being deselected at login and at the launch of certain applications. This problem does not exist in v10.5 "Leopard" or later.

Unicode Script

The Unicode script is intended for keyboard layouts whose characters are not all found in any single script. Assigning your layout to the "Unicode" script will deselect your layout and render it unselectable whenever you enter an application that does not support Unicode. (In versions of Mac OS X prior to v10.5 "Leopard" this also occurs when you are in a Unicode-based application and a text entry box is not present.)

General Considerations regarding Encodings

Although the characters that you specify for the keyboard layout must be in the script's character set in order to work smoothly with Script Manager-based applications that do not support Unicode, the specification is still given in Unicode values, not the MacRoman, MacCyrillic or MacCentralEuropean values. This means that it is possible to assign to a key a character that does not exist in your script (e.g., you may add a Dingbat to your Roman keyboard, or a Cyrillic "hooked K" to your Cyrillic keyboard), but if you do, that key will produce no output in non-Unicode-supporting applications.

Format of the layout specification

Syntax

The syntax is multiple lines of the following form: input, basic output, submap.

An input is defined as an optional modifier code followed by a key code. Valid key codes are (lowercase) letters of the alphabet, numbers, and the fourteen symbols _ ` , ' / \ ] [ - = . ; § ¥ -- optionally preceded by a number sign (#). A key code beginning with number sign indicates a key on the numeric keypad. Each key code corresponds to the key on the standard keyboard that you must press to get that symbol, except for the underscore (_), which stands for the space bar. Note that the section sign (§) corresponds to the key above tab on the ISO Extended (physical) Keyboard; it does not correspond to any key on U.S. standard physical keyboards. Likewise, the Japanese (JIS) keyboard has two unique keys: the Yen key (¥) just left of the delete key, and a key for underscore just left of the right shift key, represented by a number sign-preifxed underscore (#_). Valid modifier codes are P (plain), S (shift and shift-caps), C (caps), O (option), OS (option-shift and option-shift-caps), OC (option-caps), M (command), and T (control). "P" means you don't press any modifier keys. If the modifier code is omitted, "P" is assumed.

An output is defined as a string of characters, where each character stands for itself, except that spaces (including tabs) and colons (:) are not permitted. A dollar-sign ($) followed by up to six hexadecimal digits (0-9,a-f) and, optionally, terminating dot (".") represents the corresponding Unicode character. Leading zeroes are optional. Spaces are represented as "$20", dollar signs as "$24", and colons as "$3A".

A submapping is a space-delimited series with elements of the form: original output, colon(:), new output. Note that it is not key codes that are mapped to new outputs, but outputs that are mapped to other outputs.

Semantics

When a keystroke occurs that matches the input for a rule, the string represented by the output is generated, unless the rule has a submapping. A keystroke with a submapping is called a "dead key" because it simulates typewriter keys that do not cause the print head to advance (instead, they print an accent that appears above or below the next typed character). In the case of a rule with a submapping, the output is suppressed until the next keystroke, and then the output that would have been generated by that keystroke is replaced with the one from the corresponding "new output" from the first keystroke. If no such corresponding output exists, the first (non-submapping) output of the first keystroke is generated, followed by the output of the second keystroke.

Note also that if, for a given key code, there is an output for C or OC, that output is automatically assigned to S or OS, respectively. In other words, outputs defined as "capital" letters are accessible through both caps and shift. However, it is possible to define outputs for both (O)C and (O)S, in which case, the results for caps and shift will be different. In all cases, pressing caps and shift together is the same as just pressing shift.

Comments

Comments are preceded by two colons, and are ignored by the parser.

Example Rules

You can copy and paste these rules into the form input box to try them out. Please email me at if there's a capability you'd like your layout to have but you're not sure what the rule should be.
:: Some Simple Rules
 Sa abc   ::Shift-A key generates the sequence "abc"
 Oa $0447 ::Option-A generates Cyrillic Letter Che.
 S4 $0024  ::Shift-"4" is the dollar sign (but not Caps-"4").
 S; colon  ::Shift-semicolon (ordinarily ":") now spells out "colon"
 #1 one  ::"1" on the numeric keypad spells out "one"
C#1 ONE  ::Caps version of the above (accessible through caps or shift)
 
:: Three rules that give three levels of capitalization.
 Os sh ::Option-S generates the sequence "sh".
OCs SH ::All caps
OSs Sh  ::Just shift (init caps).

:: The following examples illustrate the function of "."
  e $10429 ::The "e" key generates Deseret small long e.
 Se $104.29 :: Shift-"e" generates captal A with hook below, followed by "29".

:: option-minus will give you a macron (U+00AF), UNLESS it is
:: followed by an a, in which case you will get a+macron, same for e, etc.
O- $AF a:$101 e:$113 i:$12B o:$14D u:$16B

:: This does the same thing, except with combining characters ($304 = 
:: combining macron). With the combining macron, we can also specify
:: n-macron and m-macron, which don't have their own single Unicode
:: code points. Note that the code for the standalone macron is $AF,
:: while the combining version is $304.
O- $AF a:a$304 e:e$304 i:i$304 o:o$304 u:u$304 n:n$304 m:m$304


Installation

On Mac OS X

Version 10.2 "Jaguar" and higher

Create a ".keylayout" file with the web tool. Drag this file into the folder "(HOME)/Library/Keyboard Layouts" to make it available to your user (note this folder is hidden starting with OS X 10.7 "Lion"; use command-shift-G in the Finder and enter "~/Library/Keyboard Layouts" to open it) and into "/Library/Keyboard Layouts" to make it available to all users. The keyboard is immediately available to all applications that launch after this point; you have to quit and relaunch running applications (including the Finder) for them to recognize the keyboard. This includes System Preferences, which is the application that you use to add the keyboard to the keyboard menu. When in doubt, log out and in again. For more information on this XML format, see
Apple Tech Note 2056, Installable Keyboard Layouts.

Note: If you are having trouble with the XML layout, You may also try the .rsrc (binary) format. (In the past, layouts with either 1 or 2 submappings did not work in the XML format. This has been corrected as of Nov 20, 2002.) You may rename your generated file (preserving the .rsrc suffix) to distinguish it from other .rsrc files in your Keyboard Layouts folder, but this will not have an effect on the name that shows up in the keyboard menu. Please let me know at if you get differing results for .keylayout and .rsrc keyboard files with the same keyboard definition.

Version 10.1

Generate Rez Source Code with the web tool. Save as a text file (e.g. "layout.r". For this method, you need the Rez command-line tool, which is available on the Mac OS X Developer Tools CD (comes with OS X). The way to actually get the resource working on the system involves patching a file that should not, generally be touched, since it is under the "/System" directory. Do this at your own risk. Make a backup of "/System/Library/Frameworks/.../HIToolbox.rsrc" (full path given below). As administrator, run the following script with the name of your file as the argument. You must have superuser privileges. If you do not know what that means, or how to do it, you should probably upgrade to a later version of Mac OS X (see above).

#!/bin/sh
suitcase=/System/Library/Frameworks/Carbon.framework/Frameworks/HIToolbox.framework/Resources/HIToolbox.rsrc
resource=$1
if test -w $suitcase; then
	/Developer/Tools/Rez -append -useDF -o $suitcase $resource
else
	echo "You don't have permission to add a resource to $suitcase." >&2
fi

On Mac OS 9

First install the Unicode Script. It is in the Mac OS 9 Installer Disk under CD Extras:Unicode.

With the web tool, generate a "Mac OS 9 Keyboard File". This will give you a file, "layout.as", which has your layout encoded in the "AppleSingle" transfer encoding. Decode it with your favorite "expander" application if your browser doesn't do it for your automatically. If all goes well, you will end up with a keyboard layout file (the icon will have a picture of a keyboard on it if you are in Mac OS 9) with the name of your layout, in your downloads folder (or on the desktop). The "layout.as" file may be put in the trash. In the extremely unlikely event your system cannot handle AppleSingle, you may try the following instead:

With the web tool, generate a "Raw Hexadecimal" resource. Select all and copy. Launch ResEdit, and create a new file (From the "File" menu, select "New"), and give it a name the same as your layout. Then select "new resource" from the Resource menu (or Command-K) type in uchr (note: all lower case!) and click OK. Now paste. Close the "uchr ID = 128" window, and then select "Get Resource Info" from the Resource menu. Check "System Heap" and "Purgeable", and replace the number 128 with a negative number between -100 and -32767, and again set the name to be the same as your layout. Close that window. Select "Get info for " from the File menu, change the type to kfil and the creator to movr. Then Save and Close from the File menu.

Note: If the resource ID of the layout you created is the same as an existing keyboard, the new keyboard will replace the old one. You can use ResEdit to examine the copy of your old System Folder to find the conflicting 'uchr' or 'KCHR' (old-style keyboard) ID.

Now, make a backup copy of the "System" file (inside your System Folder). Drag the keyboard file you just downloaded (or created) onto the System file (or you can drag it onto the closed System Folder). You will probably get some self explanatory dialog boxes before the Macintosh lets you actually add the resource.