A simple example of private.xml

<?xml version="1.0"?>
<root>
  <item>
    <name>Swap Space and Tab</name>
    <identifier>private.swap_space_and_tab</identifier>
    <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
    <autogen>__KeyToKey__ KeyCode::TAB, KeyCode::SPACE</autogen>
  </item>

  <item>
    <name>Change Right Command Key to Escape</name>
    <identifier>private.right_command_to_escape</identifier>
    <autogen>__KeyToKey__ KeyCode::COMMAND_R, KeyCode::ESCAPE</autogen>
  </item>
</root>

2 settings are added by this private.xml.

Examples of <autogen>

There are a lot of examples of <autogen> in "Samples for KeyRemap4MacBook Developer" at the bottom of KeyRemap4MacBook Prefs.
You can see the raw XML from samples.xml.

In addition, prepared settings are described in checkbox.xml. These are also good examples of <autogen>.

You can add a new setting by <item>.

<?xml version="1.0"?>
<root>

  <item>
    <name>Name of Setting</name>
    <appendix>Optional Description of Setting</appendix>
    <identifier>Unique Identifier of Setting</identifier>
    <autogen>Behavior Definition</autogen>
    <autogen>Behavior Definition</autogen>
  </item>

  <item>...</item>

  <item>...</item>

</root>

Please write <name>, <identifier>, <autogen> under <item>.

<name>
<appendix>
These values are used in Preference Pane.
<identifier> This value is used to identify setting.
You need to specify a unique value. We recommend you to add a "private." prefix to your identifier. It prevents conflicts with identifiers of prepared settings.
<autogen> Definition of this setting behavior.
For example, __KeyToKey__, __PointingButtonToKey__.

List of KeyCode, ConsumerKeyCode, PointingButton

__KeyToKey__ syntax

Plain

This <autogen> changes space key to tab key.

<autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>

Modifier+Key to Key

This <autogen> changes "left control+space key" to tab key.

<autogen>
  __KeyToKey__
  KeyCode::SPACE, ModifierFlag::CONTROL_L,
  KeyCode::TAB
</autogen>

Modifier+Key to Modifier+Key

This <autogen> changes "left control+space key" to "left control+tab key".

<autogen>
  __KeyToKey__
  KeyCode::SPACE, ModifierFlag::CONTROL_L,
  KeyCode::TAB,   ModifierFlag::CONTROL_L
</autogen>

Multiple modifiers

You can use "|" to specify multiple modifiers.

This <autogen> changes "left control+fn+space key" to tab key.

<autogen>
  __KeyToKey__
  KeyCode::SPACE, ModifierFlag::CONTROL_L | ModifierFlag::FN,
  KeyCode::TAB
</autogen>

ModifierFlag::NONE

If you want to change key behavior only when specific modifiers are pressed, use ModifierFlag::NONE.

This <autogen> changes "fn+space key" to tab key and retain other modifier combinations+space key behavior.

Physical key Changed key State
space space Not changed
control+space control+space Not changed
fn+space tab Changed
fn+control+space fn+control+space Not changed
<autogen>
  __KeyToKey__
  KeyCode::SPACE, ModifierFlag::FN | ModifierFlag::NONE,
  KeyCode::TAB
</autogen>

Change to multiple keys

This <autogen> changes space key to tab,return key.

<autogen>
  __KeyToKey__
  KeyCode::SPACE,
  KeyCode::TAB, KeyCode::RETURN
</autogen>

Order of <autogen>

Basic case

KeyRemap4MacBook applies only the first matched <autogen>.

The following autogens change space key to tab key (not return key).

<autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
<autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::RETURN</autogen>

More complex case

If you want to change "shift+space to tab" and "space to return", you need to order <autogen> as follows.

Physical key Changed key
shift+space tab
space return
<!-- shift+space to tab -->
<autogen>__KeyToKey__ KeyCode::SPACE, ModifierFlag::SHIFT_L, KeyCode::TAB</autogen>

<!-- space to return -->
<autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::RETURN</autogen>

Wrong case If you've put them in reverse order, KeyRemap4MacBook changes "shift+space" to "shift+return".

<!-- KeyRemap4MacBook always changes space key to return key even if you're pressing shift modifier. -->
<autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::RETURN</autogen>

<!-- *** This autogen is never applied. *** -->
<autogen>__KeyToKey__ KeyCode::SPACE, ModifierFlag::SHIFT_L, KeyCode::TAB</autogen>

Type of identifier prefix

You can add a special behavior by using some prefix on <identifier>.

