+ 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:
+
+LeftRightHotkeyObject:enable() -- enables the registered hotkey.LeftRightHotkeyObject:disable() -- disables the registered hotkey.LeftRightHotkeyObject:delete() -- deletes the registered hotkey.- `LeftRightHotkeyObject:isEnabled() -- returns a boolean value specifying whether the hotkey is currently enabled (true) or disabled (false)
+
+The following modifiers are recognized by this spoon in the modifier table when setting up hotkeys with this spoon:
+
+- "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
+
+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 eventtaps, if the Hammerspoon application is particularly busy with some other task, it is possible for the flag change to be missed or for the macOS to disable the eventtap entirely.
+- behind the scenes, when a given set of flag changes occur that match a defined hotkey, the hotkey is actually enabled through
hs.hotkey:enable() -- this means that in truth, either side's modifiers would trigger the callback. Under normal circumstances this won't be noticed because as soon as you switch to the alternate side's modifier, the flag change event will be detected and the hotkey will be disabled. However, as noted above, if Hammerspoon is particularly busy, it is possible for this event to be missed.
+- a timer runs (once this Spoon has been started the first time) which will check to see if the eventtap has been internally disabled and re-enable it if necessary; alternatively you can re-issue LeftRightHotkey:start() to force the eventtap to be reset if necessary.
+- if your hotkeys seem out of sync, try pressing and releasing any modifier key -- this will reset the enabled/disabled hotkeys if a previous flag change was missed, but the eventtap is still running or has been reset by one of the methods described above.
+
+
+
+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
+
+
+
diff --git a/docs/templated_docs.json b/docs/templated_docs.json
index 751990a2..b8240850 100644
--- a/docs/templated_docs.json
+++ b/docs/templated_docs.json
@@ -9715,6 +9715,369 @@
"submodules": [],
"type": "Module"
},
+ {
+ "Command": [],
+ "Constant": [],
+ "Constructor": [],
+ "Deprecated": [],
+ "Field": [],
+ "Function": [],
+ "Method": [
+ {
+ "def": "LeftRightHotkey:bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "def_gfm": "LeftRightHotkey:bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "desc": "Create and enable a new hotkey with the specified left/right specific modifiers.",
+ "desc_gfm": "Create and enable a new hotkey with the specified left/right specific modifiers.
\n",
+ "doc": "Create and enable a new hotkey with the specified left/right specific modifiers.\n\nParameters:\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) when the hotkey has been triggered; if omitted, no alert will be shown\n * pressedfn - A function that will be called when the hotkey has been pressed, or nil\n * releasedfn - A function that will be called when the hotkey has been released, or nil\n * repeatfn - A function that will be called when a pressed hotkey is repeating, or nil\n\nReturns:\n * a new enabled hotkey with the specified left/right modifiers.\n\nNotes:\n * This function is just a wrapper that performs `LeftRightHotkey:new(...):enable()`\n * 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](hs.hotkey.html#bind) as is and any caveats or considerations outlined there also apply here.",
+ "doc_gfm": "Create and enable a new hotkey with the specified left/right specific modifiers.
\nParameters:\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\nReturns:
\n\n- a new enabled hotkey with the specified left/right modifiers.
\n
\nNotes:
\n\n- This function is just a wrapper that performs
LeftRightHotkey:new(...):enable() \n- 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.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "415",
+ "name": "bind",
+ "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](hs.hotkey.html#bind) as is and any caveats or considerations outlined there also apply here."
+ ],
+ "notes_gfm": "\n- This function is just a wrapper that performs
LeftRightHotkey:new(...):enable() \n- 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.
\n
\n",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number",
+ " * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) 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"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\n",
+ "returns": [
+ " * a new enabled hotkey with the specified left/right modifiers."
+ ],
+ "returns_gfm": "\n- a new enabled hotkey with the specified left/right modifiers.
\n
\n",
+ "signature": "LeftRightHotkey:bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:deleteAll(mods, key)",
+ "def_gfm": "LeftRightHotkey:deleteAll(mods, key)",
+ "desc": "Deletes all previously set callbacks for a given keyboard combination",
+ "desc_gfm": "Deletes all previously set callbacks for a given keyboard combination
\n",
+ "doc": "Deletes all previously set callbacks for a given keyboard combination\n\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n\nReturns:\n * None",
+ "doc_gfm": "Deletes all previously set callbacks for a given keyboard combination
\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\nReturns:
\n\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "326",
+ "name": "deleteAll",
+ "notes": [],
+ "notes_gfm": "",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\n",
+ "returns": [
+ " * None"
+ ],
+ "returns_gfm": "\n",
+ "signature": "LeftRightHotkey:deleteAll(mods, key)",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:disableAll(mods, key)",
+ "def_gfm": "LeftRightHotkey:disableAll(mods, key)",
+ "desc": "Disables all previously set callbacks for a given keyboard combination",
+ "desc_gfm": "Disables all previously set callbacks for a given keyboard combination
\n",
+ "doc": "Disables all previously set callbacks for a given keyboard combination\n\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n\nReturns:\n * None",
+ "doc_gfm": "Disables all previously set callbacks for a given keyboard combination
\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\nReturns:
\n\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "373",
+ "name": "disableAll",
+ "notes": [],
+ "notes_gfm": "",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\n",
+ "returns": [
+ " * None"
+ ],
+ "returns_gfm": "\n",
+ "signature": "LeftRightHotkey:disableAll(mods, key)",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "def_gfm": "LeftRightHotkey:new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "desc": "Create a new hotkey with the specified left/right specific modifiers.",
+ "desc_gfm": "Create a new hotkey with the specified left/right specific modifiers.
\n",
+ "doc": "Create a new hotkey with the specified left/right specific modifiers.\n\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) when the hotkey has been triggered; if omitted, no alert will be shown\n * pressedfn - A function that will be called when the hotkey has been pressed, or nil\n * releasedfn - A function that will be called when the hotkey has been released, or nil\n * repeatfn - A function that will be called when a pressed hotkey is repeating, or nil\n\nReturns:\n * a new, initially disabled, hotkey with the specified left/right modifiers.\n\nNotes:\n * 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](hs.hotkey.html#new) as is and any caveats or considerations outlined there also apply here.",
+ "doc_gfm": "Create a new hotkey with the specified left/right specific modifiers.
\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\nReturns:
\n\n- a new, initially disabled, hotkey with the specified left/right modifiers.
\n
\nNotes:
\n\n- 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.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "263",
+ "name": "new",
+ "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](hs.hotkey.html#new) as is and any caveats or considerations outlined there also apply here."
+ ],
+ "notes_gfm": "\n- 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.
\n
\n",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number",
+ " * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) 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"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\n",
+ "returns": [
+ " * a new, initially disabled, hotkey with the specified left/right modifiers."
+ ],
+ "returns_gfm": "\n- a new, initially disabled, hotkey with the specified left/right modifiers.
\n
\n",
+ "signature": "LeftRightHotkey:new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:start() -> self",
+ "def_gfm": "LeftRightHotkey:start() -> self",
+ "desc": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.",
+ "desc_gfm": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\n",
+ "doc": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.\n\nParameters:\n * None\n\nReturns:\n * the LeftRightHotkey spoon object\n\nNotes:\n * this enables the use of hotkeys created by using this Spoon.",
+ "doc_gfm": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\nParameters:
\n\nReturns:
\n\n- the LeftRightHotkey spoon object
\n
\nNotes:
\n\n- this enables the use of hotkeys created by using this Spoon.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "444",
+ "name": "start",
+ "notes": [
+ " * this enables the use of hotkeys created by using this Spoon."
+ ],
+ "notes_gfm": "\n- this enables the use of hotkeys created by using this Spoon.
\n
\n",
+ "parameters": [
+ " * None"
+ ],
+ "parameters_gfm": "\n",
+ "returns": [
+ " * the LeftRightHotkey spoon object"
+ ],
+ "returns_gfm": "\n- the LeftRightHotkey spoon object
\n
\n",
+ "signature": "LeftRightHotkey:start() -> self",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:stop() -> self",
+ "def_gfm": "LeftRightHotkey:stop() -> self",
+ "desc": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.",
+ "desc_gfm": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\n",
+ "doc": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.\n\nParameters:\n * None\n\nReturns:\n * the LeftRightHotkey spoon object\n\nNotes:\n * this will implicitly disable all hotkeys created by using this Spoon -- only those hotkeys which are defined with [hs.hotkey](hs.hotkey.html) directly will still be available.",
+ "doc_gfm": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\nParameters:
\n\nReturns:
\n\n- the LeftRightHotkey spoon object
\n
\nNotes:
\n\n- 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.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "471",
+ "name": "stop",
+ "notes": [
+ " * this will implicitly disable all hotkeys created by using this Spoon -- only those hotkeys which are defined with [hs.hotkey](hs.hotkey.html) directly will still be available."
+ ],
+ "notes_gfm": "\n- 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.
\n
\n",
+ "parameters": [
+ " * None"
+ ],
+ "parameters_gfm": "\n",
+ "returns": [
+ " * the LeftRightHotkey spoon object"
+ ],
+ "returns_gfm": "\n- the LeftRightHotkey spoon object
\n
\n",
+ "signature": "LeftRightHotkey:stop() -> self",
+ "stripped_doc": "",
+ "type": "Method"
+ }
+ ],
+ "Variable": [],
+ "desc": "This spoon addresses a limitation within the [hs.hotkey](hs.hotkey.html) module that allows the creation of hotkeys bound to specific left or right keyboard modifiers while leaving the other side free.",
+ "desc_gfm": "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.
\n",
+ "doc": "This spoon addresses a limitation within the [hs.hotkey](hs.hotkey.html) module that allows the creation of hotkeys bound to specific left or right keyboard modifiers while leaving the other side free.\n\nThis is accomplished by creating unactivated hotkeys for each definition and using an [hs.eventtap](hs.eventtap.html) 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.\n\nThe `LeftRightHotkeyObject` that is returned by [LeftRightHotkey:new](#new) and [LeftRightHotkey:bind](#bind) supports the following methods in a manner similar to the [hs.hotkey](hs.hotkey.html) equivalents:\n\n * `LeftRightHotkeyObject:enable()` -- enables the registered hotkey.\n * `LeftRightHotkeyObject:disable()` -- disables the registered hotkey.\n * `LeftRightHotkeyObject:delete()` -- deletes the registered hotkey.\n * `LeftRightHotkeyObject:isEnabled() -- returns a boolean value specifying whether the hotkey is currently enabled (true) or disabled (false)\n\nThe following modifiers are recognized by this spoon in the modifier table when setting up hotkeys with this spoon:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n\nThe 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](hs.hotkey.html).\n\nAlternatively, 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:\n e.g. `LeftRightHotkey:bind({ \"rCmd\", \"rShift\" }, \"a\", myFunction)` *and* `LeftRightHotkey:bind({ \"lCmd\", \"rShift\" }, \"a\", myFunction)`\n\nThis 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:\n * like all eventtaps, if the Hammerspoon application is particularly busy with some other task, it is possible for the flag change to be missed or for the macOS to disable the eventtap entirely.\n * behind the scenes, when a given set of flag changes occur that match a defined hotkey, the hotkey is actually enabled through `hs.hotkey:enable()` -- this means that in truth, either side's modifiers would trigger the callback. Under normal circumstances this won't be noticed because as soon as you switch to the alternate side's modifier, the flag change event will be detected and the hotkey will be disabled. However, as noted above, if Hammerspoon is particularly busy, it is possible for this event to be missed.\n * a timer runs (once this Spoon has been started the first time) which will check to see if the eventtap has been internally disabled and re-enable it if necessary; alternatively you can re-issue [LeftRightHotkey:start()](#start) to force the eventtap to be reset if necessary.\n * if your hotkeys seem out of sync, try pressing and releasing any modifier key -- this will reset the enabled/disabled hotkeys if a previous flag change was missed, but the eventtap is still running or has been reset by one of the methods described above.\n\nLike all Spoons, don't forget to use the [LeftRightHotkey:start()](#start) method to activate the modifier key watcher.\n\nDownload: [https://github.com/Hammerspoon/Spoons/raw/master/Spoons/LeftRightHotkey.spoon.zip](https://github.com/Hammerspoon/Spoons/raw/master/Spoons/LeftRightHotkey.spoon.zip)",
+ "doc_gfm": "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.
\nThis 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.
\nThe LeftRightHotkeyObject that is returned by LeftRightHotkey:new and LeftRightHotkey:bind supports the following methods in a manner similar to the hs.hotkey equivalents:
\n\nLeftRightHotkeyObject:enable() -- enables the registered hotkey.LeftRightHotkeyObject:disable() -- disables the registered hotkey.LeftRightHotkeyObject:delete() -- deletes the registered hotkey.- `LeftRightHotkeyObject:isEnabled() -- returns a boolean value specifying whether the hotkey is currently enabled (true) or disabled (false)
\n
\nThe following modifiers are recognized by this spoon in the modifier table when setting up hotkeys with this spoon:
\n\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\nThe 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.
\nAlternatively, 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:\n e.g. LeftRightHotkey:bind({ "rCmd", "rShift" }, "a", myFunction) and LeftRightHotkey:bind({ "lCmd", "rShift" }, "a", myFunction)
\nThis 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:
\n\n- like all eventtaps, if the Hammerspoon application is particularly busy with some other task, it is possible for the flag change to be missed or for the macOS to disable the eventtap entirely.
\n- behind the scenes, when a given set of flag changes occur that match a defined hotkey, the hotkey is actually enabled through
hs.hotkey:enable() -- this means that in truth, either side's modifiers would trigger the callback. Under normal circumstances this won't be noticed because as soon as you switch to the alternate side's modifier, the flag change event will be detected and the hotkey will be disabled. However, as noted above, if Hammerspoon is particularly busy, it is possible for this event to be missed.\n- a timer runs (once this Spoon has been started the first time) which will check to see if the eventtap has been internally disabled and re-enable it if necessary; alternatively you can re-issue LeftRightHotkey:start() to force the eventtap to be reset if necessary.
\n- if your hotkeys seem out of sync, try pressing and releasing any modifier key -- this will reset the enabled/disabled hotkeys if a previous flag change was missed, but the eventtap is still running or has been reset by one of the methods described above.
\n
\n \n
\nLike all Spoons, don't forget to use the LeftRightHotkey:start() method to activate the modifier key watcher.
\nDownload: https://github.com/Hammerspoon/Spoons/raw/master/Spoons/LeftRightHotkey.spoon.zip
\n",
+ "items": [
+ {
+ "def": "LeftRightHotkey:bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "def_gfm": "LeftRightHotkey:bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "desc": "Create and enable a new hotkey with the specified left/right specific modifiers.",
+ "desc_gfm": "Create and enable a new hotkey with the specified left/right specific modifiers.
\n",
+ "doc": "Create and enable a new hotkey with the specified left/right specific modifiers.\n\nParameters:\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) when the hotkey has been triggered; if omitted, no alert will be shown\n * pressedfn - A function that will be called when the hotkey has been pressed, or nil\n * releasedfn - A function that will be called when the hotkey has been released, or nil\n * repeatfn - A function that will be called when a pressed hotkey is repeating, or nil\n\nReturns:\n * a new enabled hotkey with the specified left/right modifiers.\n\nNotes:\n * This function is just a wrapper that performs `LeftRightHotkey:new(...):enable()`\n * 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](hs.hotkey.html#bind) as is and any caveats or considerations outlined there also apply here.",
+ "doc_gfm": "Create and enable a new hotkey with the specified left/right specific modifiers.
\nParameters:\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\nReturns:
\n\n- a new enabled hotkey with the specified left/right modifiers.
\n
\nNotes:
\n\n- This function is just a wrapper that performs
LeftRightHotkey:new(...):enable() \n- 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.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "415",
+ "name": "bind",
+ "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](hs.hotkey.html#bind) as is and any caveats or considerations outlined there also apply here."
+ ],
+ "notes_gfm": "\n- This function is just a wrapper that performs
LeftRightHotkey:new(...):enable() \n- 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.
\n
\n",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number",
+ " * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) 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"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\n",
+ "returns": [
+ " * a new enabled hotkey with the specified left/right modifiers."
+ ],
+ "returns_gfm": "\n- a new enabled hotkey with the specified left/right modifiers.
\n
\n",
+ "signature": "LeftRightHotkey:bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:deleteAll(mods, key)",
+ "def_gfm": "LeftRightHotkey:deleteAll(mods, key)",
+ "desc": "Deletes all previously set callbacks for a given keyboard combination",
+ "desc_gfm": "Deletes all previously set callbacks for a given keyboard combination
\n",
+ "doc": "Deletes all previously set callbacks for a given keyboard combination\n\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n\nReturns:\n * None",
+ "doc_gfm": "Deletes all previously set callbacks for a given keyboard combination
\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\nReturns:
\n\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "326",
+ "name": "deleteAll",
+ "notes": [],
+ "notes_gfm": "",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\n",
+ "returns": [
+ " * None"
+ ],
+ "returns_gfm": "\n",
+ "signature": "LeftRightHotkey:deleteAll(mods, key)",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:disableAll(mods, key)",
+ "def_gfm": "LeftRightHotkey:disableAll(mods, key)",
+ "desc": "Disables all previously set callbacks for a given keyboard combination",
+ "desc_gfm": "Disables all previously set callbacks for a given keyboard combination
\n",
+ "doc": "Disables all previously set callbacks for a given keyboard combination\n\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n\nReturns:\n * None",
+ "doc_gfm": "Disables all previously set callbacks for a given keyboard combination
\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\nReturns:
\n\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "373",
+ "name": "disableAll",
+ "notes": [],
+ "notes_gfm": "",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n
\n",
+ "returns": [
+ " * None"
+ ],
+ "returns_gfm": "\n",
+ "signature": "LeftRightHotkey:disableAll(mods, key)",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "def_gfm": "LeftRightHotkey:new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "desc": "Create a new hotkey with the specified left/right specific modifiers.",
+ "desc_gfm": "Create a new hotkey with the specified left/right specific modifiers.
\n",
+ "doc": "Create a new hotkey with the specified left/right specific modifiers.\n\nParameters:\n * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number\n * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) when the hotkey has been triggered; if omitted, no alert will be shown\n * pressedfn - A function that will be called when the hotkey has been pressed, or nil\n * releasedfn - A function that will be called when the hotkey has been released, or nil\n * repeatfn - A function that will be called when a pressed hotkey is repeating, or nil\n\nReturns:\n * a new, initially disabled, hotkey with the specified left/right modifiers.\n\nNotes:\n * 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](hs.hotkey.html#new) as is and any caveats or considerations outlined there also apply here.",
+ "doc_gfm": "Create a new hotkey with the specified left/right specific modifiers.
\nParameters:
\n\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\nReturns:
\n\n- a new, initially disabled, hotkey with the specified left/right modifiers.
\n
\nNotes:
\n\n- 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.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "263",
+ "name": "new",
+ "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](hs.hotkey.html#new) as is and any caveats or considerations outlined there also apply here."
+ ],
+ "notes_gfm": "\n- 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.
\n
\n",
+ "parameters": [
+ " * mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier",
+ " * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number",
+ " * message - (optional) A string containing a message to be displayed via [hs.alert()](hs.alert.html) 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"
+ ],
+ "parameters_gfm": "\n- mods - A table containing as elements the keyboard modifiers required, which should be one or more of the following:
\n- "lCmd", "lCommand", or "l⌘" for the left Command modifier
\n- "rCmd", "rCommand", or "r⌘" for the right Command modifier
\n- "lCtrl", "lControl" or "l⌃" for the left Control modifier
\n- "rCtrl", "rControl" or "r⌃" for the right Control modifier
\n- "lAlt", "lOpt", "lOption" or "l⌥" for the left Option modifier
\n- "rAlt", "rOpt", "rOption" or "r⌥" for the right Option modifier
\n- "lShift" or "l⇧" for the left Shift modifier
\n- "rShift" or "r⇧" for the right Shift modifier
\n
\n \n- key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number
\n- 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
\n- pressedfn - A function that will be called when the hotkey has been pressed, or nil
\n- releasedfn - A function that will be called when the hotkey has been released, or nil
\n- repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
\n
\n",
+ "returns": [
+ " * a new, initially disabled, hotkey with the specified left/right modifiers."
+ ],
+ "returns_gfm": "\n- a new, initially disabled, hotkey with the specified left/right modifiers.
\n
\n",
+ "signature": "LeftRightHotkey:new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> LeftRightHotkeyObject",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:start() -> self",
+ "def_gfm": "LeftRightHotkey:start() -> self",
+ "desc": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.",
+ "desc_gfm": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\n",
+ "doc": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.\n\nParameters:\n * None\n\nReturns:\n * the LeftRightHotkey spoon object\n\nNotes:\n * this enables the use of hotkeys created by using this Spoon.",
+ "doc_gfm": "Starts watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\nParameters:
\n\nReturns:
\n\n- the LeftRightHotkey spoon object
\n
\nNotes:
\n\n- this enables the use of hotkeys created by using this Spoon.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "444",
+ "name": "start",
+ "notes": [
+ " * this enables the use of hotkeys created by using this Spoon."
+ ],
+ "notes_gfm": "\n- this enables the use of hotkeys created by using this Spoon.
\n
\n",
+ "parameters": [
+ " * None"
+ ],
+ "parameters_gfm": "\n",
+ "returns": [
+ " * the LeftRightHotkey spoon object"
+ ],
+ "returns_gfm": "\n- the LeftRightHotkey spoon object
\n
\n",
+ "signature": "LeftRightHotkey:start() -> self",
+ "stripped_doc": "",
+ "type": "Method"
+ },
+ {
+ "def": "LeftRightHotkey:stop() -> self",
+ "def_gfm": "LeftRightHotkey:stop() -> self",
+ "desc": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.",
+ "desc_gfm": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\n",
+ "doc": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.\n\nParameters:\n * None\n\nReturns:\n * the LeftRightHotkey spoon object\n\nNotes:\n * this will implicitly disable all hotkeys created by using this Spoon -- only those hotkeys which are defined with [hs.hotkey](hs.hotkey.html) directly will still be available.",
+ "doc_gfm": "Stops watching for flag (modifier key) change events that can determine if the right or left modifiers have been pressed.
\nParameters:
\n\nReturns:
\n\n- the LeftRightHotkey spoon object
\n
\nNotes:
\n\n- 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.
\n
\n",
+ "examples": [],
+ "file": "Source/LeftRightHotkey.spoon/init.lua",
+ "lineno": "471",
+ "name": "stop",
+ "notes": [
+ " * this will implicitly disable all hotkeys created by using this Spoon -- only those hotkeys which are defined with [hs.hotkey](hs.hotkey.html) directly will still be available."
+ ],
+ "notes_gfm": "\n- 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.
\n
\n",
+ "parameters": [
+ " * None"
+ ],
+ "parameters_gfm": "\n",
+ "returns": [
+ " * the LeftRightHotkey spoon object"
+ ],
+ "returns_gfm": "\n- the LeftRightHotkey spoon object
\n
\n",
+ "signature": "LeftRightHotkey:stop() -> self",
+ "stripped_doc": "",
+ "type": "Method"
+ }
+ ],
+ "name": "LeftRightHotkey",
+ "stripped_doc": "\nThis is accomplished by creating unactivated hotkeys for each definition and using an [hs.eventtap](hs.eventtap.html) 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.\n\nThe `LeftRightHotkeyObject` that is returned by [LeftRightHotkey:new](#new) and [LeftRightHotkey:bind](#bind) supports the following methods in a manner similar to the [hs.hotkey](hs.hotkey.html) equivalents:\n\n * `LeftRightHotkeyObject:enable()` -- enables the registered hotkey.\n * `LeftRightHotkeyObject:disable()` -- disables the registered hotkey.\n * `LeftRightHotkeyObject:delete()` -- deletes the registered hotkey.\n * `LeftRightHotkeyObject:isEnabled() -- returns a boolean value specifying whether the hotkey is currently enabled (true) or disabled (false)\n\nThe following modifiers are recognized by this spoon in the modifier table when setting up hotkeys with this spoon:\n * \"lCmd\", \"lCommand\", or \"l⌘\" for the left Command modifier\n * \"rCmd\", \"rCommand\", or \"r⌘\" for the right Command modifier\n * \"lCtrl\", \"lControl\" or \"l⌃\" for the left Control modifier\n * \"rCtrl\", \"rControl\" or \"r⌃\" for the right Control modifier\n * \"lAlt\", \"lOpt\", \"lOption\" or \"l⌥\" for the left Option modifier\n * \"rAlt\", \"rOpt\", \"rOption\" or \"r⌥\" for the right Option modifier\n * \"lShift\" or \"l⇧\" for the left Shift modifier\n * \"rShift\" or \"r⇧\" for the right Shift modifier\n\nThe 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](hs.hotkey.html).\n\nAlternatively, 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:\n e.g. `LeftRightHotkey:bind({ \"rCmd\", \"rShift\" }, \"a\", myFunction)` *and* `LeftRightHotkey:bind({ \"lCmd\", \"rShift\" }, \"a\", myFunction)`\n\nThis 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:\n * like all eventtaps, if the Hammerspoon application is particularly busy with some other task, it is possible for the flag change to be missed or for the macOS to disable the eventtap entirely.\n * behind the scenes, when a given set of flag changes occur that match a defined hotkey, the hotkey is actually enabled through `hs.hotkey:enable()` -- this means that in truth, either side's modifiers would trigger the callback. Under normal circumstances this won't be noticed because as soon as you switch to the alternate side's modifier, the flag change event will be detected and the hotkey will be disabled. However, as noted above, if Hammerspoon is particularly busy, it is possible for this event to be missed.\n * a timer runs (once this Spoon has been started the first time) which will check to see if the eventtap has been internally disabled and re-enable it if necessary; alternatively you can re-issue [LeftRightHotkey:start()](#start) to force the eventtap to be reset if necessary.\n * if your hotkeys seem out of sync, try pressing and releasing any modifier key -- this will reset the enabled/disabled hotkeys if a previous flag change was missed, but the eventtap is still running or has been reset by one of the methods described above.\n\nLike all Spoons, don't forget to use the [LeftRightHotkey:start()](#start) method to activate the modifier key watcher.\n\nDownload: [https://github.com/Hammerspoon/Spoons/raw/master/Spoons/LeftRightHotkey.spoon.zip](https://github.com/Hammerspoon/Spoons/raw/master/Spoons/LeftRightHotkey.spoon.zip)",
+ "submodules": [],
+ "type": "Module"
+ },
{
"Command": [],
"Constant": [],