Internationalisation
Bundled Plugins API
modal
Create/manage modal keyboard shortcut environments
Usage:
1
k = hs.hotkey.modal.new('cmd-shift', 'd')
2
function k:entered() hs.alert'Entered mode' end
3
function k:exited() hs.alert'Exited mode' end
4
k:bind('', 'escape', function() k:exit() end)
5
k:bind('', 'J', 'Pressed J',function() print'let the record show that J was pressed' end)```
6
7
## API Overview
8
* Constructors - API calls which return an object, typically one that offers API methods
9
* [new](#new)
10
* Methods - API calls which can only be made on an object returned by a constructor
11
* [bind](#bind)
12
* [delete](#delete)
13
* [enter](#enter)
14
* [entered](#entered)
15
* [exit](#exit)
16
* [exited](#exited)
17
18
## API Documentation
19
20
### Constructors
21
22
#### [new](#new)
23
| <span style="float: left;">**Signature**</span> | <span style="float: left;">`hs.hotkey.modal.new(mods, key, message) -> hs.hotkey.modal object` </span> |
24
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
25
| **Type** | Constructor |
26
| **Description** | Creates a new modal state, optionally with a global keyboard combination to trigger it |
27
| **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:</li><li>"cmd", "command" or "⌘"</li><li>"ctrl", "control" or "⌃"</li><li>"alt", "option" or "⌥"</li><li>"shift" or "⇧"</li><li>key - A string containing the name of a keyboard key (as found in <a href="hs.keycodes.html#map">hs.keycodes.map</a> ), or a raw keycode number</li><li>message - A string containing a message to be displayed via <code>hs.alert()</code> when the hotkey has been triggered, or nil for no alert</li></ul> |
28
| **Returns** | <ul><li>A new <code>hs.hotkey.modal</code> object</li></ul> |
29
| **Notes** | <ul><li>If <code>key</code> is nil, no global hotkey will be registered (all other parameters will be ignored)</li></ul> |
30
31
### Methods
32
33
#### [bind](#bind)
34
| <span style="float: left;">**Signature**</span> | <span style="float: left;">`hs.hotkey.modal:bind(mods, key, message, pressedfn, releasedfn, repeatfn) -> hs.hotkey.modal object` </span> |
35
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
36
| **Type** | Method |
37
| **Description** | Creates a hotkey that is enabled/disabled as the modal is entered/exited |
38
| **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:</li><li>"cmd", "command" or "⌘"</li><li>"ctrl", "control" or "⌃"</li><li>"alt", "option" or "⌥"</li><li>"shift" or "⇧"</li><li>key - A string containing the name of a keyboard key (as found in <a href="hs.keycodes.html#map">hs.keycodes.map</a> ), or a raw keycode number</li><li>message - A string containing a message to be displayed via <code>hs.alert()</code> 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> |
39
| **Returns** | <ul><li>The <code>hs.hotkey.modal</code> object for method chaining</li></ul> |
40
41
#### [delete](#delete)
42
| <span style="float: left;">**Signature**</span> | <span style="float: left;">`hs.hotkey.modal:delete()` </span> |
43
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
44
| **Type** | Method |
45
| **Description** | Deletes a modal hotkey object without calling :exited() |
46
| **Parameters** | <ul><li>None</li></ul> |
47
| **Returns** | <ul><li>None</li></ul> |
48
49
#### [enter](#enter)
50
| <span style="float: left;">**Signature**</span> | <span style="float: left;">`hs.hotkey.modal:enter() -> hs.hotkey.modal object` </span> |
51
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
52
| **Type** | Method |
53
| **Description** | Enters a modal state |
54
| **Parameters** | <ul><li>None</li></ul> |
55
| **Returns** | <ul><li>The <code>hs.hotkey.modal</code> object for method chaining</li></ul> |
56
| **Notes** | <ul><li>This method will enable all of the hotkeys defined in the modal state via <code>hs.hotkey.modal:bind()</code>, 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> |
57
58
#### [entered](#entered)
59
| <span style="float: left;">**Signature**</span> | <span style="float: left;">`hs.hotkey.modal:entered()` </span> |
60
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
61
| **Type** | Method |
62
| **Description** | Optional callback for when a modal is entered |
63
| **Parameters** | <ul><li>None</li></ul> |
64
| **Returns** | <ul><li>None</li></ul> |
65
| **Notes** | <ul><li>This is a pre-existing function that you should override if you need to use it; the default implementation does nothing.</li></ul> |
66
67
#### [exit](#exit)
68
| <span style="float: left;">**Signature**</span> | <span style="float: left;">`hs.hotkey.modal:exit() -> hs.hotkey.modal object` </span> |
69
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
70
| **Type** | Method |
71
| **Description** | Exits a modal state |
72
| **Parameters** | <ul><li>None</li></ul> |
73
| **Returns** | <ul><li>The <code>hs.hotkey.modal</code> object for method chaining</li></ul> |
74
| **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> |
75
76
#### [exited](#exited)
77
| <span style="float: left;">**Signature**</span> | <span style="float: left;">`hs.hotkey.modal:exited()` </span> |
78
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
79
| **Type** | Method |
80
| **Description** | Optional callback for when a modal is exited |
81
| **Parameters** | <ul><li>None</li></ul> |
82
| **Returns** | <ul><li>None</li></ul> |
83
| **Notes** | <ul><li>This is a pre-existing function that you should override if you need to use it; the default implementation does nothing.</li></ul> |
Copied!
Last modified 1mo ago
Export as PDF
Copy link