docs » LeftRightHotkey

This spoon addresses a limitation within the hs.hotkey module that allows the creation of hotkeys bound to specific left or right keyboard modifiers while leaving the other side free.

This is accomplished by creating unactivated hotkeys for each definition and using an hs.eventtap watcher to detect when modifier keys are pressed and conditionally activating only those hotkeys which correspond to the left or right modifiers currently active as specified by the bind and new methods of this spoon.

The LeftRightHotkeyObject that is returned by LeftRightHotkey:new and LeftRightHotkey:bind supports the following methods in a manner similar to the hs.hotkey equivalents:

The following modifiers are recognized by this spoon in the modifier table when setting up hotkeys with this spoon:

The modifiers table for any given hotkey is all inclusive; this means that if you specify { "rShift", "lShift" } then both the left and right shift keys must be pressed to trigger the hotkey -- if you want either/or, then stick with hs.hotkey.

Alternatively, if you want to setup a hotkey when either command key is pressed with only the right shift, you would need to set up two hotkeys with this spoon: e.g. LeftRightHotkey:bind({ "rCmd", "rShift" }, "a", myFunction) and LeftRightHotkey:bind({ "lCmd", "rShift" }, "a", myFunction)

This spoon works by using an eventtap to detect flag changes (modifier keys) and when they change, the appropriate hotkeys are enabled or disabled. This means that you should be aware of the following:

Like all Spoons, don't forget to use the LeftRightHotkey:start() method to activate the modifier key watcher.

Download: https://github.com/Hammerspoon/Spoons/raw/master/Spoons/LeftRightHotkey.spoon.zip

API Overview

API Documentation

Methods

bind
Signature LeftRightHotkey:bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject
Type Method
Description

Create and enable a new hotkey with the specified left/right specific modifiers.
Parameters
  • mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
    • "lCmd", "lCommand", or "l⌘" for the left Command modifier
    • "rCmd", "rCommand", or "r⌘" for the right Command modifier
    • "lCtrl", "lControl" or "l⌃" for the left Control modifier
    • "rCtrl", "rControl" or "r⌃" for the right Control modifier
    • "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
    • "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
    • "lShift" or "l⇧" for the left Shift modifier
    • "rShift" or "r⇧" for the right Shift modifier
  • key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
  • message - (optional) A string containing a message to be displayed via hs.alert() when the hotkey has been triggered; if omitted, no alert will be shown
  • pressedfn - A function that will be called when the hotkey has been pressed, or nil
  • releasedfn - A function that will be called when the hotkey has been released, or nil
  • repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
Returns
  • a new enabled hotkey with the specified left/right modifiers.
Notes
  • This function is just a wrapper that performs LeftRightHotkey:new(...):enable()
  • The modifiers table is adjusted for use when conditionally activating the appropriate hotkeys based on the current modifiers in effect, but the other arguments are passed to hs.hotkey.bind as is and any caveats or considerations outlined there also apply here.
Source Source/LeftRightHotkey.spoon/init.lua line 415
deleteAll
Signature LeftRightHotkey:deleteAll(mods, key)
Type Method
Description

Deletes all previously set callbacks for a given keyboard combination
Parameters
  • mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
    • "lCmd", "lCommand", or "l⌘" for the left Command modifier
    • "rCmd", "rCommand", or "r⌘" for the right Command modifier
    • "lCtrl", "lControl" or "l⌃" for the left Control modifier
    • "rCtrl", "rControl" or "r⌃" for the right Control modifier
    • "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
    • "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
    • "lShift" or "l⇧" for the left Shift modifier
    • "rShift" or "r⇧" for the right Shift modifier
  • key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
Returns
  • None
Source Source/LeftRightHotkey.spoon/init.lua line 326
disableAll
Signature LeftRightHotkey:disableAll(mods, key)
Type Method
Description

Disables all previously set callbacks for a given keyboard combination
Parameters
  • mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
    • "lCmd", "lCommand", or "l⌘" for the left Command modifier
    • "rCmd", "rCommand", or "r⌘" for the right Command modifier
    • "lCtrl", "lControl" or "l⌃" for the left Control modifier
    • "rCtrl", "rControl" or "r⌃" for the right Control modifier
    • "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
    • "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
    • "lShift" or "l⇧" for the left Shift modifier
    • "rShift" or "r⇧" for the right Shift modifier
  • key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
Returns
  • None
Source Source/LeftRightHotkey.spoon/init.lua line 373
new
Signature LeftRightHotkey:new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject
Type Method
Description

Create a new hotkey with the specified left/right specific modifiers.
Parameters
  • mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
    • "lCmd", "lCommand", or "l⌘" for the left Command modifier
    • "rCmd", "rCommand", or "r⌘" for the right Command modifier
    • "lCtrl", "lControl" or "l⌃" for the left Control modifier
    • "rCtrl", "rControl" or "r⌃" for the right Control modifier
    • "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
    • "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
    • "lShift" or "l⇧" for the left Shift modifier
    • "rShift" or "r⇧" for the right Shift modifier
  • key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
  • message - (optional) A string containing a message to be displayed via hs.alert() when the hotkey has been triggered; if omitted, no alert will be shown
  • pressedfn - A function that will be called when the hotkey has been pressed, or nil
  • releasedfn - A function that will be called when the hotkey has been released, or nil
  • repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
Returns
  • a new, initially disabled, hotkey with the specified left/right modifiers.
Notes
  • The modifiers table is adjusted for use when conditionally activating the appropriate hotkeys based on the current modifiers in effect, but the other arguments are passed to hs.hotkey.new as is and any caveats or considerations outlined there also apply here.
Source Source/LeftRightHotkey.spoon/init.lua line 263
start
Signature LeftRightHotkey:start() -> self
Type Method
Description

Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
Parameters
  • None
Returns
  • the LeftRightHotkey spoon object
Notes
  • this enables the use of hotkeys created by using this Spoon.
Source Source/LeftRightHotkey.spoon/init.lua line 444
stop
Signature LeftRightHotkey:stop() -> self
Type Method
Description

Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
Parameters
  • None
Returns
  • the LeftRightHotkey spoon object
Notes
  • this will implicitly disable all hotkeys created by using this Spoon -- only those hotkeys which are defined with hs.hotkey directly will still be available.
Source Source/LeftRightHotkey.spoon/init.lua line 471