Prefix Behavior
notsave. "notsave." prefix is designed for creating "mode".
  • This setting is not saved even if it was enabled.
  • This setting priority is higher than normal settings.
  • User cannot enable this setting by Preference. (Use KeyCode::VK_CONFIG_*.)
passthrough. "passthrough." prefix is designed for turning "Pass Through Mode" off.
  • This setting is effective even if in "Pass Through Mode".

Note This passthrough.'s special behavior has been removed since v9.3.14.
Please use Option::IGNORE_PASSTHROUGH in order to ignore "Pass Through Mode".

An example

You can define settings which are effective on specific applications only.
Add <only> or <not> to your <item>.

This private.xml exchanges space key and tab key on Safari.

<?xml version="1.0"?>
<root>
  <item>
    <name>Swap Space and Tab</name>
    <identifier>private.app_safari_swap_space_and_tab</identifier>
    <only>SAFARI</only>
    <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
    <autogen>__KeyToKey__ KeyCode::TAB, KeyCode::SPACE</autogen>
  </item>
</root>

Steps to define an application specific setting

Examine a bundle identifier of target application

  1. Launch EventViewer from a menu.
  2. See "App" tab of EventViewer.
    This list is updated when you changed the current application.

    Change the current application to target application. Then press "copy to pasteboard" button.
    You can paste this information to text area.

Add an application definition to your private.xml.

  1. Add <appdef> to your private.xml.
    <appname> is a name of application which you use in <only> filter.
    Write the bundle identifier into <equal>.
    <?xml version="1.0"?>
    <root>
      <appdef>
        <appname>APPSTORE</appname>
        <equal>com.apple.appstore</equal>
      </appdef>
    </root>
  2. Then, you can use <only>APPSTORE</only> in private.xml.
    <?xml version="1.0"?>
    <root>
      <appdef>
        <appname>APPSTORE</appname>
        <equal>com.apple.appstore</equal>
      </appdef>
    
      <item>
        <name>Space to Tab on App Store.app</name>
        <identifier>private.appdef</identifier>
        <only>APPSTORE</only>
        <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
      </item>
    </root>

Prepared application definitions

KeyRemap4MacBook provides various application definitions.
You can use them without <appdef> in private.xml.

You can also overwrite existent application definitions by private.xml.
If you overwrite TERMINAL definition as follows, <only>TERMINAL</only> is effective on Apple's Terminal.app only (not iTerm2 and other terminal apps).

<?xml version="1.0"?>
<root>
  <appdef>
    <appname>TERMINAL</appname>
    <equal>com.apple.Terminal</equal>
  </appdef>
</root>

You can define settings which are effective on specific device only.
Add <device_only> or <device_not> to your <item>.

This private.xml turns scroll wheel off on Magic Mouse.

<?xml version="1.0"?>
<root>
  <item>
    <name>Disable ScrollWheel on Magic Mouse</name>
    <identifier>private.dropscrollwheel_0x05ac_0x030d</identifier>
    <device_only>DeviceVendor::APPLE_COMPUTER,DeviceProduct::MAGIC_MOUSE</device_only>
    <autogen>__DropScrollWheel__</autogen>
  </item>
</root>

Steps to define a device specific setting

Examine Vendor ID and Product ID of a target device

  1. Launch EventViewer from a menu.
  2. See "Devices" tab of EventViewer.

    Then press "copy to pasteboard" button.
    You can paste this information to text area.

Add an device definition to your private.xml

  1. Add <devicevendordef> and <deviceproductdef> to your private.xml.
    <?xml version="1.0"?>
    <root>
      <devicevendordef>
        <vendorname>HEWLETT_PACKARD</vendorname>
        <vendorid>0x03f0</vendorid>
      </devicevendordef>
    
      <deviceproductdef>
        <productname>MY_HP_KEYBOARD</productname>
        <productid>0x0224</productid>
      </deviceproductdef>
    </root>
  2. Then, you can use <device_only> in private.xml.
    <?xml version="1.0"?>
    <root>
      <devicevendordef>
        <vendorname>HEWLETT_PACKARD</vendorname>
        <vendorid>0x03f0</vendorid>
      </devicevendordef>
    
      <deviceproductdef>
        <productname>MY_HP_KEYBOARD</productname>
        <productid>0x0224</productid>
      </deviceproductdef>
    
      <item>
        <name>Space to Tab in MY_HP_KEYBOARD</name>
        <identifier>private.deviceproductdef</identifier>
        <device_only>DeviceVendor::HEWLETT_PACKARD, DeviceProduct::MY_HP_KEYBOARD</device_only>
        <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
      </item>
    
    </root>

Prepared device definitions

