Hotkeys

Plugins bind global hotkeys that work in any app. You can change every one of them in Settings, give a shortcut to any app or launcher command, and see the full list in one overlay.

Where hotkeys come from

Plugin hotkeys. A plugin binds a combo at load with macotron.keyboard.on(). Window Controls, for example, binds ⌃⌥← to Left Half.
Command shortcuts. Any launcher command, app, or plugin row can have a shortcut. Plugins do not set these; you do.
App shortcuts. A combo that opens an app, set in Settings → Shortcuts.
Macotron's own. The launcher hotkey (⌥Space by default) and the Show Hotkeys overlay.

// The first argument is the label in Settings. The second is the default combo.
macotron.keyboard.on("Hello", "cmd+shift+h", () => {
  macotron.notify.toast("Hello", "From a Macotron plugin");
});

Combos are written as modifiers and a key joined with +. Modifiers are cmd, shift, ctrl, opt, and hyper. Named keys include space, return, tab, escape, delete, the arrows left right up down, home, end, pageup, and pagedown.

Changing a hotkey

Open Settings → Plugins and select the plugin. Its page has two lists:

Shortcuts: the hotkeys the plugin binds. Click a field and press a new combo to replace the default.
Commands: the plugin's launcher commands. Record a combo to run a command without opening the launcher.

You can also assign a shortcut from the launcher: select a row and press ⌘K. See Launcher.

Your choices are saved in settings.json in the workdir, so they survive reloads and updates to the plugin.

App shortcuts

Settings → Shortcuts holds shortcuts that open apps. Click +, choose an application (or Other… to pick one from disk), and record a combo. The same shortcut hides the app when it is already in front, so one key toggles it.

Launcher and Show Hotkeys

Settings → General has two recorders:

Launcher Hotkey: opens the launcher. The default is ⌥Space.
Show Hotkeys: opens an overlay that lists every bound combo with its label. It has no default combo. You can always run Show Hotkeys from the launcher.

Press Esc, click elsewhere, or press the hotkey again to close the overlay.

Conflicts

When two bindings use the same combo, Settings shows "Also used by" under the field, followed by the names of the others. A plugin with a conflict is marked in the Settings → Plugins list. Change one of the combos to fix it.

Hyper key

The built-in Hyper Key plugin turns Caps Lock into a Hyper key: Command, Shift, Control, and Option together. Combos that no app uses on its own are then easy to press. Bind them with the hyper modifier:

macotron.keyboard.setHyperKey("caps");
macotron.keyboard.on("Hyper H", "hyper+h", () => {
  macotron.notify.toast("Hyper", "Hyper+H");
});

setHyperKey also accepts "fn" to use the Fn key instead.

Hotkeys that watch the keyboard, such as the Hyper key and Option-Tab in the Window Switcher, need Input Monitoring and Accessibility. See Permissions.