# hs.hotkey

Create and manage global keyboard shortcuts

---

# Submodules

• hs.hotkey.modal

---

# API Overview

Variables - Configurable values

• alertDuration

Functions - API calls offered directly by the extension

• assignable
• deleteAll
• disableAll
• getHotkeys
• showHotkeys
• systemAssigned

Constructors - API calls which return an object, typically one that offers API methods

• bind
• bindSpec
• new

Methods - API calls which can only be made on an object returned by a constructor

• delete
• disable
• enable

---

# API Documentation

# Variables

# alertDuration

---

# Functions

# assignable

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.assignable(mods, key) -> boolean | | Type | Function | | Description | Determines whether the hotkey combination can be assigned a callback through Hammerspoon. | | Parameters |

• mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required, which should be zero or more of the following: "cmd", "command" or "⌘" "ctrl", "control" or "⌃" "alt", "option" or "⌥" "shift" or "⇧"
• key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number

| | Returns |

• a boolean value, true if the hotkey combination can be given an assignment by Hammerspoon or false if it cannot.

| | Notes |

• The most common reason a hotkey combination cannot be given an assignment by Hammerspoon is because it is in use by the Mac operating system -- see the Shortcuts tab of Keyboard in the System Preferences application or hs.hotkey.systemAssigned.

| | Examples | None | | Source | extensions/hotkey/hotkey.lua line 254 |

---

# deleteAll

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.deleteAll(mods, key) | | Type | Function | | Description | Deletes all previously set callbacks for a given keyboard combination | | Parameters |

• mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required, which should be zero or more of the following: "cmd", "command" or "⌘" "ctrl", "control" or "⌃" "alt", "option" or "⌥" "shift" or "⇧"
• key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number

| | Returns |

• None

| | Notes | None | | Examples | None | | Source | extensions/hotkey/hotkey.lua line 304 |

---

# disableAll

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.disableAll(mods, key) | | Type | Function | | Description | Disables all previously set callbacks for a given keyboard combination | | Parameters |

• mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required, which should be zero or more of the following: "cmd", "command" or "⌘" "ctrl", "control" or "⌃" "alt", "option" or "⌥" "shift" or "⇧"
• key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number

| | Returns |

• None

| | Notes | None | | Examples | None | | Source | extensions/hotkey/hotkey.lua line 284 |

---

# getHotkeys

---

# showHotkeys

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.showHotkeys(mods, key) -> hs.hotkey object | | Type | Function | | Description | Creates (and enables) a hotkey that shows all currently active hotkeys (i.e. enabled and not "shadowed" in the current context) while pressed | | Parameters |

• mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required, which should be zero or more of the following: "cmd", "command" or "⌘" "ctrl", "control" or "⌃" "alt", "option" or "⌥" "shift" or "⇧"
• key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number

| | Returns |

• The new hs.hotkey object

| | Notes | None | | Examples | None | | Source | extensions/hotkey/hotkey.lua line 340 |

---

# systemAssigned

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.systemAssigned(mods, key) -> table | false | | Type | Function | | Description | Examine whether a potential hotkey is in use by the macOS system such as the Screen Capture, Universal Access, and Keyboard Navigation keys. | | Parameters |

• mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required, which should be zero or more of the following: "cmd", "command" or "⌘" "ctrl", "control" or "⌃" "alt", "option" or "⌥" "shift" or "⇧"
• key - A string containing the name of a keyboard key (as found in hs.keycodes.map ), or a raw keycode number

| | Returns |

• if the hotkey combination is in use by a system function, returns a table containing the following keys:
• keycode - the numeric keycode for the hotkey
• mods - a numeric representation of the modifier flags for the hotkey
• enabled - a boolean indicating whether or not the key is currently enabled
• if the hotkey combination is not in use by the operating system, returns the boolean value false

| | Notes |

• this is provided for informational purposes and does not provide a reliable test as to whether or not Hammerspoon can use the combination to create a custom hotkey -- some combinations which return a table can be over-ridden by Hammerspoon while others cannot. See also hs.hotkey.assignable.

| | Examples | None | | Source | extensions/hotkey/hotkey.lua line 225 |

---

# Constructors

# bind

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> hs.hotkey object | | Type | Constructor | | Description | Creates a new hotkey and enables it immediately | | Parameters |

• mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required, which should be zero or more of the following: "cmd", "command" or "⌘" "ctrl", "control" or "⌃" "alt", "option" or "⌥" "shift" or "⇧"
• 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 hs.hotkey object or nil if the hotkey could not be enabled

| | Notes |

• This function is just a wrapper that performs hs.hotkey.new(...):enable()
• You can create multiple hs.hotkey objects for the same keyboard combination, but only one can be active
• at any given time - see hs.hotkey:enable()
• If message is the empty string "", the alert will just show the triggered keyboard combination
• If you don't want any alert, you must actually omit the message parameter; a nil in 3rd position
• will be interpreted as a missing pressedfn
• You must pass at least one of pressedfn, releasedfn or repeatfn; to delete a hotkey, use hs.hotkey:delete()

| | Examples | None | | Source | extensions/hotkey/hotkey.lua line 385 |

---

# bindSpec

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.bindSpec(keyspec, ...) -> hs.hotkey object | | Type | Constructor | | Description | Creates a hotkey and enables it immediately | | Parameters |

• keyspec - A table containing two items: first, a table containing keyboard modifiers, as specified in hs.hotkey.bind() second, a string containing the name of a keyboard key, as specified in hs.hotkey.bind()
• ... - All remaining arguments are as specified in hs.hotkey.bind()

| | Returns |

• A new hs.hotkey object for method chaining

| | Notes |

• This function is just a wrapper that performs hs.hotkey.bind(keyspec[1], keyspec[2], ...)

| | Examples | None | | Source | extensions/hotkey/hotkey.lua line 418 |

---

# new

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.hotkey.new(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> hs.hotkey object | | Type | Constructor | | Description | Creates a new hotkey | | Parameters |

• mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required, which should be zero or more of the following: "cmd", "command" or "⌘" "ctrl", "control" or "⌃" "alt", "option" or "⌥" "shift" or "⇧"
• 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 hs.hotkey object or nil if the hotkey could not be enabled

| | Notes |

• You can create multiple hs.hotkey objects for the same keyboard combination, but only one can be active
• at any given time - see hs.hotkey:enable()
• If message is the empty string "", the alert will just show the triggered keyboard combination
• If you don't want any alert, you must actually omit the message parameter; a nil in 3rd position
• will be interpreted as a missing pressedfn
• You must pass at least one of pressedfn, releasedfn or repeatfn; to delete a hotkey, use hs.hotkey:delete()

| | Examples | None | | Source | extensions/hotkey/hotkey.lua line 165 |

---

# Methods

# delete

---

# disable

---

# enable

---

---