Macotron

macotron.keyboard

Register global hotkeys that the user can rebind in Settings, read which modifier keys are down, and turn Caps Lock or Fn into a Hyper key.

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

Hotkeys

on(id: string, defaultCombo: string, callback: () => void): void

Calls callback when the user presses the combo, in any app. id is the label the user sees in Settings → Plugins, and it must be unique within the plugin. defaultCombo is the combo to use until the user picks another one in Settings. If the user clears the shortcut, it stays off.

Register hotkeys when the plugin loads. Global hotkeys need no permission.

For a command that should also show in the launcher, use macotron.command with an id instead. The user can give it a shortcut in the same place.

Combo strings

A combo is modifiers and one key joined with +, in any case, such as "cmd+shift+c" or "ctrl+opt+left".

PartNames
Modifierscmd (command, meta), shift, ctrl (control), opt (option, alt), and hyper, which means all four together
Letters and digitsa to z, 0 to 9
Function keysf1 to f12
Named keysleft, right, up, down, return (enter), tab, space, delete (backspace), forwarddelete, escape (esc), home, end, pageup, pagedown
Punctuation- = [ ] ; ' \ , . / `, or by name: minus, equal, leftbracket, rightbracket, semicolon, quote, backslash, comma, period, slash, grave

Keys are matched by their position on a US keyboard. A combo that does not parse is skipped and logged.

Modifier state

flags(): { cmd, shift, ctrl, opt, caps, fn }

Which modifier keys are held right now, each a boolean. caps is true while Caps Lock is on.

macotron.command("Open Notes", "Hold Shift for a new window", () => {
  const { shift } = macotron.keyboard.flags();
  // ...
});

Hyper key

setHyperKey(key: "caps" | "fn" | null): boolean

While the key is held, every key you press also carries Command, Shift, Control, and Option. Bind combos to it with hyper+. The Caps Lock or Fn press itself is swallowed, so Caps Lock no longer toggles caps.

Pass null to turn it off. Returns false for any other value, or when the keyboard tap cannot be installed, which usually means Macotron lacks Accessibility permission.

hyperKey(): "caps" | "fn" | null

The current Hyper key, or null when none is set.

Events

keyboard:<binding>

on() subscribes your callback to this event for you. The name is keyboard: followed by {filename}/{id}. It has no payload.

See also