.keylayout file cheat sheet

readme.md

.keylayout file on Mac

• Spec
• Ukelele tutorial
• Ukelele

keyboard

• id: 0
• group: 126 (hardcode)
• name: The name of your keyboard
• maxout: The maximum number of UTF-16 values that can be generated from one keypress.

The keyboard element must contain exactly one <layouts> element, one or more <modifierMap> elements, one or more <keyMapSet> elements, an optional <actions> element, and an optional <terminators> element.

layouts

The <layouts> element has no attributes, and contains one or more <layout> elements.

layout

The <layout> element is an empty element (i.e., it has no subelements and is written in the empty form: <layout />).

• first: The hardware ID of the first keyboard type controlled by this element.
• last: The hardware ID of the last keyboard type controlled by this element
• modifiers: The identifier of the <modifierMap> element to use for this range of hardware keyboard types.
• mapSet: The identifier of the <mapSet> element to use for this range of hardware keyboard types.

Example:

<layouts>
  <layout first="0" last="17" mapSet="ANSI" modifiers="Modifiers"/>
  <layout first="18" last="18" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="21" last="23" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="30" last="30" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="33" last="33" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="36" last="36" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="194" last="194" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="197" last="197" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="200" last="201" mapSet="JIS" modifiers="Modifiers"/>
  <layout first="206" last="207" mapSet="JIS" modifiers="Modifiers"/>
</layouts>

modifierMap

• id: An arbitrary string, used to identify this <modifierMap> elsewhere (currently, only in the <layout> element). This identifier must be unique across all <modifierMap> elements.
• defaultIndex: The table number to use for modifier key combinations which are not explicitly specified by any <modifier> element within the <modifierMap>.

Example:

<modifierMap id="Modifiers" defaultIndex="0">
  <keyMapSelect mapIndex="0">
    <modifier keys=""/>
  </keyMapSelect>
  <keyMapSelect mapIndex="1">
    <modifier keys="anyShift"/>
  </keyMapSelect>
  <keyMapSelect mapIndex="2">
    <modifier keys="anyOption"/>
  </keyMapSelect>
  <keyMapSelect mapIndex="3">
    <modifier keys="caps"/>
  </keyMapSelect>
  <keyMapSelect mapIndex="4">
    <modifier keys="anyShift caps? anyOption"/>
  </keyMapSelect>
</modifierMap>

keyMapSelect

• mapIndex: A table number, starting from 0, to which modifier key combinations specified by <modifier> elements within this <keyMapSelect> element should be mapped. The table numbers should be contiguous and compact as the underlying implementation uses an array.

modifier

• keys:
  • shift: The left Shift key
  • rightShift: The right Shift key
  • anyShift: Matches either the left or right Shift key
  • option: The left Option key
  • rightOption: The right Option key
  • anyOption: Matches either the left or right Option key
  • control: The left Control key
  • rightControl: The right Control key
  • anyControl: Any Control key
  • command: The Command key
  • caps: the Caps Lock key

keyMapSet

This element collects a set of tables that are used to map from key presses to results. Typically there is one set for each class of hardware keyboard. Since the ISO keyboard used in Europe can be handled with the same layout as the ANSI keyboard used in the US, that leaves ANSI and JIS (used in Japan) as the two classes that need to be handled.

Example:

<keyMapSet id="JIS">
  <keyMap index="0" baseMapSet="ANSI" baseIndex="0">
    <key code="512" output=""/>
  </keyMap>
  <keyMap index="1" baseMapSet="ANSI" baseIndex="1">
    <key code="512" output=""/>
  </keyMap>
  <keyMap index="2" baseMapSet="ANSI" baseIndex="2">
    <key code="512" output=""/>
  </keyMap>
  <keyMap index="3" baseMapSet="ANSI" baseIndex="3">
    <key code="512" output=""/>
  </keyMap>
  <keyMap index="4" baseMapSet="ANSI" baseIndex="4">
    <key code="512" output=""/>
  </keyMap>
</keyMapSet>

keyMap

• index: Same as the keyMapSet mapIndex.

key

• code: The decimal number of the virtual key code which this element maps. This number must be unique across all <key> elements within a particular <keyMap> element. (You can't map the same key in two different ways.)

Examples:

<key code="19" output="CE"/>
<key code="20" output=""/>
<key code="21" action="Dead Key State 0"/>

A deadkey example

In the <keyMap> for the unshifted keyboard, we have:

<key code="14" action="e" />

This specifies that when key code 14 is received, we take the action named "e". In the <keyMap> for the option key, we have:

<key code="14" action="acute" />

<actions>
  <action id="acute">
    <when state="none" next="acute" />
  </action>
  <action id="e">
    <when state="none" output="e" />
    <when state="acute" output="é" />
  </action>
</actions>
<terminators>
  <when state="acute" output="´" />
</terminators>