grettke/maccadet

Use all of Emacs modifiers on macOS with various keyboards.

MacCadet

About

Use all of Emacs’s modifiers on macOS with various keyboards.

Table of Contents

• About
• Table of Contents
• Purpose
• Goal
• Usage
• First: The Legend
• Software
• Hardware

Purpose

When non-Emacs users observe Emacs users laboring over their key binding configuration their typical range of reactions include finding it to be interesting, surprising, remarkable, strange, weird, incredible, striking, bizarre, deviant, eccentric, freakish, monstrous, incomprehensible, inconceivable, incredible, unimaginable, and unthinkable. With that range reactions in mind it is self-evident that if you are reading this then you already know why you want to use more of the Emacs’s modifier keys you just want to know how. The purpose of this project is to capture one way of using all of Emacs’s modifier keys.

Goal

• Usable on stock Mac keyboards and Windows (ANSI) keyboard.
• Mirrored meta keys as much as possible
• Minimize invasive changes to
  • the physical keyboard layout
  • the Emacs bindings for which you already have strong muscle memory.
  • the built-in macOS keybindings
  • the most egregious violation here is stomping on:
    • F3
      • On Mac OS X: Opens Mission Control.
      • On Windows: Opens search feature in Windows Explorer.
      • In MS Word: Shift + F3 lets you change from lowercase to uppercase to all caps.
      • In Chrome and Firefox: Opens find feature
    • F4
      • On Mac OS X: Opens Launchpad
      • On Windows: Alt + F4 closes window. In Windows Explorer places the cursor in the address bar in Explorer
• Leave door open to “correcting” physical keyboard layout and built-in macOS keybindings to our advantage.
  • For example stomp on probably useless keys to make our real life easier.

Usage

Load maccadet.el file in your init file and study it. It defines the mapping between the USB modifiers CONTROL, GUI, and ALT (see USB Modifier Specification) and the Emacs modifiers.

To put those mappings into effect you can either configure your keyboard using software or using hardware.

The software route uses Karabiner-Elements:

• Pros
  • Works on any keyboard
  • Doesn’t require configuring a keyboard using special software
  • Adapts to just about anything keyboard device
• Cons
  • If Karabiner-Elements ever ceases to exist then you can’t use this

The hardware route uses a programmable keyboard. For example using a Durgod Taurus K320 TKL and their Zeus Engine (keyboard configurator software) that runs on Windows.

• Pros
  • Doesn’t require Karabiner-Elements
• Cons
  • Hard to program, requires a Windows box

This page documents using both the software and hardware route.

First: The Legend

The work of each configuration is mapping from one key to another so this Emacs config can give you better modifier key bindings. In order to make sense of the approach there are screenshots documenting them. Since they’ll show up in the software and hardware configuration it is better to read about the approach first. Here is how it will work:

Key Color Code provide a quick reminder for how and why the key is configured:

Pink Keys

Remapped from their hardware configuration providing modifier.

Orange Keys

Provide modifier without remapping.

Cyan Keys

Relocated keys stolen for modifiers.

Read the text on the keys from bottom to top on a Mac keyboard. On a Windows keyboard they are listed in reverse order: Physical key name, mapped to, then Emacs key.

• The Emacs modifier it provides: if it provides one (Orange keys don’t), otherwise it is blank
  • Here are the characters for specifying the modifier in your key bindings (these are the last character listed on the keycap here):

  C

  Control

  M

  Meta

  s

  Super

  H

  Hyper

  A

  Alt

• The key it is getting mapped to (either a USB spec modifier name or a shortened ANSI name).
• Physical key name.

Software

Karabiner-Elements config file is karabiner.json

karabiner.json defines a single profile named MacCadet.

The MacCadet profile defines key mappings for multiple keyboards.

For example under Devices \rarr Basic configuration you’ll see both an Apple internal keyboard and a USB Keyboard listed. Each keyboard is configured individually within the single profile. Before looking at how keyboards are used with MacCadet read about how Karabiner is configured here.

All keyboards have a unique Vendor ID and Product ID. If Karabiner recognizes your keyboard then it will show up listed correctly under Devices. If it doesn’t recognize your keyboard then it will probably get listed as USB Keyboard (No manufacturer name). However your keyboard shows up we can add it to this configuration with its real name along with the Vendor and Product ID. The following show the current configuration along with keyboard types.

• MacBook Pro Late 2013
  • Device: Apple Internal Keyboard / Trackpad (Apple Inc.)
  • Vendor ID 1452
  • Product ID 610

• WASD Code V2 PS2/USB
  • Device: USB Keyboard (No manufacturer name)
  • Vendor ID 1241
  • Product ID 361

Hardware

Keychron C3 Pro

• This keyboard uses QMK Firmware. You are free to modify every key. Consequently you can redefine even the keyboard-specifc “Menu (M1)” key itself. This configuration is the same as the with the exception that the M1 gets pushed to the end of the bottom row. Its nice to keep all of the modifiers on the bottom row. That alone warrants buying a QMK-based keyboard.
• This is identical to the WASD with M1 and Right-Control swapped
• This report doesn’t store the configuration

Durgod Taurus

• Durgod Taurus K320 TKL
  • Configured the same as the WASD but the Fn is disabled instead of the Menu key.

You need a Durgod Taurus K320 TKL and their Zeus Engine (keyboard configurator software) that runs on Windows.

The Durgod uses DurgodTaurusK320TKL.xml for their Zeus Engine. Import it as a custom profile then flash it to your keyboard.

This configuration is fun because it uses the right side page navigation keys (Home, End, …) as an Emacs modifier cluster. With this approach you can press the keys “Control-Meta-Super-Hyper-Alt-Shift” with one hand. In practice though this keyboard’s configuration in the first part is more practical and consistent with the MacBook Pro approach making it easier when you switch between the laptop and it’s exter

Note that is an upper-case L:

(defun test () (interactive) (message "Yup, it worked."))
(global-set-key (kbd "C-M-s-H-A-L") #'test)

It is worth trying out just for the fun of it. Surely there is someone out there who can take advantage of this. For the rest of us, MacCadet leaves those keys alone because they can be akward to use.