#
hs.hotkey.modal
Create/manage modal keyboard shortcut environments
Usage:
k = hs.hotkey.modal.new('cmd-shift', 'd')
function k:entered() hs.alert'Entered mode' end
function k:exited() hs.alert'Exited mode' end
k:bind('', 'escape', function() k:exit() end)
k:bind('', 'J', 'Pressed J',function() print'let the record show that J was pressed' end)```
---
## API Overview
**Constructors** - _API calls which return an object, typically one that offers API methods_
* [new](#new)
**Methods** - _API calls which can only be made on an object returned by a constructor_
* [bind](#bind)
* [delete](#delete)
* [enter](#enter)
* [entered](#entered)
* [exit](#exit)
* [exited](#exited)
---
## API Documentation
#### Constructors
### [new](#new)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `hs.hotkey.modal.new(mods, key, message) -> hs.hotkey.modal object` |
| **Type** | Constructor |
| **Description** | Creates a new modal state, optionally with a global keyboard combination to trigger it |
| **Parameters** | <ul><li>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 "⇧"</li><li>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</li><li>message - A string containing a message to be displayed via `hs.alert()` when the hotkey has been triggered, or nil for no alert</li></ul> |
| **Returns** | <ul><li>A new `hs.hotkey.modal` object</li></ul> |
| **Notes** | <ul><li>If `key` is nil, no global hotkey will be registered (all other parameters will be ignored)</li></ul> |
| **Examples** | None |
| **Source** | [extensions/hotkey/hotkey.lua line 552](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/hotkey/hotkey.lua#L552){target="_blank"} |
---
#### Methods
### [bind](#bind)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `hs.hotkey.modal:bind(mods, key, message, pressedfn, releasedfn, repeatfn) -> hs.hotkey.modal object` |
| **Type** | Method |
| **Description** | Creates a hotkey that is enabled/disabled as the modal is entered/exited |
| **Parameters** | <ul><li>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 "⇧"</li><li>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</li><li>message - A string containing a message to be displayed via `hs.alert()` when the hotkey has been triggered, or nil for no alert</li><li>pressedfn - A function that will be called when the hotkey has been pressed, or nil</li><li>releasedfn - A function that will be called when the hotkey has been released, or nil</li><li>repeatfn - A function that will be called when a pressed hotkey is repeating, or nil</li></ul> |
| **Returns** | <ul><li>The `hs.hotkey.modal` object for method chaining</li></ul> |
| **Notes** | None |
| **Examples** | None |
| **Source** | [extensions/hotkey/hotkey.lua line 482](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/hotkey/hotkey.lua#L482){target="_blank"} |
---
### [delete](#delete)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `hs.hotkey.modal:delete()` |
| **Type** | Method |
| **Description** | Deletes a modal hotkey object without calling :exited() |
| **Parameters** | <ul><li>None</li></ul> |
| **Returns** | <ul><li>None</li></ul> |
| **Notes** | None |
| **Examples** | None |
| **Source** | [extensions/hotkey/hotkey.lua line 580](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/hotkey/hotkey.lua#L580){target="_blank"} |
---
### [enter](#enter)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `hs.hotkey.modal:enter() -> hs.hotkey.modal object` |
| **Type** | Method |
| **Description** | Enters a modal state |
| **Parameters** | <ul><li>None</li></ul> |
| **Returns** | <ul><li>The `hs.hotkey.modal` object for method chaining</li></ul> |
| **Notes** | <ul><li>This method will enable all of the hotkeys defined in the modal state via `hs.hotkey.modal:bind()`,</li><li> and disable the hotkey that entered the modal state (if one was defined)</li><li>If the modal state was created with a keyboard combination, this method will be called automatically</li></ul> |
| **Examples** | None |
| **Source** | [extensions/hotkey/hotkey.lua line 506](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/hotkey/hotkey.lua#L506){target="_blank"} |
---
### [entered](#entered)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `hs.hotkey.modal:entered()` |
| **Type** | Method |
| **Description** | Optional callback for when a modal is entered |
| **Parameters** | <ul><li>None</li></ul> |
| **Returns** | <ul><li>None</li></ul> |
| **Notes** | <ul><li>This is a preexisting function that you should override if you need to use it; the default implementation does nothing.</li></ul> |
| **Examples** | None |
| **Source** | [extensions/hotkey/hotkey.lua line 452](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/hotkey/hotkey.lua#L452){target="_blank"} |
---
### [exit](#exit)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `hs.hotkey.modal:exit() -> hs.hotkey.modal object` |
| **Type** | Method |
| **Description** | Exits a modal state |
| **Parameters** | <ul><li>None</li></ul> |
| **Returns** | <ul><li>The `hs.hotkey.modal` object for method chaining</li></ul> |
| **Notes** | <ul><li>This method will disable all of the hotkeys defined in the modal state, and enable the hotkey for entering the modal state (if one was defined)</li></ul> |
| **Examples** | None |
| **Source** | [extensions/hotkey/hotkey.lua line 530](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/hotkey/hotkey.lua#L530){target="_blank"} |
---
### [exited](#exited)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `hs.hotkey.modal:exited()` |
| **Type** | Method |
| **Description** | Optional callback for when a modal is exited |
| **Parameters** | <ul><li>None</li></ul> |
| **Returns** | <ul><li>None</li></ul> |
| **Notes** | <ul><li>This is a preexisting function that you should override if you need to use it; the default implementation does nothing.</li></ul> |
| **Examples** | None |
| **Source** | [extensions/hotkey/hotkey.lua line 467](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/hotkey/hotkey.lua#L467){target="_blank"} |
---
---
<script src="https://giscus.app/client.js"
data-repo="CommandPost/CommandPost"
data-repo-id="MDEwOlJlcG9zaXRvcnk3NDY0NTk2NQ=="
data-category="Website Discussion"
data-category-id="DIC_kwDOBHMBzc4CXFFA"
data-mapping="pathname"
data-strict="0"
data-reactions-enabled="1"
data-emit-metadata="0"
data-input-position="bottom"
data-theme="preferred_color_scheme"
data-lang="en"
crossorigin="anonymous"
async>
</script>