diff --git a/SUMMARY.md b/SUMMARY.md
index 0c9c75d..5782865 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -43,6 +43,9 @@
* [cp](api/cp/cp.md)
* [18n](api/cp/cp.18n.md)
+ * [aftereffects](api/cp/cp.adobe.aftereffects.md)
+ * [app](api/cp/cp.adobe.aftereffects.app.md)
+ * [shortcuts](api/cp/cp.adobe.aftereffects.shortcuts.md)
* [app](api/cp/cp.app.md)
* [menu](api/cp/cp.app.menu.md)
* [prefs](api/cp/cp.app.prefs.md)
@@ -334,7 +337,11 @@
## Bundled Plugins API
* [plugins](api/plugins/index.md)
- * [tangent](api/plugins/plugins.colorfinale.tangent.md)
+ * [manager](api/plugins/plugins.aftereffects.application.manager.md)
+ * [effects](api/plugins/plugins.aftereffects.effects.md)
+ * [preferences](api/plugins/plugins.aftereffects.preferences.md)
+ * [shortcuts](api/plugins/plugins.aftereffects.shortcuts.md)
+ * [manager](api/plugins/plugins.aftereffects.tangent.manager.md)
* [manager](api/plugins/plugins.compressor.application.manager.md)
* [bugreport](api/plugins/plugins.compressor.feedback.bugreport.md)
* [media](api/plugins/plugins.compressor.watchfolders.panels.media.md)
@@ -365,9 +372,8 @@
* [userguide](api/plugins/plugins.core.helpandsupport.userguide.md)
* [language](api/plugins/plugins.core.language.md)
* [prefs](api/plugins/plugins.core.loupedeck.prefs.md)
- * [changeapplications](api/plugins/plugins.core.loupedeckct.changeapplications.md)
- * [manager](api/plugins/plugins.core.loupedeckct.manager.md)
- * [prefs](api/plugins/plugins.core.loupedeckct.prefs.md)
+ * [manager](api/plugins/plugins.core.loupedeckctandlive.manager.md)
+ * [prefs](api/plugins/plugins.core.loupedeckctandlive.prefs.md)
* [prefs](api/plugins/plugins.core.loupedeckplus.prefs.md)
* [manager](api/plugins/plugins.core.menu.manager.md)
* [section](api/plugins/plugins.core.menu.manager.section.md)
@@ -393,23 +399,16 @@
* [prefs](api/plugins/plugins.core.shortcuts.prefs.md)
* [manager](api/plugins/plugins.core.streamdeck.manager.md)
* [prefs](api/plugins/plugins.core.streamdeck.prefs.md)
- * [commandpost](api/plugins/plugins.core.tangent.commandpost.md)
- * [favourites](api/plugins/plugins.core.tangent.commandpost.favourites.md)
- * [functions](api/plugins/plugins.core.tangent.commandpost.functions.md)
* [manager](api/plugins/plugins.core.tangent.manager.md)
* [action](api/plugins/plugins.core.tangent.manager.action.md)
* [binding](api/plugins/plugins.core.tangent.manager.binding.md)
+ * [connection](api/plugins/plugins.core.tangent.manager.connection.md)
* [controls](api/plugins/plugins.core.tangent.manager.controls.md)
* [group](api/plugins/plugins.core.tangent.manager.group.md)
* [menu](api/plugins/plugins.core.tangent.manager.menu.md)
* [mode](api/plugins/plugins.core.tangent.manager.mode.md)
* [named](api/plugins/plugins.core.tangent.manager.named.md)
* [parameter](api/plugins/plugins.core.tangent.manager.parameter.md)
- * [os](api/plugins/plugins.core.tangent.os.md)
- * [display](api/plugins/plugins.core.tangent.os.display.md)
- * [pasteboard](api/plugins/plugins.core.tangent.os.pasteboard.md)
- * [sound](api/plugins/plugins.core.tangent.os.sound.md)
- * [window](api/plugins/plugins.core.tangent.os.window.md)
* [prefs](api/plugins/plugins.core.tangent.prefs.md)
* [manager](api/plugins/plugins.core.toolbox.manager.md)
* [caffeinate](api/plugins/plugins.core.tools.caffeinate.md)
@@ -429,6 +428,7 @@
* [panel](api/plugins/plugins.core.watchfolders.manager.panel.md)
* [menuitem](api/plugins/plugins.core.watchfolders.menuitem.md)
* [manager](api/plugins/plugins.diskutility.application.manager.md)
+ * [manager](api/plugins/plugins.ecammlive.application.manager.md)
* [custom](api/plugins/plugins.finalcutpro.actions.custom.md)
* [backupinterval](api/plugins/plugins.finalcutpro.advanced.backupinterval.md)
* [disablewaveforms](api/plugins/plugins.finalcutpro.advanced.disablewaveforms.md)
@@ -510,15 +510,21 @@
* [audio](api/plugins/plugins.finalcutpro.tangent.audio.md)
* [browser](api/plugins/plugins.finalcutpro.tangent.browser.md)
* [clip](api/plugins/plugins.finalcutpro.tangent.clip.md)
- * [commandpost](api/plugins/plugins.finalcutpro.tangent.commandpost.md)
+ * [color](api/plugins/plugins.finalcutpro.tangent.color.md)
+ * [functions](api/plugins/plugins.finalcutpro.tangent.commandpost.functions.md)
* [common](api/plugins/plugins.finalcutpro.tangent.common.md)
* [edit](api/plugins/plugins.finalcutpro.tangent.edit.md)
+ * [features](api/plugins/plugins.finalcutpro.tangent.features.md)
* [generator](api/plugins/plugins.finalcutpro.tangent.generator.md)
* [info](api/plugins/plugins.finalcutpro.tangent.info.md)
* [manager](api/plugins/plugins.finalcutpro.tangent.manager.md)
- * [modes](api/plugins/plugins.finalcutpro.tangent.modes.md)
* [new](api/plugins/plugins.finalcutpro.tangent.new.md)
* [open](api/plugins/plugins.finalcutpro.tangent.open.md)
+ * [os](api/plugins/plugins.finalcutpro.tangent.os.md)
+ * [display](api/plugins/plugins.finalcutpro.tangent.os.display.md)
+ * [pasteboard](api/plugins/plugins.finalcutpro.tangent.os.pasteboard.md)
+ * [sound](api/plugins/plugins.finalcutpro.tangent.os.sound.md)
+ * [window](api/plugins/plugins.finalcutpro.tangent.os.window.md)
* [overlay](api/plugins/plugins.finalcutpro.tangent.overlay.md)
* [pasteboard](api/plugins/plugins.finalcutpro.tangent.pasteboard.md)
* [playback](api/plugins/plugins.finalcutpro.tangent.playback.md)
@@ -586,6 +592,8 @@
* [manager](api/plugins/plugins.motion.application.manager.md)
* [bugreport](api/plugins/plugins.motion.feedback.bugreport.md)
* [manager](api/plugins/plugins.resolve.application.manager.md)
+ * [emulation ===
](api/plugins/plugins.resolve.tangent.emulation ===
.md)
+ * [manager](api/plugins/plugins.resolve.tangent.manager.md)
* [manager](api/plugins/plugins.skype.application.manager.md)
* [shortcuts](api/plugins/plugins.skype.shortcuts.md)
* [manager](api/plugins/plugins.systempreferences.application.manager.md)
@@ -603,7 +611,9 @@
* [audiodevice](api/hs/hs.audiodevice.md)
* [datasource](api/hs/hs.audiodevice.datasource.md)
* [watcher](api/hs/hs.audiodevice.watcher.md)
- * [audiounit](api/hs/hs.audiounit.md)
+ * [axuielement](api/hs/hs.axuielement.md)
+ * [axtextmarker](api/hs/hs.axuielement.axtextmarker.md)
+ * [observer](api/hs/hs.axuielement.observer.md)
* [base64](api/hs/hs.base64.md)
* [battery](api/hs/hs.battery.md)
* [watcher](api/hs/hs.battery.watcher.md)
@@ -691,6 +701,7 @@
* [socket](api/hs/hs.socket.md)
* [udp](api/hs/hs.socket.udp.md)
* [sound](api/hs/hs.sound.md)
+ * [spaces](api/hs/hs.spaces.md)
* [watcher](api/hs/hs.spaces.watcher.md)
* [speech](api/hs/hs.speech.md)
* [listener](api/hs/hs.speech.listener.md)
diff --git a/api/cp/cp.adobe.aftereffects.app.md b/api/cp/cp.adobe.aftereffects.app.md
new file mode 100644
index 0000000..d3c6d19
--- /dev/null
+++ b/api/cp/cp.adobe.aftereffects.app.md
@@ -0,0 +1,19 @@
+# [docs](index.md) » cp.adobe.aftereffects.app
+---
+
+The `cp.app` for Adobe After Effects.
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [app](#app)
+
+## API Documentation
+
+### Constants
+
+#### [app](#app)
+| **Signature** | `cp.adobe.aftereffects.app ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The `cp.app` for After Effects. |
+
diff --git a/api/cp/cp.adobe.aftereffects.md b/api/cp/cp.adobe.aftereffects.md
new file mode 100644
index 0000000..e8cb734
--- /dev/null
+++ b/api/cp/cp.adobe.aftereffects.md
@@ -0,0 +1,80 @@
+# [docs](index.md) » cp.adobe.aftereffects
+---
+
+Adobe After Effects Extension
+
+## Submodules
+ * [cp.adobe.aftereffects.app](cp.adobe.aftereffects.app.md)
+ * [cp.adobe.aftereffects.shortcuts](cp.adobe.aftereffects.shortcuts.md)
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [preferences](#preferences)
+* Functions - API calls offered directly by the extension
+ * [allowScriptsToWriteFilesAndAccessNetwork](#allowscriptstowritefilesandaccessnetwork)
+ * [preferencesFilePath](#preferencesfilepath)
+ * [preferencesPath](#preferencespath)
+ * [refreshPreferences](#refreshpreferences)
+ * [shortcutsPreferences](#shortcutspreferences)
+ * [shortcutsPreferencesPath](#shortcutspreferencespath)
+
+## API Documentation
+
+### Constants
+
+#### [preferences](#preferences)
+| **Signature** | `cp.adobe.aftereffects.preferences ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The `cp.app.prefs` for After Effects. |
+
+### Functions
+
+#### [allowScriptsToWriteFilesAndAccessNetwork](#allowscriptstowritefilesandaccessnetwork)
+| **Signature** | `cp.adobe.aftereffects:allowScriptsToWriteFilesAndAccessNetwork() -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Is "Allow Scripts to Write Files and Access Network" enabled in After Effects Preferences? |
+| **Parameters** | |
+| **Returns** | |
+
+#### [preferencesFilePath](#preferencesfilepath)
+| **Signature** | `cp.adobe.aftereffects:preferencesFilePath() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | The path to the main Preferences file. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [preferencesPath](#preferencespath)
+| **Signature** | `cp.adobe.aftereffects:preferencesPath() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | The path to After Effects Preferences folder. |
+| **Parameters** | |
+| **Returns** | - A string or
nil if no path can be found.
|
+
+#### [refreshPreferences](#refreshpreferences)
+| **Signature** | `cp.adobe.aftereffects:refreshPreferences() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | If After Effects is running, this forces the preferences file to be saved to disk. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [shortcutsPreferences](#shortcutspreferences)
+| **Signature** | `cp.adobe.aftereffects:shortcutsPreferences() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets a table of all the active After Effects keyboard shortcuts. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [shortcutsPreferencesPath](#shortcutspreferencespath)
+| **Signature** | `cp.adobe.aftereffects:shortcutsPreferencesPath() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets the active shortcut key preferences file path. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/cp/cp.adobe.aftereffects.shortcuts.md b/api/cp/cp.adobe.aftereffects.shortcuts.md
new file mode 100644
index 0000000..c360f28
--- /dev/null
+++ b/api/cp/cp.adobe.aftereffects.shortcuts.md
@@ -0,0 +1,33 @@
+# [docs](index.md) » cp.adobe.aftereffects.shortcuts
+---
+
+Translations between After Effects shortcuts and Hammerspoon-friendly shortcuts.
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [keys](#keys)
+ * [labels](#labels)
+ * [modifiers](#modifiers)
+
+## API Documentation
+
+### Constants
+
+#### [keys](#keys)
+| **Signature** | `cp.adobe.aftereffects.shortcuts.keys -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | Table containing key translations. |
+
+#### [labels](#labels)
+| **Signature** | `cp.adobe.aftereffects.shortcuts.labels -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | Table containing label translations. |
+
+#### [modifiers](#modifiers)
+| **Signature** | `cp.adobe.aftereffects.shortcuts.modifiers -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | Table containing modifier translations. |
+
diff --git a/api/cp/cp.apple.finalcutpro.inspector.color.CorrectionsBar.md b/api/cp/cp.apple.finalcutpro.inspector.color.CorrectionsBar.md
index f8d7c2b..b75c233 100644
--- a/api/cp/cp.apple.finalcutpro.inspector.color.CorrectionsBar.md
+++ b/api/cp/cp.apple.finalcutpro.inspector.color.CorrectionsBar.md
@@ -15,6 +15,7 @@ Requires Final Cut Pro 10.4 or later.
* Methods - API calls which can only be made on an object returned by a constructor
* [activate](#activate)
* [add](#add)
+ * [doActivate](#doactivate)
* [doShow](#doshow)
* [findCorrectionLabel](#findcorrectionlabel)
* [show](#show)
@@ -56,12 +57,12 @@ Requires Final Cut Pro 10.4 or later.
### Methods
#### [activate](#activate)
-| **Signature** | `cp.apple.finalcutpro.inspector.color.CorrectionsBar:activate(correctionType, number) -> cp.rx.go.Statement` |
+| **Signature** | `cp.apple.finalcutpro.inspector.color.CorrectionsBar:activate(correctionType, number) -> cp.apple.finalcutpro.inspector.color.CorrectionsBar` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
-| **Description** | A Statement that activates a correction type. |
+| **Description** | Activates a correction type. |
| **Parameters** | correctionType - The correction type as string.number - The number of the correction.
|
-| **Returns** | |
+| **Returns** | cp.apple.finalcutpro.inspector.color.CorrectionsBar object.
|
#### [add](#add)
| **Signature** | `cp.apple.finalcutpro.inspector.color.CorrectionsBar:add(correctionType) -> cp.apple.finalcutpro.inspector.color.CorrectionsBar` |
@@ -71,6 +72,14 @@ Requires Final Cut Pro 10.4 or later.
| **Parameters** | correctionType - The correction type as string.
|
| **Returns** | cp.apple.finalcutpro.inspector.color.CorrectionsBar object.
|
+#### [doActivate](#doactivate)
+| **Signature** | `cp.apple.finalcutpro.inspector.color.CorrectionsBar:doActivate(correctionType, number) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A Statement that activates a correction type. |
+| **Parameters** | correctionType - The correction type as string.number - The number of the correction.
|
+| **Returns** | |
+
#### [doShow](#doshow)
| **Signature** | `cp.apple.finalcutpro.inspector.color.CorrectionsBar:doShow() -> cp.rx.go.Statement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/cp/cp.json.md b/api/cp/cp.json.md
index fa0753e..ceb59a0 100644
--- a/api/cp/cp.json.md
+++ b/api/cp/cp.json.md
@@ -34,7 +34,7 @@ A collection of handy JSON tools.
| **Notes** | - This is useful for storing some of the more complex lua table structures as a persistent setting (see
hs.settings)
|
#### [prop](#prop)
-| **Signature** | `cp.json.prop(path, folder, filename, defaultValue) -> cp.prop` |
+| **Signature** | `cp.json.prop(path, folder, filename, defaultValue[, errorCallbackFn]) -> cp.prop` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns a `cp.prop` instance for a JSON file. |
diff --git a/api/cp/cp.md b/api/cp/cp.md
index 03d4e58..cf87b3a 100644
--- a/api/cp/cp.md
+++ b/api/cp/cp.md
@@ -5,6 +5,7 @@ Core CommandPost functionality.
## Submodules
* [cp.18n](cp.18n.md)
+ * [cp.adobe](cp.adobe.md)
* [cp.app](cp.app.md)
* [cp.apple](cp.apple.md)
* [cp.battery](cp.battery.md)
diff --git a/api/cp/cp.tools.md b/api/cp/cp.tools.md
index d4c24f6..2348094 100644
--- a/api/cp/cp.tools.md
+++ b/api/cp/cp.tools.md
@@ -173,7 +173,7 @@ A collection of handy miscellaneous tools for Lua development.
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Ensures all steps on a provided path exist. If not, attempts to create them. |
-| **Parameters** | rootPath - The root path (should already exist).... - The list of path steps to create
|
+| **Parameters** | rootPath - The root path... - The list of path steps to create
|
| **Returns** | - The full path, if it exists, or
nil if unable to create the directory for some reason.
|
#### [exactMatch](#exactmatch)
diff --git a/api/cp/cp.ui.Menu.md b/api/cp/cp.ui.Menu.md
index e6560c8..6686495 100644
--- a/api/cp/cp.ui.Menu.md
+++ b/api/cp/cp.ui.Menu.md
@@ -54,10 +54,10 @@ UI for AXMenus.
| **Returns** | |
#### [doSelectValue](#doselectvalue)
-| **Signature** | `cp.ui.Menu:doSelectValue(value) -> cp.rx.go.Statement` |
+| **Signature** | `cp.ui.Menu:doSelectValue(pattern[, altPattern]) -> cp.rx.go.Statement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | A [Statement](cp.rx.go.Statement.md) that will select an item on the `Menu` by value. |
-| **Parameters** | - value - The value of the item to match.
|
+| **Parameters** | - pattern - The pattern to match.
- [altPattern] - An optional alternate pattern to match if the first pattern fails.
|
| **Returns** | |
diff --git a/api/cp/cp.ui.MenuButton.md b/api/cp/cp.ui.MenuButton.md
index 6e68ba1..61ab48b 100644
--- a/api/cp/cp.ui.MenuButton.md
+++ b/api/cp/cp.ui.MenuButton.md
@@ -88,11 +88,11 @@ Menu Button Module.
| **Returns** | |
#### [doSelectItemMatching](#doselectitemmatching)
-| **Signature** | `cp.ui.MenuButton:doSelectItemMatching(pattern) -> cp.rx.go.Statement` |
+| **Signature** | `cp.ui.MenuButton:doSelectItemMatching(pattern[, altPattern]) -> cp.rx.go.Statement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | A [Statement](cp.rx.go.Statement.md) that will select an item on the `MenuButton` by pattern. |
-| **Parameters** | - pattern - The pattern to match.
|
+| **Parameters** | - pattern - The pattern to match.
- [altPattern] - An optional alternate pattern to match if the first pattern fails.
|
| **Returns** | |
#### [doSelectValue](#doselectvalue)
diff --git a/api/cp/index.md b/api/cp/index.md
index c225a30..ea5e209 100644
--- a/api/cp/index.md
+++ b/api/cp/index.md
@@ -4,20 +4,23 @@
## Project Links
| Resource | Link |
| --------------- | -------------------------------- |
-| Website | [http://www.hammerspoon.org/](http://www.hammerspoon.org/) |
+| Website | [https://www.hammerspoon.org/](https://www.hammerspoon.org/) |
| GitHub page | [https://github.com/Hammerspoon/hammerspoon](https://github.com/Hammerspoon/hammerspoon) |
-| Getting Started Guide | [http://www.hammerspoon.org/go/](http://www.hammerspoon.org/go/) |
+| Getting Started Guide | [https://www.hammerspoon.org/go/](https://www.hammerspoon.org/go/) |
| Spoon Plugin Documentation | [https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md](https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md) |
-| Official Spoon repository | [http://www.hammerspoon.org/Spoons](http://www.hammerspoon.org/Spoons) |
+| Official Spoon repository | [https://www.hammerspoon.org/Spoons](https://www.hammerspoon.org/Spoons) |
| IRC channel | [irc://chat.freenode.net/#hammerspoon](irc://chat.freenode.net/#hammerspoon) |
| Mailing list | [https://groups.google.com/forum/#!forum/hammerspoon/](https://groups.google.com/forum/#!forum/hammerspoon/) |
-| LuaSkin API docs | [http://www.hammerspoon.org/docs/LuaSkin/](http://www.hammerspoon.org/docs/LuaSkin/) |
+| LuaSkin API docs | [https://www.hammerspoon.org/docs/LuaSkin/](https://www.hammerspoon.org/docs/LuaSkin/) |
## API Documentation
| Module | Description |
| ------------------------------------------------------------------ | --------------------- |
| [cp](cp.md) | Core CommandPost functionality. |
| [cp.18n](cp.18n.md) | CommandPost's Internationalisation & Localisation Manger. |
+| [cp.adobe.aftereffects](cp.adobe.aftereffects.md) | Adobe After Effects Extension |
+| [cp.adobe.aftereffects.app](cp.adobe.aftereffects.app.md) | The `cp.app` for Adobe After Effects. |
+| [cp.adobe.aftereffects.shortcuts](cp.adobe.aftereffects.shortcuts.md) | Translations between After Effects shortcuts and Hammerspoon-friendly shortcuts. |
| [cp.app](cp.app.md) | This class assists with working with macOS apps. It provides functions for |
| [cp.app.menu](cp.app.menu.md) | Represents an app's menu bar, providing multi-lingual access to find and |
| [cp.app.prefs](cp.app.prefs.md) | Provides access to application preferences, typically stored via `NSUserDefaults` or `CFProperties`. |
diff --git a/api/hs/hs.application.md b/api/hs/hs.application.md
index 6946268..4a07fc6 100644
--- a/api/hs/hs.application.md
+++ b/api/hs/hs.application.md
@@ -331,7 +331,7 @@ Manipulate running applications
| **Signature** | `hs.application:name()` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
-| **Description** | Alias for `hs.application:title()` |
+| **Description** | Alias for [`hs.application:title()`](#title) |
#### [path](#path)
| **Signature** | `hs.application:path() -> string` |
diff --git a/api/hs/hs.audiodevice.md b/api/hs/hs.audiodevice.md
index 298cac0..199f5d8 100644
--- a/api/hs/hs.audiodevice.md
+++ b/api/hs/hs.audiodevice.md
@@ -15,6 +15,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
* [allInputDevices](#allinputdevices)
* [allOutputDevices](#alloutputdevices)
* [current](#current)
+ * [defaultEffectDevice](#defaulteffectdevice)
* [defaultInputDevice](#defaultinputdevice)
* [defaultOutputDevice](#defaultoutputdevice)
* [findDeviceByName](#finddevicebyname)
@@ -39,6 +40,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
* [outputMuted](#outputmuted)
* [outputVolume](#outputvolume)
* [setBalance](#setbalance)
+ * [setDefaultEffectDevice](#setdefaulteffectdevice)
* [setDefaultInputDevice](#setdefaultinputdevice)
* [setDefaultOutputDevice](#setdefaultoutputdevice)
* [setInputMuted](#setinputmuted)
@@ -93,6 +95,14 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Parameters** | - output - An optional boolean, true to fetch information about the default input device, false for output device. Defaults to false
|
| **Returns** | - A table with the following contents:
lua { name = defaultOutputDevice():name(), uid = module.defaultOutputDevice():uid(), muted = defaultOutputDevice():muted(), volume = defaultOutputDevice():volume(), device = defaultOutputDevice(), }
|
+#### [defaultEffectDevice](#defaulteffectdevice)
+| **Signature** | `hs.audiodevice.defaultEffectDevice() -> audio or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Get the currently selected sound effect device |
+| **Parameters** | |
+| **Returns** | - An hs.audiodevice object, or nil if no suitable device could be found
|
+
#### [defaultInputDevice](#defaultinputdevice)
| **Signature** | `hs.audiodevice.defaultInputDevice() -> audio or nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -286,6 +296,14 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Returns** | - True if the balance was set, false if the audio device does not support setting a balance.
|
| **Notes** | - This method will inspect the device to determine if it is an input or output device, and set the appropriate volume. For devices that are both input and output devices, see
:setInputVolume() and :setOutputVolume()
|
+#### [setDefaultEffectDevice](#setdefaulteffectdevice)
+| **Signature** | `hs.audiodevice:setDefaultEffectDevice() -> bool` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Selects this device as the audio output device for system sound effects |
+| **Parameters** | |
+| **Returns** | - True if the audio device was successfully selected, otherwise false.
|
+
#### [setDefaultInputDevice](#setdefaultinputdevice)
| **Signature** | `hs.audiodevice:setDefaultInputDevice() -> bool` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/hs/hs.audiounit.md b/api/hs/hs.audiounit.md
deleted file mode 100644
index 48789e5..0000000
--- a/api/hs/hs.audiounit.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# [docs](index.md) » hs.audiounit
----
-
-Audio Units Extension.
-
-## API Overview
-* Functions - API calls offered directly by the extension
- * [getAudioEffectNames](#getaudioeffectnames)
-
-## API Documentation
-
-### Functions
-
-#### [getAudioEffectNames](#getaudioeffectnames)
-| **Signature** | `hs.audiounit.getAudioEffectNames() -> table` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Gets a table of installed Audio Units Effect names. |
-| **Parameters** | |
-| **Returns** | - A table containing the names of all installed Audio Units Effects.
|
-| **Notes** | - Example usage:
hs.inspect(hs.audiounit.getAudioEffectNames())
|
-
diff --git a/api/hs/hs.axuielement.axtextmarker.md b/api/hs/hs.axuielement.axtextmarker.md
new file mode 100644
index 0000000..f5c8767
--- /dev/null
+++ b/api/hs/hs.axuielement.axtextmarker.md
@@ -0,0 +1,97 @@
+# [docs](index.md) » hs.axuielement.axtextmarker
+---
+
+This submodule allows hs.axuielement to support using AXTextMarker and AXTextMarkerRange objects as parameters for parameterized Accessibility attributes with applications that support them.
+
+Most Accessibility object values correspond to the common data types found in most programming languages -- strings, numbers, tables (arrays and dictionaries), etc. AXTextMarker and AXTextMarkerRange types are application specific and do not have a direct mapping to a simple data type. The description I've found most apt comes from comments within the Chromium source for the Mac version of their browser:
+
+> // A serialization of a position as POD. Not for sharing on disk or sharing
+> // across thread or process boundaries, just for passing a position to an
+> // API that works with positions as opaque objects.
+
+This submodule allows Lua to represent these as userdata which can be passed in to parameterized attributes for the appliction from which they were retrieved. Examples are expected to be added to the Hammerspoon wiki soon.
+
+As this submodule utilizes private and undocumented functions in the HIServices framework, if you receive an error using any of these functions or methods indicating an undefined CF function (the function or method will return nil and a string of the format "CF function AX... undefined"), please make sure to include the output of the following in any issue you submit to the Hammerspoon github page (enter these into the Hammerspoon console):
+
+ hs.inspect(hs.axuielement.axtextmarker._functionCheck())
+ hs.inspect(hs.processInfo)
+ hs.host.operatingSystemVersionString()
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [_functionCheck](#_functioncheck)
+ * [bytes](#bytes)
+ * [endMarker](#endmarker)
+ * [length](#length)
+ * [startMarker](#startmarker)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [newMarker](#newmarker)
+ * [newRange](#newrange)
+
+## API Documentation
+
+### Functions
+
+#### [_functionCheck](#_functioncheck)
+| **Signature** | `hs.axuielement.axtextmarker._functionCheck() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns a table of the AXTextMarker and AXTextMarkerRange functions that have been discovered and are used within this module. |
+| **Parameters** | |
+| **Returns** | - a table with key-value pairs where the keys correspond to the undocumented Core Foundation functions required by this module to support AXTextMarker and AXTextMarkerRange and the value will be a boolean indicating whether the function exists in the currently loaded frameworks.
|
+| **Notes** | - the functions are defined within the HIServices framework which is part of the ApplicationServices framework, so it is expected that the necessary functions will always be available; however, if you ever receive an error message from a function or method within this submodule of the form "CF function AX... undefined", please see the submodule heading documentation for a description of the information, including that which this function provides, that should be included in any error report you submit.
|
+
+#### [bytes](#bytes)
+| **Signature** | `hs.axuielement.axtextmarker:bytes() -> string | nil, errorString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns a string containing the opaque binary data contained within the axTextMarkerObject |
+| **Parameters** | |
+| **Returns** | - a string containing the opaque binary data contained within the axTextMarkerObject
|
+| **Notes** | - the string will likely contain invalid UTF8 code sequences or unprintable ascii values; to see the data in decimal or hexidecimal form you can use:
|
+
+#### [endMarker](#endmarker)
+| **Signature** | `hs.axuielement.axtextmarker:endMarker() -> axTextMarkerObject | nil, errorString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns the ending marker for an axTextMarkerRangeObject |
+| **Parameters** | |
+| **Returns** | - the ending marker for an axTextMarkerRangeObject
|
+
+#### [length](#length)
+| **Signature** | `hs.axuielement.axtextmarker:length() -> integer | nil, errorString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns an integer specifying the number of bytes in the data portion of the axTextMarkerObject. |
+| **Parameters** | |
+| **Returns** | - an integer specifying the number of bytes in the data portion of the axTextMarkerObject
|
+| **Notes** | - As the data is application specific, it is unlikely that you will use this method often; it is included primarily for testing and debugging purposes.
|
+
+#### [startMarker](#startmarker)
+| **Signature** | `hs.axuielement.axtextmarker:startMarker() -> axTextMarkerObject | nil, errorString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns the starting marker for an axTextMarkerRangeObject |
+| **Parameters** | |
+| **Returns** | - the starting marker for an axTextMarkerRangeObject
|
+
+### Constructors
+
+#### [newMarker](#newmarker)
+| **Signature** | `hs.axuielement.axtextmarker.newMarker(string) -> axTextMarkerObject | nil, errorString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new AXTextMarker object from the string of binary data provided |
+| **Parameters** | string - a string containing 1 or more bytes of data for the AXTextMarker object
|
+| **Returns** | - a new axTextMarkerObject or nil and a string description if there was an error
|
+| **Notes** | - This function is included primarily for testing and debugging purposes -- in general you will probably never use this constructor; AXTextMarker objects appear to be mostly application dependant and have no meaning external to the application from which it was created.
|
+
+#### [newRange](#newrange)
+| **Signature** | `hs.axuielement.axtextmarker.newRange(startMarker, endMarker) -> axTextMarkerRangeObject | nil, errorString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new AXTextMarkerRange object from the start and end markers provided |
+| **Parameters** | startMarker - an axTextMarkerObject representing the start of the range to be createdendMarker - an axTextMarkerObject representing the end of the range to be created
|
+| **Returns** | - a new axTextMarkerRangeObject or nil and a string description if there was an error
|
+| **Notes** | - this constructor can be used to create a range from axTextMarkerObjects obtained from an application to specify a new range for a paramterized attribute. As a simple example (it is hoped that more will be added to the Hammerspoon wiki shortly):
|
+
diff --git a/api/hs/hs.axuielement.md b/api/hs/hs.axuielement.md
new file mode 100644
index 0000000..fa74c88
--- /dev/null
+++ b/api/hs/hs.axuielement.md
@@ -0,0 +1,413 @@
+# [docs](index.md) » hs.axuielement
+---
+
+This module allows you to access the accessibility objects of running applications, their windows, menus, and other user interface elements that support the OS X accessibility API.
+
+This module works through the use of axuielementObjects, which is the Hammerspoon representation for an accessibility object. An accessibility object represents any object or component of an OS X application which can be manipulated through the OS X Accessibility API -- it can be an application, a window, a button, selected text, etc. As such, it can only support those features and objects within an application that the application developers make available through the Accessibility API.
+
+In addition to the formal methods described in this documentation, dynamic methods exist for accessing element attributes and actions. These will differ somewhat between objects as the specific attributes and actions will depend upon the accessibility object's role and purpose, but the following outlines the basics.
+
+Getting and Setting Attribute values:
+ * `object.attribute` is a shortcut for `object:attributeValue(attribute)`
+ * `object.attribute = value` is a shortcut for `object:setAttributeValue(attribute, value)`
+ * If detecting accessiblity errors that may occur is necessary, you must use the formal methods [hs.axuielement:attributeValue](#attributeValue) and [hs.axuielement:setAttributeValue](#setAttributeValue)
+ * Note that setting an attribute value is not guaranteeed to work with either method:
+ * internal logic within the receiving application may decline to accept the newly assigned value
+ * an accessibility error may occur
+ * the element may not be settable (surprisingly this does not return an error, even when [hs.axuielement:isAttributeSettable](#isAttributeSettable) returns false for the attribute specified)
+ * If you require confirmation of the change, you will need to check the value of the attribute with one of the methods described above after setting it.
+
+Iteration over Attributes:
+ * `for k,v in pairs(object) do ... end` is a shortcut for `for k,_ in ipairs(object:attributeNames()) do local v = object:attributeValue(k) ; ... end` or `for k,v in pairs(object:allAttributeValues()) do ... end` (though see note below)
+ * If detecting accessiblity errors that may occur is necessary, you must use one of the formal approaches [hs.axuielement:allAttributeValues](#allAttributeValues) or [hs.axuielement:attributeNames](#attributeNames) and [hs.axuielement:attributeValue](#attributeValue)
+ * By default, [hs.axuielement:allAttributeValues](#allAttributeValues) will not include key-value pairs for which the attribute (key) exists for the element but has no assigned value (nil) at the present time. This is because the value of `nil` prevents the key from being retained in the table returned. See [hs.axuielement:allAttributeValues](#allAttributeValues) for details and a workaround.
+
+Iteration over Child Elements (AXChildren):
+ * `for i,v in ipairs(object) do ... end` is a shortcut for `for i,v in pairs(object:attributeValue("AXChildren") or {}) do ... end`
+ * Note that `object:attributeValue("AXChildren")` *may* return nil if the object does not have the `AXChildren` attribute; the shortcut does not have this limitation.
+ * `#object` is a shortcut for `#object:attributeValue("AXChildren")`
+ * `object[i]` is a shortcut for `object:attributeValue("AXChildren")[i]`
+ * If detecting accessiblity errors that may occur is necessary, you must use the formal method [hs.axuielement:attributeValue](#attributeValue) to get the "AXChildren" attribute.
+
+Actions ([hs.axuielement:actionNames](#actionNames)):
+ * `object:do()` is a shortcut for `object:performAction(action)`
+ * See [hs.axuielement:performAction](#performAction) for a description of the return values and [hs.axuielement:actionNames](#actionNames) to get a list of actions that the element supports.
+
+ParameterizedAttributes:
+ * `object:WithParameter(value)` is a shortcut for `object:parameterizedAttributeValue(attribute, value)
+ * See [hs.axuielement:parameterizedAttributeValue](#parameterizedAttributeValue) for a description of the return values and [hs.axuielement:parameterizedAttributeNames](#parameterizedAttributeNames) to get a list of parameterized values that the element supports
+
+ * The specific value required for a each parameterized attribute is different and is often application specific thus requiring some experimentation. Notes regarding identified parameter types and thoughts on some still being investigated will be provided in the Hammerspoon Wiki, hopefully shortly after this module becomes part of a Hammerspoon release.
+
+## Submodules
+ * [hs.axuielement.axtextmarker](hs.axuielement.axtextmarker.md)
+ * [hs.axuielement.observer](hs.axuielement.observer.md)
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [actions](#actions)
+ * [attributes](#attributes)
+ * [orientations](#orientations)
+ * [parameterizedAttributes](#parameterizedattributes)
+ * [roles](#roles)
+ * [rulerMarkers](#rulermarkers)
+ * [sortDirections](#sortdirections)
+ * [subroles](#subroles)
+ * [units](#units)
+* Functions - API calls offered directly by the extension
+ * [searchCriteriaFunction](#searchcriteriafunction)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [applicationElement](#applicationelement)
+ * [applicationElementForPID](#applicationelementforpid)
+ * [systemElementAtPosition](#systemelementatposition)
+ * [systemWideElement](#systemwideelement)
+ * [windowElement](#windowelement)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [actionDescription](#actiondescription)
+ * [actionNames](#actionnames)
+ * [allAttributeValues](#allattributevalues)
+ * [allDescendantElements](#alldescendantelements)
+ * [asHSApplication](#ashsapplication)
+ * [asHSWindow](#ashswindow)
+ * [attributeNames](#attributenames)
+ * [attributeValue](#attributevalue)
+ * [attributeValueCount](#attributevaluecount)
+ * [buildTree](#buildtree)
+ * [copy](#copy)
+ * [elementAtPosition](#elementatposition)
+ * [elementSearch](#elementsearch)
+ * [isAttributeSettable](#isattributesettable)
+ * [isValid](#isvalid)
+ * [matchesCriteria](#matchescriteria)
+ * [parameterizedAttributeNames](#parameterizedattributenames)
+ * [parameterizedAttributeValue](#parameterizedattributevalue)
+ * [path](#path)
+ * [performAction](#performaction)
+ * [pid](#pid)
+ * [setAttributeValue](#setattributevalue)
+ * [setTimeout](#settimeout)
+
+## API Documentation
+
+### Constants
+
+#### [actions](#actions)
+| **Signature** | `hs.axuielement.actions[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of common accessibility object action names, provided for reference. |
+| **Notes** | - this table is provided for reference only and is not intended to be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.actions
|
+
+#### [attributes](#attributes)
+| **Signature** | `hs.axuielement.attributes[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of common accessibility object attribute names which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as keys in the match criteria argument. |
+| **Notes** | - This table is provided for reference only and is not intended to be comprehensive.
- You can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.attributes
|
+
+#### [orientations](#orientations)
+| **Signature** | `hs.axuielement.orientations[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of orientation types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXOrientation" in the match criteria argument. |
+| **Notes** | - this table is provided for reference only and may not be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.orientations
|
+
+#### [parameterizedAttributes](#parameterizedattributes)
+| **Signature** | `hs.axuielement.parameterizedAttributes[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of common accessibility object parameterized attribute names, provided for reference. |
+| **Notes** | - this table is provided for reference only and is not intended to be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.parameterizedAttributes
|
+
+#### [roles](#roles)
+| **Signature** | `hs.axuielement.roles[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of common accessibility object roles which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXRole" in the match criteria argument. |
+| **Notes** | - this table is provided for reference only and is not intended to be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.roles
|
+
+#### [rulerMarkers](#rulermarkers)
+| **Signature** | `hs.axuielement.rulerMarkers[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of ruler marker types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXMarkerType" in the match criteria argument. |
+| **Notes** | - this table is provided for reference only and may not be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.rulerMarkers
|
+
+#### [sortDirections](#sortdirections)
+| **Signature** | `hs.axuielement.sortDirections[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of sort direction types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXSortDirection" in the match criteria argument. |
+| **Notes** | - this table is provided for reference only and may not be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.sortDirections
|
+
+#### [subroles](#subroles)
+| **Signature** | `hs.axuielement.subroles[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of common accessibility object subroles which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXSubrole" in the match criteria argument. |
+| **Notes** | - this table is provided for reference only and is not intended to be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.subroles
|
+
+#### [units](#units)
+| **Signature** | `hs.axuielement.units[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of measurement unit types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for attributes which specify measurement unit types (e.g. "AXUnits", "AXHorizontalUnits", and "AXVerticalUnits") in the match criteria argument. |
+| **Notes** | - this table is provided for reference only and may not be comprehensive.
- you can view the contents of this table from the Hammerspoon console by typing in
hs.axuielement.units
|
+
+### Functions
+
+#### [searchCriteriaFunction](#searchcriteriafunction)
+| **Signature** | `hs.axuielement.searchCriteriaFunction(criteria) -> function` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns a function for use with [hs.axuielement:elementSearch](#elementSearch) that uses [hs.axuielement:matchesCriteria](#matchesCriteria) with the specified criteria. |
+| **Parameters** | |
+| **Returns** | |
+
+### Constructors
+
+#### [applicationElement](#applicationelement)
+| **Signature** | `hs.axuielement.applicationElement(applicationObject) -> axuielementObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Returns the top-level accessibility object for the application specified by the `hs.application` object. |
+| **Parameters** | applicationObject - the hs.application object for the Application or a string or number which will be passed to hs.application.find to get an hs.application object.
|
+| **Returns** | - an axuielementObject for the application specified
|
+| **Notes** | - if
applicationObject is a string or number, only the first item found with hs.application.find will be used by this function to create an axuielementObject.
|
+
+#### [applicationElementForPID](#applicationelementforpid)
+| **Signature** | `hs.axuielement.applicationElementForPID(pid) -> axuielementObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Returns the top-level accessibility object for the application with the specified process ID. |
+| **Parameters** | pid - the process ID of the application.
|
+| **Returns** | - an axuielementObject for the application specified, or nil if it cannot be determined
|
+
+#### [systemElementAtPosition](#systemelementatposition)
+| **Signature** | `hs.axuielement.systemElementAtPosition(x, y | pointTable) -> axuielementObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Returns the accessibility object at the specified position on the screen. The top-left corner of the primary screen is 0, 0. |
+| **Parameters** | x - the x coordinate of the screen location to testy - the y coordinate of the screen location to testpointTable - the x and y coordinates of the screen location to test, provided as a point-table, like the one returned by hs.mouse.getAbsolutePosition. A point-table is a table with key-value pairs for keys x and y.
|
+| **Returns** | - an axuielementObject for the object at the specified coordinates, or nil if no object could be identified.
|
+| **Notes** | |
+
+#### [systemWideElement](#systemwideelement)
+| **Signature** | `hs.axuielement.systemWideElement() -> axuielementObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Returns an accessibility object that provides access to system attributes. |
+| **Parameters** | |
+| **Returns** | - the axuielementObject for the system attributes
|
+
+#### [windowElement](#windowelement)
+| **Signature** | `hs.axuielement.windowElement(windowObject) -> axuielementObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Returns the accessibility object for the window specified by the `hs.window` object. |
+| **Parameters** | windowObject - the hs.window object for the window or a string or number which will be passed to hs.window.find to get an hs.window object.
|
+| **Returns** | - an axuielementObject for the window specified
|
+| **Notes** | - if
windowObject is a string or number, only the first item found with hs.window.find will be used by this function to create an axuielementObject.
|
+
+### Methods
+
+#### [actionDescription](#actiondescription)
+| **Signature** | `hs.axuielement:actionDescription(action) -> string | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a localized description of the specified accessibility object's action. |
+| **Parameters** | |
+| **Returns** | - a string containing a description of the object's action, nil if no description is available, or nil and an error string if an accessibility error occurred
|
+| **Notes** | - The action descriptions are provided by the target application; as such their accuracy and usefulness rely on the target application's developers.
|
+
+#### [actionNames](#actionnames)
+| **Signature** | `hs.axuielement:actionNames() -> table | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a list of all the actions the specified accessibility object can perform. |
+| **Parameters** | |
+| **Returns** | - an array of the names of all actions supported by the axuielementObject or nil and an error string if an accessibility error occurred
|
+| **Notes** | - Common action names can be found in the hs.axuielement.actions table; however, this method will list only those names which are supported by this object, and is not limited to just those in the referenced table.
|
+
+#### [allAttributeValues](#allattributevalues)
+| **Signature** | `hs.axuielement:allAttributeValues([includeErrors]) -> table | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table containing key-value pairs for all attributes of the accessibility object. |
+| **Parameters** | includeErrors - an optional boolean, default false, that specifies whether attribute names which generate an error when retrieved are included in the returned results.
|
+| **Returns** | - a table with key-value pairs corresponding to the attributes of the accessibility object or nil and an error string if an accessibility error occurred
|
+| **Notes** | - if
includeErrors is not specified or is false, then attributes which exist for the element, but currently have no value assigned, will not appear in the table. This is because Lua treats a nil value for a table's key-value pair as an instruction to remove the key from the table, if it currently exists. - To include attributes which exist but are currently unset, you need to specify
includeErrors as true. - attributes for which no value is currently assigned will be given a table value with the following key-value pairs:
_code = -25212error = "Requested value does not exist"
|
+
+#### [allDescendantElements](#alldescendantelements)
+| **Signature** | `hs.axuielement:allDescendantElements(callback, [withParents]) -> elementSearchObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Query the accessibility object for all child accessibility objects and their descendants |
+| **Parameters** | callback - a required function which should expect two arguments: a msg string specifying how the search ended, and a table containing the discovered descendant elements. msg will be "completed" when the traversal has completed normally and will contain a string starting with "**" if it terminates early for some reason (see Notes: section for more information)withParents - an optional boolean, default false, indicating that the parent of objects (and their descendants) should be collected as well.
|
+| **Returns** | |
+| **Notes** | - This method is syntactic sugar for
hs.axuielement:elementSearch(callback, { [includeParents = withParents] }). Please refer to hs.axuielement:elementSearch for details about the returned object and callback arguments.
|
+
+#### [asHSApplication](#ashsapplication)
+| **Signature** | `hs.axuielement:asHSApplication() -> hs.application object | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | If the element referes to an application, return an `hs.application` object for the element. |
+| **Parameters** | |
+| **Returns** | - if the element refers to an application, return an
hs.application object for the element ; otherwise return nil
|
+| **Notes** | - An element is considered an application by this method if it has an AXRole of AXApplication and has a process identifier (pid).
|
+
+#### [asHSWindow](#ashswindow)
+| **Signature** | `hs.axuielement:asHSWindow() -> hs.window object | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | If the element referes to a window, return an `hs.window` object for the element. |
+| **Parameters** | |
+| **Returns** | - if the element refers to a window, return an
hs.window object for the element ; otherwise return nil
|
+| **Notes** | - An element is considered a window by this method if it has an AXRole of AXWindow.
|
+
+#### [attributeNames](#attributenames)
+| **Signature** | `hs.axuielement:attributeNames() -> table | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a list of all the attributes supported by the specified accessibility object. |
+| **Parameters** | |
+| **Returns** | - an array of the names of all attributes supported by the axuielementObject or nil and an error string if an accessibility error occurred
|
+| **Notes** | - Common attribute names can be found in the hs.axuielement.attributes tables; however, this method will list only those names which are supported by this object, and is not limited to just those in the referenced table.
|
+
+#### [attributeValue](#attributevalue)
+| **Signature** | `hs.axuielement:attributeValue(attribute) -> value | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the value of an accessibility object's attribute. |
+| **Parameters** | |
+| **Returns** | - the current value of the attribute, nil if the attribute has no value, or nil and an error string if an accessibility error occurred
|
+
+#### [attributeValueCount](#attributevaluecount)
+| **Signature** | `hs.axuielement:attributeValueCount(attribute) -> integer | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the count of the array of an accessibility object's attribute value. |
+| **Parameters** | |
+| **Returns** | - the number of items in the value for the attribute, if it is an array, or nil and an error string if an accessibility error occurred
|
+
+#### [buildTree](#buildtree)
+| **Signature** | `hs.axuielement:buildTree(callback, [depth], [withParents]) -> elementSearchObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Captures all of the available information for the accessibility object and its descendants and returns it in a table for inspection. |
+| **Parameters** | callback - a required function which should expect two arguments: a msg string specifying how the search ended, and a table containing the recorded information. msg will be "completed" when the search has completed normally (or reached the specified depth) and will contain a string starting with "**" if it terminates early for some reason (see Notes: section for more information)depth - an optional integer, default math.huge, specifying the maximum depth from the initial accessibility object that should be visited to identify descendant elements and their attributes.withParents - an optional boolean, default false, specifying whether or not an element's (or descendant's) attributes for AXParent and AXTopLevelUIElement should also be visited when identifying additional elements to include in the results table.
|
+| **Returns** | |
+| **Notes** | - The format of the
results table passed to the callback for this method is primarily for debugging and exploratory purposes and may not be arranged for easy programatic evaluation.
|
+
+#### [copy](#copy)
+| **Signature** | `hs.axuielement:copy() -> axuielementObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Return a duplicate userdata reference to the Accessibility object. |
+| **Parameters** | |
+| **Returns** | - a new userdata object representing a new reference to the Accessibility object.
|
+
+#### [elementAtPosition](#elementatposition)
+| **Signature** | `hs.axuielement:elementAtPosition(x, y | pointTable) -> axuielementObject | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the accessibility object at the specified position on the screen. The top-left corner of the primary screen is 0, 0. |
+| **Parameters** | x - the x coordinate of the screen location to tesy - the y coordinate of the screen location to testpointTable - the x and y coordinates of the screen location to test, provided as a point-table, like the one returned by hs.mouse.getAbsolutePosition. A point-table is a table with key-value pairs for keys x and y.
|
+| **Returns** | - an axuielementObject for the object at the specified coordinates, or nil and an error string if no object could be identified or an accessibility error occurred
|
+| **Notes** | |
+
+#### [elementSearch](#elementsearch)
+| **Signature** | `hs.axuielement:elementSearch(callback, [criteria], [namedModifiers]) -> elementSearchObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Search for and generate a table of the accessibility elements for the attributes and descendants of this object based on the specified criteria. |
+| **Parameters** | callback - a (usually) required function which will receive the results of this search. The callback should expect three arguments and return none. The arguments to the callback function will be msg, a string specifying how the search ended and results, the elementSearchObject containing the requested results, and the number of items added to the results (see count in namedModifiers). msg will be "completed" if the search completes normally, or a string starting with "**" if it is terminated early (see Returns: and Notes: for more details).criteria - an optional function which should accept one argument (the current element being examined) and return true if it should be included in the results or false if it should be rejected. See hs.axuielement.searchCriteriaFunction to create a search function that uses hs.axuielement:matchesCriteria for evaluation.namedModifiers - an optional table specifying key-value pairs that further modify or control the search. This table may contain 0 or more of the following keys:count - an optional integer, default math.huge, specifying the maximum number of matches to collect before ending the search and invoking the callback. You can continue the search to find additional elements by invoking elementSearchObject:next() (described below in the Returns section) on the return value of this method, or on the results argument passed to the callback.depth - an optional integer, default math.huge, specifying the maximum number of steps (descendants) from the initial accessibility element the search should visit. If you know that your desired element(s) are relatively close to your starting element, setting this to a lower value can significantly speed up the search.
|
+| **Returns** | - an elementSearchObject which contains metamethods allowing you to check to see if the process has completed and cancel it early if desired. The methods include:
elementSearchObject:cancel([reason]) - cancels the current search and invokes the callback with the partial results already collected. If you specify reason, the msg argument for the callback will be ** <reason>; otherwise it will be "** cancelled".elementSearchObject:isRunning() - returns true if the search is currently ongoing or false if it has completed or been cancelled.elementSearchObject:matched() - returns an integer specifying the number of elements which have already been found that meet the specified criteria function.elementSearchObject:runTime() - returns an integer specifying the number of seconds spent performing this search. Note that this is not an accurate measure of how much time a given search will always take because the time will be greatly affected by how much other activity is occurring within Hammerspoon and on the users computer. Resuming a cancelled search or a search which invoked the callback because it reached count items with the next method (descibed below) will cause this number to begin increasing again to provide a cumulative total of time spent performing the search; time between when the callback is invoked and the next method is invoked is not included.elementSearchObject:visited() - returns an integer specifying the number of elements which have been examined during the search so far.
|
+| **Notes** | - This method utilizes coroutines to keep Hammerspoon responsive, but may be slow to complete if
includeParents is true, if you do not specify depth, or if you start from an element that has a lot of descendants (e.g. the application element for a web browser). This is dependent entirely upon how many active accessibility elements the target application defines and where you begin your search and cannot reliably be determined up front, so you may need to experiment to find the best balance for your specific requirements.
|
+
+#### [isAttributeSettable](#isattributesettable)
+| **Signature** | `hs.axuielement:isAttributeSettable(attribute) -> boolean | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns whether the specified accessibility object's attribute can be modified. |
+| **Parameters** | |
+| **Returns** | - a boolean value indicating whether or not the value of the parameter can be modified or nil and an error string if an accessibility error occurred
|
+
+#### [isValid](#isvalid)
+| **Signature** | `hs.axuielement:isValid() -> boolean | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns whether the specified accessibility object is still valid. |
+| **Parameters** | |
+| **Returns** | - a boolean value indicating whether or not the accessibility object is still valid or nil and an error string if any other accessibility error occurred
|
+| **Notes** | - an accessibilityObject can become invalid for a variety of reasons, including but not limited to the element referred to no longer being available (e.g. an element referring to a window or one of its descendants that has been closed) or the application terminating.
|
+
+#### [matchesCriteria](#matchescriteria)
+| **Signature** | `hs.axuielement:matchesCriteria(criteria) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns true if the axuielementObject matches the specified criteria or false if it does not. |
+| **Parameters** | criteria - the criteria to compare against the accessibility object
|
+| **Returns** | - true if the axuielementObject matches the criteria, false if it does not.
|
+| **Notes** | - the
criteria argument must be one of the following: - a single string, specifying the value the element's AXRole attribute must equal for a positive match
|
+
+#### [parameterizedAttributeNames](#parameterizedattributenames)
+| **Signature** | `hs.axuielement:parameterizedAttributeNames() -> table | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a list of all the parameterized attributes supported by the specified accessibility object. |
+| **Parameters** | |
+| **Returns** | - an array of the names of all parameterized attributes supported by the axuielementObject or nil and an error string if an accessibility error occurred
|
+
+#### [parameterizedAttributeValue](#parameterizedattributevalue)
+| **Signature** | `hs.axuielement:parameterizedAttributeValue(attribute, parameter) -> value | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the value of an accessibility object's parameterized attribute. |
+| **Parameters** | |
+| **Returns** | - the current value of the parameterized attribute, nil if the parameterized attribute has no value, or nil and an error string if an accessibility error occurred
|
+| **Notes** | - The specific parameter required for a each parameterized attribute is different and is often application specific thus requiring some experimentation. Notes regarding identified parameter types and thoughts on some still being investigated will be provided in the Hammerspoon Wiki, hopefully shortly after this module becomes part of a Hammerspoon release.
|
+
+#### [path](#path)
+| **Signature** | `hs.axuielement:path() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table of axuielements tracing this object through its parent objects to the root for this element, most likely an application object or the system wide object. |
+| **Parameters** | |
+| **Returns** | - a table containing this object and 0 or more parent objects representing the path from the root object to this element.
|
+| **Notes** | - this object will always exist as the last element in the table (e.g. at
table[#table]) with its most immediate parent at #table - 1, etc. until the rootmost object for this element is reached at index position 1.
|
+
+#### [performAction](#performaction)
+| **Signature** | `hs.axuielement:performAction(action) -> axuielement | false | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Requests that the specified accessibility object perform the specified action. |
+| **Parameters** | |
+| **Returns** | - if the requested action was accepted by the target, returns the axuielementObject; if the requested action was rejected, returns false; otherwise returns nil and an error string if an accessibility error occurred
|
+| **Notes** | - The return value only suggests success or failure, but is not a guarantee. The receiving application may have internal logic which prevents the action from occurring at this time for some reason, even though this method returns success (the axuielementObject). Contrawise, the requested action may trigger a requirement for a response from the user and thus appear to time out, causing this method to return false or nil.
|
+
+#### [pid](#pid)
+| **Signature** | `hs.axuielement:pid() -> integer | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the process ID associated with the specified accessibility object. |
+| **Parameters** | |
+| **Returns** | - the process ID for the application to which the accessibility object ultimately belongs or nil and an error string if an accessibility error occurred
|
+
+#### [setAttributeValue](#setattributevalue)
+| **Signature** | `hs.axuielement:setAttributeValue(attribute, value) -> axuielementObject | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets the accessibility object's attribute to the specified value. |
+| **Parameters** | |
+| **Returns** | - the axuielementObject on success; nil and an error string if the attribute could not be set or an accessibility error occurred.
|
+
+#### [setTimeout](#settimeout)
+| **Signature** | `hs.axuielement:setTimeout(value) -> axuielementObject | nil, errString` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets the timeout value used accessibility queries performed from this element. |
+| **Parameters** | value - the number of seconds for the new timeout value. Must be 0 or positive.
|
+| **Returns** | - the axuielementObject or nil and an error string if an accessibility error occurred
|
+| **Notes** | - To change the global timeout affecting all queries on elements which do not have a specific timeout set, use this method on the systemwide element (see hs.axuielement.systemWideElement.
- Changing the timeout value for an axuielement object only changes the value for that specific element -- other axuieleement objects that may refer to the identical accessibiity item are not affected.
|
+
diff --git a/api/hs/hs.axuielement.observer.md b/api/hs/hs.axuielement.observer.md
new file mode 100644
index 0000000..f76b906
--- /dev/null
+++ b/api/hs/hs.axuielement.observer.md
@@ -0,0 +1,105 @@
+# [docs](index.md) » hs.axuielement.observer
+---
+
+This submodule allows you to create observers for accessibility elements and be notified when they trigger notifications. Not all notifications are supported by all elements and not all elements support notifications, so some trial and error will be necessary, but for compliant applications, this can allow your code to be notified when an application's user interface changes in some way.
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [notifications](#notifications)
+* 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
+ * [addWatcher](#addwatcher)
+ * [callback](#callback)
+ * [isRunning](#isrunning)
+ * [removeWatcher](#removewatcher)
+ * [start](#start)
+ * [stop](#stop)
+ * [watching](#watching)
+
+## API Documentation
+
+### Constants
+
+#### [notifications](#notifications)
+| **Signature** | `hs.axuielement.observer.notifications[]` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | A table of common accessibility object notification names, provided for reference. |
+| **Notes** | - Notifications are application dependent and can be any string that the application developers choose; this list provides the suggested notification names found within the macOS Framework headers, but the list is not exhaustive nor is an application or element required to provide them.
|
+
+### Constructors
+
+#### [new](#new)
+| **Signature** | `hs.axuielement.observer.new(pid) -> observerObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new observer object for the application with the specified process ID. |
+| **Parameters** | pid - the process ID of the application.
|
+| **Returns** | - a new observerObject; generates an error if the pid does not exist or if the object cannot be created.
|
+| **Notes** | - If you already have the
hs.application object for an application, you can get its process ID with hs.application:pid() - If you already have an
hs.axuielement from the application you wish to observe (it doesn't have to be the application axuielement object, just one belonging to the application), you can get the process ID with hs.axuielement:pid().
|
+
+### Methods
+
+#### [addWatcher](#addwatcher)
+| **Signature** | `hs.axuielement.observer:addWatcher(element, notification) -> observerObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Registers the specified notification for the specified accesibility element with the observer. |
+| **Parameters** | element - the hs.axuielement representing an accessibility element of the application the observer was created for.notification - a string specifying the notification.
|
+| **Returns** | - the observerObject; generates an error if watcher cannot be registered
|
+| **Notes** | - multiple notifications for the same accessibility element can be registered by invoking this method multiple times with the same element but different notification strings.
- if the specified element and notification string are already registered, this method does nothing.
- the notification string is application dependent and can be any string that the application developers choose; some common ones are found in
hs.axuielement.observer.notifications, but the list is not exhaustive nor is an application or element required to provide them.
|
+
+#### [callback](#callback)
+| **Signature** | `hs.axuielement.observer:callback([fn]) -> observerObject | fn | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Get or set the callback for the observer. |
+| **Parameters** | fn - a function, specifying the callback to the observer will invoke when the assigned elements generate notifications. If nil is supplied, the existing callback function will be removed
|
+| **Returns** | - If an argument is provided, the observerObject; otherwise the current value.
|
+| **Notes** | - the callback should expect 4 arguments and return none. The arguments passed to the callback will be as follows:
- the observerObject itself
- the
hs.axuielement object for the accessibility element which generated the notification - a string specifying the specific notification which was received
- a table containing key-value pairs with more information about the notification, if the element and notification type provide it. Commonly this will be an empty table indicating that no additional detail was provided.
|
+
+#### [isRunning](#isrunning)
+| **Signature** | `hs.axuielement.observer:isRunning() -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns true or false indicating whether the observer is currently watching for notifications and generating callbacks. |
+| **Parameters** | |
+| **Returns** | - a boolean value indicating whether or not the observer is currently active.
|
+
+#### [removeWatcher](#removewatcher)
+| **Signature** | `hs.axuielement.observer:removeWatcher(element, notification) -> observerObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Unregisters the specified notification for the specified accessibility element from the observer. |
+| **Parameters** | element - the hs.axuielement representing an accessibility element of the application the observer was created for.notification - a string specifying the notification.
|
+| **Returns** | - the observerObject; generates an error if watcher cannot be unregistered
|
+| **Notes** | - if the specified element and notification string are not currently registered with the observer, this method does nothing.
|
+
+#### [start](#start)
+| **Signature** | `hs.axuielement.observer:start() -> observerObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Start observing the application and trigger callbacks for the elements and notifications assigned. |
+| **Parameters** | |
+| **Returns** | |
+| **Notes** | - This method does nothing if the observer is already running
|
+
+#### [stop](#stop)
+| **Signature** | `hs.axuielement.observer:stop() -> observerObject` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Stop observing the application; no further callbacks will be generated. |
+| **Parameters** | |
+| **Returns** | |
+| **Notes** | - This method does nothing if the observer is not currently running
|
+
+#### [watching](#watching)
+| **Signature** | `hs.axuielement.observer:watching([element]) -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table of the notifications currently registered with the observer. |
+| **Parameters** | element - an optional hs.axuielement to return a list of registered notifications for.
|
+| **Returns** | - a table containing the currently registered notifications
|
+| **Notes** | - If an element is specified, then the table returned will contain a list of strings specifying the specific notifications that the observer is watching that element for.
- If no argument is specified, then the table will contain key-value pairs in which each key will be an
hs.axuielement that is being observed and the corresponding value will be a table containing a list of strings specifying the specific notifications that the observer is watching for from from that element.
|
+
diff --git a/api/hs/hs.bonjour.service.md b/api/hs/hs.bonjour.service.md
index d8a1712..cf5f5bf 100644
--- a/api/hs/hs.bonjour.service.md
+++ b/api/hs/hs.bonjour.service.md
@@ -147,6 +147,7 @@ Additional submodules which may address this limitation as well as provide addit
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Stop advertising or resolving the service specified by the serviceObject |
+| **Parameters** | |
| **Returns** | |
| **Notes** | |
diff --git a/api/hs/hs.brightness.md b/api/hs/hs.brightness.md
index acc1809..09c4fee 100644
--- a/api/hs/hs.brightness.md
+++ b/api/hs/hs.brightness.md
@@ -24,7 +24,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Description** | Gets the current ambient brightness |
| **Parameters** | |
| **Returns** | - A number containing the current ambient brightness, measured in lux. If an error occurred, the number will be -1
|
-| **Notes** | - Even though external Apple displays include an ambient light sensor, their data is typically not available, so this function will likely only be useful to MacBook users
- The raw sensor data is converted to lux via an algorithm used by Mozilla Firefox and is not guaranteed to give an accurate lux value
|
+| **Notes** | - Even though external Apple displays include an ambient light sensor, their data is typically not available, so this function will likely only be useful to MacBook users
|
#### [get](#get)
| **Signature** | `hs.brightness.get() -> number` |
diff --git a/api/hs/hs.canvas.md b/api/hs/hs.canvas.md
index 15db760..01d378e 100644
--- a/api/hs/hs.canvas.md
+++ b/api/hs/hs.canvas.md
@@ -23,10 +23,9 @@ Some examples of how to use this module can be found at https://github.com/asmag
* [windowLevels](#windowlevels)
* Functions - API calls offered directly by the extension
* [defaultTextStyle](#defaulttextstyle)
- * [disableScreenUpdates](#disablescreenupdates)
* [elementSpec](#elementspec)
- * [enableScreenUpdates](#enablescreenupdates)
* [help](#help)
+ * [useCustomAccessibilitySubrole](#usecustomaccessibilitysubrole)
* Constructors - API calls which return an object, typically one that offers API methods
* [new](#new)
* Fields - Variables which can only be accessed from an object returned by a constructor
@@ -34,6 +33,7 @@ Some examples of how to use this module can be found at https://github.com/asmag
* [object](#object)
* [percentages](#percentages)
* Methods - API calls which can only be made on an object returned by a constructor
+ * [_accessibilitySubrole](#_accessibilitysubrole)
* [alpha](#alpha)
* [appendElements](#appendelements)
* [assignElement](#assignelement)
@@ -109,15 +109,6 @@ Some examples of how to use this module can be found at https://github.com/asmag
| **Returns** | - a table containing the default style attributes
hs.canvas uses for text drawing objects in the hs.styledtext attributes table format.
|
| **Notes** | - This method is intended to be used in conjunction with
hs.styledtext to create styledtext objects that are based on, or a slight variation of, the defaults used by hs.canvas.
|
-#### [disableScreenUpdates](#disablescreenupdates)
-| **Signature** | `hs.canvas.disableScreenUpdates() -> None` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Tells the OS X window server to pause updating the physical displays for a short while. |
-| **Parameters** | |
-| **Returns** | |
-| **Notes** | - This method can be used to allow multiple changes which are being made to the users display appear as if they all occur simultaneously by holding off on updating the screen on the regular schedule.
- This method should always be balanced with a call to hs.canvas.enableScreenUpdates when your updates have been completed. Failure to do so will be logged in the system logs.
|
-
#### [elementSpec](#elementspec)
| **Signature** | `hs.canvas.elementSpec() -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -127,15 +118,6 @@ Some examples of how to use this module can be found at https://github.com/asmag
| **Returns** | - A table containing the attributes and specifications defined for this module.
|
| **Notes** | - This is primarily for debugging purposes and may be removed in the future.
|
-#### [enableScreenUpdates](#enablescreenupdates)
-| **Signature** | `hs.canvas.enableScreenUpdates() -> None` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Tells the OS X window server to resume updating the physical displays after a previous pause. |
-| **Parameters** | |
-| **Returns** | |
-| **Notes** | - In conjunction with hs.canvas.disableScreenUpdates, this method can be used to allow multiple changes which are being made to the users display appear as if they all occur simultaneously by holding off on updating the screen on the regular schedule.
- This method should always be preceded by a call to hs.canvas.disableScreenUpdates. Failure to do so will be logged in the system logs.
|
-
#### [help](#help)
| **Signature** | `hs.canvas.help([attribute]) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -144,6 +126,15 @@ Some examples of how to use this module can be found at https://github.com/asmag
| **Parameters** | attribute - an optional string specifying an element attribute. If this argument is not provided, all attributes are listed.
|
| **Returns** | - a string containing some of the information provided by the hs.canvas.elementSpec in a manner that is easy to reference from the Hammerspoon console.
|
+#### [useCustomAccessibilitySubrole](#usecustomaccessibilitysubrole)
+| **Signature** | `hs.canvas.useCustomAccessibilitySubrole([state]) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Get or set whether or not canvas objects use a custom accessibility subrole for the contaning system window. |
+| **Parameters** | state - an optional boolean, default true, specifying whether or not canvas containers should use a custom accessibility subrole.
|
+| **Returns** | - the current, possibly changed, value as a boolean
|
+| **Notes** | - Under some conditions, it has been observed that Hammerspoon's
hs.window.filter module will misidentify Canvas and Drawing objects as windows of the Hammerspoon application that it should consider when evaluating its filters. To eliminate this, hs.canvas objects (and previously hs.drawing objects, which are now deprecated and pass through to hs.canvas) were given a nonstandard accessibilty subrole to prevent them from being included. This has caused some issues with third party tools, like Yabai, which also use the accessibility subroles for determining what actions it may take with Hammerspoon windows.
|
+
### Constructors
#### [new](#new)
@@ -177,6 +168,15 @@ Some examples of how to use this module can be found at https://github.com/asmag
### Methods
+#### [_accessibilitySubrole](#_accessibilitysubrole)
+| **Signature** | `hs.canvas:_accessibilitySubrole([subrole]) -> canvasObject | current value` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Get or set the accessibility subrole returned by `hs.canvas` objects. |
+| **Parameters** | subrole - an optional string or explicit nil wihch specifies what accessibility subrole value should be returned when canvas objects are queried through the macOS accessibility framework. See Notes for a discussion of how this value is interpreted. Defaults to nil.
|
+| **Returns** | - If an argument is specified, returns the canvasObject; otherwise returns the current value.
|
+| **Notes** | - Most people will probably not need to use this method; See hs.canvas.useCustomAccessibilitySubrole for a discussion as to why this method may be of use when Hammerspoon is being controlled through the accessibility framework by other applications.
|
+
#### [alpha](#alpha)
| **Signature** | `hs.canvas:alpha([alpha]) -> canvasObject | currentValue` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -186,7 +186,7 @@ Some examples of how to use this module can be found at https://github.com/asmag
| **Returns** | - If an argument is provided, the canvas object; otherwise the current value.
|
#### [appendElements](#appendelements)
-| **Signature** | `hs.canvas:appendElements(element, ...) -> canvasObject` |
+| **Signature** | `hs.canvas:appendElements(element...) -> canvasObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Appends the elements specified to the canvas. |
@@ -299,7 +299,7 @@ Some examples of how to use this module can be found at https://github.com/asmag
| **Notes** | - This method is automatically called during garbage collection, notably during a Hammerspoon termination or reload, with a fade time of 0.
|
#### [draggingCallback](#draggingcallback)
-| **Signature** | `hs.canvas:draggingCallback(fn | nil) -> canvasObject` |
+| **Signature** | `hs.canvas:draggingCallback(fn) -> canvasObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets or remove a callback for accepting dragging and dropping items onto the canvas. |
@@ -456,7 +456,7 @@ Some examples of how to use this module can be found at https://github.com/asmag
| **Returns** | |
#### [replaceElements](#replaceelements)
-| **Signature** | `hs.canvas:replaceElements(element, ...) -> canvasObject` |
+| **Signature** | `hs.canvas:replaceElements(element...) -> canvasObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Replaces all of the elements in the canvas with the elements specified. Shortens or lengthens the canvas element count if necessary to accomodate the new canvas elements. |
diff --git a/api/hs/hs.chooser.md b/api/hs/hs.chooser.md
index b392326..a3cd2da 100644
--- a/api/hs/hs.chooser.md
+++ b/api/hs/hs.chooser.md
@@ -20,6 +20,7 @@ Notes:
* [fgColor](#fgcolor)
* [hide](#hide)
* [hideCallback](#hidecallback)
+ * [invalidCallback](#invalidcallback)
* [isVisible](#isvisible)
* [placeholderText](#placeholdertext)
* [query](#query)
@@ -61,11 +62,11 @@ Notes:
### Methods
#### [attachedToolbar](#attachedtoolbar)
-| **Signature** | `hs.chooser:attachedToolbar([toolbar | nil]) -> hs.chooser object | currentValue` |
+| **Signature** | `hs.chooser:attachedToolbar([toolbar]) -> hs.chooser object | currentValue` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Get or attach/detach a toolbar to/from the chooser. |
-| **Parameters** | toolbar - if an hs.webview.toolbar object is specified, it will be attached to the chooser. If an explicit nil is specified, the current toolbar will be removed from the chooser.
|
+| **Parameters** | toolbar - An hs.webview.toolbar object to be attached to the chooser. If nil is supplied, the current toolbar will be removed
|
| **Returns** | - if a toolbarObject or explicit nil is specified, returns the hs.chooser object; otherwise returns the current toolbarObject or nil, if no toolbar is attached to the chooser.
|
| **Notes** | - this method is a convenience wrapper for the
hs.webview.toolbar.attachToolbar function.
|
@@ -93,7 +94,7 @@ Notes:
| **Description** | Sets the choices for a chooser |
| **Parameters** | - choices - Either a function to call when the list of choices is needed, or nil to remove any existing choices/callback, or a table containing static choices.
|
| **Returns** | |
-| **Notes** | - The table of choices (be it provided statically, or returned by the callback) must contain at least the following keys for each choice:
- text - A string or hs.styledtext object that will be shown as the main text of the choice
- Each choice may also optionally contain the following keys:
- subText - A string or hs.styledtext object that will be shown underneath the main text of the choice
- image - An
hs.image image object that will be displayed next to the choice - Any other keys/values in each choice table will be retained by the chooser and returned to the completion callback when a choice is made. This is useful for storing UUIDs or other non-user-facing information, however, it is important to note that you should not store userdata objects in the table - it is run through internal conversion functions, so only basic Lua types should be stored.
- If a function is given, it will be called once, when the chooser window is displayed. The results are then cached until this method is called again, or
hs.chooser:refreshChoicesCallback() is called. - If you're using a hs.styledtext object for text or subText choices, make sure you specify a color, otherwise your text could appear transparent depending on the bgDark setting.
|
+| **Notes** | - The table of choices (be it provided statically, or returned by the callback) must contain at least the following keys for each choice:
- text - A string or hs.styledtext object that will be shown as the main text of the choice
- Each choice may also optionally contain the following keys:
- subText - A string or hs.styledtext object that will be shown underneath the main text of the choice
- image - An
hs.image image object that will be displayed next to the choice - valid - A boolean that defaults to
true, if set to false selecting the choice will invoke the invalidCallback method instead of dismissing the chooser - Any other keys/values in each choice table will be retained by the chooser and returned to the completion callback when a choice is made. This is useful for storing UUIDs or other non-user-facing information, however, it is important to note that you should not store userdata objects in the table - it is run through internal conversion functions, so only basic Lua types should be stored.
- If a function is given, it will be called once, when the chooser window is displayed. The results are then cached until this method is called again, or
hs.chooser:refreshChoicesCallback() is called. - If you're using a hs.styledtext object for text or subText choices, make sure you specify a color, otherwise your text could appear transparent depending on the bgDark setting.
|
#### [delete](#delete)
| **Signature** | `hs.chooser:delete()` |
@@ -128,6 +129,15 @@ Notes:
| **Returns** | |
| **Notes** | - This callback is called after the chooser is hidden.
- This callback is called after hs.chooser.globalCallback.
|
+#### [invalidCallback](#invalidcallback)
+| **Signature** | `hs.chooser:invalidCallback([fn]) -> hs.chooser object` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets/clears a callback for invalid choices |
+| **Parameters** | - fn - An optional function that will be called whenever the user select an choice set as invalid. If this parameter is omitted, the existing callback will be removed.
|
+| **Returns** | |
+| **Notes** | - The callback may accept one argument, it will be a table containing whatever information you supplied for the item the user chose.
- To display a context menu, see
hs.menubar, specifically the :popupMenu() method
|
+
#### [isVisible](#isvisible)
| **Signature** | `hs.chooser:isVisible() -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/hs/hs.console.md b/api/hs/hs.console.md
index 9cd774f..3e85077 100644
--- a/api/hs/hs.console.md
+++ b/api/hs/hs.console.md
@@ -254,7 +254,7 @@ These functions allow altering the behavior and display of the Hammerspoon conso
| **Notes** | - Window behaviors determine how the webview object is handled by Spaces and Exposé. See
hs.drawing.windowBehaviors for more information.
|
#### [toolbar](#toolbar)
-| **Signature** | `hs.console.toolbar([toolbar | nil]) -> toolbarObject | currentValue` |
+| **Signature** | `hs.console.toolbar([toolbar]) -> toolbarObject | currentValue` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Get or attach/detach a toolbar to/from the Hammerspoon console. |
diff --git a/api/hs/hs.doc.hsdocs.md b/api/hs/hs.doc.hsdocs.md
index 9b0a88a..df05029 100644
--- a/api/hs/hs.doc.hsdocs.md
+++ b/api/hs/hs.doc.hsdocs.md
@@ -11,7 +11,7 @@ Future enhancements to this module under consideration include:
* Documentation for the LuaSkin Objective-C Framework
* Lua Reference documentation
-The intent of this sub-module is to provide as close a rendering of the same documentation available at the Hammerspoon Github site and Dash documentation as possible in a manner suitable for run-time modification so module developers can test out documentation additions without requiring a complete recompilation of the Hammerspoon source. As always, the most current and official documentation can be found at http://www.hammerspoon.org and in the official Hammerspoon Dash docset.
+The intent of this sub-module is to provide as close a rendering of the same documentation available at the Hammerspoon Github site and Dash documentation as possible in a manner suitable for run-time modification so module developers can test out documentation additions without requiring a complete recompilation of the Hammerspoon source. As always, the most current and official documentation can be found at https://www.hammerspoon.org and in the official Hammerspoon Dash docset.
## API Overview
* Functions - API calls offered directly by the extension
diff --git a/api/hs/hs.dockicon.md b/api/hs/hs.dockicon.md
index a8e22ac..631f6a4 100644
--- a/api/hs/hs.dockicon.md
+++ b/api/hs/hs.dockicon.md
@@ -11,6 +11,9 @@ This module is based primarily on code from the previous incarnation of Mjolnir
* [hide](#hide)
* [setBadge](#setbadge)
* [show](#show)
+ * [tileCanvas](#tilecanvas)
+ * [tileSize](#tilesize)
+ * [tileUpdate](#tileupdate)
* [visible](#visible)
## API Documentation
@@ -47,6 +50,33 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Parameters** | |
| **Returns** | |
+#### [tileCanvas](#tilecanvas)
+| **Signature** | `hs.dockicon.tileCanvas([canvas]) -> canvasObject | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Get or set a canvas object to be displayed as the Hamemrspoon dock icon |
+| **Parameters** | canvas - an optional hs.canvas object specifying the canvas to be displayed as the dock icon for Hammerspoon. If an explicit nil is specified, the dock icon will revert to the Hammerspoon application icon.
|
+| **Returns** | - If the dock icon is assigned a canvas object, that canvas object will be returned, otherwise returns nil.
|
+| **Notes** | - If you update the canvas object by changing any of its components, it will not be reflected in the dock icon until you invoke hs.dockicon.tileUpdate.
|
+
+#### [tileSize](#tilesize)
+| **Signature** | `hs.dockicon.tileSize() -> size table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns a table containing the size of the tile representing the dock icon. |
+| **Parameters** | |
+| **Returns** | - a table containing the size of the tile representing the dock icon for Hammerspoon. This table will contain
h and w keys specifying the tile height and width as numbers.
|
+| **Notes** | - the size returned specifies the display size of the dock icon tile. If your canvas item is larger than this, then only the top left portion corresponding to the size returned will be displayed.
|
+
+#### [tileUpdate](#tileupdate)
+| **Signature** | `hs.dockicon.tileUpdate() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Force an update of the dock icon. |
+| **Parameters** | |
+| **Returns** | |
+| **Notes** | - Changes made to a canvas object are not reflected automatically like they are when a canvas is being displayed on the screen; you must invoke this method after making changes to the canvas for the updates to be reflected in the dock icon.
|
+
#### [visible](#visible)
| **Signature** | `hs.dockicon.visible() -> bool` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/hs/hs.drawing.md b/api/hs/hs.drawing.md
index e9eb824..ef0b3d4 100644
--- a/api/hs/hs.drawing.md
+++ b/api/hs/hs.drawing.md
@@ -124,7 +124,7 @@ hs.drawing is now deprecated and will be removed in a future release. Its functi
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Get the size of the rectangle necessary to fully render the text with the specified style so that is will be completely visible. |
-| **Parameters** | - styledTextObject - an object created with the hs.styledtext module or its table representation (see
hs.styledtext).
|
+| **Parameters** | - styledTextObject - an object created with the hs.styledtext module or its table representation (see
hs.styledtext). - textStyle - an optional table containing one or more of the following keys to set for the text of the drawing object (if textStyle is nil or missing, the
hs.drawing defaults are used):
|
| **Returns** | - sizeTable - a table containing the Height and Width necessary to fully display the text drawing object, or nil if an error occurred
|
| **Notes** | - This function assumes the default values specified for any key which is not included in the provided textStyle.
- The size returned is an approximation and may return a width that is off by about 4 points. Use the returned size as a minimum starting point. Sometimes using the "clip" or "truncateMiddle" lineBreak modes or "justified" alignment will fit, but its safest to add in your own buffer if you have the space in your layout.
- Multi-line text (separated by a newline or return) is supported. The height will be for the multiple lines and the width returned will be for the longest line.
|
@@ -241,7 +241,7 @@ hs.drawing is now deprecated and will be removed in a future release. Its functi
| **Notes** | - Setting this to false changes a drawing object's AXsubrole value and may affect the results of filters defined for hs.window.filter, depending upon how they are defined.
|
#### [clippingRectangle](#clippingrectangle)
-| **Signature** | `hs.drawing:clippingRectangle([rect | nil]) -> drawingObject or current value` |
+| **Signature** | `hs.drawing:clippingRectangle([rect]) -> drawingObject or current value` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Set the screen area in which the drawing contents are visible. |
diff --git a/api/hs/hs.eventtap.event.md b/api/hs/hs.eventtap.event.md
index c10f0cb..73a82a5 100644
--- a/api/hs/hs.eventtap.event.md
+++ b/api/hs/hs.eventtap.event.md
@@ -5,6 +5,25 @@ Create, modify and inspect events for `hs.eventtap`
This module is based primarily on code from the previous incarnation of Mjolnir by [Steven Degutis](https://github.com/sdegutis/).
+`hs.eventtap.event.newGesture` uses an external library by Calf Trail Software, LLC.
+
+Touch
+Copyright (C) 2010 Calf Trail Software, LLC
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
## API Overview
* Constants - Useful values which cannot be changed
* [properties](#properties)
@@ -16,6 +35,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
* [copy](#copy)
* [newEvent](#newevent)
* [newEventFromData](#neweventfromdata)
+ * [newGesture](#newgesture)
* [newKeyEvent](#newkeyevent)
* [newMouseEvent](#newmouseevent)
* [newScrollEvent](#newscrollevent)
@@ -28,6 +48,8 @@ This module is based primarily on code from the previous incarnation of Mjolnir
* [getKeyCode](#getkeycode)
* [getProperty](#getproperty)
* [getRawEventData](#getraweventdata)
+ * [getTouchDetails](#gettouchdetails)
+ * [getTouches](#gettouches)
* [getType](#gettype)
* [getUnicodeString](#getunicodestring)
* [location](#location)
@@ -50,7 +72,6 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constant |
| **Description** | A table containing property types for use with `hs.eventtap.event:getProperty()` and `hs.eventtap.event:setProperty()`. The table supports forward (label to number) and reverse (number to label) lookups to increase its flexibility. |
-| **Notes** | - This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing
hs.eventtap.event.properties. - In previous versions of Hammerspoon, property labels were defined with the labels in all lowercase. This practice is deprecated, but an __index metamethod allows the lowercase labels to still be used; however a warning will be printed to the Hammerspoon console. At some point, this may go away, so please update your code to follow the new format.
|
#### [rawFlagMasks](#rawflagmasks)
| **Signature** | `hs.eventtap.event.rawFlagMasks[]` |
@@ -63,7 +84,6 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constant |
| **Description** | A table containing event types to be used with `hs.eventtap.new(...)` and returned by `hs.eventtap.event:type()`. The table supports forward (label to number) and reverse (number to label) lookups to increase its flexibility. |
-| **Notes** | - This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing
hs.eventtap.event.types. - In previous versions of Hammerspoon, type labels were defined with the labels in all lowercase. This practice is deprecated, but an __index metamethod allows the lowercase labels to still be used; however a warning will be printed to the Hammerspoon console. At some point, this may go away, so please update your code to follow the new format.
|
### Functions
@@ -103,6 +123,15 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Parameters** | |
| **Returns** | - a new
hs.eventtap.event object or nil if the string did not represent a valid event
|
+#### [newGesture](#newgesture)
+| **Signature** | `hs.eventtap.event.newGesture(gestureType[, gestureValue]) -> event` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates an gesture event. |
+| **Parameters** | - gestureType - the type of gesture you want to create as a string (see notes below).
- [gestureValue] - an optional value for the specific gesture (i.e. magnification amount or rotation in degrees).
|
+| **Returns** | - a new
hs.eventtap.event object or nil if the gestureType is not valid.
|
+| **Notes** | - Valid gestureType values are:
beginMagnify - Starts a magnification event with an optional magnification value as a number (defaults to 0). The exact unit of measurement is unknown.endMagnify - Starts a magnification event with an optional magnification value as a number (defaults to 0.1). The exact unit of measurement is unknown.beginRotate - Starts a rotation event with an rotation value in degrees (i.e. a value of 45 turns it 45 degrees left - defaults to 0).endRotate - Starts a rotation event with an rotation value in degrees (i.e. a value of 45 turns it 45 degrees left - defaults to 45).beginSwipeLeft - Begin a swipe left.endSwipeLeft - End a swipe left.beginSwipeRight - Begin a swipe right.endSwipeRight - End a swipe right.beginSwipeUp - Begin a swipe up.endSwipeUp - End a swipe up.beginSwipeDown - Begin a swipe down.endSwipeDown - End a swipe down.
|
+
#### [newKeyEvent](#newkeyevent)
| **Signature** | `hs.eventtap.event.newKeyEvent([mods], key, isdown) -> event` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -146,7 +175,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Description** | Returns a string containing binary data representing the event. This can be used to record events for later use. |
| **Parameters** | |
| **Returns** | - a string representing the event or nil if the event cannot be represented as a string
|
-| **Notes** | |
+| **Notes** | |
#### [getButtonState](#getbuttonstate)
| **Signature** | `hs.eventtap.event:getButtonState(button) -> bool` |
@@ -201,13 +230,31 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Returns** | - A table with two keys:
- CGEventData -- a table with keys containing CGEvent data about the event.
- NSEventData -- a table with keys containing NSEvent data about the event.
|
| **Notes** | - Most of the data in
CGEventData is already available through other methods, but is presented here without any cleanup or parsing. - This method is expected to be used mostly for testing and expanding the range of possibilities available with the hs.eventtap module. If you find that you are regularly using specific data from this method for common or re-usable purposes, consider submitting a request for adding a more targeted method to hs.eventtap or hs.eventtap.event -- it will likely be more efficient and faster for common tasks, something eventtaps need to be to minimize affecting system responsiveness.
|
+#### [getTouchDetails](#gettouchdetails)
+| **Signature** | `hs.eventtap.event:getTouchDetails() -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table contining more information about some touch related events. |
+| **Parameters** | |
+| **Returns** | - if the event is a touch event (i.e. is an event of type
hs.eventtap.event.types.gesture), then this method returns a table with zero or more of the following key-value pairs: - if the gesture is for a pressure event:
pressure - a number between 0.0 and 1.0 inclusive indicating the relative amount of pressure applied by the touch; trackpads which are not pressure sensitive will only report the discrete values of 0.0 and 1.0.stage - an integer between 0 and 2 specifying the stage. 0 represents a touch transitioning to a state too light to be considered a touch, usually at the end of a click; 1 represents a touch with enough pressure to be considered a mouseDown event; 2 represents additional pressure, usually what would trigger a "deep" or "force" touch.stageTransition - a number between 0.0 and 1.0. As the pressure increases and transition between stages begins, this will rise from 0.0 to 1.0; as the pressure decreases and a transition between stages begins, this will fall from 0.0 to -1.0. When the pressure is solidly within a specific stage, this will remain 0.0.pressureBehavior - a string specifying the effect or purpose of the pressure. Note that the exact meaning (in terms of haptic feedback or action being performed) of each label is target application or ui element specific. Valid values for this key are:- "unknown", "default", "click", "generic", "accelerator", "deepClick", "deepDrag"
- if the gesture is for a magnification event:
magnification - a number specifying the change in magnification that should be added to the current scaling of an item to achieve the new scale factor.
- if the gesture is for a rotation event:
rotation - a number specifying in degrees the change in rotation that should be added as specified by this event. Clockwise rotation is indicated by a negative number while counter-clockwise rotation will be positive.
|
+
+#### [getTouches](#gettouches)
+| **Signature** | `hs.eventtap.event:getTouches() -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table of details containing information about touches on the trackpad associated with this event if the event is of the type `hs.eventtap.event.types.gesture`. |
+| **Parameters** | |
+| **Returns** | - if the event is of the type gesture, returns a table; otherwise returns nil.
|
+| **Notes** | - if the event is of the type gesture, the table will contain one or more tables in an array. Each member table of the array will have the following key-value pairs:
device - a string containing a unique identifier for the device on which the touch occurred. At present we do not have a way to match the identifier to a specific touch device, but if multiple such devices are attached to the computer, this value will differ between them.deviceSize - a size table containing keys h and w for the height and width of the touch device in points (72 PPI resolution).force - a number representing a measure of the force of the touch when the device is a forcetouch trackpad. This will be 0.0 for non-forcetouch trackpads and the touchbar.identity - a string specifying a unique identifier for the touch guaranteed to be unique for the life of the touch. This identifier may be used to track the movement of a specific touch (e.g. finger) as it moves through successive callbacks.phase - a string specifying the current phase the touch is considered to be in. The possible values are: "began", "moved", "stationary", "ended", or "cancelled".resting - Resting touches occur when a user simply rests their thumb on the trackpad device. Requires that the foreground window has views accepting resting touches.timestamp - a number representing the time the touch was detected. This number corresponds to seconds since the last system boot, not including time the computer has been asleep. Comparable to hs.timer.absoluteTime() / 1000000000.touching - a boolean specifying whether or not the touch phase is "began", "moved", or "stationary" (i.e. is not "ended" or "cancelled").type - a string specifying the type of touch. A "direct" touch will indicate a touchbar, while a trackpad will report "indirect".
|
+
#### [getType](#gettype)
-| **Signature** | `hs.eventtap.event:getType() -> number` |
+| **Signature** | `hs.eventtap.event:getType([nsSpecificType]) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets the type of the event |
-| **Parameters** | |
+| **Parameters** | nsSpecificType - an optional boolean, default false, specifying whether or not a more specific Cocoa NSEvent type should be returned, if available.
|
| **Returns** | - A number containing the type of the event, taken from
hs.eventtap.event.types
|
+| **Notes** | - some newer events are grouped into a more generic event for watching purposes and the specific event type is determined by examining the event through the Cocoa API. The primary example of this is for gestures on a trackpad or touches of the touchbar, as all of these are grouped under the
hs.eventtap.event.types.gesture event. For example:
|
#### [getUnicodeString](#getunicodestring)
| **Signature** | `hs.eventtap.event:getUnicodeString()` |
diff --git a/api/hs/hs.eventtap.md b/api/hs/hs.eventtap.md
index 6e4815d..b6d367f 100644
--- a/api/hs/hs.eventtap.md
+++ b/api/hs/hs.eventtap.md
@@ -49,7 +49,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns a table containing the current mouse buttons being pressed *at this instant*. |
-| **Parameters** | None
|
+| **Parameters** | |
| **Returns** | - Returns an array containing indicies starting from 1 up to the highest numbered button currently being pressed where the index is
true if the button is currently pressed or false if it is not. - Special hash tag synonyms for
left (button 1), right (button 2), and middle (button 3) are also set to true if these buttons are currently being pressed.
|
| **Notes** | - This is an instantaneous poll of the current mouse buttons, not a callback. This is useful primarily in conjuction with other modules, such as
hs.menubar, when a callback is already in progress or waiting for an event callback is not practical or possible.
|
@@ -87,20 +87,20 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Returns** | - A number containing the number of seconds between keyboard events, if a key is held down
|
#### [keyStroke](#keystroke)
-| **Signature** | `hs.eventtap.keyStroke(modifiers, character[, delay])` |
+| **Signature** | `hs.eventtap.keyStroke(modifiers, character[, delay, application])` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Generates and emits a single keystroke event pair for the supplied keyboard modifiers and character |
-| **Parameters** | - modifiers - A table containing the keyboard modifiers to apply ("fn", "ctrl", "alt", "cmd", "shift", or their Unicode equivalents)
- character - A string containing a character to be emitted
- delay - An optional delay (in microseconds) between key down and up event. Defaults to 200000 (i.e. 200ms)
|
+| **Parameters** | - modifiers - A table containing the keyboard modifiers to apply ("fn", "ctrl", "alt", "cmd", "shift", or their Unicode equivalents)
- character - A string containing a character to be emitted
- delay - An optional delay (in microseconds) between key down and up event. Defaults to 200000 (i.e. 200ms)
- application - An optional hs.application object to send the keystroke to
|
| **Returns** | |
| **Notes** | - This function is ideal for sending single keystrokes with a modifier applied (e.g. sending ⌘-v to paste, with
hs.eventtap.keyStroke({"cmd"}, "v")). If you want to emit multiple keystrokes for typing strings of text, see hs.eventtap.keyStrokes()
|
#### [keyStrokes](#keystrokes)
-| **Signature** | `hs.eventtap.keyStrokes(text)` |
+| **Signature** | `hs.eventtap.keyStrokes(text[, application])` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Generates and emits keystroke events for the supplied text |
-| **Parameters** | - text - A string containing the text to be typed
|
+| **Parameters** | - text - A string containing the text to be typed
- application - An optional hs.application object to send the keystrokes to
|
| **Returns** | |
| **Notes** | - If you want to send a single keystroke with keyboard modifiers (e.g. sending ⌘-v to paste), see
hs.eventtap.keyStroke()
|
diff --git a/api/hs/hs.expose.md b/api/hs/hs.expose.md
index 9cf6004..3255fd4 100644
--- a/api/hs/hs.expose.md
+++ b/api/hs/hs.expose.md
@@ -91,5 +91,7 @@ hs.hotkey.bind('ctrl-cmd-shift','e','App Expose',function()expose_app:toggleShow
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Toggles the expose - see `hs.expose:show()` and `hs.expose:hide()` |
+| **Parameters** | - activeApplication - (optional) if true, only show windows of the active application (within the scope of the instance windowfilter); otherwise show all windows allowed by the instance windowfilter
|
| **Returns** | |
+| **Notes** | - passing
true for activeApplication will simply hide hints/thumbnails for applications other than the active one, without recalculating the hints layout; conversely, setting onlyActiveApplication=true for an expose instance's ui will calculate an optimal layout for the current active application's windows - Completing a hint will exit the expose and focus the selected window.
- Pressing esc will exit the expose and with no action taken.
- If shift is being held when a hint is completed (the background will be red), the selected window will be closed. If it's the last window of an application, the application will be closed.
- If alt is being held when a hint is completed (the background will be blue), the selected window will be minimized (if visible) or unminimized/unhidden (if minimized or hidden).
|
diff --git a/api/hs/hs.fs.md b/api/hs/hs.fs.md
index 14bab03..f5ed002 100644
--- a/api/hs/hs.fs.md
+++ b/api/hs/hs.fs.md
@@ -3,9 +3,7 @@
Access/inspect the filesystem
-Home: http://keplerproject.github.io/luafilesystem
-
-This module is produced by the Kepler Project under the name "Lua File System"
+This module is partial superset of LuaFileSystem 1.8.0 (http://keplerproject.github.io/luafilesystem/). It has been modified to remove functions which do not apply to macOS filesystems and additional functions providing macOS specific filesystem information have been added.
## Submodules
* [hs.fs.volume](hs.fs.volume.md)
@@ -38,6 +36,7 @@ This module is produced by the Kepler Project under the name "Lua File System"
* [temporaryDirectory](#temporarydirectory)
* [touch](#touch)
* [unlock](#unlock)
+ * [urlFromPath](#urlfrompath)
## API Documentation
@@ -49,7 +48,7 @@ This module is produced by the Kepler Project under the name "Lua File System"
| **Type** | Function |
| **Description** | Gets the attributes of a file |
| **Parameters** | - filepath - A string containing the path of a file to inspect
- aName - An optional attribute name. If this value is specified, only the attribute requested, is returned
|
-| **Returns** | - A table with the file attributes corresponding to filepath (or nil followed by an error message in case of error). If the second optional argument is given, then a string is returned with the value of the named attribute. attribute mode is a string, all the others are numbers, and the time related attributes use the same time reference of os.time:
- dev - A number containing the device the file resides on
- ino - A number containing the inode of the file
- mode - A string containing the type of the file (possible values are: file, directory, link, socket, named pipe, char device, block device or other)
- nlink - A number containing a count of hard links to the file
- uid - A number containing the user-id of owner
- gid - A number containing the group-id of owner
- rdev - A number containing the type of device, for files that are char/block devices
- access - A number containing the time of last access modification (as seconds since the UNIX epoch)
- change - A number containing the time of last file status change (as seconds since the UNIX epoch)
- modification - A number containing the time of the last file contents change (as seconds since the UNIX epoch)
- creation - A number containing the time the file was created (as seconds since the UNIX epoch)
- size - A number containing the file size, in bytes
- blocks - A number containing the number of blocks allocated for file
- blksize - A number containing the optimal file system I/O blocksize
|
+| **Returns** | - A table with the file attributes corresponding to filepath (or nil followed by an error message in case of error). If the second optional argument is given, then a string is returned with the value of the named attribute. attribute mode is a string, all the others are numbers, and the time related attributes use the same time reference of os.time:
- dev - A number containing the device the file resides on
- ino - A number containing the inode of the file
- mode - A string containing the type of the file (possible values are: file, directory, link, socket, named pipe, char device, block device or other)
- nlink - A number containing a count of hard links to the file
- uid - A number containing the user-id of owner
- gid - A number containing the group-id of owner
- rdev - A number containing the type of device, for files that are char/block devices
- access - A number containing the time of last access modification (as seconds since the UNIX epoch)
- change - A number containing the time of last file status change (as seconds since the UNIX epoch)
- modification - A number containing the time of the last file contents change (as seconds since the UNIX epoch)
- permissions - A 9 character string specifying the user access permissions for the file. The first three characters represent Read/Write/Execute permissions for the file owner. The first character will be "r" if the user has read permissions, "-" if they do not; the second will be "w" if they have write permissions, "-" if they do not; the third will be "x" if they have execute permissions, "-" if they do not. The second group of three characters follow the same convention, but refer to whether or not the file's group have Read/Write/Execute permissions, and the final three characters follow the same convention, but apply to other system users not covered by the Owner or Group fields.
- creation - A number containing the time the file was created (as seconds since the UNIX epoch)
- size - A number containing the file size, in bytes
- blocks - A number containing the number of blocks allocated for file
- blksize - A number containing the optimal file system I/O blocksize
|
| **Notes** | - This function uses
stat() internally thus if the given filepath is a symbolic link, it is followed (if it points to another link the chain is followed recursively) and the information is about the file it refers to. To obtain information about the link itself, see function hs.fs.symlinkAttributes()
|
#### [chdir](#chdir)
@@ -69,13 +68,13 @@ This module is produced by the Kepler Project under the name "Lua File System"
| **Returns** | - A string containing the current working directory, or if an error occured, nil and an error string
|
#### [dir](#dir)
-| **Signature** | `hs.fs.dir(path) -> iter_fn, dir_obj` |
+| **Signature** | `hs.fs.dir(path) -> iter_fn, dir_obj, nil, dir_obj` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Creates an iterator for walking a filesystem path |
| **Parameters** | - path - A string containing a directory to iterate
|
-| **Returns** | - An iterator function or
nil if the supplied path cannot be iterated - A data object to pass to the iterator function or an error message as a string
|
-| **Notes** | - The data object should be passed to the iterator function. Each call will return either a string containing the name of an entry in the directory, or
nil if there are no more entries. - Iteration can also be performed by calling
:next() on the data object. Note that if you do this, you must call :close() on the object when you have finished. - The iterator function will return
nil if the supplied path cannot be iterated, as well as the error message as a string. - Example Usage:
local iterFn, dirObj = hs.fs.dir("/Users/Guest/Documents") if iterFn then for file in iterFn, dirObj do print(file) end else print(string.format("The following error occurred: %s", dirObj)) end
|
+| **Returns** | - An iterator function
- A data object to pass to the iterator function or an error message as a string
nil as the initial argument for the iterator (unused and unnecessary in this case, but conforms to Lua spec for iterators). Ignore this value if you are not using this function with for (see Notes).- A second data object used by
for to close the directory object immediately when the loop terminates. Ignore this value if you are not using this function with for (see Notes).
|
+| **Notes** | - Unlike most functions in this module,
hs.fs.dir will throw a Lua error if the supplied path cannot be iterated.
|
#### [displayName](#displayname)
| **Signature** | `hs.fs.displayName(filepath) -> string` |
@@ -158,7 +157,7 @@ This module is produced by the Kepler Project under the name "Lua File System"
| **Type** | Function |
| **Description** | Gets the absolute path of a given path |
| **Parameters** | - filepath - Any kind of file or directory path, be it relative or not
|
-| **Returns** | - A string containing the absolute path of
filepath (i.e. one that doesn't intolve ., .. or symlinks) - Note that symlinks will be resolved to their target file
|
+| **Returns** | - A string containing the absolute path of
filepath (i.e. one that doesn't include ., .. or symlinks) - Note that symlinks will be resolved to their target file
|
#### [pathToBookmark](#pathtobookmark)
| **Signature** | `hs.fs.pathToBookmark(path) -> string | nil` |
@@ -192,7 +191,7 @@ This module is produced by the Kepler Project under the name "Lua File System"
| **Description** | Gets the attributes of a symbolic link |
| **Parameters** | - filepath - A string containing the path of a link to inspect
- aName - An optional attribute name. If this value is specified, only the attribute requested, is returned
|
| **Returns** | - A table or string if the values could be found, otherwise nil and an error string.
|
-| **Notes** | - The return values for this function are identical to those provided by
hs.fs.attributes()
|
+| **Notes** | - The return values for this function are identical to those provided by
hs.fs.attributes() with the following addition: the attribute name "target" is added and specifies a string containing the absolute path that the symlink points to.
|
#### [tagsAdd](#tagsadd)
| **Signature** | `hs.fs.tagsAdd(filepath, tags)` |
@@ -250,3 +249,11 @@ This module is produced by the Kepler Project under the name "Lua File System"
| **Parameters** | - filehandle - An open file
- start - An optional number containing an offset from the start of the file, to unlock. Defaults to 0
- length - An optional number containing the length of file to unlock. Defaults to the full size of the file
|
| **Returns** | - True if the unlock succeeded, otherwise nil and an error string
|
+#### [urlFromPath](#urlfrompath)
+| **Signature** | `hs.fs.urlFromPath(path) -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns the encoded URL from a path. |
+| **Parameters** | |
+| **Returns** | - A string or
nil if path is invalid.
|
+
diff --git a/api/hs/hs.fs.xattr.md b/api/hs/hs.fs.xattr.md
index 10a9594..43f939a 100644
--- a/api/hs/hs.fs.xattr.md
+++ b/api/hs/hs.fs.xattr.md
@@ -43,7 +43,7 @@ Note that the following options did not seem to be valid for the initial tests p
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | A wrapper to [hs.fs.xattr.get](#get) which returns non UTF-8 data as a hexadecimal dump provided by `hs.utf8.hexDump`. |
-| **Parameters** | |
+| **Parameters** | path - A string specifying the path to the file or directory to get the extended attribute fromattribute - A string specifying the name of the extended attribute to get the value ofoptions - An optional table containing options as described in this module's documentation header. Defaults to {} (an empty array).position - An optional integer specifying the offset within the extended attribute. Defaults to 0. Setting this argument to a value other than 0 is only valid when att ribute is "com.apple.ResourceFork".
|
| **Returns** | - if the returned data does not conform to proper UTF-8 byte sequences, passes the string through
hs.utf8.hexDump first. Otherwise the return values follow the description for hs.fs.xattr.get .
|
| **Notes** | - This is provided for testing and debugging purposes; in general you probably want hs.fs.xattr.get once you know how to properly understand the data returned for the attribute.
- This is similar to the long format option in the command line
xattr command.
|
diff --git a/api/hs/hs.geometry.md b/api/hs/hs.geometry.md
index 906d441..8cb5350 100644
--- a/api/hs/hs.geometry.md
+++ b/api/hs/hs.geometry.md
@@ -94,6 +94,7 @@ You can use any of these anywhere an hs.geometry object is expected in Hammerspo
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constructor |
| **Description** | Creates a new hs.geometry object |
+| **Parameters** | - ... - see the module description at the top
|
| **Returns** | - a newly created hs.geometry object
|
#### [point](#point)
diff --git a/api/hs/hs.grid.md b/api/hs/hs.grid.md
index 57e4c55..38a192a 100644
--- a/api/hs/hs.grid.md
+++ b/api/hs/hs.grid.md
@@ -224,7 +224,7 @@ After highlighting enough cells, press enter to move/resize the window to the hi
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Shows the grid and starts the modal interactive resizing process for the focused or frontmost window. |
-| **Parameters** | - exitedCallback - (optional) a function that will be called after the user dismisses the modal interface
- multipleWindows - (optional) if
true, the resizing grid won't automatically go away after selecting the desired cells for the frontmost window; instead, it'll switch to the next window
|
+| **Parameters** | - exitedCallback - (optional) a function that will be called after the user dismisses the modal interface
- multipleWindows - (optional) if
true, the resizing grid won't automatically go away after selecting the desired cells for the frontmost window; instead, it'll switch to the next window
|
| **Returns** | |
| **Notes** | - In the modal interface, press the arrow keys to jump to adjacent screens; spacebar to maximize/unmaximize; esc to quit without any effect
- Pressing
tab or shift-tab in the modal interface will cycle to the next or previous window; if multipleWindows is false or omitted, the first press will just enable the multiple windows behaviour - The keyboard hints assume a QWERTY layout; if you use a different layout, change
hs.grid.HINTS accordingly - If grid dimensions are greater than 10x10 then you may have to change
hs.grid.HINTS depending on your requirements. See note in HINTS.
|
@@ -241,5 +241,6 @@ After highlighting enough cells, press enter to move/resize the window to the hi
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Toggles the grid and modal resizing mode - see `hs.grid.show()` and `hs.grid.hide()` |
+| **Parameters** | - exitedCallback - (optional) a function that will be called after the user dismisses the modal interface
- multipleWindows - (optional) if
true, the resizing grid won't automatically go away after selecting the desired cells for the frontmost window; instead, it'll switch to the next window
|
| **Returns** | |
diff --git a/api/hs/hs.hid.md b/api/hs/hs.hid.md
index c79a603..37176c2 100644
--- a/api/hs/hs.hid.md
+++ b/api/hs/hs.hid.md
@@ -23,6 +23,7 @@ Portions sourced from (https://discussions.apple.com/thread/7094207).
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Checks the state of the caps lock via HID |
+| **Parameters** | |
| **Returns** | |
#### [set](#set)
@@ -38,5 +39,6 @@ Portions sourced from (https://discussions.apple.com/thread/7094207).
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Toggles the state of caps lock via HID |
+| **Parameters** | |
| **Returns** | |
diff --git a/api/hs/hs.hotkey.md b/api/hs/hs.hotkey.md
index 3e1c716..393a6e3 100644
--- a/api/hs/hs.hotkey.md
+++ b/api/hs/hs.hotkey.md
@@ -90,13 +90,13 @@ Create and manage global keyboard shortcuts
### Constructors
#### [bind](#bind)
-| **Signature** | `hs.hotkey.bind(mods, key, message, pressedfn, releasedfn, repeatfn) -> hs.hotkey object` |
+| **Signature** | `hs.hotkey.bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> hs.hotkey object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constructor |
-| **Description** | Creates a 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 - A string containing a message to be displayed via
hs.alert() when the hotkey has been triggered, or nil for no alert - 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 for method chaining
|
-| **Notes** | - This function is just a wrapper that performs
hs.hotkey.new(...):enable()
|
+| **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()
|
#### [bindSpec](#bindspec)
| **Signature** | `hs.hotkey.bindSpec(keyspec, ...) -> hs.hotkey object` |
diff --git a/api/hs/hs.http.md b/api/hs/hs.http.md
index e089f7d..6b9559f 100644
--- a/api/hs/hs.http.md
+++ b/api/hs/hs.http.md
@@ -54,7 +54,7 @@ Perform HTTP requests
| **Description** | Convert all recognized HTML Entities in the `inString` to appropriate UTF8 byte sequences and returns the converted text. |
| **Parameters** | - inString -- A string containing any number of HTML Entities (&whatever;) in the text.
|
| **Returns** | - outString -- the input string with all recognized HTML Entity sequences converted to UTF8 byte sequences.
|
-| **Notes** | - Recognized HTML Entities are those registered in
hs.http.htmlEntities or numeric entity sequences: &#n; where n can be any integer number. - This function is especially useful as a post-filter to data retrieved by the
hs.http.get and hs.http.asyncGet functions.
|
+| **Notes** | - Recognized HTML Entities are those registered in
hs.http.htmlEntities or numeric entity sequences: &#n; where n can be any integer number. - This function is especially useful as a post-filter to data retrieved by the
hs.http.get and hs.http.asyncGet functions.
|
#### [doAsyncRequest](#doasyncrequest)
| **Signature** | `hs.http.doAsyncRequest(url, method, data, headers, callback, [cachePolicy])` |
@@ -88,6 +88,7 @@ Perform HTTP requests
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Sends an HTTP GET request to a URL |
+| **Parameters** | - url - A string containing the URL to retrieve
- headers - A table containing string keys and values representing the request headers, or nil to add no headers
|
| **Returns** | - A number containing the HTTP response status
- A string containing the response body
- A table containing the response headers
|
| **Notes** | - If authentication is required in order to download the request, the required credentials must be specified as part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the connection will attempt to continue without credentials.
|
@@ -96,6 +97,7 @@ Perform HTTP requests
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Sends an HTTP POST request to a URL |
+| **Parameters** | - url - A string containing the URL to submit to
- data - A string containing the request body, or nil to send no body
- headers - A table containing string keys and values representing the request headers, or nil to add no headers
|
| **Returns** | - A number containing the HTTP response status
- A string containing the response body
- A table containing the response headers
|
| **Notes** | - If authentication is required in order to download the request, the required credentials must be specified as part of the URL (e.g. "http://user:password@host.com/"). If authentication fails, or credentials are missing, the connection will attempt to continue without credentials.
|
diff --git a/api/hs/hs.image.md b/api/hs/hs.image.md
index 590f440..b7057f5 100644
--- a/api/hs/hs.image.md
+++ b/api/hs/hs.image.md
@@ -8,6 +8,8 @@ A module for capturing and manipulating image objects from other modules for use
* Constants - Useful values which cannot be changed
* [additionalImageNames](#additionalimagenames)
* [systemImageNames](#systemimagenames)
+* Functions - API calls offered directly by the extension
+ * [getExifFromPath](#getexiffrompath)
* Constructors - API calls which return an object, typically one that offers API methods
* [iconForFile](#iconforfile)
* [iconForFileType](#iconforfiletype)
@@ -48,6 +50,16 @@ A module for capturing and manipulating image objects from other modules for use
| **Description** | Table containing the names of internal system images for use with hs.drawing.image |
| **Notes** | - Image names pulled from NSImage.h
- This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing
hs.image.systemImageNames.
|
+### Functions
+
+#### [getExifFromPath](#getexiffrompath)
+| **Signature** | `hs.image.getExifFromPath(path) -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets the EXIF metadata information from an image file. |
+| **Parameters** | - path - The path to the image file.
|
+| **Returns** | - A table of EXIF metadata, or
nil if no metadata can be found or the file path is invalid.
|
+
### Constructors
#### [iconForFile](#iconforfile)
diff --git a/api/hs/hs.keycodes.md b/api/hs/hs.keycodes.md
index d026dad..065d9ea 100644
--- a/api/hs/hs.keycodes.md
+++ b/api/hs/hs.keycodes.md
@@ -1,7 +1,7 @@
# [docs](index.md) » hs.keycodes
---
-Convert between key-strings and key-codes. Also provides funcionality for querying and changing keyboard layouts.
+Convert between key-strings and key-codes. Also provides functionality for querying and changing keyboard layouts.
## API Overview
* Constants - Useful values which cannot be changed
diff --git a/api/hs/hs.layout.md b/api/hs/hs.layout.md
index e905517..4accea4 100644
--- a/api/hs/hs.layout.md
+++ b/api/hs/hs.layout.md
@@ -100,5 +100,5 @@ This extension allows you to trigger window placement/sizing to a number of wind
| **Description** | Applies a layout to applications/windows |
| **Parameters** | - table - A table describing your desired layout. Each element in the table should be another table describing a set of windows to match, and their desired size/position. The fields in each of these tables are:
- A string containing an application name, or an
hs.application object, or nil - A string containing a window title, or an
hs.window object, or a function, or nil - A string containing a screen name, or an
hs.screen object, or a function that accepts no parameters and returns an hs.screen object, or nil to select the first available screen - A Unit rect, or a function which is called for each window and returns a unit rect (see
hs.window.moveToUnit()). The function should accept one parameter, which is the window object. - A Frame rect, or a function which is called for each window and returns a frame rect (see
hs.screen:frame()). The function should accept one parameter, which is the window object. - A Full-frame rect, of a function which is called for each window and returns a full-frame rect (see
hs.screen:fullFrame()). The function should accept one parameter, which is the window object. - windowTitleComparator - (optional) Function to use for window title comparison. It is called with two string arguments (below) and its return value is evaluated as a boolean. If no comparator is provided, the '==' operator is used
- windowTitle: The
:title() of the window object being examined - layoutWindowTitle: The window title string (second field) specified in each element of the layout table
- Optionally a final element, the key "options" and a table value that can contain the following keys:
absolute_x: A boolean indicating that the x value in a frame rect above, is an absolute co-ordinate (ie useful for negative absolute co-ordinates)absolute_y: A boolean indicating that the y value in a frame rect above, is an absolute co-ordinate (ie useful for negative absolute co-ordinates)
|
| **Returns** | |
-| **Notes** | - If the application name argument is nil, window titles will be matched regardless of which app they belong to
- If the window title argument is nil, all windows of the specified application will be matched
- If the window title argument is a function, the function will be called with the application name argument (which may be nil), and should return a table of
hs.window objects (even if there is only one window it must be in a table) - You can specify both application name and window title if you want to match only one window of a particular application
- If you specify neither application name or window title, no windows will be matched :)
- Monitor name is a string, as found in
hs.screen:name(). You can also pass an hs.screen object, or a function that returns an hs.screen object. If you pass nil, the first screen will be selected - The final three arguments use
hs.geometry.rect() objects to describe the desired position and size of matched windows: - Unit rect will be passed to
hs.window.moveToUnit() - Frame rect will be passed to
hs.window.setFrame() (including menubar and dock) - Full-frame rect will be passed to
hs.window.setFrame() (ignoring menubar and dock) - If either the x or y components of frame/full-frame rect are negative, they will be applied as offsets against the opposite edge of the screen (e.g. If x is -100 then the left edge of the window will be 100 pixels from the right edge of the screen)
- Only one of the rect arguments will apply to any matched windows. If you specify more than one, the first will win
- An example usage:
|
+| **Notes** | - If the application name argument is nil, window titles will be matched regardless of which app they belong to
- If the window title argument is nil, all windows of the specified application will be matched
- If the window title argument is a function, the function will be called with the application name argument (which may be nil), and should return a table of
hs.window objects (even if there is only one window it must be in a table) - You can specify both application name and window title if you want to match only one window of a particular application
- If you specify neither application name or window title, no windows will be matched :)
- Monitor name is a string, as found in
hs.screen:name() or hs.screen:getUUID(). You can also pass an hs.screen object, or a function that returns an hs.screen object. If you pass nil, the first screen will be selected - The final three arguments use
hs.geometry.rect() objects to describe the desired position and size of matched windows: - Unit rect will be passed to
hs.window.moveToUnit() - Frame rect will be passed to
hs.window.setFrame() (including menubar and dock) - Full-frame rect will be passed to
hs.window.setFrame() (ignoring menubar and dock) - If either the x or y components of frame/full-frame rect are negative, they will be applied as offsets against the opposite edge of the screen (e.g. If x is -100 then the left edge of the window will be 100 pixels from the right edge of the screen)
- Only one of the rect arguments will apply to any matched windows. If you specify more than one, the first will win
- An example usage:
|
diff --git a/api/hs/hs.location.md b/api/hs/hs.location.md
index 6ec00d2..6061941 100644
--- a/api/hs/hs.location.md
+++ b/api/hs/hs.location.md
@@ -180,7 +180,7 @@ The following labels are used to describe tables which are used by functions and
| **Notes** | - This method activates Location Services for Hammerspoon, so the first time you call this, you may be prompted to authorise Hammerspoon to use Location Services.
- If the
identifier key is not provided, a new UUID string is generated and used as the identifier. - If the
identifier key matches an already monitored region, this region will replace the existing one.
|
#### [callback](#callback)
-| **Signature** | `hs.location:callback(fn | nil) -> locationObject` |
+| **Signature** | `hs.location:callback(fn) -> locationObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets or removes the callback function for this locationObject |
diff --git a/api/hs/hs.math.md b/api/hs/hs.math.md
index 4ca0a73..b43a86e 100644
--- a/api/hs/hs.math.md
+++ b/api/hs/hs.math.md
@@ -68,6 +68,7 @@ Additional functions and values that are specific to Hammerspoon which provide e
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns whether or not the value is a finite number |
+| **Parameters** | value - the value to be tested
|
| **Returns** | - true if the value is a finite number, or false otherwise
|
| **Notes** | |
diff --git a/api/hs/hs.md b/api/hs/hs.md
index 705ee8d..398daab 100644
--- a/api/hs/hs.md
+++ b/api/hs/hs.md
@@ -9,7 +9,7 @@ Core Hammerspoon functionality
* [hs.applescript](hs.applescript.md)
* [hs.application](hs.application.md)
* [hs.audiodevice](hs.audiodevice.md)
- * [hs.audiounit](hs.audiounit.md)
+ * [hs.axuielement](hs.axuielement.md)
* [hs.base64](hs.base64.md)
* [hs.battery](hs.battery.md)
* [hs.bonjour](hs.bonjour.md)
@@ -216,7 +216,7 @@ Core Hammerspoon functionality
| **Signature** | `hs.accessibilityState(shouldPrompt) -> isEnabled` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | |
+| **Description** | Checks the Accessibility Permissions for Hammerspoon, and optionally allows you to prompt for permissions. |
| **Parameters** | - shouldPrompt - an optional boolean value indicating if the dialog box asking if the System Preferences application should be opened should be presented when Accessibility is not currently enabled for Hammerspoon. Defaults to false.
|
| **Returns** | - True or False indicating whether or not Accessibility is enabled for Hammerspoon.
|
| **Notes** | - Since this check is done automatically when Hammerspoon loads, it is probably of limited use except for skipping things that are known to fail when Accessibility is not enabled. Evettaps which try to capture keyUp and keyDown events, for example, will fail until Accessibility is enabled and the Hammerspoon application is relaunched.
|
@@ -251,7 +251,7 @@ Core Hammerspoon functionality
| **Signature** | `hs.cameraState(shouldPrompt) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | |
+| **Description** | Checks the Camera Permissions for Hammerspoon, and optionally allows you to prompt for permissions. |
| **Parameters** | - shouldPrompt - an optional boolean value indicating if we should request camear access. Defaults to false.
|
| **Returns** | true or false indicating whether or not Camera access is enabled for Hammerspoon.
|
| **Notes** | - Will always return
true on macOS 10.13 or earlier.
|
@@ -296,6 +296,7 @@ Core Hammerspoon functionality
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Closes the Hammerspoon Preferences window |
+| **Parameters** | |
| **Returns** | |
#### [consoleOnTop](#consoleontop)
@@ -338,6 +339,8 @@ Core Hammerspoon functionality
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Makes Hammerspoon the foreground app. |
+| **Parameters** | |
+| **Returns** | |
#### [getObjectMetatable](#getobjectmetatable)
| **Signature** | `hs.getObjectMetatable(name) -> table or nil` |
@@ -372,7 +375,7 @@ Core Hammerspoon functionality
| **Description** | Loads a Spoon |
| **Parameters** | - name - The name of a Spoon (without the trailing
.spoon) - global - An optional boolean. If true, this function will insert the spoon into Lua's global namespace as
spoon.NAME. Defaults to true.
|
| **Returns** | - The object provided by the Spoon (which can be ignored if you chose to make the Spoon global)
|
-| **Notes** | - Spoons are a way of distributing self-contained units of Lua functionality, for Hammerspoon. For more information, see https://github.com/Hammerspoon/hammerspoon/blob/master/SPOON.md
- This function will load the Spoon and call its
:init() method if it has one. If you do not wish this to happen, or wish to use a Spoon that somehow doesn't fit with the behaviours of this function, you can also simply require('name') to load the Spoon - If the Spoon provides documentation, it will be loaded by made available in hs.docs
- To learn how to distribute your own code as a Spoon, see https://github.com/Hammerspoon/hammerspoon/blob/master/SPOON.md
|
+| **Notes** | - Spoons are a way of distributing self-contained units of Lua functionality, for Hammerspoon. For more information, see https://github.com/Hammerspoon/hammerspoon/blob/master/SPOON.md
- This function will load the Spoon and call its
:init() method if it has one. If you do not wish this to happen, or wish to use a Spoon that somehow doesn't fit with the behaviours of this function, you can also simply require('name') to load the Spoon - If the Spoon has a
:start() method you are responsible for calling it before using the functionality of the Spoon. - If the Spoon provides documentation, it will be loaded by made available in hs.docs
- To learn how to distribute your own code as a Spoon, see https://github.com/Hammerspoon/hammerspoon/blob/master/SPOON.md
|
#### [menuIcon](#menuicon)
| **Signature** | `hs.menuIcon([state]) -> bool` |
@@ -386,7 +389,7 @@ Core Hammerspoon functionality
| **Signature** | `hs.microphoneState(shouldPrompt) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | |
+| **Description** | Checks the Microphone Permissions for Hammerspoon, and optionally allows you to prompt for permissions. |
| **Parameters** | - shouldPrompt - an optional boolean value indicating if we should request microphone access. Defaults to false.
|
| **Returns** | true or false indicating whether or not Microphone access is enabled for Hammerspoon.
|
| **Notes** | - Will always return
true on macOS 10.13 or earlier.
|
@@ -404,6 +407,8 @@ Core Hammerspoon functionality
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Displays the OS X About panel for Hammerspoon; implicitly focuses Hammerspoon. |
+| **Parameters** | |
+| **Returns** | |
#### [openConsole](#openconsole)
| **Signature** | `hs.openConsole([bringToFront])` |
@@ -427,6 +432,8 @@ Core Hammerspoon functionality
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Displays the Hammerspoon Preferences panel; implicitly focuses Hammerspoon. |
+| **Parameters** | |
+| **Returns** | |
#### [preferencesDarkMode](#preferencesdarkmode)
| **Signature** | `hs.preferencesDarkMode([state]) -> bool` |
@@ -467,12 +474,14 @@ Core Hammerspoon functionality
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Reloads your init-file in a fresh Lua environment. |
+| **Parameters** | |
+| **Returns** | |
#### [screenRecordingState](#screenrecordingstate)
| **Signature** | `hs.screenRecordingState(shouldPrompt) -> isEnabled` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | |
+| **Description** | Checks the Screen Recording Permissions for Hammerspoon, and optionally allows you to prompt for permissions. |
| **Parameters** | - shouldPrompt - an optional boolean value indicating if the dialog box asking if the System Preferences application should be opened should be presented when Screen Recording is not currently enabled for Hammerspoon. Defaults to false.
|
| **Returns** | - True or False indicating whether or not Screen Recording is enabled for Hammerspoon.
|
| **Notes** | - If you trigger the prompt and the user denies it, you cannot bring up the prompt again - the user must manually enable it in System Preferences.
|
@@ -511,5 +520,5 @@ Core Hammerspoon functionality
| **Description** | Get or set the "Upload Crash Data" preference for Hammerspoon |
| **Parameters** | - state - An optional boolean, true to upload crash reports, false to not
|
| **Returns** | - True if Hammerspoon is currently (or has just been) set to upload crash data or False otherwise
|
-| **Notes** | - If at all possible, please do allow Hammerspoon to upload crash reports to us, it helps a great deal in keeping Hammerspoon stable
- Our Privacy Policy can be found here: http://www.hammerspoon.org/privacy.html
|
+| **Notes** | - If at all possible, please do allow Hammerspoon to upload crash reports to us, it helps a great deal in keeping Hammerspoon stable
- Our Privacy Policy can be found here: https://www.hammerspoon.org/privacy.html
|
diff --git a/api/hs/hs.menubar.md b/api/hs/hs.menubar.md
index b96b18d..fc30151 100644
--- a/api/hs/hs.menubar.md
+++ b/api/hs/hs.menubar.md
@@ -71,6 +71,7 @@ Create and manage menubar icons
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Returns the menubar item frame |
+| **Parameters** | |
| **Returns** | - an hs.geometry rect describing the menubar item's frame or nil if the menubar item is not currently in the menubar.
|
| **Notes** | - This will return a frame even if no icon or title is set
|
diff --git a/api/hs/hs.midi.md b/api/hs/hs.midi.md
index 25892c6..1eb3ae5 100644
--- a/api/hs/hs.midi.md
+++ b/api/hs/hs.midi.md
@@ -102,7 +102,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
### Methods
#### [callback](#callback)
-| **Signature** | `hs.midi:callback(callbackFn | nil)` |
+| **Signature** | `hs.midi:callback(callbackFn)` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets or removes a callback function for the `hs.midi` object. |
diff --git a/api/hs/hs.mouse.md b/api/hs/hs.mouse.md
index d723da0..2232052 100644
--- a/api/hs/hs.mouse.md
+++ b/api/hs/hs.mouse.md
@@ -33,14 +33,13 @@ misrepresented as being the original software.
## API Overview
* Functions - API calls offered directly by the extension
+ * [absolutePosition](#absoluteposition)
* [count](#count)
- * [getAbsolutePosition](#getabsoluteposition)
* [getButtons](#getbuttons)
* [getCurrentScreen](#getcurrentscreen)
* [getRelativePosition](#getrelativeposition)
* [names](#names)
* [scrollDirection](#scrolldirection)
- * [setAbsolutePosition](#setabsoluteposition)
* [setRelativePosition](#setrelativeposition)
* [trackingSpeed](#trackingspeed)
@@ -48,6 +47,15 @@ misrepresented as being the original software.
### Functions
+#### [absolutePosition](#absoluteposition)
+| **Signature** | `hs.mouse.absolutePosition([point]) -> point` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Get or set the absolute co-ordinates of the mouse pointer |
+| **Parameters** | - An optional point table containing the absolute x and y co-ordinates to move the mouse pointer to
|
+| **Returns** | - A point table containing the absolute x and y co-ordinates of the mouse pointer
|
+| **Notes** | - If no parameters are supplied, the current position will be returned. If a point table parameter is supplied, the mouse pointer poisition will be set and the new co-ordinates returned
|
+
#### [count](#count)
| **Signature** | `hs.mouse.count([includeInternal]) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -57,21 +65,12 @@ misrepresented as being the original software.
| **Returns** | - The number of mice connected to your system
|
| **Notes** | - This function leverages code from ManyMouse.
- This function considers any mouse labelled as "Apple Internal Keyboard / Trackpad" to be an internal mouse.
|
-#### [getAbsolutePosition](#getabsoluteposition)
-| **Signature** | `hs.mouse.getAbsolutePosition() -> point` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Gets the absolute co-ordinates of the mouse pointer |
-| **Parameters** | |
-| **Returns** | - A point-table containing the absolute x and y co-ordinates of the mouse pointer
|
-| **Notes** | - The co-ordinates returned by this function are in relation to the full size of your desktop. If you have multiple monitors, the desktop is a large virtual rectangle that contains them all (e.g. if you have two 1920x1080 monitors and the mouse is in the middle of the second monitor, the returned table would be
{ x=2879, y=540 }) - Multiple monitors of different sizes can cause the co-ordinates of some areas of the desktop to be negative. This is perfectly normal. 0,0 in the co-ordinates of the desktop is the top left of the primary monitor
|
-
#### [getButtons](#getbuttons)
| **Signature** | `hs.mouse.getButtons() -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns a table containing the current mouse buttons being pressed *at this instant*. |
-| **Parameters** | None
|
+| **Parameters** | |
| **Returns** | - Returns an array containing indicies starting from 1 up to the highest numbered button currently being pressed where the index is
true if the button is currently pressed or false if it is not. - Special hash tag synonyms for
left (button 1), right (button 2), and middle (button 3) are also set to true if these buttons are currently being pressed.
|
| **Notes** | - This function is a wrapper to
hs.eventtap.checkMouseButtons - This is an instantaneous poll of the current mouse buttons, not a callback.
|
@@ -109,15 +108,6 @@ misrepresented as being the original software.
| **Parameters** | |
| **Returns** | - A string, either "natural" or "normal"
|
-#### [setAbsolutePosition](#setabsoluteposition)
-| **Signature** | `hs.mouse.setAbsolutePosition(point)` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Sets the absolute co-ordinates of the mouse pointer |
-| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
|
-| **Returns** | |
-| **Notes** | - The co-ordinates given to this function must be in relation to the full size of your desktop. See the notes for
hs.mouse.getAbsolutePosition for more information
|
-
#### [setRelativePosition](#setrelativeposition)
| **Signature** | `hs.mouse.setRelativePosition(point[, screen])` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -132,6 +122,6 @@ misrepresented as being the original software.
| **Type** | Function |
| **Description** | Gets/Sets the current system mouse tracking speed setting |
| **Parameters** | - speed - An optional number containing the new tracking speed to set. If this is ommitted, the current setting is returned
|
-| **Returns** | - A number (currently between 0.0 and 3.0) indicating the current tracking speed setting for mice, or -1 if an error occurred
|
-| **Notes** | - This is represented in the System Preferences as the "Tracking speed" setting for mice
- Note that not all values will work, they should map to the steps defined in the System Preferences app
|
+| **Returns** | - A number indicating the current tracking speed setting for mice
|
+| **Notes** | - This is represented in the System Preferences as the "Tracking speed" setting for mice
- Note that not all values will work, they should map to the steps defined in the System Preferences app, which are:
- 0.0, 0.125, 0.5, 0.6875, 0.875, 1.0, 1.5, 2.0, 2.5, 3.0
- Note that changes to this value will not be noticed immedaitely by macOS
|
diff --git a/api/hs/hs.network.configuration.md b/api/hs/hs.network.configuration.md
index c5c13e0..36fd1ce 100644
--- a/api/hs/hs.network.configuration.md
+++ b/api/hs/hs.network.configuration.md
@@ -125,7 +125,7 @@ This sub-module provides access to the current location set configuration settin
| **Notes** | - You can also retrieve this information as key-value pairs with
hs.network.configuration:contents("State:/Network/Global/Proxies")
|
#### [setCallback](#setcallback)
-| **Signature** | `hs.network.configuration:setCallback(function | nil) -> storeObject` |
+| **Signature** | `hs.network.configuration:setCallback(function) -> storeObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Set or remove the callback function for a store object |
diff --git a/api/hs/hs.network.md b/api/hs/hs.network.md
index 929b636..93f369f 100644
--- a/api/hs/hs.network.md
+++ b/api/hs/hs.network.md
@@ -22,11 +22,11 @@ This module provides functions for inquiring about and monitoring changes to the
### Functions
#### [addresses](#addresses)
-| **Signature** | `hs.network.addresses([interface, ...]) -> table` |
+| **Signature** | `hs.network.addresses([interface_list]) -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns a list of the IPv4 and IPv6 addresses for the specified interfaces, or all interfaces if no arguments are given. |
-| **Parameters** | - interface, ... - The interface names to return the IP addresses for. It should be specified as one of the following:
- one or more interface names, separated by a comma
- if the first argument is a table, it is assumes to be a table containing a list of interfaces and this list is used instead, ignoring any additional arguments that may be provided
- if no arguments are specified, then the results of hs.network.interfaces is used.
|
+| **Parameters** | - interface_list - The interface names to return the IP addresses for. It should be specified as one of the following:
- one or more interface names, separated by a comma
- if the first argument is a table, it is assumes to be a table containing a list of interfaces and this list is used instead, ignoring any additional arguments that may be provided
- if no arguments are specified, then the results of hs.network.interfaces is used.
|
| **Returns** | - A table containing a list of the IP addresses for the interfaces as determined by the arguments provided.
|
| **Notes** | - The order of the IP addresses returned is undefined.
- If no arguments are provided, then this function returns the same results as
hs.host.addresses, but does not block.
|
@@ -44,6 +44,7 @@ This module provides functions for inquiring about and monitoring changes to the
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns the user defined name for the specified interface or the primary interface if no interface is specified. |
+| **Parameters** | - interface - an optional string specifying the interface to retrieve the name for. Defaults to the primary interface if not specified.
- favorIPv6 - an optional boolean specifying whether or not to prefer the primary IPv6 or the primary IPv4 interface if
interface is not specified. Defaults to false.
|
| **Returns** | - A string containing the user defined name for the interface, if one exists, or false if the interface does not have a user defined name. Logs an error and returns nil if there was a problem retrieving this information.
|
| **Notes** | - Only interfaces which show up in the System Preferences Network panel will have a user defined name.
|
diff --git a/api/hs/hs.network.ping.echoRequest.md b/api/hs/hs.network.ping.echoRequest.md
index df20f72..90281cb 100644
--- a/api/hs/hs.network.ping.echoRequest.md
+++ b/api/hs/hs.network.ping.echoRequest.md
@@ -126,7 +126,7 @@ In cases where the callback receives a "receivedUnexpectedPacket" message becaus
| **Notes** | - By convention, unless you are trying to test for specific network fragmentation or congestion problems, ICMP Echo Requests are generally 64 bytes in length (this includes the 8 byte header, giving 56 bytes of payload data). If you do not specify a payload, a default payload which will result in a packet size of 64 bytes is constructed.
|
#### [setCallback](#setcallback)
-| **Signature** | `hs.network.ping.echoRequest:setCallback(fn | nil) -> echoRequestObject` |
+| **Signature** | `hs.network.ping.echoRequest:setCallback(fn) -> echoRequestObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Set or remove the object callback function |
diff --git a/api/hs/hs.network.ping.md b/api/hs/hs.network.ping.md
index f4548a3..918ee40 100644
--- a/api/hs/hs.network.ping.md
+++ b/api/hs/hs.network.ping.md
@@ -122,7 +122,7 @@ This module provides a basic ping function which can test host availability. Pin
| **Returns** | - A string matching the hostname or ip address given to the hs.network.ping.ping constructor for this object.
|
#### [setCallback](#setcallback)
-| **Signature** | `hs.network.ping:setCallback(fn | nil) -> pingObject` |
+| **Signature** | `hs.network.ping:setCallback(fn) -> pingObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Set or remoce the callback function for the pingObject. |
diff --git a/api/hs/hs.network.reachability.md b/api/hs/hs.network.reachability.md
index 112eaaf..f49334c 100644
--- a/api/hs/hs.network.reachability.md
+++ b/api/hs/hs.network.reachability.md
@@ -107,7 +107,7 @@ A specific test for determining if an OpenVPN network is available. This exampl
### Methods
#### [setCallback](#setcallback)
-| **Signature** | `hs.network.reachability:setCallback(function | nil) -> reachabilityObject` |
+| **Signature** | `hs.network.reachability:setCallback(function) -> reachabilityObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Set or remove the callback function for a reachability object |
diff --git a/api/hs/hs.notify.md b/api/hs/hs.notify.md
index dfb2b71..dc42f48 100644
--- a/api/hs/hs.notify.md
+++ b/api/hs/hs.notify.md
@@ -46,7 +46,6 @@ This module is based in part on code from the previous incarnation of Mjolnir by
* [informativeText](#informativetext)
* [otherButtonTitle](#otherbuttontitle)
* [presented](#presented)
- * [release](#release)
* [response](#response)
* [responsePlaceholder](#responseplaceholder)
* [schedule](#schedule)
@@ -124,7 +123,7 @@ This module is based in part on code from the previous incarnation of Mjolnir by
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Unregisters a function callback so that it is no longer available as a callback when notifications corresponding to the specified entry are interacted with. |
-| **Parameters** | - id or tag - the numerical id provided by hs.notify.register or string tag representing the callback function to be removed
|
+| **Parameters** | - id - the numerical id provided by hs.notify.register
- tag - a string tag representing the callback function to be removed
|
| **Returns** | |
#### [unregisterall](#unregisterall)
@@ -313,15 +312,6 @@ This module is based in part on code from the previous incarnation of Mjolnir by
| **Returns** | - A boolean indicating whether the users Notification Center decided to display the notification
|
| **Notes** | - Examples of why the users Notification Center would choose not to display a notification would be if Hammerspoon is the currently focussed application, being attached to a projector, or the user having set Do Not Disturb.
|
-#### [release](#release)
-| **Signature** | `hs.notify:release() -> notificationObject` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | This is a no-op included for backwards compatibility. |
-| **Parameters** | |
-| **Returns** | |
-| **Notes** | - This is no longer required during garbage collection as function tags can be re-established after a reload.
- The proper way to release a notifications callback is to remove its tag from the hs.notify.registry with hs.notify.unregister.
- This is included for backwards compatibility.
|
-
#### [response](#response)
| **Signature** | `hs.notify:response() -> string | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -398,12 +388,13 @@ This module is based in part on code from the previous incarnation of Mjolnir by
| **Type** | Method |
| **Description** | Withdraws a delivered notification from the Notification Center. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | - The notification object
- This method allows you to unlock a dispatched notification so that it can be modified and resent.
|
#### [withdrawAfter](#withdrawafter)
| **Signature** | `hs.notify:withdrawAfter([seconds]) -> notificationObject | number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Get or set the number of seconds after which to automatically withdraw a notification |
+| **Parameters** | - seconds - An optional number, default 5, of seconds after which to withdraw a notification. A value of 0 will not withdraw a notification automatically
|
| **Returns** | - The notification object, if an argument is present; otherwise the current value.
|
diff --git a/api/hs/hs.pasteboard.md b/api/hs/hs.pasteboard.md
index 49d9575..f62d7fd 100644
--- a/api/hs/hs.pasteboard.md
+++ b/api/hs/hs.pasteboard.md
@@ -11,6 +11,7 @@ This module is based partially on code from the previous incarnation of Mjolnir
## API Overview
* Functions - API calls offered directly by the extension
* [allContentTypes](#allcontenttypes)
+ * [callbackWhenChanged](#callbackwhenchanged)
* [changeCount](#changecount)
* [clearContents](#clearcontents)
* [contentTypes](#contenttypes)
@@ -48,6 +49,15 @@ This module is based partially on code from the previous incarnation of Mjolnir
| **Parameters** | - name - an optional string indicating the pasteboard name. If nil or not present, defaults to the system pasteboard.
|
| **Returns** | - an array with each index representing an object on the pasteboard. If the pasteboard contains only one element, this is equivalent to
{ hs.pasteboard.contentTypes(name) }.
|
+#### [callbackWhenChanged](#callbackwhenchanged)
+| **Signature** | `hs.pasteboard.callbackWhenChanged([name], [timeout], callback) -> None` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Invokes callback when the specified pasteoard has changed or the timeout is reached. |
+| **Parameters** | name - an optional string indicating the pasteboard name. If nil or not present, defaults to the system pasteboard.timeout - an optional number, default 2.0, specifying the time in seconds that this function should wait for a change to the specified pasteboard before timing out.callback - a required callback function that will be invoked when either the specified pasteboard contents have changed or the timeout has been reached. The function should expect one boolean argument, true if the pasteboard contents have changed or false if timeout has been reached.
|
+| **Returns** | |
+| **Notes** | - This function can be used to capture the results of a copy operation issued programatically with
hs.application:selectMenuItem or hs.eventtap.keyStroke without resorting to creating your own timers:
|
+
#### [changeCount](#changecount)
| **Signature** | `hs.pasteboard.changeCount([name]) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/hs/hs.plist.md b/api/hs/hs.plist.md
index 24e3675..8080e40 100644
--- a/api/hs/hs.plist.md
+++ b/api/hs/hs.plist.md
@@ -8,6 +8,7 @@ Read and write Property List files
* [read](#read)
* [readString](#readstring)
* [write](#write)
+ * [writeString](#writestring)
## API Documentation
@@ -22,11 +23,11 @@ Read and write Property List files
| **Returns** | - The contents of the plist as a Lua table
|
#### [readString](#readstring)
-| **Signature** | `hs.plist.readString(value) -> table | nil` |
+| **Signature** | `hs.plist.readString(value, [binary]) -> table | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Interpretes a property list file within a string into a table. |
-| **Parameters** | - value - The contents of the property list as a string
|
+| **Parameters** | - value - The contents of the property list as a string
- binary - an optional boolean, specifying whether the value should be treated as raw binary (true) or as an UTF8 encoded string (false). If you do not provide this argument, the function will attempt to auto-detect the type.
|
| **Returns** | - The contents of the property list as a Lua table or
nil if an error occurs
|
#### [write](#write)
@@ -38,3 +39,11 @@ Read and write Property List files
| **Returns** | - A boolean, true if the plist was written successfully, otherwise false
|
| **Notes** | - Only simple types can be converted to plist items:
- Strings
- Numbers
- Booleans
- Tables
- You should be careful when reading a plist, modifying and writing it - Hammerspoon may not be able to preserve all of the datatypes via Lua
|
+#### [writeString](#writestring)
+| **Signature** | `hs.plist.writeString(data, [binary]) -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Interpretes a property list file within a string into a table. |
+| **Parameters** | - data - A Lua table containing the data to write into a plist string
- binary - an optional boolean, default false, specifying that the resulting string should be encoded as a binary plist.
|
+| **Returns** | - A string representing the data as a plist or nil if there was a problem with the date or serialization.
|
+
diff --git a/api/hs/hs.screen.md b/api/hs/hs.screen.md
index cbe5155..d38afb7 100644
--- a/api/hs/hs.screen.md
+++ b/api/hs/hs.screen.md
@@ -37,6 +37,8 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
* [getUUID](#getuuid)
* [id](#id)
* [localToAbsolute](#localtoabsolute)
+ * [mirrorOf](#mirrorof)
+ * [mirrorStop](#mirrorstop)
* [name](#name)
* [next](#next)
* [position](#position)
@@ -147,8 +149,8 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Type** | Method |
| **Description** | Returns a table containing the screen modes supported by the screen. A screen mode is a combination of resolution, scaling factor and colour depth |
| **Parameters** | |
-| **Returns** | - A table containing the supported screen modes. The keys of the table take the form of "1440x900@2x" (for a HiDPI mode) or "1680x1050@1x" (for a native DPI mode). The values are tables which contain the keys:
- w - A number containing the width of the screen mode in points
- h - A number containing the height of the screen mode in points
- scale - A number containing the scaling factor of the screen mode (typically
1 for a native mode, 2 for a HiDPI mode)
|
-| **Notes** | - Only 32-bit colour modes are returned. If you really need to know about 16-bit modes, please file an Issue on GitHub
- "points" are not necessarily the same as pixels, because they take the scale factor into account (e.g. "1440x900@2x" is a 2880x1800 screen resolution, with a scaling factor of 2, i.e. with HiDPI pixel-doubled rendering enabled), however, they are far more useful to work with than native pixel modes, when a Retina screen is involved. For non-retina screens, points and pixels are equivalent.
|
+| **Returns** | - A table containing the supported screen modes. The keys of the table take the form of "1440x900@2x" (for a HiDPI mode) or "1680x1050@1x" (for a native DPI mode). The values are tables which contain the keys:
- w - A number containing the width of the screen mode in points
- h - A number containing the height of the screen mode in points
- scale - A number containing the scaling factor of the screen mode (typically
1 for a native mode, 2 for a HiDPI mode) - freq - A number containing the vertical refresh rate in Hz
- depth - A number containing the bit depth of the display mode
|
+| **Notes** | - Prior to 0.9.83, only 32-bit colour modes would be returned, but now all colour depths are returned. This has necessitated changing the naming of the modes in the returned table.
- "points" are not necessarily the same as pixels, because they take the scale factor into account (e.g. "1440x900@2x" is a 2880x1800 screen resolution, with a scaling factor of 2, i.e. with HiDPI pixel-doubled rendering enabled), however, they are far more useful to work with than native pixel modes, when a Retina screen is involved. For non-retina screens, points and pixels are equivalent.
|
#### [currentMode](#currentmode)
| **Signature** | `hs.screen:currentMode() -> table` |
@@ -156,7 +158,7 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Type** | Method |
| **Description** | Returns a table describing the current screen mode |
| **Parameters** | |
-| **Returns** | - A table containing the current screen mode. The keys of the table are:
- w - A number containing the width of the screen mode in points
- h - A number containing the height of the screen mode in points
- scale - A number containing the scaling factor of the screen mode (typically
1 for a native mode, 2 for a HiDPI mode) - desc - A string containing a representation of the mode as used in
hs.screen:availableModes() - e.g. "1920x1080@2x"
|
+| **Returns** | - A table containing the current screen mode. The keys of the table are:
- w - A number containing the width of the screen mode in points
- h - A number containing the height of the screen mode in points
- scale - A number containing the scaling factor of the screen mode (typically
1 for a native mode, 2 for a HiDPI mode) - freq - A number containing the vertical refresh rate in Hz
- depth - A number containing the bit depth
- desc - A string containing a representation of the mode as used in
hs.screen:availableModes() - e.g. "1920x1080@2x 60Hz 4bpp"
|
#### [desktopImageURL](#desktopimageurl)
| **Signature** | `hs.screen:desktopImageURL([imageURL])` |
@@ -248,6 +250,22 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Parameters** | - geom - an hs.geometry point or rect, or arguments to construct one
|
| **Returns** | - an hs.geometry point or rect, transformed to the absolute coordinate space
|
+#### [mirrorOf](#mirrorof)
+| **Signature** | `hs.screen:mirrorOf(aScreen[, permanent]) -> bool` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Make this screen mirror another |
+| **Parameters** | - aScreen - an hs.screen object you wish to mirror
- permament - an optional bool, true if this should be configured permanently, false if it should apply just for this login session. Defaults to false.
|
+| **Returns** | - true if the operation succeeded, otherwise false
|
+
+#### [mirrorStop](#mirrorstop)
+| **Signature** | `hs.screen:mirrorStop([permanent]) -> bool` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Stops this screen mirroring another |
+| **Parameters** | - permanent - an optional bool, true if this should be configured permanently, false if it should apply just for this login session. Defaults to false.
|
+| **Returns** | - true if the operation succeeded, otherwise false
|
+
#### [name](#name)
| **Signature** | `hs.screen:name() -> string or nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -322,11 +340,11 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Returns** | |
#### [setMode](#setmode)
-| **Signature** | `hs.screen:setMode(width, height, scale) -> boolean` |
+| **Signature** | `hs.screen:setMode(width, height, scale, frequency, depth) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets the screen to a new mode |
-| **Parameters** | - width - A number containing the width in points of the new mode
- height - A number containing the height in points of the new mode
- scale - A number containing the scaling factor of the new mode (typically 1 for native pixel resolutions, 2 for HiDPI/Retina resolutions)
|
+| **Parameters** | - width - A number containing the width in points of the new mode
- height - A number containing the height in points of the new mode
- scale - A number containing the scaling factor of the new mode (typically 1 for native pixel resolutions, 2 for HiDPI/Retina resolutions)
- frequency - A number containing the vertical refresh rate, in Hertz of the new mode
- depth - A number containing the bit depth of the new mode
|
| **Returns** | - A boolean, true if the requested mode was set, otherwise false
|
| **Notes** | - The available widths/heights/scales can be seen in the output of
hs.screen:availableModes(), however, it should be noted that the CoreGraphics subsystem seems to list more modes for a given screen than it is actually prepared to set, so you may find that seemingly valid modes still return false. It is not currently understood why this is so!
|
@@ -371,7 +389,7 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Returns** | - An
hs.image object, or nil if an error occurred
|
#### [toEast](#toeast)
-| **Signature** | `hs.screen:toEast() -> hs.screen object` |
+| **Signature** | `hs.screen:toEast(from, strict) -> hs.screen object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets the first screen to the east of this one, ordered by proximity to its center or a specified point. |
@@ -379,7 +397,7 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Returns** | - An
hs.screen object, or nil if not found
|
#### [toNorth](#tonorth)
-| **Signature** | `hs.screen:toNorth() -> hs.screen object` |
+| **Signature** | `hs.screen:toNorth(from, strict) -> hs.screen object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets the first screen to the north of this one, ordered by proximity to its center or a specified point. |
@@ -387,7 +405,7 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Returns** | - An
hs.screen object, or nil if not found
|
#### [toSouth](#tosouth)
-| **Signature** | `hs.screen:toSouth() -> hs.screen object` |
+| **Signature** | `hs.screen:toSouth(from, strict) -> hs.screen object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets the first screen to the south of this one, ordered by proximity to its center or a specified point. |
@@ -404,7 +422,7 @@ System Preferences->Displays->Arrangement). The origin `0,0` is at the top left
| **Notes** | - this method is just a convenience wrapper for
hs.geometry.toUnitRect(rect,this_screen:frame())
|
#### [toWest](#towest)
-| **Signature** | `hs.screen:toWest() -> hs.screen object` |
+| **Signature** | `hs.screen:toWest(from, strict) -> hs.screen object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets the first screen to the west of this one, ordered by proximity to its center or a specified point. |
diff --git a/api/hs/hs.screen.watcher.md b/api/hs/hs.screen.watcher.md
index 4c6c2b4..f231e58 100644
--- a/api/hs/hs.screen.watcher.md
+++ b/api/hs/hs.screen.watcher.md
@@ -27,7 +27,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Description** | Creates a new screen-watcher. |
| **Parameters** | - The function to be called when a change in the screen layout occurs. This function should take no arguments.
|
| **Returns** | - An
hs.screen.watcher object
|
-| **Notes** | - A screen layout change usually involves a change that is made from the Displays Preferences Panel or when a monitor is attached or removed.
|
+| **Notes** | - A screen layout change usually involves a change that is made from the Displays Preferences Panel or when a monitor is attached or removed. It can also be caused by a change in the Dock size or presence.
|
#### [newWithActiveScreen](#newwithactivescreen)
| **Signature** | `hs.screen.watcher.newWithActiveScreen(fn) -> watcher` |
@@ -36,7 +36,7 @@ This module is based primarily on code from the previous incarnation of Mjolnir
| **Description** | Creates a new screen-watcher that is also called when the active screen changes. |
| **Parameters** | - The function to be called when a change in the screen layout or active screen occurs. This function can optionally take one argument, a boolean which will indicate if the change was due to a screen layout change (nil) or because the active screen changed (true).
|
| **Returns** | - An
hs.screen.watcher object
|
-| **Notes** | - A screen layout change usually involves a change that is made from the Displays Preferences Panel or when a monitor is attached or removed.
nil was chosen instead of false for the argument type when this type of change occurs to more closely match the previous behavior of having no argument passed to the callback function.- An active screen change indicates that the focused or main screen has changed when the user has "Displays have separate spaces" checked in the Mission Control Preferences Panel (the focused display is the display which has the active window and active menubar).
- Detecting a change in the active display relies on watching for the
NSWorkspaceActiveDisplayDidChangeNotification message which is not documented by Apple. While this message has been around at least since OS X 10.9, because it is undocumented, we cannot be positive that Apple won't remove it in a future OS X update. Because this watcher works by listening for posted messages, should Apple remove this notification, your callback function will no longer receive messages about this change -- it won't crash or change behavior in any other way. This documentation will be updated if this status changes.
|
+| **Notes** | - A screen layout change usually involves a change that is made from the Displays Preferences Panel or when a monitor is attached or removed. It can also be caused by a change in the Dock size or presence.
nil was chosen instead of false for the argument type when this type of change occurs to more closely match the previous behavior of having no argument passed to the callback function.- An active screen change indicates that the focused or main screen has changed when the user has "Displays have separate spaces" checked in the Mission Control Preferences Panel (the focused display is the display which has the active window and active menubar).
- Detecting a change in the active display relies on watching for the
NSWorkspaceActiveDisplayDidChangeNotification message which is not documented by Apple. While this message has been around at least since OS X 10.9, because it is undocumented, we cannot be positive that Apple won't remove it in a future OS X update. Because this watcher works by listening for posted messages, should Apple remove this notification, your callback function will no longer receive messages about this change -- it won't crash or change behavior in any other way. This documentation will be updated if this status changes. - Plugging in or unplugging a monitor can cause both a screen layout callback and an active screen change callback.
|
### Methods
diff --git a/api/hs/hs.serial.md b/api/hs/hs.serial.md
index 2304bc1..cbc1d87 100644
--- a/api/hs/hs.serial.md
+++ b/api/hs/hs.serial.md
@@ -98,7 +98,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
| **Notes** | - This function supports the following standard baud rates as numbers: 300, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, 115200, 230400.
- If no baud rate is supplied, it defaults to 115200.
|
#### [callback](#callback)
-| **Signature** | `hs.serial:callback(callbackFn | nil) -> serialPortObject` |
+| **Signature** | `hs.serial:callback(callbackFn) -> serialPortObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets or removes a callback function for the `hs.serial` object. |
@@ -119,8 +119,8 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets or sets the number of data bits for the serial port. |
-| **Parameters** | - value - An optional number to set the number of stop bits. It can be 5 to 8.
|
-| **Returns** | - If a value is specified, then this method returns the serial port object. Otherwise this method reutrns a string value of "none", "odd" or "even".
- The default value is 8.
|
+| **Parameters** | - value - An optional number to set the number of data bits. It can be 5 to 8.
|
+| **Returns** | - If a value is specified, then this method returns the serial port object. Otherwise this method returns the data bits as a number.
- The default value is 8.
|
#### [isOpen](#isopen)
| **Signature** | `hs.serial:isOpen() -> boolean` |
@@ -152,7 +152,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
| **Type** | Method |
| **Description** | Gets or sets the parity for the serial port. |
| **Parameters** | - value - An optional string to set the parity. It can be "none", "odd" or "even".
|
-| **Returns** | - If a value is specified, then this method returns the serial port object. Otherwise this method reutrns a string value of "none", "odd" or "even".
|
+| **Returns** | - If a value is specified, then this method returns the serial port object. Otherwise this method returns a string value of "none", "odd" or "even".
|
#### [path](#path)
| **Signature** | `hs.serial:path() -> string` |
@@ -184,7 +184,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
| **Type** | Method |
| **Description** | Gets or sets the number of stop bits for the serial port. |
| **Parameters** | - value - An optional number to set the number of stop bits. It can be 1 or 2.
|
-| **Returns** | - If a value is specified, then this method returns the serial port object. Otherwise this method reutrns a string value of "none", "odd" or "even".
- The default value is 1.
|
+| **Returns** | - If a value is specified, then this method returns the serial port object. Otherwise this method returns the number of stop bits as a number.
- The default value is 1.
|
#### [usesDTRDSRFlowControl](#usesdtrdsrflowcontrol)
| **Signature** | `hs.serial:usesDTRDSRFlowControl([value]) -> boolean | serialPortObject` |
diff --git a/api/hs/hs.settings.md b/api/hs/hs.settings.md
index 2dad75f..125cfc8 100644
--- a/api/hs/hs.settings.md
+++ b/api/hs/hs.settings.md
@@ -69,9 +69,9 @@ This module is based partially on code from the previous incarnation of Mjolnir
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Saves a setting with common datatypes |
-| **Parameters** | - key - A string containing the name of the setting
- val - An optional value for the setting. Valid datatypes are:
- string
- number
- boolean
- nil
- table (which may contain any of the same valid datatypes)
- if no value is provided, it is assumed to be nil
|
+| **Parameters** | - key - A string containing the name of the setting
- val - An optional value for the setting. Valid datatypes are:
- string
- number
- boolean
- nil
- table (which may contain any of the same valid datatypes)
|
| **Returns** | |
-| **Notes** | - This function cannot set dates or raw data types, see
hs.settings.setDate() and hs.settings.setData() - Assigning a nil value is equivalent to clearing the value with
hs.settings.clear
|
+| **Notes** | - If no val parameter is provided, it is assumed to be nil
- This function cannot set dates or raw data types, see
hs.settings.setDate() and hs.settings.setData() - Assigning a nil value is equivalent to clearing the value with
hs.settings.clear
|
#### [setData](#setdata)
| **Signature** | `hs.settings.setData(key, val)` |
@@ -91,7 +91,7 @@ This module is based partially on code from the previous incarnation of Mjolnir
| **Notes** | - See
hs.settings.dateFormat for a convenient representation of the RFC3339 format, to use with other time/date related functions
|
#### [watchKey](#watchkey)
-| **Signature** | `hs.settings.watchKey(identifier, key, [fn | nil]) -> identifier | current value` |
+| **Signature** | `hs.settings.watchKey(identifier, key, [fn]) -> identifier | current value` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Get or set a watcher to invoke a callback when the specified settings key changes |
diff --git a/api/hs/hs.sharing.md b/api/hs/hs.sharing.md
index aa98d02..6a4b22f 100644
--- a/api/hs/hs.sharing.md
+++ b/api/hs/hs.sharing.md
@@ -126,11 +126,11 @@ Common item data types that can be shared with Sharing Services include (but are
| **Notes** | - not all sharing services will set a value for this property.
|
#### [callback](#callback)
-| **Signature** | `hs.sharing:callback(function | nil) -> sharingObject` |
+| **Signature** | `hs.sharing:callback(fn) -> sharingObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Set or clear the callback for the sharingObject. |
-| **Parameters** | - a function, or nil, to set or remove the callback for the sharingObject
|
+| **Parameters** | - fn - A function, or nil, to set or remove the callback for the sharingObject
|
| **Returns** | |
| **Notes** | - the callback should expect 3 or 4 arguments and return no results. The arguments will be as follows:
- the sharingObject itself
- the callback message, which will be a string equal to one of the following:
- "didFail" - an error occurred while attempting to share the items
- "didShare" - the sharing service has finished sharing the items
- "willShare" - the sharing service is about to start sharing the items; occurs before sharing actually begins
- an array (table) containing the items being shared; if the message is "didFail" or "didShare", the items may be in a different order or converted to a different internal type to facilitate sharing.
- if the message is "didFail", the fourth argument will be a localized description of the error that occurred.
|
diff --git a/api/hs/hs.sound.md b/api/hs/hs.sound.md
index 6600108..4998d4e 100644
--- a/api/hs/hs.sound.md
+++ b/api/hs/hs.sound.md
@@ -5,6 +5,7 @@ Load/play/manipulate sound files
## API Overview
* Functions - API calls offered directly by the extension
+ * [getAudioEffectNames](#getaudioeffectnames)
* [soundFileTypes](#soundfiletypes)
* [soundTypes](#soundtypes)
* [systemSounds](#systemsounds)
@@ -30,6 +31,15 @@ Load/play/manipulate sound files
### Functions
+#### [getAudioEffectNames](#getaudioeffectnames)
+| **Signature** | `hs.sound.getAudioEffectNames() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets a table of installed Audio Units Effect names. |
+| **Parameters** | |
+| **Returns** | - A table containing the names of all installed Audio Units Effects.
|
+| **Notes** | - Example usage:
hs.inspect(hs.audiounit.getAudioEffectNames())
|
+
#### [soundFileTypes](#soundfiletypes)
| **Signature** | `hs.sound.soundFileTypes() -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/hs/hs.spaces.md b/api/hs/hs.spaces.md
new file mode 100644
index 0000000..2942d94
--- /dev/null
+++ b/api/hs/hs.spaces.md
@@ -0,0 +1,12 @@
+# [docs](index.md) » hs.spaces
+---
+
+Controls for macOS Spaces. Currenly only used by `hs.spaces.watcher`.
+
+## Submodules
+ * [hs.spaces.watcher](hs.spaces.watcher.md)
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/hs/hs.speech.listener.md b/api/hs/hs.speech.listener.md
index f7066a1..4b3239e 100644
--- a/api/hs/hs.speech.listener.md
+++ b/api/hs/hs.speech.listener.md
@@ -77,7 +77,7 @@ The speech recognizer functions and methods provide a way to add commands which
| **Returns** | - true if the listener is listening (has been started) or false if it is not.
|
#### [setCallback](#setcallback)
-| **Signature** | `hs.speech.listener:setCallback(fn | nil) -> recognizerObject` |
+| **Signature** | `hs.speech.listener:setCallback(fn) -> recognizerObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets or removes a callback function for the speech recognizer. |
diff --git a/api/hs/hs.speech.md b/api/hs/hs.speech.md
index a368c3c..f264c24 100644
--- a/api/hs/hs.speech.md
+++ b/api/hs/hs.speech.md
@@ -180,7 +180,7 @@ A discussion concerning the embedding of commands into the text to be spoken can
| **Notes** | - This method will reset a synthesizer to its default state, including pitch, modulation, volume, rate, etc.
- The changes go into effect immediately, if queried, but will not affect a synthesis in progress.
|
#### [setCallback](#setcallback)
-| **Signature** | `hs.speech:setCallback(fn | nil) -> synthesizerObject` |
+| **Signature** | `hs.speech:setCallback(fn) -> synthesizerObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets or removes a callback function for the synthesizer. |
diff --git a/api/hs/hs.spoons.md b/api/hs/hs.spoons.md
index c860e7f..8c418ce 100644
--- a/api/hs/hs.spoons.md
+++ b/api/hs/hs.spoons.md
@@ -3,7 +3,7 @@
Utility and management functions for Spoons
Spoons are Lua plugins for Hammerspoon.
-See http://www.hammerspoon.org/Spoons/ for more information
+See https://www.hammerspoon.org/Spoons/ for more information
## API Overview
* Functions - API calls offered directly by the extension
@@ -53,7 +53,7 @@ See http://www.hammerspoon.org/Spoons/ for more information
| **Returns** | - Table with a list of installed/loaded spoons (depending on the value of
onlyLoaded). Each entry is a table with the following entries: name - Spoon nameloaded - boolean indication of whether the Spoon is loaded (true) or only installed (false)version - Spoon version number. Available only for loaded Spoons.
|
#### [newSpoon](#newspoon)
-| **Signature** | `hs.spoons.newSpoon(name, basedir, metadata) -> string | nil` |
+| **Signature** | `hs.spoons.newSpoon(name, basedir, metadata, [template]) -> string | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Create a skeleton for a new Spoon |
@@ -77,7 +77,7 @@ See http://www.hammerspoon.org/Spoons/ for more information
| **Returns** | - String with the path from where the calling code was loaded.
|
#### [use](#use)
-| **Signature** | `hs.spoons.use(name, arg) -> boolean | nil` |
+| **Signature** | `hs.spoons.use(name, arg, [noerror]) -> boolean | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Declaratively load and configure a Spoon |
diff --git a/api/hs/hs.spotlight.md b/api/hs/hs.spotlight.md
index 93fbfe5..014a15a 100644
--- a/api/hs/hs.spotlight.md
+++ b/api/hs/hs.spotlight.md
@@ -166,7 +166,7 @@ You can access the individual results of the query with the [hs.spotlight:result
| **Notes** | - Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.
|
#### [setCallback](#setcallback)
-| **Signature** | `hs.spotlight:setCallback(fn | nil) -> spotlightObject` |
+| **Signature** | `hs.spotlight:setCallback(fn) -> spotlightObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Set or remove the callback function for the Spotlight search object. |
diff --git a/api/hs/hs.sqlite3.md b/api/hs/hs.sqlite3.md
index f0e3640..3bc7c01 100644
--- a/api/hs/hs.sqlite3.md
+++ b/api/hs/hs.sqlite3.md
@@ -4,7 +4,7 @@
Interact with SQLite databases
Notes:
- * This module is LSQLite 0.9.4 as found at http://lua.sqlite.org/index.cgi/index
+ * This module is LSQLite 0.9.5 as found at http://lua.sqlite.org/index.cgi/index
* It is unmodified apart from removing `db:load_extension()` as this feature is not available in Apple's libsqlite3.dylib
* For API documentation please see [http://lua.sqlite.org](http://lua.sqlite.org)
diff --git a/api/hs/hs.streamdeck.md b/api/hs/hs.streamdeck.md
index bb17a78..43adfab 100644
--- a/api/hs/hs.streamdeck.md
+++ b/api/hs/hs.streamdeck.md
@@ -78,6 +78,7 @@ This module would not have been possible without standing on the shoulders of ot
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets the layout of buttons the device has |
+| **Parameters** | |
| **Returns** | - The number of columns
- The number of rows
|
#### [firmwareVersion](#firmwareversion)
diff --git a/api/hs/hs.styledtext.md b/api/hs/hs.styledtext.md
index 6070ba3..2cd1606 100644
--- a/api/hs/hs.styledtext.md
+++ b/api/hs/hs.styledtext.md
@@ -215,6 +215,7 @@ Note that due to differences in the way Lua determines when to use metamethods f
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Loads a font from a file at the specified path. |
+| **Parameters** | path - the path and filename of the font file to attempt to load
|
| **Returns** | - If the font can be registered returns
true, otherwise false and an error message as string.
|
#### [validFont](#validfont)
diff --git a/api/hs/hs.task.md b/api/hs/hs.task.md
index ba8cef1..ed06000 100644
--- a/api/hs/hs.task.md
+++ b/api/hs/hs.task.md
@@ -35,7 +35,7 @@ Notes:
### Functions
#### [new](#new)
-| **Signature** | `hs.task.new(launchPath, callbackFn[, streamCallbackFn, arguments]) -> hs.task object` |
+| **Signature** | `hs.task.new(launchPath, callbackFn[, streamCallbackFn][, arguments]) -> hs.task object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Creates a new hs.task object |
diff --git a/api/hs/hs.timer.delayed.md b/api/hs/hs.timer.delayed.md
index 67df1a6..3f82119 100644
--- a/api/hs/hs.timer.delayed.md
+++ b/api/hs/hs.timer.delayed.md
@@ -24,7 +24,7 @@ Specialized timer objects to coalesce processing of unpredictable asynchronous e
| **Description** | Creates a new delayed timer. |
| **Parameters** | - delay - number of seconds to wait for after a
:start() invocation (the "callback countdown") - fn - a function to call after
delay has fully elapsed without any further :start() invocations
|
| **Returns** | - a new
hs.timer.delayed object
|
-| **Notes** | - these timers are meant to be long-lived: once instantiated, there's no way to remove them from the run loop; create them once at the module level.
|
+| **Notes** | - these timers are meant to be long-lived: once instantiated, there's no way to remove them from the run loop; create them once at the module level.
|
### Methods
@@ -58,7 +58,7 @@ Specialized timer objects to coalesce processing of unpredictable asynchronous e
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Starts or restarts the callback countdown |
-| **Parameters** | - delay - (optional) if provided, sets the countdown duration to this number of seconds for this time only; subsequent calls to
:start() will revert to the original delay (or to the delay set with :setDelay(delay))
|
+| **Parameters** | - delay - (optional) if provided, sets the countdown duration to this number of seconds for this time only; subsequent calls to
:start() will revert to the original delay (or to the delay set with :setDelay(delay))
|
| **Returns** | |
#### [stop](#stop)
diff --git a/api/hs/hs.timer.md b/api/hs/hs.timer.md
index faa600e..ece9c59 100644
--- a/api/hs/hs.timer.md
+++ b/api/hs/hs.timer.md
@@ -3,6 +3,10 @@
Execute functions with various timing rules
+**NOTE**: timers use NSTimer internally, which will be paused when computers sleep.
+Especially, repeating timers won't be triggered at the specificed time when there are sleeps in between.
+The workaround is to prevent system from sleeping, configured in Energy Saver in System Preferences.
+
## Submodules
* [hs.timer.delayed](hs.timer.delayed.md)
diff --git a/api/hs/hs.watchable.md b/api/hs/hs.watchable.md
index 6264a70..51a9b65 100644
--- a/api/hs/hs.watchable.md
+++ b/api/hs/hs.watchable.md
@@ -44,7 +44,7 @@ The goal is to provide a mechanism for sharing state information between separat
### Methods
#### [callback](#callback)
-| **Signature** | `hs.watchable:callback(fn | nil) -> watchableObject` |
+| **Signature** | `hs.watchable:callback(fn) -> watchableObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Change or remove the callback function for the watchableObject. |
diff --git a/api/hs/hs.websocket.md b/api/hs/hs.websocket.md
index c802f84..7152fc4 100644
--- a/api/hs/hs.websocket.md
+++ b/api/hs/hs.websocket.md
@@ -35,12 +35,13 @@ Simple websocket client.
| **Returns** | |
#### [send](#send)
-| **Signature** | `hs.websocket:send(message) -> object` |
+| **Signature** | `hs.websocket:send(message[, isData]) -> object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
-| **Description** | Sends a message to the websocket client |
-| **Parameters** | - message - A string containing the message to send
|
+| **Description** | Sends a message to the websocket client. |
+| **Parameters** | - message - A string containing the message to send.
- isData - An optional boolean that sends the message as binary data (defaults to true).
|
| **Returns** | |
+| **Notes** | - Forcing a text representation by setting isData to
false may alter the data if it contains invalid UTF8 character sequences (the default string behavior is to make sure everything is "printable" by converting invalid sequences into the Unicode Invalid Character sequence).
|
#### [status](#status)
| **Signature** | `hs.websocket:status() -> string` |
diff --git a/api/hs/hs.webview.md b/api/hs/hs.webview.md
index e43f0c2..1a6e69e 100644
--- a/api/hs/hs.webview.md
+++ b/api/hs/hs.webview.md
@@ -148,7 +148,7 @@ Any suggestions or updates to the code to address any of these or other limitati
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constructor |
| **Description** | Create a webviewObject and optionally modify its preferences. |
-| **Parameters** | rect - a rectangle specifying where the webviewObject should be displayed.preferencesTable - an optional table which can include one of more of the following keys:javaEnabled - java is enabled (default false)javaScriptEnabled - JavaScript is enabled (default true)javaScriptCanOpenWindowsAutomatically - can JavaScript open windows without user intervention (default true)minimumFontSize - minimum font size (default 0.0)plugInsEnabled - plug-ins are enabled (default false)developerExtrasEnabled - include "Inspect Element" in the context menusuppressesIncrementalRendering - suppresses content rendering until fully loaded into memory (default false)
|
+| **Parameters** | rect - a rectangle specifying where the webviewObject should be displayed.preferencesTable - an optional table which can include one of more of the following keys:javaEnabled - java is enabled (default false)javaScriptEnabled - JavaScript is enabled (default true)javaScriptCanOpenWindowsAutomatically - can JavaScript open windows without user intervention (default true)minimumFontSize - minimum font size (default 0.0)plugInsEnabled - plug-ins are enabled (default false)developerExtrasEnabled - include "Inspect Element" in the context menusuppressesIncrementalRendering - suppresses content rendering until fully loaded into memory (default false)- The following additional preferences may also be set under OS X 10.11 or later (they will be ignored with a warning printed if used under OS X 10.10):
applicationName - a string specifying an application name to be listed at the end of the browser's USER-AGENT header. Note that this is only appended to the default user agent string; if you set a custom one with hs.webview:userAgent, this value is ignored.allowsAirPlay - a boolean specifying whether media playback within the webview can play through AirPlay devices.datastore - an hs.webview.datastore object specifying where website data such as cookies, cacheable content, etc. is to be stored.privateBrowsing - a boolean (default false) specifying that the datastore should be set to a new, empty and non-persistent datastore. Note that this will override the datastore key if both are specified and this is set to true.
userContentController - an optional hs.webview.usercontent object to provide script injection and JavaScript messaging with Hammerspoon from the webview.
|
| **Returns** | |
| **Notes** | - To set the initial URL, use the
hs.webview:url method before showing the webview object. - Preferences can only be set when the webview object is created. To change the preferences of an open webview, you will need to close it and recreate it with this method.
|
@@ -157,9 +157,9 @@ Any suggestions or updates to the code to address any of these or other limitati
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constructor |
| **Description** | Create a webviewObject with some presets common to an interactive web browser. |
-| **Parameters** | - The parameters are the same as for hs.webview.new -- check there for more details
rect - a rectangle specifying where the webviewObject should be displayed.preferencesTable - an optional table which specifies special settings for the webview object.userContentController - an optional hs.webview.usercontent object to provide script injection and JavaScript messaging with Hammerspoon from the webview.
|
+| **Parameters** | rect - a rectangle specifying where the webviewObject should be displayed.preferencesTable - an optional table which specifies special settings for the webview object.userContentController - an optional hs.webview.usercontent object to provide script injection and JavaScript messaging with Hammerspoon from the webview.
|
| **Returns** | |
-| **Notes** | - This constructor is just a short-hand for
hs.webview.new(...):allowTextEntry(true):allowGestures(true):windowStyle(15), which specifies a webview with a title bar, title bar buttons (zoom, close, minimize), and allows form entry and gesture support for previous and next pages.
|
+| **Notes** | - The parameters are the same as for hs.webview.new -- check there for more details
- This constructor is just a short-hand for
hs.webview.new(...):allowTextEntry(true):allowGestures(true):windowStyle(15), which specifies a webview with a title bar, title bar buttons (zoom, close, minimize), and allows form entry and gesture support for previous and next pages.
|
### Methods
@@ -214,7 +214,7 @@ Any suggestions or updates to the code to address any of these or other limitati
| **Returns** | - If a parameter is provided, returns the webview object; otherwise returns the current value.
|
#### [attachedToolbar](#attachedtoolbar)
-| **Signature** | `hs.webview:attachedToolbar([toolbar | nil]) -> webviewObject | currentValue` |
+| **Signature** | `hs.webview:attachedToolbar([toolbar]) -> webviewObject | currentValue` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Get or attach/detach a toolbar to/from the webview. |
diff --git a/api/hs/hs.webview.toolbar.md b/api/hs/hs.webview.toolbar.md
index 7286677..bda2d81 100644
--- a/api/hs/hs.webview.toolbar.md
+++ b/api/hs/hs.webview.toolbar.md
@@ -96,7 +96,7 @@ Notes:
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Get or attach/detach a toolbar to the webview, chooser, or console. |
-| **Parameters** | - if no arguments are present, this function returns the current toolbarObject for the Hammerspoon console, or nil if one is not attached.
- if one argument is provided and it is a toolbarObject or nil, this function will attach or detach a toolbarObject to/from the Hammerspoon console.
- if one argument is provided and it is an hs.webview or hs.chooser object, this function will return the current toolbarObject for the object, or nil if one is not attached.
- if two arguments are provided and the first is an hs.webview or hs.chooser object and the second is a toolbarObject or nil, this function will attach or detach a toolbarObject to/from the object.
|
+| **Parameters** | - obj1 - An optional toolbarObject
- obj2 - An optional toolbarObject
- if no arguments are present, this function returns the current toolbarObject for the Hammerspoon console, or nil if one is not attached.
- if one argument is provided and it is a toolbarObject or nil, this function will attach or detach a toolbarObject to/from the Hammerspoon console.
- if one argument is provided and it is an hs.webview or hs.chooser object, this function will return the current toolbarObject for the object, or nil if one is not attached.
- if two arguments are provided and the first is an hs.webview or hs.chooser object and the second is a toolbarObject or nil, this function will attach or detach a toolbarObject to/from the object.
|
| **Returns** | - if the function is used to attach/detach a toolbar, then the first object provided (the target) will be returned ; if this function is used to get the current toolbar object for a webview, chooser, or console, then the toolbarObject or nil will be returned.
|
| **Notes** | - This function is not expected to be used directly (though it can be) -- it is added to the
hs.webview and hs.chooser object metatables so that it may be invoked as hs.webview:attachedToolbar([toolbarObject | nil])/hs.chooser:attachedToolbar([toolbarObject | nil]) and to the hs.console module so that it may be invoked as hs.console.toolbar([toolbarObject | nil]).
|
@@ -278,7 +278,7 @@ Notes:
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Remove the toolbar item at the index position specified, or with the specified identifier, if currently present in the toolbar. |
-| **Parameters** | index - the numerical position of the toolbar item to remove. oridentifier - the identifier of the toolbar item to remove, if currently active in the toolbar
|
+| **Parameters** | index - the numerical position of the toolbar item to remove.identifier - the identifier of the toolbar item to remove, if currently active in the toolbar
|
| **Returns** | |
| **Notes** | - the toolbar position must be between 1 and the number of currently active toolbar items.
|
@@ -318,7 +318,7 @@ Notes:
| **Returns** | - if an argument is provided, returns the toolbar object; otherwise returns the current value
|
#### [setCallback](#setcallback)
-| **Signature** | `hs.webview.toolbar:setCallback(fn | nil) -> toolbarObject` |
+| **Signature** | `hs.webview.toolbar:setCallback(fn) -> toolbarObject` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Sets or removes the global callback function for the toolbar. |
diff --git a/api/hs/hs.window.md b/api/hs/hs.window.md
index a94e061..631ba9c 100644
--- a/api/hs/hs.window.md
+++ b/api/hs/hs.window.md
@@ -120,7 +120,7 @@ Notes:
| **Type** | Function |
| **Description** | Returns the desktop "window" |
| **Parameters** | |
-| **Returns** | - An
hs.window object representing the desktop
|
+| **Returns** | - An
hs.window object representing the desktop, or nil if Finder is not running
|
| **Notes** | - The desktop belongs to Finder.app: when Finder is the active application, you can focus the desktop by cycling through windows via cmd-`
- The desktop window has no id, a role of
AXScrollArea and no subrole - The desktop is filtered out from
hs.window.allWindows() (and downstream uses)
|
#### [invisibleWindows](#invisiblewindows)
@@ -291,18 +291,27 @@ Notes:
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Focuses the nearest possible window to the north (i.e. up) |
+| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true focuses the nearest window that isn't occluded by any other window
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
|
+| **Returns** | true if a window was found and focused, false otherwise; nil if the search couldn't take place
|
+| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
#### [focusWindowSouth](#focuswindowsouth)
| **Signature** | `hs.window:focusWindowSouth([candidateWindows[, frontmost[, strict]]]) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Focuses the nearest possible window to the south (i.e. down) |
+| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true focuses the nearest window that isn't occluded by any other window
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
|
+| **Returns** | true if a window was found and focused, false otherwise; nil if the search couldn't take place
|
+| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
#### [focusWindowWest](#focuswindowwest)
| **Signature** | `hs.window:focusWindowWest([candidateWindows[, frontmost[, strict]]]) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Focuses the nearest possible window to the west (i.e. left) |
+| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true focuses the nearest window that isn't occluded by any other window
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
|
+| **Returns** | true if a window was found and focused, false otherwise; nil if the search couldn't take place
|
+| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
#### [frame](#frame)
| **Signature** | `hs.window:frame() -> hs.geometry rect` |
@@ -333,6 +342,7 @@ Notes:
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Determines if a window is maximizable |
+| **Parameters** | |
| **Returns** | - True if the window is maximizable, False if it isn't, or nil if an error occurred
|
#### [isMinimized](#isminimized)
@@ -400,18 +410,24 @@ Notes:
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Moves the window one screen north (i.e. up) |
+| **Parameters** | - noResize - (optional) if
true, maintain the window's absolute size - ensureInScreenBounds - (optional) if
true, use setFrameInScreenBounds() to ensure the resulting window frame is fully contained within the window's screen - duration - (optional) The number of seconds to animate the transition. Defaults to the value of
hs.window.animationDuration
|
+| **Returns** | |
#### [moveOneScreenSouth](#moveonescreensouth)
| **Signature** | `hs.window:moveOneScreenSouth([noResize, ensureInScreenBounds][, duration]) -> hs.window object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Moves the window one screen south (i.e. down) |
+| **Parameters** | - noResize - (optional) if
true, maintain the window's absolute size - ensureInScreenBounds - (optional) if
true, use setFrameInScreenBounds() to ensure the resulting window frame is fully contained within the window's screen - duration - (optional) The number of seconds to animate the transition. Defaults to the value of
hs.window.animationDuration
|
+| **Returns** | |
#### [moveOneScreenWest](#moveonescreenwest)
| **Signature** | `hs.window:moveOneScreenWest([noResize, ensureInScreenBounds][, duration]) -> hs.window object` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Moves the window one screen west (i.e. left) |
+| **Parameters** | - noResize - (optional) if
true, maintain the window's absolute size - ensureInScreenBounds - (optional) if
true, use setFrameInScreenBounds() to ensure the resulting window frame is fully contained within the window's screen - duration - (optional) The number of seconds to animate the transition. Defaults to the value of
hs.window.animationDuration
|
+| **Returns** | |
#### [moveToScreen](#movetoscreen)
| **Signature** | `hs.window:moveToScreen(screen[, noResize, ensureInScreenBounds][, duration]) -> hs.window object` |
@@ -607,27 +623,36 @@ Notes:
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets all windows to the east of this window |
-| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
|
+| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the east are candidates.
- frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the eastward axis
|
| **Returns** | - A list of
hs.window objects representing all windows positioned east (i.e. right) of the window, in ascending order of distance
|
-| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
+| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
#### [windowsToNorth](#windowstonorth)
| **Signature** | `hs.window:windowsToNorth([candidateWindows[, frontmost[, strict]]]) -> list of hs.window objects` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets all windows to the north of this window |
+| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the north are candidates.
- frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the northward axis
|
+| **Returns** | - A list of
hs.window objects representing all windows positioned north (i.e. up) of the window, in ascending order of distance
|
+| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
#### [windowsToSouth](#windowstosouth)
| **Signature** | `hs.window:windowsToSouth([candidateWindows[, frontmost[, strict]]]) -> list of hs.window objects` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets all windows to the south of this window |
+| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the south are candidates.
- frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the southward axis
|
+| **Returns** | - A list of
hs.window objects representing all windows positioned south (i.e. down) of the window, in ascending order of distance
|
+| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
#### [windowsToWest](#windowstowest)
| **Signature** | `hs.window:windowsToWest([candidateWindows[, frontmost[, strict]]]) -> list of hs.window objects` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Method |
| **Description** | Gets all windows to the west of this window |
+| **Parameters** | - candidateWindows - (optional) a list of candidate windows to consider; if nil, all visible windows to the west are candidates.
- frontmost - (optional) boolean, if true unoccluded windows will be placed before occluded ones in the result list
- strict - (optional) boolean, if true only consider windows at an angle between 45° and -45° on the westward axis
|
+| **Returns** | - A list of
hs.window objects representing all windows positioned west (i.e. left) of the window, in ascending order of distance
|
+| **Notes** | - If you don't pass
candidateWindows, Hammerspoon will query for the list of all visible windows every time this method is called; this can be slow, and some undesired "windows" could be included (see the notes for hs.window.allWindows()); consider using the equivalent methods in hs.window.filter instead
|
#### [zoomButtonRect](#zoombuttonrect)
| **Signature** | `hs.window:zoomButtonRect() -> rect-table or nil` |
diff --git a/api/hs/hs.window.tiling.md b/api/hs/hs.window.tiling.md
index 95d65c3..8a13ae6 100644
--- a/api/hs/hs.window.tiling.md
+++ b/api/hs/hs.window.tiling.md
@@ -24,7 +24,7 @@ The `tileWindows` function in this module is primarily meant for use by `hs.wind
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Tile (or fit) windows into a rect |
-| **Parameters** | - windows - a list of
hs.window objects indicating the windows to tile or fit - rect - an
hs.geometry rect (or constructor argument), indicating the desired onscreen region that the windows will be tiled within - desiredAspect - (optional) an
hs.geometry size (or constructor argument) or a number, indicating the desired optimal aspect ratio (width/height) of the tiled windows; the tiling engine will decide how to subdivide the rect among windows by trying to maintain every window's aspect ratio as close as possible to this; if omitted, defaults to 1 (i.e. try to keep the windows as close to square as possible) - processInOrder - (optional) if
true, windows will be placed left-to-right and top-to-bottom following the list order in windows; if false or omitted, the tiling engine will try to maintain the spatial distribution of windows, i.e. (roughly speaking) pick the closest window for each destination "tile"; note that in some cases this isn't possible and the windows might get "reshuffled" around in unexpected ways - preserveRelativeArea - (optional) if
true, preserve the relative area among windows; that is, if window A is currently twice as large as window B, the same will be true after both windows have been processed and placed into the rect; if false or omitted, all windows will have the same area (= area of the rect / number of windows) after processing - animationDuration - (optional) the number of seconds to animate the move/resize operations of the windows; if omitted, defaults to the value of
hs.window.animationDuration
|
+| **Parameters** | - windows - a list of
hs.window objects indicating the windows to tile or fit - rect - an
hs.geometry rect (or constructor argument), indicating the desired onscreen region that the windows will be tiled within - desiredAspect - (optional) an
hs.geometry size (or constructor argument) or a number, indicating the desired optimal aspect ratio (width/height) of the tiled windows; the tiling engine will decide how to subdivide the rect among windows by trying to maintain every window's aspect ratio as close as possible to this; if omitted, defaults to 1 (i.e. try to keep the windows as close to square as possible) - processInOrder - (optional) if
true, windows will be placed left-to-right and top-to-bottom following the list order in windows; if false or omitted, the tiling engine will try to maintain the spatial distribution of windows, i.e. (roughly speaking) pick the closest window for each destination "tile"; note that in some cases this isn't possible and the windows might get "reshuffled" around in unexpected ways - preserveRelativeArea - (optional) if
true, preserve the relative area among windows; that is, if window A is currently twice as large as window B, the same will be true after both windows have been processed and placed into the rect; if false or omitted, all windows will have the same area (= area of the rect / number of windows) after processing - animationDuration - (optional) the number of seconds to animate the move/resize operations of the windows; if omitted, defaults to the value of
hs.window.animationDuration
|
| **Returns** | |
| **Notes** | - To ensure all windows are placed in a row (side by side), use a very small aspect ratio (for "tall and narrow" windows) like 0.01; similarly, to have all windows in a column, use a very large aspect ratio (for "short and wide") like 100
- Hidden and minimized windows will be processed as well: the rect will have "gaps" where the invisible windows would lie, that will get filled as the windows get unhidden/unminimized
|
diff --git a/api/hs/index.md b/api/hs/index.md
index 5accfd8..3b3869c 100644
--- a/api/hs/index.md
+++ b/api/hs/index.md
@@ -4,14 +4,14 @@
## Project Links
| Resource | Link |
| --------------- | -------------------------------- |
-| Website | [http://www.hammerspoon.org/](http://www.hammerspoon.org/) |
+| Website | [https://www.hammerspoon.org/](https://www.hammerspoon.org/) |
| GitHub page | [https://github.com/Hammerspoon/hammerspoon](https://github.com/Hammerspoon/hammerspoon) |
-| Getting Started Guide | [http://www.hammerspoon.org/go/](http://www.hammerspoon.org/go/) |
+| Getting Started Guide | [https://www.hammerspoon.org/go/](https://www.hammerspoon.org/go/) |
| Spoon Plugin Documentation | [https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md](https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md) |
-| Official Spoon repository | [http://www.hammerspoon.org/Spoons](http://www.hammerspoon.org/Spoons) |
+| Official Spoon repository | [https://www.hammerspoon.org/Spoons](https://www.hammerspoon.org/Spoons) |
| IRC channel | [irc://chat.freenode.net/#hammerspoon](irc://chat.freenode.net/#hammerspoon) |
| Mailing list | [https://groups.google.com/forum/#!forum/hammerspoon/](https://groups.google.com/forum/#!forum/hammerspoon/) |
-| LuaSkin API docs | [http://www.hammerspoon.org/docs/LuaSkin/](http://www.hammerspoon.org/docs/LuaSkin/) |
+| LuaSkin API docs | [https://www.hammerspoon.org/docs/LuaSkin/](https://www.hammerspoon.org/docs/LuaSkin/) |
## API Documentation
| Module | Description |
@@ -25,7 +25,9 @@
| [hs.audiodevice](hs.audiodevice.md) | Manipulate the system's audio devices |
| [hs.audiodevice.datasource](hs.audiodevice.datasource.md) | Inspect/manipulate the data sources of an audio device |
| [hs.audiodevice.watcher](hs.audiodevice.watcher.md) | Watch for system level audio hardware events |
-| [hs.audiounit](hs.audiounit.md) | Audio Units Extension. |
+| [hs.axuielement](hs.axuielement.md) | This module allows you to access the accessibility objects of running applications, their windows, menus, and other user interface elements that support the OS X accessibility API. |
+| [hs.axuielement.axtextmarker](hs.axuielement.axtextmarker.md) | This submodule allows hs.axuielement to support using AXTextMarker and AXTextMarkerRange objects as parameters for parameterized Accessibility attributes with applications that support them. |
+| [hs.axuielement.observer](hs.axuielement.observer.md) | This submodule allows you to create observers for accessibility elements and be notified when they trigger notifications. Not all notifications are supported by all elements and not all elements support notifications, so some trial and error will be necessary, but for compliant applications, this can allow your code to be notified when an application's user interface changes in some way. |
| [hs.base64](hs.base64.md) | Base64 encoding and decoding |
| [hs.battery](hs.battery.md) | Battery/power information |
| [hs.battery.watcher](hs.battery.watcher.md) | Watch for battery/power state changes |
@@ -79,7 +81,7 @@
| [hs.itunes](hs.itunes.md) | Controls for iTunes music player |
| [hs.javascript](hs.javascript.md) | Execute JavaScript code |
| [hs.json](hs.json.md) | JSON encoding and decoding |
-| [hs.keycodes](hs.keycodes.md) | Convert between key-strings and key-codes. Also provides funcionality for querying and changing keyboard layouts. |
+| [hs.keycodes](hs.keycodes.md) | Convert between key-strings and key-codes. Also provides functionality for querying and changing keyboard layouts. |
| [hs.layout](hs.layout.md) | Window layout manager |
| [hs.location](hs.location.md) | Determine the machine's location and useful information about that location |
| [hs.location.geocoder](hs.location.geocoder.md) | Converts between GPS coordinates and more user friendly representations like an address or points of interest. |
@@ -113,6 +115,7 @@
| [hs.socket](hs.socket.md) | Talk to custom protocols using asynchronous TCP sockets |
| [hs.socket.udp](hs.socket.udp.md) | Talk to custom protocols using asynchronous UDP sockets |
| [hs.sound](hs.sound.md) | Load/play/manipulate sound files |
+| [hs.spaces](hs.spaces.md) | Controls for macOS Spaces. Currenly only used by `hs.spaces.watcher`. |
| [hs.spaces.watcher](hs.spaces.watcher.md) | Watches for the current Space being changed |
| [hs.speech](hs.speech.md) | This module provides access to the Speech Synthesizer component of OS X. |
| [hs.speech.listener](hs.speech.listener.md) | This module provides access to the Speech Recognizer component of OS X. |
diff --git a/api/plugins/index.md b/api/plugins/index.md
index 63c4640..0aaeb08 100644
--- a/api/plugins/index.md
+++ b/api/plugins/index.md
@@ -4,19 +4,23 @@
## Project Links
| Resource | Link |
| --------------- | -------------------------------- |
-| Website | [http://www.hammerspoon.org/](http://www.hammerspoon.org/) |
+| Website | [https://www.hammerspoon.org/](https://www.hammerspoon.org/) |
| GitHub page | [https://github.com/Hammerspoon/hammerspoon](https://github.com/Hammerspoon/hammerspoon) |
-| Getting Started Guide | [http://www.hammerspoon.org/go/](http://www.hammerspoon.org/go/) |
+| Getting Started Guide | [https://www.hammerspoon.org/go/](https://www.hammerspoon.org/go/) |
| Spoon Plugin Documentation | [https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md](https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md) |
-| Official Spoon repository | [http://www.hammerspoon.org/Spoons](http://www.hammerspoon.org/Spoons) |
+| Official Spoon repository | [https://www.hammerspoon.org/Spoons](https://www.hammerspoon.org/Spoons) |
| IRC channel | [irc://chat.freenode.net/#hammerspoon](irc://chat.freenode.net/#hammerspoon) |
| Mailing list | [https://groups.google.com/forum/#!forum/hammerspoon/](https://groups.google.com/forum/#!forum/hammerspoon/) |
-| LuaSkin API docs | [http://www.hammerspoon.org/docs/LuaSkin/](http://www.hammerspoon.org/docs/LuaSkin/) |
+| LuaSkin API docs | [https://www.hammerspoon.org/docs/LuaSkin/](https://www.hammerspoon.org/docs/LuaSkin/) |
## API Documentation
| Module | Description |
| ------------------------------------------------------------------ | --------------------- |
-| [plugins.colorfinale.tangent](plugins.colorfinale.tangent.md) | This plugin basically just disables CP's Tangent Manager when ColorFinale is running. |
+| [plugins.aftereffects.application.manager](plugins.aftereffects.application.manager.md) | Registers After Effects with the Core Application Manager if installed. |
+| [plugins.aftereffects.effects](plugins.aftereffects.effects.md) | Apply an After Effect effect to selected layer |
+| [plugins.aftereffects.preferences](plugins.aftereffects.preferences.md) | After Effects Preferences Panel |
+| [plugins.aftereffects.shortcuts](plugins.aftereffects.shortcuts.md) | Trigger After Effects Shortcuts |
+| [plugins.aftereffects.tangent.manager](plugins.aftereffects.tangent.manager.md) | Manager for After Effects Tangent Support |
| [plugins.compressor.application.manager](plugins.compressor.application.manager.md) | Registers Compressor with the Core Application Manager. |
| [plugins.compressor.feedback.bugreport](plugins.compressor.feedback.bugreport.md) | Sends Apple a Bug Report or Feature Request for Compressor. |
| [plugins.compressor.watchfolders.panels.media](plugins.compressor.watchfolders.panels.media.md) | Compressor Watch Folder Plugin. |
@@ -47,9 +51,8 @@
| [plugins.core.helpandsupport.userguide](plugins.core.helpandsupport.userguide.md) | User Guide Menu Item. |
| [plugins.core.language](plugins.core.language.md) | Language Module. |
| [plugins.core.loupedeck.prefs](plugins.core.loupedeck.prefs.md) | Loupedeck+ Preferences Panel |
-| [plugins.core.loupedeckct.changeapplications](plugins.core.loupedeckct.changeapplications.md) | Allows you to change the Loupedeck CT application if set to manual. |
-| [plugins.core.loupedeckct.manager](plugins.core.loupedeckct.manager.md) | Loupedeck CT Manager Plugin. |
-| [plugins.core.loupedeckct.prefs](plugins.core.loupedeckct.prefs.md) | Loupedeck CT Preferences Panel |
+| [plugins.core.loupedeckctandlive.manager](plugins.core.loupedeckctandlive.manager.md) | Loupedeck CT & Loupedeck Live Manager Plugin. |
+| [plugins.core.loupedeckctandlive.prefs](plugins.core.loupedeckctandlive.prefs.md) | Loupedeck CT & Loupedeck Live Preferences Panels |
| [plugins.core.loupedeckplus.prefs](plugins.core.loupedeckplus.prefs.md) | Loupedeck+ Preferences Panel |
| [plugins.core.menu.manager](plugins.core.menu.manager.md) | Menu Manager Plugin. |
| [plugins.core.menu.manager.section](plugins.core.menu.manager.section.md) | Controls sections for the CommandPost menu. |
@@ -75,23 +78,16 @@
| [plugins.core.shortcuts.prefs](plugins.core.shortcuts.prefs.md) | Shortcuts Preferences Panel |
| [plugins.core.streamdeck.manager](plugins.core.streamdeck.manager.md) | Elgato Stream Deck Manager Plugin. |
| [plugins.core.streamdeck.prefs](plugins.core.streamdeck.prefs.md) | Stream Deck Preferences Panel |
-| [plugins.core.tangent.commandpost](plugins.core.tangent.commandpost.md) | CommandPost Group for the Tangent. |
-| [plugins.core.tangent.commandpost.favourites](plugins.core.tangent.commandpost.favourites.md) | Tangent Favourites. |
-| [plugins.core.tangent.commandpost.functions](plugins.core.tangent.commandpost.functions.md) | CommandPost Functions for Tangent. |
| [plugins.core.tangent.manager](plugins.core.tangent.manager.md) | Tangent Control Surface Manager |
| [plugins.core.tangent.manager.action](plugins.core.tangent.manager.action.md) | Represents a Tangent Action |
| [plugins.core.tangent.manager.binding](plugins.core.tangent.manager.binding.md) | Represents a Tangent Binding |
+| [plugins.core.tangent.manager.connection](plugins.core.tangent.manager.connection.md) | Represents a Tangent Connection. |
| [plugins.core.tangent.manager.controls](plugins.core.tangent.manager.controls.md) | Represents a Tangent Group |
| [plugins.core.tangent.manager.group](plugins.core.tangent.manager.group.md) | Represents a Tangent Group. Groups can also be used to enable/disable multiple |
| [plugins.core.tangent.manager.menu](plugins.core.tangent.manager.menu.md) | Represents a Tangent Menu. Menus are controls that have a fixed set of |
| [plugins.core.tangent.manager.mode](plugins.core.tangent.manager.mode.md) | Represents a Tangent Mode |
| [plugins.core.tangent.manager.named](plugins.core.tangent.manager.named.md) | Provides common functions for 'named' Tangent nodes |
| [plugins.core.tangent.manager.parameter](plugins.core.tangent.manager.parameter.md) | Represents a Tangent Parameter control. |
-| [plugins.core.tangent.os](plugins.core.tangent.os.md) | macOS Group for the Tangent. |
-| [plugins.core.tangent.os.display](plugins.core.tangent.os.display.md) | Tangent Display Functions. |
-| [plugins.core.tangent.os.pasteboard](plugins.core.tangent.os.pasteboard.md) | Pasteboard Tools for Tangent. |
-| [plugins.core.tangent.os.sound](plugins.core.tangent.os.sound.md) | Tangent Display Functions. |
-| [plugins.core.tangent.os.window](plugins.core.tangent.os.window.md) | Window Management Tools for Tangent. |
| [plugins.core.tangent.prefs](plugins.core.tangent.prefs.md) | Tangent Preferences Panel |
| [plugins.core.toolbox.manager](plugins.core.toolbox.manager.md) | Manager for the CommandPost Toolbox Window. |
| [plugins.core.tools.caffeinate](plugins.core.tools.caffeinate.md) | Prevents your Mac from going to sleep. |
@@ -111,6 +107,7 @@
| [plugins.core.watchfolders.manager.panel](plugins.core.watchfolders.manager.panel.md) | Watch Folder Panel Manager. |
| [plugins.core.watchfolders.menuitem](plugins.core.watchfolders.menuitem.md) | Adds the "Setup Watch Folders" to the menu bar. |
| [plugins.diskutility.application.manager](plugins.diskutility.application.manager.md) | Registers Disk Utility with the Core Application Manager. |
+| [plugins.ecammlive.application.manager](plugins.ecammlive.application.manager.md) | Registers Ecamm Live with the Core Application Manager. |
| [plugins.finalcutpro.actions.custom](plugins.finalcutpro.actions.custom.md) | Creates a bunch of commands that can be used to assign actions to. |
| [plugins.finalcutpro.advanced.backupinterval](plugins.finalcutpro.advanced.backupinterval.md) | Change Final Cut Pro's Backup Interval. |
| [plugins.finalcutpro.advanced.disablewaveforms](plugins.finalcutpro.advanced.disablewaveforms.md) | Disable Waveforms Plugin. |
@@ -192,15 +189,21 @@
| [plugins.finalcutpro.tangent.audio](plugins.finalcutpro.tangent.audio.md) | Final Cut Pro Audio Inspector for Tangent |
| [plugins.finalcutpro.tangent.browser](plugins.finalcutpro.tangent.browser.md) | Final Cut Pro Tangent Browser Group |
| [plugins.finalcutpro.tangent.clip](plugins.finalcutpro.tangent.clip.md) | Final Cut Pro Tangent View Group |
-| [plugins.finalcutpro.tangent.commandpost](plugins.finalcutpro.tangent.commandpost.md) | Final Cut Pro CommandPost Actions for Tangent |
+| [plugins.finalcutpro.tangent.color](plugins.finalcutpro.tangent.color.md) | Final Cut Pro Tangent Color Manager. |
+| [plugins.finalcutpro.tangent.commandpost.functions](plugins.finalcutpro.tangent.commandpost.functions.md) | CommandPost Functions for Tangent. |
| [plugins.finalcutpro.tangent.common](plugins.finalcutpro.tangent.common.md) | Common Final Cut Pro functions for Tangent |
| [plugins.finalcutpro.tangent.edit](plugins.finalcutpro.tangent.edit.md) | Final Cut Pro Tangent View Group |
+| [plugins.finalcutpro.tangent.features](plugins.finalcutpro.tangent.features.md) | Final Cut Pro CommandPost Actions for Tangent |
| [plugins.finalcutpro.tangent.generator](plugins.finalcutpro.tangent.generator.md) | Final Cut Pro Generator Inspector for Tangent |
| [plugins.finalcutpro.tangent.info](plugins.finalcutpro.tangent.info.md) | Final Cut Pro Info Inspector for Tangent |
-| [plugins.finalcutpro.tangent.manager](plugins.finalcutpro.tangent.manager.md) | Final Cut Pro Tangent Color Manager. |
-| [plugins.finalcutpro.tangent.modes](plugins.finalcutpro.tangent.modes.md) | Final Cut Pro Modes for Tangent |
+| [plugins.finalcutpro.tangent.manager](plugins.finalcutpro.tangent.manager.md) | Manager for Final Cut Pro's Tangent Support |
| [plugins.finalcutpro.tangent.new](plugins.finalcutpro.tangent.new.md) | Final Cut Pro Tangent View Group |
| [plugins.finalcutpro.tangent.open](plugins.finalcutpro.tangent.open.md) | Final Cut Pro Tangent Open FCPX. |
+| [plugins.finalcutpro.tangent.os](plugins.finalcutpro.tangent.os.md) | macOS Group for the Tangent. |
+| [plugins.finalcutpro.tangent.os.display](plugins.finalcutpro.tangent.os.display.md) | Tangent Display Functions. |
+| [plugins.finalcutpro.tangent.os.pasteboard](plugins.finalcutpro.tangent.os.pasteboard.md) | Pasteboard Tools for Tangent. |
+| [plugins.finalcutpro.tangent.os.sound](plugins.finalcutpro.tangent.os.sound.md) | Tangent Sound Functions. |
+| [plugins.finalcutpro.tangent.os.window](plugins.finalcutpro.tangent.os.window.md) | Window Management Tools for Tangent. |
| [plugins.finalcutpro.tangent.overlay](plugins.finalcutpro.tangent.overlay.md) | Final Cut Pro Tangent Viewer Overlay Group |
| [plugins.finalcutpro.tangent.pasteboard](plugins.finalcutpro.tangent.pasteboard.md) | Final Cut Pro Tangent Pasteboard Group |
| [plugins.finalcutpro.tangent.playback](plugins.finalcutpro.tangent.playback.md) | Final Cut Pro Tangent Playback Group/Management |
@@ -268,6 +271,8 @@
| [plugins.motion.application.manager](plugins.motion.application.manager.md) | Registers Motion with the Core Application Manager. |
| [plugins.motion.feedback.bugreport](plugins.motion.feedback.bugreport.md) | Sends Apple a Bug Report or Feature Request for Motion. |
| [plugins.resolve.application.manager](plugins.resolve.application.manager.md) | Registers Motion with the Core Application Manager. |
+| [plugins.resolve.tangent.emulation ===
](plugins.resolve.tangent.emulation ===
.md) | Emulates a Tangent Element Panel.
|
+| [plugins.resolve.tangent.manager](plugins.resolve.tangent.manager.md) | Manager for DaVinci Resolve's Tangent Support |
| [plugins.skype.application.manager](plugins.skype.application.manager.md) | Registers Skype with the Core Application Manager if installed. |
| [plugins.skype.shortcuts](plugins.skype.shortcuts.md) | Trigger Skype Shortcuts |
| [plugins.systempreferences.application.manager](plugins.systempreferences.application.manager.md) | Registers System Preferences with the Core Application Manager. |
diff --git a/api/plugins/plugins.aftereffects.application.manager.md b/api/plugins/plugins.aftereffects.application.manager.md
new file mode 100644
index 0000000..191c77f
--- /dev/null
+++ b/api/plugins/plugins.aftereffects.application.manager.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.aftereffects.application.manager
+---
+
+Registers After Effects with the Core Application Manager if installed.
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.aftereffects.effects.md b/api/plugins/plugins.aftereffects.effects.md
new file mode 100644
index 0000000..dddf720
--- /dev/null
+++ b/api/plugins/plugins.aftereffects.effects.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.aftereffects.effects
+---
+
+Apply an After Effect effect to selected layer
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.aftereffects.preferences.md b/api/plugins/plugins.aftereffects.preferences.md
new file mode 100644
index 0000000..9626b27
--- /dev/null
+++ b/api/plugins/plugins.aftereffects.preferences.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.aftereffects.preferences
+---
+
+After Effects Preferences Panel
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.aftereffects.shortcuts.md b/api/plugins/plugins.aftereffects.shortcuts.md
new file mode 100644
index 0000000..4bc2d2d
--- /dev/null
+++ b/api/plugins/plugins.aftereffects.shortcuts.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.aftereffects.shortcuts
+---
+
+Trigger After Effects Shortcuts
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.aftereffects.tangent.manager.md b/api/plugins/plugins.aftereffects.tangent.manager.md
new file mode 100644
index 0000000..2e9de44
--- /dev/null
+++ b/api/plugins/plugins.aftereffects.tangent.manager.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.aftereffects.tangent.manager
+---
+
+Manager for After Effects Tangent Support
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.colorfinale.tangent.md b/api/plugins/plugins.colorfinale.tangent.md
deleted file mode 100644
index 18f909d..0000000
--- a/api/plugins/plugins.colorfinale.tangent.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# [docs](index.md) » plugins.colorfinale.tangent
----
-
-This plugin basically just disables CP's Tangent Manager when ColorFinale is running.
-
-## API Overview
-* Variables - Configurable values
- * [colorFinaleActive](#colorfinaleactive)
- * [colorFinaleInstalled](#colorfinaleinstalled)
- * [colorFinaleVisible](#colorfinalevisible)
- * [colorFinaleWindowUI](#colorfinalewindowui)
-* Functions - API calls offered directly by the extension
- * [init](#init)
-
-## API Documentation
-
-### Variables
-
-#### [colorFinaleActive](#colorfinaleactive)
-| **Signature** | `plugins.colorfinale.tangent.colorFinaleActive ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Checks to see if ColorFinale is active. |
-
-#### [colorFinaleInstalled](#colorfinaleinstalled)
-| **Signature** | `plugins.colorfinale.tangent.colorFinaleInstalled ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Checks to see if ColorFinale is installed. This prop is cached to improve performance. |
-
-#### [colorFinaleVisible](#colorfinalevisible)
-| **Signature** | `plugins.colorfinale.tangent.colorFinaleVisible ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Checks to see if an object is a Color Finale window. |
-
-#### [colorFinaleWindowUI](#colorfinalewindowui)
-| **Signature** | `plugins.colorfinale.tangent.colorFinaleWindowUI ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Returns the `axuielement` for the ColorFinale window, if present. |
-
-### Functions
-
-#### [init](#init)
-| **Signature** | `plugins.colorfinale.tangent.init(tangentManager) -> module` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Initialise the module. |
-| **Parameters** | - tangentManager - The Tangent Manager
|
-| **Returns** | - The ColorFinale Tangent Module.
|
-
diff --git a/api/plugins/plugins.core.action.handler.md b/api/plugins/plugins.core.action.handler.md
index c048fea..e3474d5 100644
--- a/api/plugins/plugins.core.action.handler.md
+++ b/api/plugins/plugins.core.action.handler.md
@@ -26,6 +26,7 @@ containing the details of the action to execute if the choice is selected.
* [execute](#execute)
* [group](#group)
* [id](#id)
+ * [label](#label)
* [onActionId](#onactionid)
* [onChoices](#onchoices)
* [onExecute](#onexecute)
@@ -40,7 +41,7 @@ containing the details of the action to execute if the choice is selected.
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constructor |
| **Description** | Creates a new handler with the specified ID. |
-| **Parameters** | id - The unique ID of the action handler.group - The group the handler belongs to.
|
+| **Parameters** | id - The unique ID of the action handler.group - The group the handler belongs to.label - An optional label for the handler (over-riding a supplied i18n value)
|
| **Returns** | - The new action handler instance.
|
### Fields
@@ -89,6 +90,14 @@ containing the details of the action to execute if the choice is selected.
| **Parameters** | |
| **Returns** | |
+#### [label](#label)
+| **Signature** | `plugins.core.action.handler:label() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the label for this handler. |
+| **Parameters** | |
+| **Returns** | |
+
#### [onActionId](#onactionid)
| **Signature** | `plugins.core.action.handler:onActionId(actionFn) -> handler` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/plugins/plugins.core.action.manager.md b/api/plugins/plugins.core.action.manager.md
index 81bf2ad..4b6565f 100644
--- a/api/plugins/plugins.core.action.manager.md
+++ b/api/plugins/plugins.core.action.manager.md
@@ -37,7 +37,7 @@ Action Manager Module.
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Adds a new action handler with the specified unique ID and returns it for further configuration. |
-| **Parameters** | |
+| **Parameters** | id - The unique IDgroup - The group the handler belongs to.label - An optional label for the handler (over-riding a supplied i18n value)
|
| **Returns** | |
#### [getActivator](#getactivator)
@@ -45,7 +45,7 @@ Action Manager Module.
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns an activator with the specified ID. If it doesn't exist, it will be created. |
-| **Parameters** | activatorId - The unique ID of the activator.
|
+| **Parameters** | activatorId - The unique ID of the activator.
|
| **Returns** | - The activator with the specified ID.
|
#### [getHandler](#gethandler)
@@ -53,7 +53,7 @@ Action Manager Module.
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Returns an existing handler with the specified ID. |
-| **Parameters** | id - The unique ID of the action handler.
|
+| **Parameters** | id - The unique ID of the action handler.
|
| **Returns** | - The action handler, or
nil
|
#### [getURL](#geturl)
diff --git a/api/plugins/plugins.core.loupedeckctandlive.manager.md b/api/plugins/plugins.core.loupedeckctandlive.manager.md
new file mode 100644
index 0000000..efd051f
--- /dev/null
+++ b/api/plugins/plugins.core.loupedeckctandlive.manager.md
@@ -0,0 +1,79 @@
+# [docs](index.md) » plugins.core.loupedeckctandlive.manager
+---
+
+Loupedeck CT & Loupedeck Live Manager Plugin.
+
+## 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
+ * [callback](#callback)
+ * [clearCache](#clearcache)
+ * [getFlashDrivePath](#getflashdrivepath)
+ * [refresh](#refresh)
+ * [refreshItems](#refreshitems)
+ * [reset](#reset)
+
+## API Documentation
+
+### Constructors
+
+#### [new](#new)
+| **Signature** | `plugins.core.loupedeckctandlive.manager.new() -> Loupedeck` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new Loupedeck object. |
+| **Parameters** | - deviceType - The device type defined in
hs.loupedeck.deviceTypes
|
+| **Returns** | |
+| **Notes** | - The deviceType should be either
hs.loupedeck.deviceTypes.LIVE or hs.loupedeck.deviceTypes.CT.
|
+
+### Methods
+
+#### [callback](#callback)
+| **Signature** | `plugins.core.loupedeckctandlive.manager:callback(data) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | The Loupedeck callback. |
+| **Parameters** | - data - The callback data.
|
+| **Returns** | |
+
+#### [clearCache](#clearcache)
+| **Signature** | `plugins.core.loupedeckctandlive.manager:clearCache() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Clears the cache. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [getFlashDrivePath](#getflashdrivepath)
+| **Signature** | `plugins.core.loupedeckctandlive.manager:getFlashDrivePath() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the Loupedeck Flash Drive path. |
+| **Parameters** | |
+| **Returns** | - The Loupedeck Flash Drive path as a string
|
+
+#### [refresh](#refresh)
+| **Signature** | `plugins.core.loupedeckctandlive.manager:refresh()` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Refreshes the Loupedeck screens and LED buttons. |
+| **Parameters** | - dueToAppChange - A optional boolean to specify whether the refresh is due to an application focus change.
|
+| **Returns** | |
+
+#### [refreshItems](#refreshitems)
+| **Signature** | `plugins.core.loupedeckctandlive.manager:refreshItems() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Refreshes the items to either either local drive or the Loupedeck Flash Drive. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [reset](#reset)
+| **Signature** | `plugins.core.loupedeckctandlive.manager:reset()` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Resets the config back to the default layout. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/plugins/plugins.core.loupedeckctandlive.prefs.md b/api/plugins/plugins.core.loupedeckctandlive.prefs.md
new file mode 100644
index 0000000..5f9e2ff
--- /dev/null
+++ b/api/plugins/plugins.core.loupedeckctandlive.prefs.md
@@ -0,0 +1,99 @@
+# [docs](index.md) » plugins.core.loupedeckctandlive.prefs
+---
+
+Loupedeck CT & Loupedeck Live Preferences Panels
+
+## API Overview
+* Variables - Configurable values
+ * [defaultIconPath](#defaulticonpath)
+ * [supportedExtensions](#supportedextensions)
+* Functions - API calls offered directly by the extension
+ * [updateUI](#updateui)
+* 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
+ * [generateContent](#generatecontent)
+ * [generateKnobImages](#generateknobimages)
+ * [panelCallback](#panelcallback)
+ * [renderPanel](#renderpanel)
+ * [setItem](#setitem)
+
+## API Documentation
+
+### Variables
+
+#### [defaultIconPath](#defaulticonpath)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs.defaultIconPath -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Variable |
+| **Description** | Default Path where built-in icons are stored |
+
+#### [supportedExtensions](#supportedextensions)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs.supportedExtensions -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Variable |
+| **Description** | Table of supported extensions for Icons. |
+
+### Functions
+
+#### [updateUI](#updateui)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs:updateUI([params]) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Update the Preferences Panel UI. |
+| **Parameters** | - params - A optional table of parameters
|
+| **Returns** | |
+
+### Constructors
+
+#### [new](#new)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs.new() -> Loupedeck` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new Loupedeck Preferences panel. |
+| **Parameters** | - deviceType - The device type defined in
hs.loupedeck.deviceTypes
|
+| **Returns** | |
+| **Notes** | - The deviceType should be either
hs.loupedeck.deviceTypes.LIVE or hs.loupedeck.deviceTypes.CT.
|
+
+### Methods
+
+#### [generateContent](#generatecontent)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs:generateContent() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Generates the Preference Panel HTML Content. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [generateKnobImages](#generateknobimages)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs:generateKnobImages(app, bank, id) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Generates a combined image for all the knobs. |
+| **Parameters** | - app - The application bundle ID
- bank - The bank as a string
- id - The ID
|
+| **Returns** | |
+
+#### [panelCallback](#panelcallback)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs:panelCallback() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | JavaScript Callback for the Preferences Panel |
+| **Parameters** | - id - ID as string
- params - Table of paramaters
|
+| **Returns** | |
+
+#### [renderPanel](#renderpanel)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs:renderPanel(context) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Generates the Preference Panel HTML Content. |
+| **Parameters** | - context - Table of data that you want to share with the renderer
|
+| **Returns** | |
+
+#### [setItem](#setitem)
+| **Signature** | `plugins.core.loupedeckctandlive.prefs:setItem(app, bank, controlType, id, valueA, valueB) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Update the Loupedeck CT layout file. |
+| **Parameters** | - app - The application bundle ID as a string
- bank - The bank ID as a string
- controlType - The control type as a string
- id - The ID of the item as a string
- valueA - The value of the item as a string
- valueB - An optional value
|
+| **Returns** | |
+
diff --git a/api/plugins/plugins.core.tangent.commandpost.favourites.md b/api/plugins/plugins.core.tangent.commandpost.favourites.md
deleted file mode 100644
index fd99a55..0000000
--- a/api/plugins/plugins.core.tangent.commandpost.favourites.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# [docs](index.md) » plugins.core.tangent.commandpost.favourites
----
-
-Tangent Favourites.
-
-## API Overview
-* Functions - API calls offered directly by the extension
- * [clearAction](#clearaction)
- * [favourites](#favourites)
- * [init](#init)
- * [saveAction](#saveaction)
- * [updateControls](#updatecontrols)
-
-## API Documentation
-
-### Functions
-
-#### [clearAction](#clearaction)
-| **Signature** | `plugins.core.tangent.commandpost.favourites.clearAction(buttonID) -> none` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Clears an Action from Favourites. |
-| **Parameters** | - buttonID - The button ID you want to clear.
|
-| **Returns** | |
-
-#### [favourites](#favourites)
-| **Signature** | `plugins.core.tangent.commandpost.favourites.favourites() -> table` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Gets a table of favourites from file. |
-| **Parameters** | |
-| **Returns** | |
-
-#### [init](#init)
-| **Signature** | `plugins.core.tangent.commandpost.favourites.init() -> none` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Initialise Module. |
-| **Parameters** | - tangentManager - Tangent Manager Plugin
- actionManager - Action Manager Plugin
- cpGroup - CommandPost Group
|
-| **Returns** | |
-
-#### [saveAction](#saveaction)
-| **Signature** | `plugins.core.tangent.commandpost.favourites.saveAction(buttonID, actionTitle, handlerID, action) -> none` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Saves an action to Favourites. |
-| **Parameters** | - buttonID - The button ID as number.
- actionTitle - The action title as string.
- handlerID - The handler ID as string.
- action - The action table.
|
-| **Returns** | |
-
-#### [updateControls](#updatecontrols)
-| **Signature** | `plugins.core.tangent.commandpost.favourites.updateControls() -> none` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Update Controls |
-| **Parameters** | |
-| **Returns** | |
-
diff --git a/api/plugins/plugins.core.tangent.commandpost.md b/api/plugins/plugins.core.tangent.commandpost.md
deleted file mode 100644
index 9b6cfee..0000000
--- a/api/plugins/plugins.core.tangent.commandpost.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# [docs](index.md) » plugins.core.tangent.commandpost
----
-
-CommandPost Group for the Tangent.
-
-## Submodules
- * [plugins.core.tangent.commandpost.favourites](plugins.core.tangent.commandpost.favourites.md)
- * [plugins.core.tangent.commandpost.functions](plugins.core.tangent.commandpost.functions.md)
-
-## API Overview
-
-## API Documentation
-
diff --git a/api/plugins/plugins.core.tangent.manager.connection.md b/api/plugins/plugins.core.tangent.manager.connection.md
new file mode 100644
index 0000000..a8a6bb8
--- /dev/null
+++ b/api/plugins/plugins.core.tangent.manager.connection.md
@@ -0,0 +1,169 @@
+# [docs](index.md) » plugins.core.tangent.manager.connection
+---
+
+Represents a Tangent Connection.
+
+## API Overview
+* Variables - Configurable values
+ * [connections](#connections)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [connection](#connection)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [addMode](#addmode)
+ * [applicationName](#applicationname)
+ * [device](#device)
+ * [displayName](#displayname)
+ * [getControlsXML](#getcontrolsxml)
+ * [getMode](#getmode)
+ * [pluginPath](#pluginpath)
+ * [setupTangentConnection](#setuptangentconnection)
+ * [systemPath](#systempath)
+ * [task](#task)
+ * [update](#update)
+ * [updateControls](#updatecontrols)
+ * [updateFavourites](#updatefavourites)
+ * [userPath](#userpath)
+ * [writeControlsXML](#writecontrolsxml)
+
+## API Documentation
+
+### Variables
+
+#### [connections](#connections)
+| **Signature** | `plugins.core.tangent.manager.connections -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Variable |
+| **Description** | A table containing all the Tangent connections. |
+
+### Constructors
+
+#### [connection](#connection)
+| **Signature** | `plugins.core.tangent.manager.connection(bundleID, manager) -> Connection object` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Connection` object. |
+| **Parameters** | - applicationName - The application name as a string. This is what appears in Tangent Mapper.
- displayName - The application display name as a string. This is what appears in CommandPost.
- systemPath - A string containing the absolute path of the directory that contains the Controls and Default Map XML files.
- userPath - An optional string containing the absolute path of the directory that contains the User’s Default Map XML files.
- task - An optional string containing the name of the task associated with the application. This is used to assist with automatic switching of panels when your application gains mouse focus on the GUI. This parameter should only be required if the string passed in appStr does not match the Task name that the OS identifies as your application. Typically, this is only usually required for Plugins which run within a parent Host application. Under these circumstances it is the name of the Host Application’s Task which should be passed.
- pluginPath - A string containing the absolute path of the directory that contains the built-in Default Map XML files.
- addDefaultModes - A boolean which indicates whether or not CommandPost should add any default modes.
- setupFn - Setup function.
- transportFn - Transport function.
- manager - The Tangent Manager module
|
+| **Returns** | |
+
+### Methods
+
+#### [addMode](#addmode)
+| **Signature** | `plugins.core.tangent.manager.connection:addMode(id, name) -> plugins.core.tangent.manager.mode` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Adds a new `mode` with the specified details and returns it. |
+| **Parameters** | - id - The id number of the Mode.
- name - The name of the Mode.
|
+| **Returns** | |
+
+#### [applicationName](#applicationname)
+| **Signature** | `plugins.core.tangent.manager.connection:applicationName() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the application name. |
+| **Parameters** | |
+| **Returns** | - The application name as a string.
|
+
+#### [device](#device)
+| **Signature** | `plugins.core.tangent.manager.connection:device() -> hs.tangent` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the `hs.tangent` object for the connnection. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [displayName](#displayname)
+| **Signature** | `plugins.core.tangent.manager.connection:displayName() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the display name for the connnection. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [getControlsXML](#getcontrolsxml)
+| **Signature** | `plugins.core.tangent.manager.connection:getControlsXML() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the controls XML. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [getMode](#getmode)
+| **Signature** | `plugins.core.tangent.manager.connection:getMode(id) -> plugins.core.tangent.manager.mode` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the `mode` with the specified ID, or `nil`. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [pluginPath](#pluginpath)
+| **Signature** | `plugins.core.tangent.manager.connection:pluginPath() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the plugin path. |
+| **Parameters** | |
+| **Returns** | - The plugin path as a string.
|
+
+#### [setupTangentConnection](#setuptangentconnection)
+| **Signature** | `plugins.core.tangent.manager.connection:setupTangentConnection() -> hs.tangent` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets up a new Tangent Connection. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [systemPath](#systempath)
+| **Signature** | `plugins.core.tangent.manager.connection:systemPath() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the system path. |
+| **Parameters** | |
+| **Returns** | - The system path as a string.
|
+
+#### [task](#task)
+| **Signature** | `plugins.core.tangent.manager.connection:task() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the task. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [update](#update)
+| **Signature** | `plugins.core.tangent.manager.connection:update() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Updates the Tangent GUIs. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [updateControls](#updatecontrols)
+| **Signature** | `plugins.core.tangent.manager.connection:updateControls() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Update Controls. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [updateFavourites](#updatefavourites)
+| **Signature** | `plugins.core.tangent.manager.connection:updateFavourites() -> boolean, string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Updates the Favourites. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [userPath](#userpath)
+| **Signature** | `plugins.core.tangent.manager.connection:userPath() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the user path. |
+| **Parameters** | |
+| **Returns** | - The user path as a string.
|
+
+#### [writeControlsXML](#writecontrolsxml)
+| **Signature** | `plugins.core.tangent.manager.connection:writeControlsXML() -> boolean, string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Writes the Tangent controls.xml File to the User's Application Support folder. |
+| **Parameters** | |
+| **Returns** | true if successfully created otherwise false if an error occurred.- If an error occurs an error message will also be returned as a string.
|
+
diff --git a/api/plugins/plugins.core.tangent.manager.controls.md b/api/plugins/plugins.core.tangent.manager.controls.md
index 0f146de..b82418c 100644
--- a/api/plugins/plugins.core.tangent.manager.controls.md
+++ b/api/plugins/plugins.core.tangent.manager.controls.md
@@ -18,6 +18,7 @@ Represents a Tangent Group
* [parameter](#parameter)
* [parent](#parent)
* [register](#register)
+ * [tangent](#tangent)
* [unregister](#unregister)
* [xml](#xml)
@@ -108,6 +109,14 @@ Represents a Tangent Group
| **Parameters** | - control - The Action/Parameter/Menu to register
|
| **Returns** | |
+#### [tangent](#tangent)
+| **Signature** | `plugins.core.tangent.manager.controls:tangent() -> hs.tangent` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | The `hs.tangent` connection. |
+| **Parameters** | |
+| **Returns** | |
+
#### [unregister](#unregister)
| **Signature** | `plugins.core.tangent.manager.controls:unregister(control) -> self` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/plugins/plugins.core.tangent.manager.group.md b/api/plugins/plugins.core.tangent.manager.group.md
index cc7d8d3..dae74e2 100644
--- a/api/plugins/plugins.core.tangent.manager.group.md
+++ b/api/plugins/plugins.core.tangent.manager.group.md
@@ -23,6 +23,7 @@ Parameters/Actions/Menus by enabling/disabling the containing group.
* [parameter](#parameter)
* [parent](#parent)
* [reset](#reset)
+ * [tangent](#tangent)
* [xml](#xml)
## API Documentation
@@ -40,11 +41,11 @@ Parameters/Actions/Menus by enabling/disabling the containing group.
### Constructors
#### [group](#group)
-| **Signature** | `plugins.core.tangent.manager.group(name[, parent[, localActive]])` |
+| **Signature** | `plugins.core.tangent.manager.group(name, manager, [, parent[, localActive]])` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constructor |
| **Description** | Creates a new `Group` instance. |
-| **Parameters** | - name - The name of the group.
- parent - The parent group.
- localActive - If
true, this group will ignore the parent's active status when determining its own active status. Defaults to false.
|
+| **Parameters** | - name - The name of the group.
- manager - The Tangent Manager.
- parent - The parent group.
- localActive - If
true, this group will ignore the parent's active status when determining its own active status. Defaults to false.
|
### Fields
@@ -135,6 +136,14 @@ Parameters/Actions/Menus by enabling/disabling the containing group.
| **Parameters** | |
| **Returns** | |
+#### [tangent](#tangent)
+| **Signature** | `plugins.core.tangent.manager.group:tangent() -> hs.tangent` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | The `hs.tangent` connection. |
+| **Parameters** | |
+| **Returns** | |
+
#### [xml](#xml)
| **Signature** | `plugins.core.tangent.manager.group:xml() -> cp.web.xml` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
diff --git a/api/plugins/plugins.core.tangent.manager.md b/api/plugins/plugins.core.tangent.manager.md
index 7dda0b7..9048f54 100644
--- a/api/plugins/plugins.core.tangent.manager.md
+++ b/api/plugins/plugins.core.tangent.manager.md
@@ -12,6 +12,7 @@ here: http://www.tangentwave.co.uk/developer-support
## Submodules
* [plugins.core.tangent.manager.action](plugins.core.tangent.manager.action.md)
* [plugins.core.tangent.manager.binding](plugins.core.tangent.manager.binding.md)
+ * [plugins.core.tangent.manager.connection](plugins.core.tangent.manager.connection.md)
* [plugins.core.tangent.manager.controls](plugins.core.tangent.manager.controls.md)
* [plugins.core.tangent.manager.group](plugins.core.tangent.manager.group.md)
* [plugins.core.tangent.manager.menu](plugins.core.tangent.manager.menu.md)
@@ -21,82 +22,59 @@ here: http://www.tangentwave.co.uk/developer-support
## API Overview
* Constants - Useful values which cannot be changed
- * [activeMode](#activemode)
- * [FCP_KEYPRESS_APPS_PATH](#fcp_keypress_apps_path)
- * [HIDE_FILE_PATH](#hide_file_path)
- * [LAUNCH_AGENT_PATH](#launch_agent_path)
- * [TANGENT_MAPPER_BUNDLE_ID](#tangent_mapper_bundle_id)
+ * [APPLICATION_NAME_SUFFIX](#application_name_suffix)
+ * [MAXIMUM_CONNECTIONS](#maximum_connections)
+ * [NUMBER_OF_FAVOURITES](#number_of_favourites)
+ * [USER_CONTROL_MAPS_FOLDER](#user_control_maps_folder)
* Variables - Configurable values
- * [connectable](#connectable)
- * [connected](#connected)
+ * [customApplications](#customapplications)
* [enabled](#enabled)
- * [interrupted](#interrupted)
- * [requiresConnection](#requiresconnection)
- * [requiresDisconnection](#requiresdisconnection)
* [tangentHubInstalled](#tangenthubinstalled)
* [tangentMapperInstalled](#tangentmapperinstalled)
- * [tangentMapperRunning](#tangentmapperrunning)
* Functions - API calls offered directly by the extension
- * [addMode](#addmode)
- * [areMappingsInstalled](#aremappingsinstalled)
- * [disableFinalCutProInTangentHub](#disablefinalcutprointangenthub)
- * [getControlsXML](#getcontrolsxml)
- * [getMode](#getmode)
- * [interruptWhen](#interruptwhen)
+ * [applicationNames](#applicationnames)
+ * [getConnection](#getconnection)
* [launchTangentMapper](#launchtangentmapper)
- * [update](#update)
- * [updateControls](#updatecontrols)
- * [writeControlsXML](#writecontrolsxml)
-* Fields - Variables which can only be accessed from an object returned by a constructor
- * [activeModeID](#activemodeid)
+ * [newConnection](#newconnection)
+ * [registerCustomApplication](#registercustomapplication)
+ * [removeCustomApplication](#removecustomapplication)
+ * [setupCustomApplications](#setupcustomapplications)
## API Documentation
### Constants
-#### [activeMode](#activemode)
-| **Signature** | `plugins.core.tangent.manager.activeMode ` |
+#### [APPLICATION_NAME_SUFFIX](#application_name_suffix)
+| **Signature** | `plugins.core.tangent.manager.APPLICATION_NAME_SUFFIX -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constant |
-| **Description** | Represents the currently active `mode`. |
+| **Description** | A suffix applied to the end of Application Names as they appear in Tangent Mapper |
-#### [FCP_KEYPRESS_APPS_PATH](#fcp_keypress_apps_path)
-| **Signature** | `plugins.core.tangent.manager.FCP_KEYPRESS_APPS_PATH -> string` |
+#### [MAXIMUM_CONNECTIONS](#maximum_connections)
+| **Signature** | `plugins.core.tangent.manager.MAXIMUM_CONNECTIONS -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constant |
-| **Description** | Final Cut Pro Keypress Apps Path for Tangent Mapper. |
+| **Description** | Maximum number of socket connections to Tangent Hub. |
-#### [HIDE_FILE_PATH](#hide_file_path)
-| **Signature** | `plugins.core.tangent.manager.HIDE_FILE_PATH -> string` |
+#### [NUMBER_OF_FAVOURITES](#number_of_favourites)
+| **Signature** | `plugins.core.tangent.manager.NUMBER_OF_FAVOURITES -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constant |
-| **Description** | Tangent Mapper Hide File Path. |
+| **Description** | Maximum number of favourites. |
-#### [LAUNCH_AGENT_PATH](#launch_agent_path)
-| **Signature** | `plugins.core.tangent.manager.LAUNCH_AGENT_PATH -> string` |
+#### [USER_CONTROL_MAPS_FOLDER](#user_control_maps_folder)
+| **Signature** | `plugins.core.tangent.manager.USER_CONTROL_MAPS_FOLDER -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Constant |
-| **Description** | Path to Tangent Hub's Launch Agent. |
-
-#### [TANGENT_MAPPER_BUNDLE_ID](#tangent_mapper_bundle_id)
-| **Signature** | `plugins.core.tangent.manager.TANGENT_MAPPER_BUNDLE_ID -> string` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constant |
-| **Description** | Tangent Mapper Bundle ID. |
+| **Description** | The full name for storing User Control Maps |
### Variables
-#### [connectable](#connectable)
-| **Signature** | `plugins.core.tangent.manager.connectable ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Is the Tangent Enabled, Not Interrupted, and the Tangent Hub Installed? |
-
-#### [connected](#connected)
-| **Signature** | `plugins.core.tangent.manager.connected ` |
+#### [customApplications](#customapplications)
+| **Signature** | `plugins.core.tangent.manager.customApplications ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Variable |
-| **Description** | A `cp.prop` that tracks the connection status to the Tangent Hub. |
+| **Description** | Table of Custom Applications |
#### [enabled](#enabled)
| **Signature** | `plugins.core.tangent.manager.enabled ` |
@@ -104,24 +82,6 @@ here: http://www.tangentwave.co.uk/developer-support
| **Type** | Variable |
| **Description** | Enable or disables the Tangent Manager. |
-#### [interrupted](#interrupted)
-| **Signature** | `plugins.core.tangent.manager.interrupted ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | If this property is `true` it will temporarily interrupt the Tangent connection, if it is enabled. |
-
-#### [requiresConnection](#requiresconnection)
-| **Signature** | `plugins.core.tangent.manager.requiresConnection ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Is `true` when the Tangent Manager is both `enabled` but not `connected`. |
-
-#### [requiresDisconnection](#requiresdisconnection)
-| **Signature** | `plugins.core.tangent.manager.requiresDisconnection ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Is `true` when the Tangent Manager is both not `enabled` but is `connected`. |
-
#### [tangentHubInstalled](#tangenthubinstalled)
| **Signature** | `plugins.core.tangent.manager.tangentHubInstalled ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -134,61 +94,23 @@ here: http://www.tangentwave.co.uk/developer-support
| **Type** | Variable |
| **Description** | Is Tangent Mapper Installed? |
-#### [tangentMapperRunning](#tangentmapperrunning)
-| **Signature** | `plugins.core.tangent.manager.tangentMapperRunning ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Variable |
-| **Description** | Is Tangent Mapper Running? |
-
### Functions
-#### [addMode](#addmode)
-| **Signature** | `plugins.core.tangent.manager.addMode(id, name) -> plugins.core.tangent.manager.mode` |
+#### [applicationNames](#applicationnames)
+| **Signature** | `plugins.core.tangent.manager.applicationNames() -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | Adds a new `mode` with the specified details and returns it. |
-| **Parameters** | - id - The id number of the Mode.
- name - The name of the Mode.
|
-| **Returns** | |
-
-#### [areMappingsInstalled](#aremappingsinstalled)
-| **Signature** | `plugins.core.tangent.manager.areMappingsInstalled() -> boolean` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Are mapping files installed? |
+| **Description** | Gets a table listing all the connections application names. |
| **Parameters** | |
-| **Returns** | true if mapping files are installed otherwise false
|
+| **Returns** | - A table containing the names of all the registered connections.
|
-#### [disableFinalCutProInTangentHub](#disablefinalcutprointangenthub)
-| **Signature** | `plugins.core.tangent.manager.disableFinalCutProInTangentHub() -> none` |
+#### [getConnection](#getconnection)
+| **Signature** | `plugins.core.tangent.manager.getConnection(applicationName) -> connection` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | Disables the Final Cut Pro preset in the Tangent Hub Application. |
-| **Parameters** | |
-| **Returns** | |
-
-#### [getControlsXML](#getcontrolsxml)
-| **Signature** | `plugins.core.tangent.manager.getControlsXML() -> string` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Gets the controls XML. |
-| **Parameters** | |
-| **Returns** | |
-
-#### [getMode](#getmode)
-| **Signature** | `plugins.core.tangent.manager.getMode(id) -> plugins.core.tangent.manager.mode` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the `mode` with the specified ID, or `nil`. |
-| **Parameters** | |
-| **Returns** | |
-
-#### [interruptWhen](#interruptwhen)
-| **Signature** | `plugins.core.tangent.manager.interruptWhen(aProp) -> nil` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Adds a `cp.prop` that will cause an interruption to the Tangent connection when it is `true`. |
-| **Parameters** | - aProp - The
cp.prop that may interrupt the connection.
|
-| **Returns** | |
+| **Description** | Gets a Tangent connection object. |
+| **Parameters** | - applicationName - Your application name as a string
|
+| **Returns** | |
#### [launchTangentMapper](#launchtangentmapper)
| **Signature** | `plugins.core.tangent.manager.launchTangentMapper() -> none` |
@@ -198,35 +120,35 @@ here: http://www.tangentwave.co.uk/developer-support
| **Parameters** | |
| **Returns** | |
-#### [update](#update)
-| **Signature** | `plugins.core.tangent.manager.update() -> none` |
+#### [newConnection](#newconnection)
+| **Signature** | `plugins.core.tangent.manager.newConnection(applicationName, systemPath, userPath, task, pluginPath, addDefaultModes, setupFn, transportFn) -> connection` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | Updates the Tangent GUIs. |
-| **Parameters** | |
-| **Returns** | |
+| **Description** | Creates a new Tangent Connection |
+| **Parameters** | - applicationName - The application name as a string. This is what appears in CommandPost Preferences.
- systemPath - A string containing the absolute path of the directory that contains the Controls and Default Map XML files.
- userPath - An optional string containing the absolute path of the directory that contains the User’s Default Map XML files.
- task - An optional string containing the name of the task associated with the application. This is used to assist with automatic switching of panels when your application gains mouse focus on the GUI. This parameter should only be required if the string passed in appStr does not match the Task name that the OS identifies as your application. Typically, this is only usually required for Plugins which run within a parent Host application. Under these circumstances it is the name of the Host Application’s Task which should be passed.
- pluginPath - A string containing the absolute path of the directory that contains the built-in Default Map XML files.
- addDefaultModes - A boolean which indicates whether or not CommandPost should add any default modes.
- setupFn - Setup function.
- transportFn - Transport function.
|
+| **Returns** | |
-#### [updateControls](#updatecontrols)
-| **Signature** | `plugins.core.tangent.manager.updateControls() -> none` |
+#### [registerCustomApplication](#registercustomapplication)
+| **Signature** | `plugins.core.tangent.manager.registerCustomApplication(applicationName, bundleExecutable) -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | Update Controls. |
-| **Parameters** | |
-| **Returns** | |
+| **Description** | Registers a new Custom Application |
+| **Parameters** | - applicationName - The display name of the custom application
- bundleExecutable - The bundle executable identifier of the custom application
|
+| **Returns** | - A table where the application name is the key, and display name is the value.
|
-#### [writeControlsXML](#writecontrolsxml)
-| **Signature** | `plugins.core.tangent.manager.writeControlsXML() -> boolean, string` |
+#### [removeCustomApplication](#removecustomapplication)
+| **Signature** | `plugins.core.tangent.manager.removeCustomApplication(applicationName) -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
-| **Description** | Writes the Tangent controls.xml File to the User's Application Support folder. |
-| **Parameters** | |
-| **Returns** | true if successfully created otherwise false if an error occurred.- If an error occurs an error message will also be returned as a string.
|
-
-### Fields
+| **Description** | Removes a Custom Application. |
+| **Parameters** | - applicationName - The display name of the Custom Application to Remove.
|
+| **Returns** | |
-#### [activeModeID](#activemodeid)
-| **Signature** | `plugins.core.tangent.manager.activeModeID ` |
+#### [setupCustomApplications](#setupcustomapplications)
+| **Signature** | `plugins.core.tangent.manager.setupCustomApplications() -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | The current active mode ID. |
+| **Type** | Function |
+| **Description** | Setup the Custom Applications. |
+| **Parameters** | |
+| **Returns** | |
diff --git a/api/plugins/plugins.core.tangent.manager.named.md b/api/plugins/plugins.core.tangent.manager.named.md
index 8e501dd..8210720 100644
--- a/api/plugins/plugins.core.tangent.manager.named.md
+++ b/api/plugins/plugins.core.tangent.manager.named.md
@@ -20,6 +20,7 @@ as described below.
* [name](#name)
* [nameX](#namex)
* [parent](#parent)
+ * [tangent](#tangent)
## API Documentation
@@ -98,3 +99,11 @@ as described below.
| **Parameters** | |
| **Returns** | |
+#### [tangent](#tangent)
+| **Signature** | `plugins.core.tangent.manager.named:tangent() -> hs.tangent` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | The Tangent Hub connection for this value, from the `parent`. |
+| **Parameters** | |
+| **Returns** | - The
hs.tangent, if available.
|
+
diff --git a/api/plugins/plugins.core.tangent.os.md b/api/plugins/plugins.core.tangent.os.md
deleted file mode 100644
index e483d18..0000000
--- a/api/plugins/plugins.core.tangent.os.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# [docs](index.md) » plugins.core.tangent.os
----
-
-macOS Group for the Tangent.
-
-## Submodules
- * [plugins.core.tangent.os.display](plugins.core.tangent.os.display.md)
- * [plugins.core.tangent.os.pasteboard](plugins.core.tangent.os.pasteboard.md)
- * [plugins.core.tangent.os.sound](plugins.core.tangent.os.sound.md)
- * [plugins.core.tangent.os.window](plugins.core.tangent.os.window.md)
-
-## API Overview
-
-## API Documentation
-
diff --git a/api/plugins/plugins.ecammlive.application.manager.md b/api/plugins/plugins.ecammlive.application.manager.md
new file mode 100644
index 0000000..75f30e6
--- /dev/null
+++ b/api/plugins/plugins.ecammlive.application.manager.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.ecammlive.application.manager
+---
+
+Registers Ecamm Live with the Core Application Manager.
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.finalcutpro.tangent.color.md b/api/plugins/plugins.finalcutpro.tangent.color.md
new file mode 100644
index 0000000..9700c0d
--- /dev/null
+++ b/api/plugins/plugins.finalcutpro.tangent.color.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.finalcutpro.tangent.color
+---
+
+Final Cut Pro Tangent Color Manager.
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.core.tangent.commandpost.functions.md b/api/plugins/plugins.finalcutpro.tangent.commandpost.functions.md
similarity index 52%
rename from api/plugins/plugins.core.tangent.commandpost.functions.md
rename to api/plugins/plugins.finalcutpro.tangent.commandpost.functions.md
index c343361..4b52abf 100644
--- a/api/plugins/plugins.core.tangent.commandpost.functions.md
+++ b/api/plugins/plugins.finalcutpro.tangent.commandpost.functions.md
@@ -1,4 +1,4 @@
-# [docs](index.md) » plugins.core.tangent.commandpost.functions
+# [docs](index.md) » plugins.finalcutpro.tangent.commandpost.functions
---
CommandPost Functions for Tangent.
diff --git a/api/plugins/plugins.finalcutpro.tangent.commandpost.md b/api/plugins/plugins.finalcutpro.tangent.features.md
similarity index 59%
rename from api/plugins/plugins.finalcutpro.tangent.commandpost.md
rename to api/plugins/plugins.finalcutpro.tangent.features.md
index 8bcd8aa..fc9251b 100644
--- a/api/plugins/plugins.finalcutpro.tangent.commandpost.md
+++ b/api/plugins/plugins.finalcutpro.tangent.features.md
@@ -1,4 +1,4 @@
-# [docs](index.md) » plugins.finalcutpro.tangent.commandpost
+# [docs](index.md) » plugins.finalcutpro.tangent.features
---
Final Cut Pro CommandPost Actions for Tangent
diff --git a/api/plugins/plugins.finalcutpro.tangent.manager.md b/api/plugins/plugins.finalcutpro.tangent.manager.md
index 9372cdc..747d790 100644
--- a/api/plugins/plugins.finalcutpro.tangent.manager.md
+++ b/api/plugins/plugins.finalcutpro.tangent.manager.md
@@ -1,7 +1,7 @@
# [docs](index.md) » plugins.finalcutpro.tangent.manager
---
-Final Cut Pro Tangent Color Manager.
+Manager for Final Cut Pro's Tangent Support
## API Overview
diff --git a/api/plugins/plugins.finalcutpro.tangent.modes.md b/api/plugins/plugins.finalcutpro.tangent.modes.md
deleted file mode 100644
index 2944a78..0000000
--- a/api/plugins/plugins.finalcutpro.tangent.modes.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# [docs](index.md) » plugins.finalcutpro.tangent.modes
----
-
-Final Cut Pro Modes for Tangent
-
-## API Overview
-
-## API Documentation
-
diff --git a/api/plugins/plugins.core.tangent.os.display.md b/api/plugins/plugins.finalcutpro.tangent.os.display.md
similarity index 78%
rename from api/plugins/plugins.core.tangent.os.display.md
rename to api/plugins/plugins.finalcutpro.tangent.os.display.md
index 5b97afb..fa3b03d 100644
--- a/api/plugins/plugins.core.tangent.os.display.md
+++ b/api/plugins/plugins.finalcutpro.tangent.os.display.md
@@ -1,4 +1,4 @@
-# [docs](index.md) » plugins.core.tangent.os.display
+# [docs](index.md) » plugins.finalcutpro.tangent.os.display
---
Tangent Display Functions.
@@ -12,7 +12,7 @@ Tangent Display Functions.
### Functions
#### [init](#init)
-| **Signature** | `plugins.core.tangent.os.display.init() -> self` |
+| **Signature** | `plugins.finalcutpro.tangent.os.display.init() -> self` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Initialise the module. |
diff --git a/api/plugins/plugins.finalcutpro.tangent.os.md b/api/plugins/plugins.finalcutpro.tangent.os.md
new file mode 100644
index 0000000..37d982a
--- /dev/null
+++ b/api/plugins/plugins.finalcutpro.tangent.os.md
@@ -0,0 +1,15 @@
+# [docs](index.md) » plugins.finalcutpro.tangent.os
+---
+
+macOS Group for the Tangent.
+
+## Submodules
+ * [plugins.finalcutpro.tangent.os.display](plugins.finalcutpro.tangent.os.display.md)
+ * [plugins.finalcutpro.tangent.os.pasteboard](plugins.finalcutpro.tangent.os.pasteboard.md)
+ * [plugins.finalcutpro.tangent.os.sound](plugins.finalcutpro.tangent.os.sound.md)
+ * [plugins.finalcutpro.tangent.os.window](plugins.finalcutpro.tangent.os.window.md)
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.core.tangent.os.pasteboard.md b/api/plugins/plugins.finalcutpro.tangent.os.pasteboard.md
similarity index 53%
rename from api/plugins/plugins.core.tangent.os.pasteboard.md
rename to api/plugins/plugins.finalcutpro.tangent.os.pasteboard.md
index 75ab064..3292663 100644
--- a/api/plugins/plugins.core.tangent.os.pasteboard.md
+++ b/api/plugins/plugins.finalcutpro.tangent.os.pasteboard.md
@@ -1,4 +1,4 @@
-# [docs](index.md) » plugins.core.tangent.os.pasteboard
+# [docs](index.md) » plugins.finalcutpro.tangent.os.pasteboard
---
Pasteboard Tools for Tangent.
diff --git a/api/plugins/plugins.core.tangent.os.sound.md b/api/plugins/plugins.finalcutpro.tangent.os.sound.md
similarity index 75%
rename from api/plugins/plugins.core.tangent.os.sound.md
rename to api/plugins/plugins.finalcutpro.tangent.os.sound.md
index bbe7c7b..88a788e 100644
--- a/api/plugins/plugins.core.tangent.os.sound.md
+++ b/api/plugins/plugins.finalcutpro.tangent.os.sound.md
@@ -1,7 +1,7 @@
-# [docs](index.md) » plugins.core.tangent.os.sound
+# [docs](index.md) » plugins.finalcutpro.tangent.os.sound
---
-Tangent Display Functions.
+Tangent Sound Functions.
## API Overview
* Variables - Configurable values
@@ -15,13 +15,13 @@ Tangent Display Functions.
### Variables
#### [currentOutputDevice](#currentoutputdevice)
-| **Signature** | `plugins.core.tangent.os.sound.currentOutputDevice ` |
+| **Signature** | `plugins.finalcutpro.tangent.os.sound.currentOutputDevice ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Variable |
| **Description** | Current Output Device. |
#### [group](#group)
-| **Signature** | `plugins.core.tangent.os.sound.group ` |
+| **Signature** | `plugins.finalcutpro.tangent.os.sound.group ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Variable |
| **Description** | Tangent Sound Group. |
@@ -29,7 +29,7 @@ Tangent Display Functions.
### Functions
#### [init](#init)
-| **Signature** | `plugins.core.tangent.os.sound.init() -> self` |
+| **Signature** | `plugins.finalcutpro.tangent.os.sound.init() -> self` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Function |
| **Description** | Initialise the module. |
diff --git a/api/plugins/plugins.core.tangent.os.window.md b/api/plugins/plugins.finalcutpro.tangent.os.window.md
similarity index 57%
rename from api/plugins/plugins.core.tangent.os.window.md
rename to api/plugins/plugins.finalcutpro.tangent.os.window.md
index 23a8c71..021a226 100644
--- a/api/plugins/plugins.core.tangent.os.window.md
+++ b/api/plugins/plugins.finalcutpro.tangent.os.window.md
@@ -1,4 +1,4 @@
-# [docs](index.md) » plugins.core.tangent.os.window
+# [docs](index.md) » plugins.finalcutpro.tangent.os.window
---
Window Management Tools for Tangent.
diff --git a/api/plugins/plugins.finalcutpro.text2speech.md b/api/plugins/plugins.finalcutpro.text2speech.md
index 2dcf416..484105f 100644
--- a/api/plugins/plugins.finalcutpro.text2speech.md
+++ b/api/plugins/plugins.finalcutpro.text2speech.md
@@ -7,8 +7,11 @@ Text to Speech Plugin.
* Constants - Useful values which cannot be changed
* [copyToMediaFolder](#copytomediafolder)
* Variables - Configurable values
+ * [addCaption](#addcaption)
+ * [addCustomKeyword](#addcustomkeyword)
+ * [addKeywordForVoiceName](#addkeywordforvoicename)
* [addTextToNotesFieldAfterImport](#addtexttonotesfieldafterimport)
- * [createRoleForVoice](#createroleforvoice)
+ * [assignClipAudioRoleToVoiceName](#assignclipaudioroletovoicename)
* [currentIncrementalNumber](#currentincrementalnumber)
* [customPrefix](#customprefix)
* [deleteFileAfterImport](#deletefileafterimport)
@@ -38,17 +41,35 @@ Text to Speech Plugin.
### Variables
+#### [addCaption](#addcaption)
+| **Signature** | `plugins.finalcutpro.text2speech.addCaption` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Variable |
+| **Description** | Option to Add Text to Notes Field After Importing |
+
+#### [addCustomKeyword](#addcustomkeyword)
+| **Signature** | `plugins.finalcutpro.text2speech.addCustomKeyword` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Variable |
+| **Description** | Boolean that sets whether or not to add a custom keyword. |
+
+#### [addKeywordForVoiceName](#addkeywordforvoicename)
+| **Signature** | `plugins.finalcutpro.text2speech.addKeywordForVoiceName` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Variable |
+| **Description** | Boolean that sets whether or not a tag should be added for the voice. |
+
#### [addTextToNotesFieldAfterImport](#addtexttonotesfieldafterimport)
| **Signature** | `plugins.finalcutpro.text2speech.addTextToNotesFieldAfterImport` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Variable |
| **Description** | Option to Add Text to Notes Field After Importing |
-#### [createRoleForVoice](#createroleforvoice)
-| **Signature** | `plugins.finalcutpro.text2speech.createRoleForVoice` |
+#### [assignClipAudioRoleToVoiceName](#assignclipaudioroletovoicename)
+| **Signature** | `plugins.finalcutpro.text2speech.assignClipAudioRoleToVoiceName` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| **Type** | Variable |
-| **Description** | Boolean that sets whether or not a tag should be added for the voice. |
+| **Description** | Assign Clip Audio Role to Voice Name |
#### [currentIncrementalNumber](#currentincrementalnumber)
| **Signature** | `plugins.finalcutpro.text2speech.currentIncrementalNumber` |
diff --git "a/api/plugins/plugins.resolve.tangent.emulation ===\r.md" "b/api/plugins/plugins.resolve.tangent.emulation ===\r.md"
new file mode 100644
index 0000000..96af8e2
--- /dev/null
+++ "b/api/plugins/plugins.resolve.tangent.emulation ===\r.md"
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.resolve.tangent.emulation ===
+---
+
+Emulates a Tangent Element Panel.
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/plugins/plugins.resolve.tangent.manager.md b/api/plugins/plugins.resolve.tangent.manager.md
new file mode 100644
index 0000000..4f731fa
--- /dev/null
+++ b/api/plugins/plugins.resolve.tangent.manager.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » plugins.resolve.tangent.manager
+---
+
+Manager for DaVinci Resolve's Tangent Support
+
+## API Overview
+
+## API Documentation
+