KeyRemap4MacBook provides various Vendor ID and Product ID definitions.
You can use them without <devicevendordef> and <deviceproductdef> in private.xml.

You can also overwrite existent device definitions by private.xml.

How to distinguish multiple devices which have same Vendor ID and Product ID

You can use "Location ID" in order to distinguish multiple devices which have same Vendor ID and Product ID.

Learn about "Location ID"

  • "Location ID" is an unique identifier even if devices have same Vendor ID and Product ID.
  • The behavior of "Location ID" is different for each type of device.
Device Type What's Location ID? Is immutable?
USB Device Location ID is determined by USB port. This value will be changed when you pull out USB device and plug it into other USB port.
Bluetooth Device Location ID is determined by Bluetooth Address. This value is immutable.

Examine Location ID

You can examin Location ID by EventViewer.

Location ID in XML

You can specify Location ID like this.

<?xml version="1.0"?>
<root>
  <devicevendordef>
    <vendorname>HEWLETT_PACKARD</vendorname>
    <vendorid>0x03f0</vendorid>
  </devicevendordef>

  <deviceproductdef>
    <productname>MY_HP_KEYBOARD</productname>
    <productid>0x0224</productid>
  </deviceproductdef>

  <devicelocationdef>
    <locationname>MY_HP_KEYBOARD_PRIMARY</locationname>
    <locationid>0xfa120000</locationid>
  </devicelocationdef>

  <item>
    <name>Space to Tab in MY_HP_KEYBOARD</name>
    <identifier>private.deviceproductdef</identifier>
    <device_only>
      DeviceVendor::HEWLETT_PACKARD,
      DeviceProduct::MY_HP_KEYBOARD,
      DeviceLocation::MY_HP_KEYBOARD_PRIMARY,
    </device_only>
    <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
  </item>

</root>

Functions

There are two functions related with input source.

Change input source by virtual key code.

An example

This private.xml changes input source to Dvorak by Right Shift Key + D.

<?xml version="1.0"?>
<root>
  <vkchangeinputsourcedef>
    <name>KeyCode::VK_CHANGE_INPUTSOURCE_MY_DVORAK</name>
    <inputsourceid_equal>com.apple.keylayout.Dvorak</inputsourceid_equal>
  </vkchangeinputsourcedef>

  <item>
    <name>Change input source to Dvorak by right shift key + D</name>
    <identifier>private.change_input_source_to_dvorak</identifier>
    <autogen>
      __KeyToKey__
      KeyCode::D, ModifierFlag::SHIFT_R,
      KeyCode::VK_CHANGE_INPUTSOURCE_MY_DVORAK
    </autogen>
  </item>
</root>

Virtual key code definition

You can define new virtual key code by <vkchangeinputsourcedef>.

  • <name> is a name of virtual key code. This name must be started with KeyCode::VK_CHANGE_INPUTSOURCE_.
    For example, <name>KeyCode::VK_CHANGE_INPUTSOURCE_YOUR_LANGUAGE</name>.

  • <inputsourceid_equal> is a input source id of target input source.
    How to examine input source id.

Prepared virtual key code definitions

KeyRemap4MacBook provides various virtual key code definitions.
You can use them without <vkchangeinputsourcedef> in private.xml.

Settings which are effective on specific input source only.

An example

This private.xml exchanges space key and tab key on Dvorak.

<?xml version="1.0"?>
<root>
  <inputsourcedef>
    <name>MY_DVORAK</name>
    <inputsourceid_prefix>com.apple.keylayout.Dvorak</inputsourceid_prefix>
  </inputsourcedef>

  <item>
    <name>Swap Space and Tab</name>
    <identifier>private.my_dvorak_swap_space_and_tab</identifier>
    <inputsource_only>MY_DVORAK</inputsource_only>
    <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
    <autogen>__KeyToKey__ KeyCode::TAB, KeyCode::SPACE</autogen>
  </item>
</root>

Steps

  1. Examine Input Source ID of target input source.
    How to examine input source id.

  2. Add <inputsourcedef> your private.xml.

    <?xml version="1.0"?>
    <root>
      <inputsourcedef>
        <name>MY_DVORAK</name>
        <inputsourceid_prefix>com.apple.keylayout.Dvorak</inputsourceid_prefix>
      </inputsourcedef>
    </root>
  3. Then, you can use <inputsource_only> and <inputsource_not> in private.xml.

    <?xml version="1.0"?>
    <root>
      <inputsourcedef>
        <name>MY_DVORAK</name>
        <inputsourceid_prefix>com.apple.keylayout.Dvorak</inputsourceid_prefix>
      </inputsourcedef>
    
      <item>
        <name>Swap Space and Tab</name>
        <identifier>private.my_dvorak_swap_space_and_tab</identifier>
        <inputsource_only>MY_DVORAK</inputsource_only>
        <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
        <autogen>__KeyToKey__ KeyCode::TAB, KeyCode::SPACE</autogen>
      </item>
    </root>

Prepared input source definitions

KeyRemap4MacBook provides various input source definitions.
You can use them without <inputsourcedef> in private.xml.

How to examine input source id

You can examine input source id by Event Viewer.

  1. Launch Event Viewer.
  2. Switch input source into target input source.
  3. Switch input source into other input source.
  4. Again, switch input source into target input source.
  5. See Input Source ID in Event Viewer.

An example

This private.xml opens web site, launches calculator and executes a shell command "/bin/date | /usr/bin/pbcopy".

<?xml version="1.0"?>
<root>
  <!-- generic URL -->
  <vkopenurldef>
    <name>KeyCode::VK_OPEN_URL_WEB_keyremap4macbook</name>
    <url>https://pqrs.org/macosx/keyremap4macbook/</url>
  </vkopenurldef>

  <!-- file path -->
  <vkopenurldef>
    <name>KeyCode::VK_OPEN_URL_APP_Calculator</name>
    <url type="file">/Applications/Calculator.app</url>
  </vkopenurldef>

  <!-- shell commands -->
  <vkopenurldef>
    <name>KeyCode::VK_OPEN_URL_SHELL_date_pbcopy</name>
    <url type="shell">
      <![CDATA[    /bin/date | /usr/bin/pbcopy    ]]>
    </url>
  </vkopenurldef>

  <item>
    <name>Change right-command + w to open https://pqrs.org/macosx/keyremap4macbook/</name>
    <identifier>private.right_command_w</identifier>
    <autogen>
      __KeyToKey__
      KeyCode::W, ModifierFlag::COMMAND_R,
      KeyCode::VK_OPEN_URL_WEB_keyremap4macbook,
    </autogen>
  </item>

  <item>
    <name>Change right-command + c to launch calculator</name>
    <identifier>private.right_command_c</identifier>
    <autogen>
      __KeyToKey__
      KeyCode::C, ModifierFlag::COMMAND_R,
      KeyCode::VK_OPEN_URL_APP_Calculator,
    </autogen>
  </item>

  <item>
    <name>Change right-command + d to execute /bin/date | /usr/bin/pbcopy</name>
    <identifier>private.right_command_d</identifier>
    <autogen>
      __KeyToKey__
      KeyCode::D, ModifierFlag::COMMAND_R,
      KeyCode::VK_OPEN_URL_SHELL_date_pbcopy,
    </autogen>
  </item>
</root>

Virtual key code definition

You can define new virtual key code by <vkopenurldef>.

  • <name> is a name of virtual key code. This name must be started with KeyCode::VK_OPEN_URL_.
    For example, <name>KeyCode::VK_OPEN_URL_Yourapp</name>.

  • <url> is a url of virtual key code.
    <url> has a "type" attribute which determines how treat the value.

    Type attribute Description
    (empty) If you does not specify a type attribute, it will be treated as a generic URL.
    type="file" The value will be treated as file path.
    type="shell" The value will be treated as shell commands.

Prepared virtual key code definitions

KeyRemap4MacBook provides various virtual key code definitions.
You can use them without <vkopenurldef> in private.xml.

An example

You can include external xml files by <include>.

private.xml
<?xml version="1.0"?>
<root>
  <include path="core.xml" />
</root>
core.xml
<?xml version="1.0"?>
<root>
  <item>
    <name>Swap Space and Tab</name>
    <identifier>private.swap_space_and_tab</identifier>
    <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
    <autogen>__KeyToKey__ KeyCode::TAB, KeyCode::SPACE</autogen>
  </item>
</root>

<include> with Dropbox

You can synchronize your private.xml by Dropbox or other file syncing service.

private.xml
<?xml version="1.0"?>
<root>
  <include path="{{ ENV_HOME }}/Dropbox/private/KeyRemap4MacBook/core.xml" />
</root>
Dropbox/private/KeyRemap4MacBook/core.xml
<?xml version="1.0"?>
<root>
  <item>
    <name>Dropbox Test!</name>
  </item>
</root>

<include> with <replacementdef>

<replacementdef> in <include> has a local scope. These <replacementdef> are effective only in included file.

private.xml
<?xml version="1.0"?>
<root>
  <!-- Swap Space and Escape -->
  <include path="core.xml">
    <replacementdef>
      <replacementname>KEY1</replacementname>
      <replacementvalue>KeyCode::SPACE</replacementvalue>
    </replacementdef>
    <replacementdef>
      <replacementname>KEY2</replacementname>
      <replacementvalue>KeyCode::ESCAPE</replacementvalue>
    </replacementdef>
  </include>

  <!-- Swap Tab and Return -->
  <include path="core.xml">
    <replacementdef>
      <replacementname>KEY1</replacementname>
      <replacementvalue>KeyCode::TAB</replacementvalue>
    </replacementdef>
    <replacementdef>
      <replacementname>KEY2</replacementname>
      <replacementvalue>KeyCode::RETURN</replacementvalue>
    </replacementdef>
  </include>
</root>
core.xml
<?xml version="1.0"?>
<root>
  <item>
    <name>Swap {{ KEY1 }} and {{ KEY2 }}</name>
    <identifier>private.swap_{{ KEY1 }}_{{ KEY2 }}</identifier>
    <autogen>__KeyToKey__ {{ KEY1 }}, {{ KEY2 }}</autogen>
    <autogen>__KeyToKey__ {{ KEY2 }}, {{ KEY1 }}</autogen>
  </item>
</root>

An example

You can define replacement by <replacementdef>.

<?xml version="1.0"?>
<root>
  <replacementdef>
    <replacementname>MY_IGNORE_APPS</replacementname>
    <replacementvalue>SAFARI, FIREFOX, FINDER</replacementvalue>
  </replacementdef>

  <item>
    <name>Change space to tab except in my ignore apps.</name>
    <identifier>private.space_to_tab_except_my_ignore_apps</identifier>
    <not>{{ MY_IGNORE_APPS }}</not>
    <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
  </item>
</root>

{{ <replacementname> }} is replaced by <replacementvalue>.

<not>{{ MY_IGNORE_APPS }}</not>

<!-- ↑ is replaced to ↓ -->

<not>SAFARI, FIREFOX, FINDER</not>

Global scope replacement

<replacementdef> written in private.xml has a global scope. It is effective for the entire XML.

When you wrote multiple <replacementdef> for one <replacementname>, only the first one is effective.

<?xml version="1.0"?>
<root>
  <replacementdef>
    <replacementname>MY_KEYCODE</replacementname>
    <replacementvalue>KeyCode::SPACE</replacementvalue>
  </replacementdef>

  <!-- This replacementdef of MY_KEYCODE is ignored -->
  <replacementdef>
    <replacementname>MY_KEYCODE</replacementname>
    <replacementvalue>KeyCode::TAB</replacementvalue>
  </replacementdef>

  <item>
    <name>{{ MY_KEYCODE }} is KeyCode::SPACE</name>
  </item>
</root>

Local scope replacement

You can define a local scope replacement by using <replacementdef> under <include>.
See <include> with <replacementdef> section.

Prepared replacement definitions

KeyRemap4MacBook provides various replacement definitions.
You can use them without <replacementdef> in private.xml.

You can also overwrite existent replacement definitions by private.xml.
An example of overwriting VI_H:

<?xml version="1.0"?>
<root>
  <replacementdef>
    <replacementname>VI_H</replacementname>
    <replacementvalue>KeyCode::J</replacementvalue>
  </appdef>
</root>

An example

You can define new KeyCode by <symbol_map>.

<?xml version="1.0"?>
<root>
  <symbol_map type="KeyCode" name="MY_LANGUAGE_KEY" value="0x32" />

  <item>
    <name>Change KeyCode::MY_LANGUAGE_KEY to tab.</name>
    <identifier>private.my_language_key_to_tab</identifier>
    <autogen>__KeyToKey__ KeyCode::MY_LANGUAGE_KEY, KeyCode::TAB</autogen>
  </item>
</root>

Specify a raw value

You can specify a raw value by using KeyCode::RawValue.

<?xml version="1.0"?>
<root>
  <item>
    <name>Change right option key to tab key</name>
    <identifier>private.right_option_key_to_tab_key</identifier>
    <!-- change right option key (0x3d) to tab key (0x30) -->
    <autogen>__KeyToKey__ KeyCode::RawValue::0x3d, KeyCode::RawValue::0x30</autogen>
  </item>
</root>
  1. Get source code from repository.
  2. Prepared settings are defined in these files: Modify them.
  3. Install XML files. Execute these commands in Terminal.
     $ cd src/core/server/Resources
     $ make install
    
    (This commands ask your password in order to modify XML files in /Applications/KeyRemap4MacBook.app.)
  4. Then, reload XML files by "ReloadXML" button on Preference.
Please send a pull request on GitHub when improvement is complete.