` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The set of data shared by all phases of the Run. Data from parent Runs will also be available. |
+
+#### [source](#source)
+| **Signature** | `cp.spec.Run.source` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The object that initiated the run. Typically a [Definition](cp.spec.Definition.md). |
+
+### Methods
+
+#### [debug](#debug)
+| **Signature** | `cp.spec.Run:debug() -> cp.spec.Run` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Enables debugging on this `Run`. Any calls to [#log] will be output to the console. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [expectAbort](#expectabort)
+| **Signature** | `cp.spec.Run:expectAbort([messagePattern]) -> Run` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Indicates that this spec is expecting an abort/`error` to occur. |
+| **Parameters** | - messagePattern - The pattern to check the fail message against. If not provided, any message will match.
|
+| **Returns** | |
+
+#### [expectFail](#expectfail)
+| **Signature** | `cp.spec.Run:expectFail([messagePattern]) -> Run` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Indicates that this spec is expecting an assert/fail to occur. |
+| **Parameters** | - messagePattern - The pattern to check the fail message against. If not provided, any message will match.
|
+| **Returns** | |
+
+#### [isDebugging](#isdebugging)
+| **Signature** | `cp.spec.Run:isDebugging() -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if `debug` has been enabled on this or any parent `Run`. |
+
+#### [isExpectingAbort](#isexpectingabort)
+| **Signature** | `cp.spec.Run:isExpectingAbort() -> boolean, string or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if the run is expecting a abort/error to occur. |
+| **Parameters** | |
+| **Returns** | - boolean -
true, if a fail is expected. - string - the message pattern, if specified.
|
+
+#### [isExpectingFail](#isexpectingfail)
+| **Signature** | `cp.spec.Run:isExpectingFail() -> boolean, string or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if the run is expecting a fail to occur. |
+| **Parameters** | |
+| **Returns** | - boolean -
true, if a fail is expected. - string - the message pattern, if specified.
|
+
+#### [log](#log)
+| **Signature** | `cp.spec.Run:log(message[, ...])` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | When the current [Run](cp.spec.Run.md) is in [debug](#debug) mode, output the message to the console. |
+| **Parameters** | - message - the text message to output.
- ... - optional parameters, to be injected into the message, ala
string.format.
|
+
+#### [onBefore](#onbefore)
+| **Signature** | `cp.spec.Run:onBefore(actionFn) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Adds a callback function to run prior to executing the actual test. |
+| **Parameters** | - actionFn - The function to run, passed this
Run.This as the first parameter.
|
+
+#### [onBfter](#onbfter)
+| **Signature** | `cp.spec.Run:onBfter(actionFn) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Adds a callback function to run after to executing the actual test, pass or fail. |
+| **Parameters** | - actionFn - The function to run, passed this
Run as the first parameter.
|
+
+#### [onRunning](#onrunning)
+| **Signature** | `cp.spec.Run:onRunning(actionFn) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Adds a callback function to run during the test. |
+| **Parameters** | - runningFn - The function to run, passed Run.This as the first parameter.
|
+
+#### [parent](#parent)
+| **Signature** | `cp.spec.Run:parent([parent]) -> cp.spec.Run` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets and/or sets the parent `Run` for this run. |
+| **Parameters** | - parent - (optional) If set, will set the parent
Run.
|
+| **Returns** | |
+| **Notes** | - If a
parent is provided and there is already another Run set as a parent, an error is thrown.
|
+
+#### [verbose](#verbose)
+| **Signature** | `cp.spec.Run:verbose([isVerbose]) -> boolean | self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Either sets the `verbose` value and returns itself for further chaining, or returns |
+| **Parameters** | - isVerbose - (optional) if
true or false will update the verbose status and return this Run.
|
+| **Returns** | - The current
verbose status, or this Run if isVerbose is provided.
|
+
diff --git a/api/cp/cp.spec.Scenario.md b/api/cp/cp.spec.Scenario.md
new file mode 100644
index 0000000..5b03722
--- /dev/null
+++ b/api/cp/cp.spec.Scenario.md
@@ -0,0 +1,116 @@
+# [docs](index.md) » cp.spec.Scenario
+---
+
+A [Definition](cp.spec.Definition.md) which describes a specific scenario.
+
+A `Scenario` is most typically created via the [it](cp.spec.md#it) function, like so:
+
+```lua
+local spec = require "cp.spec"
+local describe, it = spec.describe, spec.it
+
+local Rainbow = require "my.rainbow"
+
+return describe "a rainbow" {
+ it "has seven colors"
+ :doing(function()
+ local rainbow = Rainbow()
+ assert(#rainbow:colors() == 7, "the rainbow has seven colors")
+ end)
+}
+```
+
+Scenarios can be run asynchronously via the [Run.This](cp.spec.Run.This.md) instance passed to the `doing` function.
+To indicate a scenario is asynchronous, call [`this:wait()`](cp.spec.Run.This.md#wait), then call
+[`this:done()`](cp.spec.Run.This.md#done), to indicate it has completed. Any `assert` call which fails will
+result in the run failing, and stop at that point.
+
+For example:
+
+```lua
+return describe "a rainbow" {
+ it "has a pot of gold at the end"
+ :doing(function(this)
+ this:wait()
+ local rainbow = Rainbow()
+ rainbow:goToEnd(function(whatIsThere)
+ assert(whatIsThere:isInstanceOf(PotOfGold))
+ this:done()
+ end)
+ end)
+}
+```
+
+Definitions can also be data-driven, via the [where](#where) method:
+
+```lua
+return describe "a rainbow" {
+ it "has ${color} at index ${index}"
+ :doing(function(this)
+ local rainbow = Rainbow()
+ assert(rainbow[this.index] == this.color)
+ end)
+ :where {
+ { "index", "color" },
+ { 1, "red" },
+ { 2, "orange" },
+ { 3, "yellow" },
+ { 4, "blue" },
+ { 5, "green" },
+ { 6, "indigo" },
+ { 7, "violet" },
+ },
+}
+```
+
+This will do a run for each variation and interpolate the value into the run name for each.
+
+**Note:** "where" parameters will not override built-in functions and fields in the [this](cp.spec.Run.This.md)
+instance (such as "async" or "done") so ensure that you pick names that don't clash.
+
+## API Overview
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Scenario](#scenario)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [doing](#doing)
+ * [run](#run)
+ * [where](#where)
+
+## API Documentation
+
+### Constructors
+
+#### [Scenario](#scenario)
+| **Signature** | `cp.spec.Scenario(name[, testFn]) -> cp.spec.Scenario` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Scenario` with the specified name. |
+| **Parameters** | - name - The name of the scenario.
- testFn - (optional) The
function which performs the test for in the scenario.
|
+| **Returns** | |
+| **Notes** | - If the
testFn is not provided here, it must be done via the doing method prior to running, an error will occur.
|
+
+### Methods
+
+#### [doing](#doing)
+| **Signature** | `cp.spec.Scenario:doing(actionFn) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Specifies the `function` for the definition. |
+| **Parameters** | - testFn - The function that will do the test.
|
+| **Returns** | |
+
+#### [run](#run)
+| **Signature** | `cp.spec.Scenario:run(...) -> cp.spec.Run` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Runs the scenario. |
+| **Parameters** | - ... - The list of filters. The first one will be compared to this scenario to determine it should be run.
|
+
+#### [where](#where)
+| **Signature** | `cp.spec.Scenario:where(data) -> cp.spec.Where` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Specifies a `table` of data that will be iterated through as multiple [Runs](cp.spec.Run.md), one row at a time. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/cp/cp.spec.Specification.md b/api/cp/cp.spec.Specification.md
new file mode 100644
index 0000000..f249eae
--- /dev/null
+++ b/api/cp/cp.spec.Specification.md
@@ -0,0 +1,83 @@
+# [docs](index.md) » cp.spec.Specification
+---
+
+A Specification is a list of [definitions](cp.spec.Definition.md) which
+will be run in sequence, and the results are collated. It is often created via
+the [describe](cp.spec.md#describe) function.
+
+Example usage:
+```
+local spec = require "cp.spec"
+local describe, it = spec.describe, spec.it
+
+return describe "a specification" {
+ it "performs an assertion"
+ :doing(function()
+ assert(true, "should not fail")
+ end),
+}
+```
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [is](#is)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Specification](#specification)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [onAfterEach](#onaftereach)
+ * [onBeforeEach](#onbeforeeach)
+ * [run](#run)
+ * [with](#with)
+
+## API Documentation
+
+### Functions
+
+#### [is](#is)
+| **Signature** | `cp.spec.Specification.is(instance) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `instance` is an instance of `Specification`. |
+| **Returns** | true if it's a Specification instance.
|
+
+### Constructors
+
+#### [Specification](#specification)
+| **Signature** | `cp.spec.Specification(name) -> cp.spec.Specification` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new test suite. |
+
+### Methods
+
+#### [onAfterEach](#onaftereach)
+| **Signature** | `cp.spec.Specification:onAfterEach(afterEachFn) -> cp.spec.Specification` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Specifies a function to execute after each of the contained specifications is run. |
+| **Parameters** | - afterEachFn - The function to run after each child runs.
|
+| **Returns** | - The same
cp.spec.Specification instance.
|
+
+#### [onBeforeEach](#onbeforeeach)
+| **Signature** | `cp.spec.Specification:onBeforeEach(beforeEachFn) -> cp.spec.Specification` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Specifies a function to execute before each of the contained specifications is run. |
+| **Parameters** | - beforeEachFn - The function to run before each child runs.
|
+| **Returns** | - The same
cp.spec.Specification instance.
|
+
+#### [run](#run)
+| **Signature** | `cp.spec.Specification:run() -> cp.spec.Run` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Runs the specification, returning the [Run](cp.spec.Run.md) instance, already running. |
+| **Returns** | |
+
+#### [with](#with)
+| **Signature** | `cp.spec.Specification:with(...) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Adds the provided [definitions](cp.spec.Definition.md) to the suite. |
+| **Parameters** | |
+| **Returns** | - The same
Specification instance, with the definitions added.
|
+
diff --git a/api/cp/cp.spec.TestCase.md b/api/cp/cp.spec.TestCase.md
new file mode 100644
index 0000000..3298786
--- /dev/null
+++ b/api/cp/cp.spec.TestCase.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » cp.spec.TestCase
+---
+
+Wraps [cp.test](cp.test.md) into a subclass of [Scenario](cp.spec.Scenario.md).
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/cp/cp.spec.Where.md b/api/cp/cp.spec.Where.md
new file mode 100644
index 0000000..d48fb9f
--- /dev/null
+++ b/api/cp/cp.spec.Where.md
@@ -0,0 +1,11 @@
+# [docs](index.md) » cp.spec.Where
+---
+
+Created via [Scenario:where(...)](cp.spec.Scenario.md#where).
+
+Extends [Definition](cp.spec.Definition.md)
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/cp/cp.spec.expect.md b/api/cp/cp.spec.expect.md
new file mode 100644
index 0000000..455b67a
--- /dev/null
+++ b/api/cp/cp.spec.expect.md
@@ -0,0 +1,18 @@
+# [docs](index.md) » cp.spec.expect
+---
+
+Provides a way of checking values match expected results. At it's core, it uses `assert` to make the check.
+
+For example:
+
+```lua
+expect("Hello World"):is("Hello World")
+expect("Hello World"):isNot("Hello Mars")
+expect(value):isAtLeast(10)
+expect.given("the world is a globe"):that(theEarth):isNot("flat")
+```
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/cp/cp.spec.md b/api/cp/cp.spec.md
new file mode 100644
index 0000000..9233a79
--- /dev/null
+++ b/api/cp/cp.spec.md
@@ -0,0 +1,239 @@
+# [docs](index.md) » cp.spec
+---
+
+An synchronous/asynchronous test library for Lua.
+
+This library uses a syntax similar to Ruby RSpec or Mocha.js.
+
+## Simple Synchronous Test
+
+To create a test, create a new file ending with `_spec.lua`. For example, `simple_spec.lua`:
+
+```lua
+local spec = require "cp.spec"
+local it = spec.it
+
+return it "always passes"
+:doing(function()
+ assert(true, "This always passes")
+end)
+```
+
+It can be run from the Debug Console like so:
+
+```
+cp.spec "simple" ()
+```
+
+It will report something like this:
+
+```
+2019-10-06 18:13:28: [RESULT] it always passes: passed: 1; failed: 0; aborted: 0; time: 0.0022s
+```
+
+## Simple Synchronous Failure
+
+If a test fails, it gives a report of where it failed, and if provided, the related message:
+
+```lua
+local spec = require "cp.spec"
+local it = spec.it
+
+return it "always fails"
+:doing(function()
+ assert(false, "This always fails")
+end)
+```
+
+This will result in something like this:
+
+```
+2019-10-06 21:54:16: [FAIL] it always fails: [.../simple_spec.lua:6] This always fails
+2019-10-06 21:54:16:
+2019-10-06 21:54:16: [RESULT] it always fails: passed: 0; failed: 1; aborted: 0; time: 0.0370s
+```
+
+You can then check the line that failed and resolve the issue.
+
+## Simple Asynchronous Test
+
+Performing an asynchronous test is only a little more complicated.
+We'll modify our `simple_spec.lua` to use of the [Run.This](cp.spec.Run.This.md) instance available to every test:
+
+```lua
+local spec = require "cp.spec"
+local it = spec.it
+local timer = require "hs.timer"
+
+return it "always passes"
+:doing(function(this)
+ this:wait(5)
+ assert(true, "This happens immediately")
+ timer.doAfter(2, function()
+ assert(true, "This happens after 2 seconds.")
+ this:done()
+ end)
+end)
+```
+
+Other than using `hs.timer` to actually make this asynchronous, the key additions here are:
+ * `this:wait(5)`: Tells the test that it is asynchronous, and to wait 5 seconds before timing out.
+ * `this:done()`: Called inside the asynchronous function to indicate that it's complete.
+
+Asycnchronous (and synchronous) tests can also be terminated by a failed `assert`, an `error` or a call to [this:fail(...)](cp.spec.Run.This.md#fail)
+or [this:abort(...)](cp.spec.Run.This.md#abort)
+
+## Multiple tests
+
+Most things you're testing will require more than a single test. For this,
+We use [Specification](cp.spec.Specification.md), most simply via the [describe](#describe) function:
+
+```lua
+local spec = require "cp.spec"
+local describe, it = spec.describe, spec.it
+
+local function sum(a,b)
+ return a + b
+end
+
+return describe "sum" {
+ it "results in 3 when you add 1 and 2"
+ :doing(function()
+ assert(sum(1, 2) == 3)
+ end),
+ it "results in 0 when you add 1 and -1"
+ :doing(function()
+ assert(sum(1, -1) == 0)
+ end),
+}
+```
+
+This will now run two tests, and report something like this:
+
+```
+2019-10-06 21:40:00: [RESULT] sum: passed: 2; failed: 0; aborted: 0; time: 0.0027s
+```
+
+## Data-driven Testing
+
+When testing a feature, there are often multiple variations you want to test,
+and repeating individual tests can get tedious.
+
+This is a great place to use the [where](cp.spec.Scenario.md#where) feature.
+Our previous test can become something like this:
+
+```lua
+return describe "sum" {
+ it "results in ${result} when you add ${a} and ${b}"
+ :doing(function(this)
+ assert(sum(this.a, this.b) == this.result)
+ end)
+ :where {
+ { "a", "b", "result"},
+ { 1, 2, 3 },
+ { 1, -1, 0 },
+ },
+}
+```
+
+Other variations can be added easily by adding more rows.
+
+## Running Multiple Specs
+
+As shown above, you can run a single spec like so:
+
+```lua
+cp.spec "path.to.spec" ()
+```
+
+You can also run that spec an all other specs under the same path by adding `".*"` to the end.
+
+```lua
+cp.spec "path.to.spec.*" ()
+```
+
+Or run every spec in your system like so:
+
+```lua
+cp.spec "*" ()
+```
+
+## Submodules
+ * [cp.spec.DefaultHandler](cp.spec.DefaultHandler.md)
+ * [cp.spec.Definition](cp.spec.Definition.md)
+ * [cp.spec.Error](cp.spec.Error.md)
+ * [cp.spec.Handler](cp.spec.Handler.md)
+ * [cp.spec.Message](cp.spec.Message.md)
+ * [cp.spec.Report](cp.spec.Report.md)
+ * [cp.spec.Run](cp.spec.Run.md)
+ * [cp.spec.Scenario](cp.spec.Scenario.md)
+ * [cp.spec.Specification](cp.spec.Specification.md)
+ * [cp.spec.TestCase](cp.spec.TestCase.md)
+ * [cp.spec.Where](cp.spec.Where.md)
+ * [cp.spec.expect](cp.spec.expect.md)
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [describe](#describe)
+ * [find](#find)
+ * [is](#is)
+ * [it](#it)
+ * [setSearchPath](#setsearchpath)
+ * [spec](#spec)
+ * [test](#test)
+
+## API Documentation
+
+### Functions
+
+#### [describe](#describe)
+| **Signature** | `cp.spec.describe(name) -> function(definitions) -> cp.spec.Specification` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns a `function` which will accept a list of test [definitions](cp.spec.Definition.md), |
+| **Parameters** | - name - The name of the test suite.
|
+| **Returns** | |
+
+#### [find](#find)
+| **Signature** | `cp.spec.find(idPattern) -> cp.spec.Definition` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Attempts to find specs that match the provided ID pattern. |
+
+#### [is](#is)
+| **Signature** | `cp.spec.Handled.is(other) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `other` is an instance of the `Handled` class. |
+
+#### [it](#it)
+| **Signature** | `cp.spec.it(name[, ...]) -> cp.spec.Scenario` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns an [Scenario](cp.spec.Scenario.md) with the specified name and optional `doingFn` function. |
+| **Parameters** | - name - The name of the scenario.
- doingFn - (optional) The
function to call when doing the operation. Will be passed the Run.This instance for the definition.
|
+| **Notes** | - See doing for more details regarding the function.
|
+
+#### [setSearchPath](#setsearchpath)
+| **Signature** | `cp.spec.setSearchPath(path)` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Sets the path that will be used to search for `spec` files with the `spec "my.extension"` call. |
+| **Parameters** | - path - The path to search for
spec files. Set to nil to only search the default package path.
|
+
+#### [spec](#spec)
+| **Signature** | `cp.spec(id) -> cp.spec.Definition` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | This will search the package path (and [specPath](#setSpecPath), if set) for `_spec.lua` files. |
+| **Parameters** | - id - the path ID for the spec. Eg. "cp.app"
|
+| **Returns** | |
+
+#### [test](#test)
+| **Signature** | `cp.spec.test(id) -> cp.spec.Definition` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Attempts to load a [cp.test](cp.test.md) with the specified ID, converting |
+| **Parameters** | - id - The
cp.test ID (eg. "cp.app").
|
+| **Returns** | - The
Definition or throws an error if it can't be found.
|
+
diff --git a/api/cp/cp.strings.md b/api/cp/cp.strings.md
index 718b7ab..13aa68f 100644
--- a/api/cp/cp.strings.md
+++ b/api/cp/cp.strings.md
@@ -18,9 +18,10 @@ Note: This will load the file on each request. To have values cached, use the `c
* 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
+ * [context](#context)
* [find](#find)
* [findInSources](#findinsources)
- * [findKeysIn](#findkeysin)
+ * [findKeys](#findkeys)
* [findKeysInSources](#findkeysinsources)
* [from](#from)
* [fromPlist](#fromplist)
@@ -30,60 +31,68 @@ Note: This will load the file on each request. To have values cached, use the `c
### Constructors
#### [new](#new)
-| **Signature** | `cp.strings.new() -> cp.strings` |
+| **Signature** | `cp.strings.new(context) -> cp.strings` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Creates a new `strings` instance. You should add sources with the [from](#from) or [fromPlist](#fromPlist) methods. |
-| **Parameters** | |
-| **Returns** | |
+| **Type** | Constructor |
+| **Description** | Creates a new `strings` instance. You should add sources with the [from](#from) or [fromPlist](#fromPlist) methods. |
+| **Parameters** | - context - The initial context.
|
+| **Returns** | |
### Methods
+#### [context](#context)
+| **Signature** | `cp.strings:context([context]) -> table | self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets or sets a context to be set for the strings. This typically includes a `language`, which |
+| **Parameters** | - context - A table with values which may be used by the source.
|
+| **Returns** | - If a new context is provided, the
cp.string.source is returned, otherwise the current context table is returned.
|
+
#### [find](#find)
-| **Signature** | `cp.strings:find(language, key) -> string | nil` |
+| **Signature** | `cp.strings:find(key[, context[, quiet]) -> string | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Searches for the specified key in the specified language, caching the result when found. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
- `key` - The key to retrieve from the file.
|
-| **Returns** | - The value of the key, or `nil` if not found.
|
+| **Type** | Method |
+| **Description** | Searches for the specified key, caching the result when found. |
+| **Parameters** | key - The key to retrieve from the file.context - Optional table with additional/alternate context.quiet - Optional boolean, defaults to false. If true, no warnings are logged for missing keys.
|
+| **Returns** | - The value of the key, or
nil if not found.
|
#### [findInSources](#findinsources)
-| **Signature** | `cp.strings:findInSources(language, key) -> string | nil` |
+| **Signature** | `cp.strings:findInSources(key[, context[, quiet]]) -> string | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Searches directly in the sources for the specified language/key combination. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
- `key` - The key to retrieve from the file.
|
-| **Returns** | - The value of the key, or `nil` if not found.
|
+| **Type** | Method |
+| **Description** | Searches directly in the sources for the specified key. |
+| **Parameters** | key - The key to retrieve from the file.context - Optional table with additional/alternate context.quiet - Optional boolean, defaults to false. If true, no warnings are logged for missing keys.
|
+| **Returns** | - The value of the key, or
nil if not found.
|
-#### [findKeysIn](#findkeysin)
-| **Signature** | `cp.strings:findKeysIn(language, value) -> string | nil` |
+#### [findKeys](#findkeys)
+| **Signature** | `cp.strings:findKeys(value[, context]) -> string | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Searches for the list of keys with a matching value, in the specified language. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
- `value` - The value to search for.
|
-| **Returns** | - The array of keys, or `{}` if not found.
|
+| **Type** | Method |
+| **Description** | Searches for the list of keys with a matching value, in the specified language. |
+| **Parameters** | value - The value to search for.context - The language code to look for (e.g. "en", or "fr").
|
+| **Returns** | - The array of keys, or
{} if not found.
|
#### [findKeysInSources](#findkeysinsources)
-| **Signature** | `cp.strings:findKeysInSources(language, value) -> string | nil` |
+| **Signature** | `cp.strings:findKeysInSources(value[, context]) -> string | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Searches directly in the sources for the specified language/value combination. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
- `value` - The value to search for.
|
-| **Returns** | - The array of keys, or `{}` if not found.
|
+| **Type** | Method |
+| **Description** | Searches directly in the sources for the specified key value pattern. |
+| **Parameters** | value - The value to search for.context - Optional additional context for the request.
|
+| **Returns** | - The array of keys, or
{} if not found.
|
#### [from](#from)
| **Signature** | `cp.strings:from(source) -> cp.strings` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Adds the source to the strings sources. |
-| **Parameters** | - `source` - The source to add.
|
-| **Returns** | - The current `cp.strings` instance.
|
+| **Type** | Method |
+| **Description** | Adds the source to the strings sources. |
+| **Parameters** | source - The source to add.
|
+| **Returns** | - The current
cp.strings instance.
|
#### [fromPlist](#fromplist)
| **Signature** | `cp.strings:fromPlist(pathPattern) -> cp.strings` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Convenience method for addedn a `plist` source to the strings instance. |
-| **Parameters** | - `pathPattern` - The path to load from. May contain a special `${language}` marker which will be replace with the provided langauge when searching.
|
-| **Returns** | - The current `cp.strings` instance.
|
+| **Type** | Method |
+| **Description** | Convenience method for adding a `plist` source to the strings instance. |
+| **Parameters** | pathPattern - The path to load from. May contain a special ${language} marker which will be replace with the provided langauge when searching.
|
+| **Returns** | - The current
cp.strings instance.
|
diff --git a/api/cp/cp.strings.source.plist.md b/api/cp/cp.strings.source.plist.md
index 398e6e1..ad1ba5c 100644
--- a/api/cp/cp.strings.source.plist.md
+++ b/api/cp/cp.strings.source.plist.md
@@ -17,6 +17,7 @@ Note: This will load the file on each request. To have values cached, use the `c
* 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
+ * [context](#context)
* [find](#find)
* [findKeys](#findkeys)
* [loadFile](#loadfile)
@@ -30,58 +31,66 @@ Note: This will load the file on each request. To have values cached, use the `c
#### [defaultCacheSeconds](#defaultcacheseconds)
| **Signature** | `cp.strings.source.plist.defaultCacheSeconds` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constant |
-| **Description** | The default number of seconds to cache results. |
+| **Type** | Constant |
+| **Description** | The default number of seconds to cache results. |
### Constructors
#### [new](#new)
-| **Signature** | `cp.strings.source.plist.new(language) -> source` |
+| **Signature** | `cp.strings.source.plist.new(pathPattern[, cacheSeconds]) -> source` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Creates a new `cp.strings` source that loads strings from a plist file. |
-| **Parameters** | - `pathPattern` - The path to load from. May contain a special `${language}` marker which will be replace with the provided langauge when searching.
- `cacheSeconds` - (optional) How long in seconds to keep the loaded values cached in memory. Defaults to [defaultCacheSeconds](#defaultCacheSeconds)
|
-| **Returns** | - The new plist `source` instance.
|
+| **Type** | Constructor |
+| **Description** | Creates a new `cp.strings` source that loads strings from a plist file. |
+| **Parameters** | pathPattern - The path to load from. May contain a special ${language} marker which will be replace with the provided langauge when searching.cacheSeconds - (optional) How long in seconds to keep the loaded values cached in memory. Defaults to defaultCacheSeconds
|
+| **Returns** | - The new plist
source instance.
|
### Methods
+#### [context](#context)
+| **Signature** | `cp.strings.source.plist:context([context]) -> table | self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets or sets a context to be set for the source. This typically includes a `language`, which |
+| **Parameters** | - context - A table with values which may be used by the source.
|
+| **Returns** | - If a new context is provided, the
cp.string.source is returned, otherwise the current context table is returned.
|
+
#### [find](#find)
-| **Signature** | `cp.strings.source.plist:find(language, key) -> string` |
+| **Signature** | `cp.strings.source.plist:find(key[, context]) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Finds the specified `key` value in the plist file for the specified `language`, if the plist can be found, and contains matching key value. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
- `key` - The key to retrieve from the file.
|
-| **Returns** | - The value of the key, or `nil` if not found.
|
+| **Type** | Method |
+| **Description** | Finds the specified `key` value in the plist, if the plist can be found, and contains matching key value. |
+| **Parameters** | key - The key to retrieve from the file.context - Optional table with additional/alternate context. It will be added to the current context temporarily.
|
+| **Returns** | - The value of the key, or
nil if not found.
|
#### [findKeys](#findkeys)
-| **Signature** | `cp.strings.source.plist:findKeys(language, value) -> {string}` |
+| **Signature** | `cp.strings.source.plist:findKeys(pattern) -> {string}` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Finds the array of keys with the matching value in the plist file for the specified `language`, if the plist can be found, and contains matching key. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
- `value` - The value.
|
-| **Returns** | - The array of keys, or `{}` if none were fround
|
+| **Type** | Method |
+| **Description** | Finds the array of keys who's value matches the pattern in this table. It will check that the pattern matches the beginning of the value. |
+| **Parameters** | - `pattern - The string pattern to match.
context - An optional additional context for the source.
|
+| **Returns** | - The array of keys, or
{} if none were fround
|
#### [loadFile](#loadfile)
-| **Signature** | `cp.strings.source.plist:loadFile(language) -> string` |
+| **Signature** | `cp.strings.source.plist:loadFile([context]) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Loads the plist file for the specified language, returning the value as a table. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
|
-| **Returns** | - The table for the specified language, or `nil` if the file doesn't exist.
|
+| **Type** | Method |
+| **Description** | Loads the plist file for the specified context, returning the value as a table. |
+| **Parameters** | context - The context to determine the absolute path with. This will be added to any values provided in the default context.
|
+| **Returns** | - The table for the specified language, or
nil if the file doesn't exist.
|
#### [pathToAbsolute](#pathtoabsolute)
-| **Signature** | `cp.strings.source.plist:pathToAbsolute(language) -> string` |
+| **Signature** | `cp.strings.source.plist:pathToAbsolute([context]) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Finds the abolute path to the `plist` represented by this source for the specified langauge, or `nil` if it does not exist. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
|
-| **Returns** | - The path to the file, or `nil` if not found.
|
+| **Type** | Method |
+| **Description** | Finds the abolute path to the `plist` represented by this source for the specified langauge, or `nil` if it does not exist. |
+| **Parameters** | context - The context to determine the absolute path with. This will be added to any values provided in the default context.
|
+| **Returns** | - The path to the file, or
nil if not found.
|
#### [reset](#reset)
| **Signature** | `cp.strings.source.plist:reset() -> cp.strings` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Clears any stored key values. |
+| **Type** | Method |
+| **Description** | Clears any stored key values. |
| **Parameters** | |
-| **Returns** | - The current `cp.strings` instance.
|
+| **Returns** | - The current
cp.strings instance.
|
diff --git a/api/cp/cp.strings.source.table.md b/api/cp/cp.strings.source.table.md
index 83ea751..31d9b4f 100644
--- a/api/cp/cp.strings.source.table.md
+++ b/api/cp/cp.strings.source.table.md
@@ -16,6 +16,8 @@ Note: This will load the file on each request. To have values cached, use the `c
* 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
+ * [add](#add)
+ * [context](#context)
* [find](#find)
## API Documentation
@@ -23,20 +25,36 @@ Note: This will load the file on each request. To have values cached, use the `c
### Constructors
#### [new](#new)
-| **Signature** | `cp.strings.source.table.new(language) -> source` |
+| **Signature** | `cp.strings.source.table.new(context) -> source` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Creates a new `cp.strings` source that loads strings from a plist file. |
-| **Parameters** | - `pathPattern` - The path to load from. May contain a special `${language}` marker which will be replace with the provided langauge when searching.
- `cacheSeconds` - (optional) How long in seconds to keep the loaded values cached in memory. Defaults to [defaultCacheSeconds](#defaultCacheSeconds)
|
-| **Returns** | - The new plist `source` instance.
|
+| **Type** | Constructor |
+| **Description** | Creates a new `cp.strings` source that loads strings from a plist file. |
+| **Parameters** | |
+| **Returns** | - The new plist
source instance.
|
### Methods
+#### [add](#add)
+| **Signature** | `cp.strings.source.table:add(keyValues) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Adds the specified table of key values in the specified language code. |
+| **Parameters** | keyValues - The table of key/value pairs to define.
|
+| **Returns** | |
+
+#### [context](#context)
+| **Signature** | `cp.strings.source.table:context([context]) -> table | self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets or sets a context to be set for the source. This typically includes a `language`, which |
+| **Parameters** | - context - A table with values which may be used by the source.
|
+| **Returns** | - If a new context is provided, the
cp.string.source is returned, otherwise the current context table is returned.
|
+
#### [find](#find)
-| **Signature** | `cp.strings.source.table:find(language) -> string` |
+| **Signature** | `cp.strings.source.table:find(key) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Finds the specified `key` value in the plist file for the specified `language`, if the plist can be found, and contains matching key value. |
-| **Parameters** | - `language` - The language code to look for (e.g. `"en"`, or `"fr"`).
- `key` - The key to retrieve from the file.
|
-| **Returns** | - The value of the key, or `nil` if not found.
|
+| **Type** | Method |
+| **Description** | Finds the specified `key` value in the plist file for the specified optional `context`, |
+| **Parameters** | key - The key to retrieve the value for.context - An optional table with additional context.
|
+| **Returns** | - The value of the key, or
nil if not found.
|
diff --git a/api/cp/cp.test.md b/api/cp/cp.test.md
new file mode 100644
index 0000000..9697f17
--- /dev/null
+++ b/api/cp/cp.test.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » cp.test
+---
+
+CommandPost Test Scripts.
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/cp/cp.text.matcher.md b/api/cp/cp.text.matcher.md
index 17ae955..3943f08 100644
--- a/api/cp/cp.text.matcher.md
+++ b/api/cp/cp.text.matcher.md
@@ -1,7 +1,37 @@
# [docs](index.md) » cp.text.matcher
---
-This module provides support for loading, manipulating, and comparing unicode text data.
+Adapted from 'utf8.lua' (https://github.com/Stepets/utf8.lua)
+
+Copyright (c) 2006-2007, Kyle Smith
+All rights reserved.
+
+Contributors:
+ Alimov Stepan
+ David Peterson
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+ * Neither the name of the author nor the names of its contributors may be
+ used to endorse or promote products derived from this software without
+ specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
## API Overview
* Constructors - API calls which return an object, typically one that offers API methods
@@ -19,43 +49,43 @@ This module provides support for loading, manipulating, and comparing unicode te
#### [matcher](#matcher)
| **Signature** | `cp.text.matcher(pattern[, plain]) -> cp.text.matcher` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Returns a matcher for the specified pattern. This follows the conventions of the standard [LUA Patterns](https://www.lua.org/pil/20.2.html) API. This will return a reusable, compiled parser for the given pattern. |
-| **Parameters** | - `pattern` - The pattern to parse
- `plain` - If `true`, the pattern is not parsed and the provided text must match exactly.
- Returns:
- * New `cp.text.matcher` for the pattern.
|
-| **Returns** | - * New `cp.text.matcher` for the pattern.
|
+| **Type** | Constructor |
+| **Description** | Returns a matcher for the specified pattern. This follows the conventions of the standard [LUA Patterns](https://www.lua.org/pil/20.2.html) API. This will return a reusable, compiled parser for the given pattern. |
+| **Parameters** | pattern - The pattern to parseplain - If true, the pattern is not parsed and the provided text must match exactly.Returns:- New
cp.text.matcher for the pattern.
|
+| **Returns** | - New
cp.text.matcher for the pattern.
|
### Methods
#### [find](#find)
| **Signature** | `cp.text.matcher:find(value[, start]) -> number, number, ...` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Processes the text, returning the start position, the end position, followed by any capture group values. |
-| **Parameters** | - `value` - The `cp.text` value to process.
- `start` - If specified, indicates the starting position to process from. Defaults to `1`.
|
-| **Returns** | - The start position for the match, end position, and the list of capture group values.
|
+| **Type** | Method |
+| **Description** | Processes the text, returning the start position, the end position, followed by any capture group values. |
+| **Parameters** | value - The cp.text value to process.start - If specified, indicates the starting position to process from. Defaults to 1.
|
+| **Returns** | - The start position for the match, end position, and the list of capture group values.
|
#### [gmatch](#gmatch)
| **Signature** | `cp.text.matcher:gmatch(value) -> function` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns an iterator function that, each time it is called, returns the next captures from pattern over string s. If pattern specifies no captures, then the whole match is produced in each call. |
-| **Parameters** | - `value` - The `cp.text` value to process.
|
-| **Returns** | |
+| **Type** | Method |
+| **Description** | Returns an iterator function that, each time it is called, returns the next captures from pattern over string s. If pattern specifies no captures, then the whole match is produced in each call. |
+| **Parameters** | value - The cp.text value to process.
|
+| **Returns** | |
#### [gsub](#gsub)
| **Signature** | `cp.text.matcher:gsub(value, repl, limit) -> text, number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns a copy of `value` in which all (or the first `n`, if given) occurrences of the pattern have been replaced by a replacement string specified by `repl`, which can be text, a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred. |
-| **Parameters** | - `value` - The text or string value to process.
- `repl` - The replacement text/string/table/function
- `limit` - The maximum number of times to do the replacement. Defaults to unlimited.
|
-| **Returns** | - `text` - The text value with replacements.
- `number` - The number of matches that occurred.
|
-| **Notes** | - If repl is text or a string, then its value is used for replacement. The character `%` works as an escape character: any sequence in repl of the form `%n`, with `n` between `1` and `9`, stands for the value of the `n`-th captured substring (see below). The sequence `%0` stands for the whole match. The sequence `%%` stands for a single `%`.
- If `repl` is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.
- If `repl` is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.
- If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is `false` or `nil`, then there is no replacement (that is, the original match is kept in the string).
|
+| **Type** | Method |
+| **Description** | Returns a copy of `value` in which all (or the first `n`, if given) occurrences of the pattern have been replaced by a replacement string specified by `repl`, which can be text, a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred. |
+| **Parameters** | value - The text or string value to process.repl - The replacement text/string/table/functionlimit - The maximum number of times to do the replacement. Defaults to unlimited.
|
+| **Returns** | text - The text value with replacements.number - The number of matches that occurred.
|
+| **Notes** | - If repl is text or a string, then its value is used for replacement. The character
% works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %. - If
repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key. - If
repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument. - If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is
false or nil, then there is no replacement (that is, the original match is kept in the string).
|
#### [match](#match)
| **Signature** | `cp.text.matcher:match(value[, start]) -> ...` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Looks for the first match of the pattern in the string `value`. If it finds one, then match returns the captures from the pattern; otherwise it returns `nil`. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is `1` and can be negative. |
-| **Parameters** | - `value` - The `cp.text` value to process.
- `start` - If specified, indicates the starting position to process from. Defaults to `1`.
|
-| **Returns** | - The capture results, the whole match, or `nil`.
|
+| **Type** | Method |
+| **Description** | Looks for the first match of the pattern in the string `value`. If it finds one, then match returns the captures from the pattern; otherwise it returns `nil`. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is `1` and can be negative. |
+| **Parameters** | value - The cp.text value to process.start - If specified, indicates the starting position to process from. Defaults to 1.
|
+| **Returns** | - The capture results, the whole match, or
nil.
|
diff --git a/api/cp/cp.text.md b/api/cp/cp.text.md
index fb451e5..4448408 100644
--- a/api/cp/cp.text.md
+++ b/api/cp/cp.text.md
@@ -62,90 +62,90 @@ Note that `text` values are not in any specific encoding, since they are stored
#### [encoding](#encoding)
| **Signature** | `cp.text.encoding` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constant |
-| **Description** | The list of supported encoding formats: |
+| **Type** | Constant |
+| **Description** | The list of supported encoding formats: |
### Functions
#### [is](#is)
| **Signature** | `cp.text.is(value) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the provided value is a `text` instance. |
-| **Parameters** | - `value` - The value to check
|
-| **Returns** | - `true` if the value is a `text` instance.
|
+| **Type** | Function |
+| **Description** | Checks if the provided value is a `text` instance. |
+| **Parameters** | value - The value to check
|
+| **Returns** | true if the value is a text instance.
|
### Constructors
#### [char](#char)
| **Signature** | `cp.text.char(...) -> text` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Returns the list of one or more codepoint items into a text value, concatenating the results. |
-| **Parameters** | - `...` - The list of codepoint integers.
|
-| **Returns** | - The `cp.text` value for the list of codepoint values.
|
+| **Type** | Constructor |
+| **Description** | Returns the list of one or more codepoint items into a text value, concatenating the results. |
+| **Parameters** | ... - The list of codepoint integers.
|
+| **Returns** | - The
cp.text value for the list of codepoint values.
|
#### [fromCodepoints](#fromcodepoints)
| **Signature** | `cp.text.fromCodepoints(codepoints[, i[, j]]) -> text` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Returns a new `text` instance representing the specified array of codepoints. Since `i` and `j` default to the first |
-| **Parameters** | - `codepoints` - The array of codepoint integers.
- `i` - The starting index to read from codepoints. Defaults to `1`.
- `j` - The ending index to read from codepoints. Default to `-1`.
|
-| **Returns** | |
-| **Notes** | - You can use a *negative* value for `i` and `j`. If so, it will count back from then end of the `codepoints` array.
- If the codepoint array begins with a Byte-Order Marker (BOM), the BOM is skipped in the resulting text.
|
+| **Type** | Constructor |
+| **Description** | Returns a new `text` instance representing the specified array of codepoints. Since `i` and `j` default to the first |
+| **Parameters** | codepoints - The array of codepoint integers.i - The starting index to read from codepoints. Defaults to 1.j - The ending index to read from codepoints. Default to -1.
|
+| **Returns** | |
+| **Notes** | - You can use a negative value for
i and j. If so, it will count back from then end of the codepoints array. - If the codepoint array begins with a Byte-Order Marker (BOM), the BOM is skipped in the resulting text.
|
#### [fromFile](#fromfile)
| **Signature** | `cp.text.fromFile(path[, encoding]) -> text` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Returns a new `text` instance representing the text loaded from the specified path. If no encoding is specified, |
-| **Parameters** | - `value` - The value to turn into a unicode text instance.
- `encoding` - One of the falues from `text.encoding`: `utf8`, `utf16le`, or `utf16be`. Defaults to `utf8`.
|
-| **Returns** | |
+| **Type** | Constructor |
+| **Description** | Returns a new `text` instance representing the text loaded from the specified path. If no encoding is specified, |
+| **Parameters** | value - The value to turn into a unicode text instance.encoding - One of the falues from text.encoding: utf8, utf16le, or utf16be. Defaults to utf8.
|
+| **Returns** | |
#### [fromString](#fromstring)
| **Signature** | `cp.text.fromString(value[, encoding]) -> text` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Returns a new `text` instance representing the string value of the specified value. If no encoding is specified, |
-| **Parameters** | - `value` - The value to turn into a unicode text instance.
- `encoding` - One of the falues from `text.encoding`: `utf8`, `utf16le`, or `utf16be`. Defaults to `utf8`.
|
-| **Returns** | |
-| **Notes** | - Calling `text(value)` is the same as calling `text.fromString(value, text.encoding.utf8)`, so simple text can be initialized via `local x = text "foo"` when the `.lua` file's encoding is UTF-8.
|
+| **Type** | Constructor |
+| **Description** | Returns a new `text` instance representing the string value of the specified value. If no encoding is specified, |
+| **Parameters** | value - The value to turn into a unicode text instance.encoding - One of the falues from text.encoding: utf8, utf16le, or utf16be. Defaults to utf8.
|
+| **Returns** | |
+| **Notes** | - Calling
text(value) is the same as calling text.fromString(value, text.encoding.utf8), so simple text can be initialized via local x = text "foo" when the .lua file's encoding is UTF-8.
|
### Methods
#### [encode](#encode)
| **Signature** | `cp.text:encode([encoding]) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns the text as an encoded `string` value. |
-| **Parameters** | - `encoding` - The encoding to use when converting. Defaults to `cp.text.encoding.utf8`.
|
+| **Type** | Method |
+| **Description** | Returns the text as an encoded `string` value. |
+| **Parameters** | encoding - The encoding to use when converting. Defaults to cp.text.encoding.utf8.
|
#### [find](#find)
| **Signature** | `cp.text:find(pattern [, init [, plain]])` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Looks for the first match of pattern in the string `value`. If it finds a match, then find returns the indices of `value` where this occurrence starts and ends; otherwise, it returns `nil`. A third, optional numerical argument `init` specifies where to start the search; its default value is `1` and can be negative. A value of `true` as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then `init` must be given as well. |
-| **Returns** | - the start index, the end index, followed by any captures
|
+| **Type** | Method |
+| **Description** | Looks for the first match of pattern in the string `value`. If it finds a match, then find returns the indices of `value` where this occurrence starts and ends; otherwise, it returns `nil`. A third, optional numerical argument `init` specifies where to start the search; its default value is `1` and can be negative. A value of `true` as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then `init` must be given as well. |
+| **Returns** | - the start index, the end index, followed by any captures
|
#### [len](#len)
| **Signature** | `cp.text:len() -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns the number of codepoints in the text. |
+| **Type** | Method |
+| **Description** | Returns the number of codepoints in the text. |
| **Parameters** | |
-| **Returns** | - The number of codepoints.
|
+| **Returns** | - The number of codepoints.
|
#### [match](#match)
| **Signature** | `cp.text:match(pattern[, start]) -> ...` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Looks for the first match of the `pattern` in the text value. If it finds one, then match returns the captures from the pattern; otherwise it returns `nil`. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument `init` specifies where to start the search; its default value is `1` and can be negative. |
-| **Parameters** | - `pattern` - The text pattern to process.
- `start` - If specified, indicates the starting position to process from. Defaults to `1`.
|
-| **Returns** | - The capture results, the whole match, or `nil`.
|
+| **Type** | Method |
+| **Description** | Looks for the first match of the `pattern` in the text value. If it finds one, then match returns the captures from the pattern; otherwise it returns `nil`. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument `init` specifies where to start the search; its default value is `1` and can be negative. |
+| **Parameters** | pattern - The text pattern to process.start - If specified, indicates the starting position to process from. Defaults to 1.
|
+| **Returns** | - The capture results, the whole match, or
nil.
|
#### [sub](#sub)
| **Signature** | `cp.text:sub(i [, j]) -> cp.text` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns the substring of this text that starts at `i` and continues until `j`; `i` and `j` can be negative. |
+| **Type** | Method |
+| **Description** | Returns the substring of this text that starts at `i` and continues until `j`; `i` and `j` can be negative. |
diff --git a/api/cp/cp.time.flicks.md b/api/cp/cp.time.flicks.md
new file mode 100644
index 0000000..ad507d4
--- /dev/null
+++ b/api/cp/cp.time.flicks.md
@@ -0,0 +1,265 @@
+# [docs](index.md) » cp.time.flicks
+---
+
+Provides support for measuring time in `flicks`, a base unit of time useful for
+working with media, such as video or audio files.
+
+From the [Flicks GitHub project]():
+
+
+A flick (frame-tick) is a very small unit of time. It is 1/705600000 of a second, exactly.
+
+`1 flick = 1/705600000 second`
+
+This unit of time is the smallest time unit which is LARGER than a nanosecond, and can in integer quantities exactly
+represent a single frame duration for 24 Hz, 25 Hz, 30 Hz, 48 Hz, 50 Hz, 60 Hz, 90 Hz, 100 Hz, 120 Hz, and
+also 1/1000 divisions of each, as well as a single sample duration for 8 kHz, 16 kHz, 22.05 kHz, 24 kHz, 32 kHz,
+44.1 kHz, 48 kHz, 88.2 kHz, 96 kHz, and 192kHz, as well as the NTSC frame durations for 24 * (1000/1001) Hz,
+30 * (1000/1001) Hz, 60 * (1000/1001) Hz, and 120 * (1000/1001) Hz.
+
+That above was one hell of a run-on sentence, but it's strictly and completely correct in its description of
+the unit.
+
+This makes flicks suitable for use via std::chrono::duration and std::ratio for doing timing work against the
+system high resolution clock, which is in nanoseconds, but doesn't get slightly out of sync when doing
+common frame rates.
+
+We also support some common audio sample rates as well. This list is not exhaustive, but covers the majority
+of digital audio formats. They are 8kHz, 16kHz, 22.05kHz, 24kHz, 32kHz, 44.1kHz, 48kHz, 88.2kHz, 96kHz, and 192kHz.
+
+Though it is not part of the design criteria, 144 Hz, which some newer monitors refresh at, does work
+correctly with flicks.
+
+NTSC IS NOT EXPLICITLY SUPPORTED IN ALL OF ITS SUBTLE NUANCES, BUT: The NTSC variations (~23.976, ~29.97, etc)
+are approximately defined as 24 * 1000/1001 and 30 * 1000/1001, etc. These can be represented exactly in flicks,
+but 1/1000 divisions are not available.
+
+Many folks online have pointed out that NTSC technically has a variable frame rate, and that this is handled
+correctly in other media playback libraries such as QuickTime. The goal of flicks is to provide a simple,
+convenient std::chrono::duration to work with when writing code that works with simulation and time in media,
+but not explicitly to handle complex variable-rate playback scenarios. So we'll stick with the 1000/1001
+approximations, and leave it at that!
+
+# Details
+
+* 24 fps frame: 29400000 flicks
+* 25 fps frame: 28224000 flicks
+* 30 fps frame: 23520000 flicks
+* 48 fps frame: 14700000 flicks
+* 50 fps frame: 14112000 flicks
+* 60 fps frame: 11760000 flicks
+* 90 fps frame: 7840000 flicks
+* 100 fps frame: 7056000 flicks
+* 120 fps frame: 5880000 flicks
+* 8000 fps frame: 88200 flicks
+* 16000 fps frame: 44100 flicks
+* 22050 fps frame: 32000 flicks
+* 24000 fps frame: 29400 flicks
+* 32000 fps frame: 22050 flicks
+* 44100 fps frame: 16000 flicks
+* 48000 fps frame: 14700 flicks
+* 88200 fps frame: 8000 flicks
+* 96000 fps frame: 7350 flicks
+* 192000 fps frame: 3675 flicks
+
+# NTSC:
+
+* 24 * 1000/1001 (~23.976) fps frame: 29429400 flicks
+* 30 * 1000/1001 (~29.97) fps frame: 23543520 flicks
+* 60 * 1000/1001 (~59.94) fps frame: 11771760 flicks
+* 120 * 1000/1001 (~119.88) fps frame: 5885880 flicks
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [perFrame100](#perframe100)
+ * [perFrame120](#perframe120)
+ * [perFrame120NTSC](#perframe120ntsc)
+ * [perFrame24](#perframe24)
+ * [perFrame24NTSC](#perframe24ntsc)
+ * [perFrame25](#perframe25)
+ * [perFrame30](#perframe30)
+ * [perFrame30NTSC](#perframe30ntsc)
+ * [perFrame44100](#perframe44100)
+ * [perFrame48](#perframe48)
+ * [perFrame48000](#perframe48000)
+ * [perFrame50](#perframe50)
+ * [perFrame60](#perframe60)
+ * [perFrame60NTSC](#perframe60ntsc)
+ * [perFrame90](#perframe90)
+ * [perHour](#perhour)
+ * [perMinutes](#perminutes)
+ * [perSecond](#persecond)
+* Functions - API calls offered directly by the extension
+ * [is](#is)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [new](#new)
+ * [parse](#parse)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [toFrames](#toframes)
+ * [toSeconds](#toseconds)
+ * [toTimecode](#totimecode)
+
+## API Documentation
+
+### Constants
+
+#### [perFrame100](#perframe100)
+| **Signature** | `cp.time.flicks.perFrame100` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 100 fps. |
+
+#### [perFrame120](#perframe120)
+| **Signature** | `cp.time.flicks.perFrame120` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 120 fps. |
+
+#### [perFrame120NTSC](#perframe120ntsc)
+| **Signature** | `cp.time.flicks.perFrame120NTSC` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | An approximate for flicks in 1 frame at 120 fps in NTSC, a.k.a. ~119.88 fps. |
+
+#### [perFrame24](#perframe24)
+| **Signature** | `cp.time.flicks.perFrame24` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 24 fps. |
+
+#### [perFrame24NTSC](#perframe24ntsc)
+| **Signature** | `cp.time.flicks.perFrame24NTSC` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | An approximate for flicks in 1 frame at 24 fps in NTSC, a.k.a. 23.976 fps. |
+
+#### [perFrame25](#perframe25)
+| **Signature** | `cp.time.flicks.perFrame25` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 25 fps. |
+
+#### [perFrame30](#perframe30)
+| **Signature** | `cp.time.flicks.perFrame30` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 30 fps. |
+
+#### [perFrame30NTSC](#perframe30ntsc)
+| **Signature** | `cp.time.flicks.perFrame30NTSC` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | An approximate for flicks in 1 frame at 30 fps in NTSC, a.k.a. 29.97 fps. |
+
+#### [perFrame44100](#perframe44100)
+| **Signature** | `cp.time.flicks.perFrame44100` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 44100 fps, a.k.a. 44.1 Hz. |
+
+#### [perFrame48](#perframe48)
+| **Signature** | `cp.time.flicks.perFrame48` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 48 fps. |
+
+#### [perFrame48000](#perframe48000)
+| **Signature** | `cp.time.flicks.perFrame48000` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 44100 fps, a.k.a. 48 Hz. |
+
+#### [perFrame50](#perframe50)
+| **Signature** | `cp.time.flicks.perFrame50` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 50 fps. |
+
+#### [perFrame60](#perframe60)
+| **Signature** | `cp.time.flicks.perFrame60` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 60 fps. |
+
+#### [perFrame60NTSC](#perframe60ntsc)
+| **Signature** | `cp.time.flicks.perFrame60NTSC` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | An approximate for flicks in 1 frame at 60 fps in NTSC, a.k.a. 59.94 fps. |
+
+#### [perFrame90](#perframe90)
+| **Signature** | `cp.time.flicks.perFrame90` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 frame at 90 fps. |
+
+#### [perHour](#perhour)
+| **Signature** | `cp.time.flicks.perHour` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 hour. |
+
+#### [perMinutes](#perminutes)
+| **Signature** | `cp.time.flicks.perMinutes` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 minute. |
+
+#### [perSecond](#persecond)
+| **Signature** | `cp.time.flicks.perSecond` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The number of flicks in 1 second. |
+
+### Functions
+
+#### [is](#is)
+| **Signature** | `cp.time.flicks.is(thing) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `thing` is a `flicks` instance. |
+| **Parameters** | - thing - the thing to check
|
+| **Returns** | true if the thingis a flicks instance, otherwise false.
|
+
+### Constructors
+
+#### [new](#new)
+| **Signature** | `cp.time.flicks.new(value) -> flicks` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `flicks` instance. By default, the unit is in flicks`, but can be set as a |
+| **Parameters** | - value - the base value to set to
|
+| **Returns** | |
+
+#### [parse](#parse)
+| **Signature** | `cp.time.flicks.parse(timecodeString, framerate) -> flicks` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Attempts to parse the timecode string value with the specified framerate. |
+| **Parameters** | - timecodeString - The timecode as a string.
- framerate - The number of frames per second.
|
+| **Returns** | - a new
flicks instance for the timecode.
|
+
+### Methods
+
+#### [toFrames](#toframes)
+| **Signature** | `cp.time.flicks:toFrames(framerate) --> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Converts the flicks into a number for the specific framerate. |
+
+#### [toSeconds](#toseconds)
+| **Signature** | `cp.time.flicks:toSeconds() -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Converts the flicks into a decimal value of the number of seconds it represents. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [toTimecode](#totimecode)
+| **Signature** | `cp.time.flicks:toTimecode(framerate[, delimeter]) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Converts the flicks into a string of the format "HH[:]MM[:]SS[:;]FF", with hours, minutes and frames listed respectively. |
+| **Parameters** | - framerate - the framerate to use when calculating frames per second.
- delimeter - either
nil (default), ":", or ";".
|
+| **Returns** | |
+
diff --git a/api/cp/cp.tools.md b/api/cp/cp.tools.md
index bd6499e..2348094 100644
--- a/api/cp/cp.tools.md
+++ b/api/cp/cp.tools.md
@@ -5,15 +5,27 @@ A collection of handy miscellaneous tools for Lua development.
## API Overview
* Functions - API calls offered directly by the extension
+ * [camelCase](#camelcase)
+ * [centre](#centre)
* [cleanupButtonText](#cleanupbuttontext)
+ * [contentsInsideBrackets](#contentsinsidebrackets)
+ * [convertSingleHexStringToDecimalString](#convertsinglehexstringtodecimalstring)
+ * [dirFiles](#dirfiles)
* [doesDirectoryExist](#doesdirectoryexist)
* [doesFileExist](#doesfileexist)
* [doubleLeftClick](#doubleleftclick)
+ * [endsWith](#endswith)
+ * [ensureDirectoryExists](#ensuredirectoryexists)
+ * [exactMatch](#exactmatch)
* [executeWithAdministratorPrivileges](#executewithadministratorprivileges)
+ * [findCommonWordWithinTwoStrings](#findcommonwordwithintwostrings)
+ * [firstToUpper](#firsttoupper)
* [getEmail](#getemail)
* [getExternalDevices](#getexternaldevices)
+ * [getFileExtensionFromPath](#getfileextensionfrompath)
* [getFilenameFromPath](#getfilenamefrompath)
* [getFullname](#getfullname)
+ * [getKeysSortedByValue](#getkeyssortedbyvalue)
* [getmacOSVersion](#getmacosversion)
* [getModelName](#getmodelname)
* [getRAMSize](#getramsize)
@@ -21,381 +33,679 @@ A collection of handy miscellaneous tools for Lua development.
* [getThunderboltDevices](#getthunderboltdevices)
* [getUSBDevices](#getusbdevices)
* [getVRAMSize](#getvramsize)
+ * [hexStringToString](#hexstringtostring)
* [iconFallback](#iconfallback)
* [incrementFilename](#incrementfilename)
+ * [incrementFilenameInPath](#incrementfilenameinpath)
+ * [isNumberString](#isnumberstring)
* [isOffScreen](#isoffscreen)
* [leftClick](#leftclick)
* [lines](#lines)
+ * [lower](#lower)
* [macOSVersion](#macosversion)
* [mergeTable](#mergetable)
- * [modifierMaskToModifiers](#modifiermasktomodifiers)
- * [modifierMatch](#modifiermatch)
* [ninjaDoubleClick](#ninjadoubleclick)
* [ninjaMouseAction](#ninjamouseaction)
* [ninjaMouseClick](#ninjamouseclick)
+ * [ninjaRightMouseClick](#ninjarightmouseclick)
* [numberToWord](#numbertoword)
+ * [optionPressed](#optionpressed)
+ * [playErrorSound](#playerrorsound)
+ * [readFromFile](#readfromfile)
* [removeFilenameFromPath](#removefilenamefrompath)
* [removeFromTable](#removefromtable)
+ * [replace](#replace)
+ * [rescale](#rescale)
+ * [rightClick](#rightclick)
* [rmdir](#rmdir)
* [round](#round)
* [safeFilename](#safefilename)
+ * [shiftPressed](#shiftpressed)
+ * [spairs](#spairs)
* [split](#split)
* [splitOnColumn](#splitoncolumn)
+ * [startsWith](#startswith)
* [stringMaxLength](#stringmaxlength)
+ * [stringToHexString](#stringtohexstring)
* [tableContains](#tablecontains)
* [tableCount](#tablecount)
+ * [tableFilter](#tablefilter)
+ * [tableMatch](#tablematch)
+ * [toRegionalNumber](#toregionalnumber)
+ * [toRegionalNumberString](#toregionalnumberstring)
* [trim](#trim)
* [unescape](#unescape)
+ * [upper](#upper)
* [urlQueryStringDecode](#urlquerystringdecode)
* [volumeFormat](#volumeformat)
+ * [writeToFile](#writetofile)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [escapeTilda](#escapetilda)
+ * [keyStroke](#keystroke)
+ * [pressSystemKey](#presssystemkey)
## API Documentation
### Functions
+#### [camelCase](#camelcase)
+| **Signature** | `cp.tools.camelCase(str) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Converts the supplied string to camelcase. |
+| **Parameters** | - str - The string you want to manipulate
|
+| **Returns** | |
+
+#### [centre](#centre)
+| **Signature** | `cp.tools.centre(frame) -> hs.geometry point` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets the centre point of a frame. |
+| **Parameters** | - frame - an
hs.geometry rect
|
+| **Returns** | |
+
#### [cleanupButtonText](#cleanupbuttontext)
| **Signature** | `cp.tools.cleanupButtonText(value) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Removes the … symbol and multiple >'s from a string. |
+| **Type** | Function |
+| **Description** | Removes the … symbol and multiple >'s from a string. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
+
+#### [contentsInsideBrackets](#contentsinsidebrackets)
+| **Signature** | `cp.tools.contentsInsideBrackets(value) -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets the contents of any text inside the first bracket set. |
+| **Parameters** | - value - The string to process
|
+| **Returns** | - The contents as a string or
nil
|
+
+#### [convertSingleHexStringToDecimalString](#convertsinglehexstringtodecimalstring)
+| **Signature** | `cp.tools.convertSingleHexStringToDecimalString(hex) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Converts a single hex string (i.e. "3") to a binary string (i.e. "0011") |
+| **Parameters** | - hex - A single string character
|
+| **Returns** | |
+
+#### [dirFiles](#dirfiles)
+| **Signature** | `cp.tools.dirFiles(path) -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets all the files in a directory |
+| **Parameters** | |
+| **Returns** | - A table containing filenames as strings, or
nil followed by the error message if an error occurs.
|
#### [doesDirectoryExist](#doesdirectoryexist)
| **Signature** | `cp.tools.doesDirectoryExist(path) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns whether or not a directory exists. |
+| **Type** | Function |
+| **Description** | Returns whether or not a directory exists. |
| **Parameters** | - path - Path to the directory
|
-| **Returns** | - `true` if the directory exists otherwise `false`
|
+| **Returns** | true if the directory exists otherwise false
|
#### [doesFileExist](#doesfileexist)
| **Signature** | `cp.tools.doesFileExist(path) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns whether or not a file exists. |
+| **Type** | Function |
+| **Description** | Returns whether or not a file exists. |
| **Parameters** | |
-| **Returns** | - `true` if the file exists otherwise `false`
|
+| **Returns** | true if the file exists otherwise false
|
#### [doubleLeftClick](#doubleleftclick)
| **Signature** | `cp.tools.doubleLeftClick(point[, delay]) -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Performs a Left Mouse Double Click. |
+| **Type** | Function |
+| **Description** | Performs a Left Mouse Double Click. |
| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
|
-| **Returns** | |
+| **Returns** | |
+
+#### [endsWith](#endswith)
+| **Signature** | `cp.tools.endsWith(str, ending) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if `str` has the same ending as `ending`. |
+| **Parameters** | - str - String to analysis
- ending - End of string to compare against
|
+| **Returns** | |
+
+#### [ensureDirectoryExists](#ensuredirectoryexists)
+| **Signature** | `cp.tools.ensureDirectoryExists(rootPath, ...) -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Ensures all steps on a provided path exist. If not, attempts to create them. |
+| **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)
+| **Signature** | `cp.tools.exactMatch(value, pattern, plain) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Compares two strings to see if they're an exact match. |
+| **Parameters** | - value - The first string
- pattern - The second string, including any patterns
- plain - Whether or not to ignore patterns. Defaults to
false. - ignoreCase - Ignore the case of the value & pattern.
|
+| **Returns** | true if there's an exact match, otherwise false.
|
#### [executeWithAdministratorPrivileges](#executewithadministratorprivileges)
| **Signature** | `cp.tools.executeWithAdministratorPrivileges(input[, stopOnError]) -> boolean or string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Executes a single or multiple shell commands with Administrator Privileges. |
+| **Type** | Function |
+| **Description** | Executes a single or multiple shell commands with Administrator Privileges. |
| **Parameters** | - input - either a string or a table of strings of commands you want to execute
- stopOnError - an optional variable that stops processing multiple commands when an individual commands returns an error
|
-| **Returns** | - `true` if successful, `false` if cancelled and a string if there's an error.
|
+| **Returns** | true if successful, false if cancelled and a string if there's an error.
|
+
+#### [findCommonWordWithinTwoStrings](#findcommonwordwithintwostrings)
+| **Signature** | `cp.tools.findCommonWordWithinTwoStrings(a, b) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Finds a common word within two strings. |
+| **Parameters** | - a - The first string
- b - The second string
|
+| **Returns** | - The first common word that's found or
nil if something goes wrong.
|
+
+#### [firstToUpper](#firsttoupper)
+| **Signature** | `cp.tools.firstToUpper(str) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Makes the first letter of a string uppercase. |
+| **Parameters** | - str - The string you want to manipulate
|
+| **Returns** | |
#### [getEmail](#getemail)
| **Signature** | `cp.tools.getEmail() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the current users Email, otherwise an empty string. |
+| **Type** | Function |
+| **Description** | Returns the current users Email, otherwise an empty string. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
#### [getExternalDevices](#getexternaldevices)
| **Signature** | `cp.tools.getExternalDevices() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns a string of USB & Thunderbolt Devices. |
+| **Type** | Function |
+| **Description** | Returns a string of USB & Thunderbolt Devices. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
-#### [getFilenameFromPath](#getfilenamefrompath)
-| **Signature** | `cp.tools.getFilenameFromPath(input) -> string` |
+#### [getFileExtensionFromPath](#getfileextensionfrompath)
+| **Signature** | `cp.tools.getFileExtensionFromPath(input) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Gets the filename component of a path. |
+| **Type** | Function |
+| **Description** | Gets the file extension from a path. |
| **Parameters** | |
-| **Returns** | - A string of the filename.
|
+| **Returns** | - A string of the file extension.
|
+
+#### [getFilenameFromPath](#getfilenamefrompath)
+| **Signature** | `cp.tools.getFilenameFromPath(input[, removeExtension]) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets the filename component of a path. |
+| **Parameters** | - input - The path
- removeExtension - (optional) set to
true if the file extension should be removed
|
+| **Returns** | - A string of the filename.
|
#### [getFullname](#getfullname)
| **Signature** | `cp.tools.getFullname() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the current users Full Name, otherwise an empty string. |
+| **Type** | Function |
+| **Description** | Returns the current users Full Name, otherwise an empty string. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
+
+#### [getKeysSortedByValue](#getkeyssortedbyvalue)
+| **Signature** | `cp.tools.getKeysSortedByValue(tbl, sortFunction) -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Sorts table keys by a value |
+| **Parameters** | - tbl - the table you want to sort
- sortFunction - the function you want to use to sort the table
|
+| **Returns** | |
#### [getmacOSVersion](#getmacosversion)
| **Signature** | `cp.tools.getmacOSVersion() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns macOS Version. |
+| **Type** | Function |
+| **Description** | Returns the macOS Version in the format that Apple's Feedback Form expects. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | - The macOS version as a string or "" if unknown.
|
#### [getModelName](#getmodelname)
| **Signature** | `cp.tools.getModelName() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns Model Name of Hardware. |
+| **Type** | Function |
+| **Description** | Returns Model Name of Hardware. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
#### [getRAMSize](#getramsize)
| **Signature** | `cp.tools.getRAMSize() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns RAM Size. |
+| **Type** | Function |
+| **Description** | Returns RAM Size in a format Apple's Feedback form expects. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | - The RAM size as a string, or "" if unknown.
|
#### [getScreenshotsAsBase64](#getscreenshotsasbase64)
| **Signature** | `cp.tools.getScreenshotsAsBase64() -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Captures all available screens and saves them as base64 encodes in a table. |
+| **Type** | Function |
+| **Description** | Captures all available screens and saves them as base64 encodes in a table. |
| **Parameters** | |
-| **Returns** | - A table containing base64 images of all available screens.
|
+| **Returns** | - A table containing base64 images of all available screens.
|
#### [getThunderboltDevices](#getthunderboltdevices)
| **Signature** | `cp.tools.getThunderboltDevices() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns a string of Thunderbolt Devices. |
+| **Type** | Function |
+| **Description** | Returns a string of Thunderbolt Devices. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
#### [getUSBDevices](#getusbdevices)
| **Signature** | `cp.tools.getUSBDevices() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns a string of USB Devices. |
+| **Type** | Function |
+| **Description** | Returns a string of USB Devices. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
#### [getVRAMSize](#getvramsize)
| **Signature** | `cp.tools.getVRAMSize() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the VRAM size in format suitable for Apple's Final Cut Pro feedback form or "" if unknown. |
+| **Type** | Function |
+| **Description** | Returns the VRAM size in format suitable for Apple's Final Cut Pro feedback form or "" if unknown. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
+
+#### [hexStringToString](#hexstringtostring)
+| **Signature** | `cp.tools.hexStringToString(value) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Converts a hex string to a string. |
+| **Parameters** | - value - The string to convert
|
+| **Returns** | |
#### [iconFallback](#iconfallback)
| **Signature** | `cp.tools.iconFallback(paths) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Excepts one or more paths to an icon, checks to see if they exist (in the order that they're given), and if none exist, returns the CommandPost icon path. |
+| **Type** | Function |
+| **Description** | Excepts one or more paths to an icon, checks to see if they exist (in the order that they're given), and if none exist, returns the CommandPost icon path. |
| **Parameters** | - paths - One or more paths to an icon
|
-| **Returns** | |
+| **Returns** | |
#### [incrementFilename](#incrementfilename)
| **Signature** | `cp.tools.incrementFilename(value) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns a table of file names for the given path. |
-| **Parameters** | |
-| **Returns** | - A table containing filenames as strings.
|
+| **Type** | Function |
+| **Description** | Increments the filename. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [incrementFilenameInPath](#incrementfilenameinpath)
+| **Signature** | `cp.tools.incrementFilenameInPath(path) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Increments the filename as it appears in a path. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [isNumberString](#isnumberstring)
+| **Signature** | `cp.tools.isNumberString(value) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns whether or not value is a number string. |
+| **Parameters** | - value - the string you want to check
|
+| **Returns** | true if value is a number string, otherwise false.
|
#### [isOffScreen](#isoffscreen)
| **Signature** | `cp.tools.isOffScreen(rect) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Determines if the given rect is off screen or not. |
+| **Type** | Function |
+| **Description** | Determines if the given rect is off screen or not. |
| **Parameters** | - rect - the rect you want to check
|
-| **Returns** | - `true` if offscreen otherwise `false`
|
+| **Returns** | true if offscreen otherwise false
|
#### [leftClick](#leftclick)
| **Signature** | `cp.tools.leftClick(point[, delay, clickNumber]) -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Performs a Left Mouse Click. |
+| **Type** | Function |
+| **Description** | Performs a Left Mouse Click. |
| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
- clickNumber - The optional number of times you want to perform the click.
|
-| **Returns** | |
+| **Returns** | |
#### [lines](#lines)
-| **Signature** | `cp.tools.lines(string) -> table` |
+| **Signature** | `cp.tools.lines(string) -> table | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Splits a string containing multiple lines of text into a table. |
+| **Type** | Function |
+| **Description** | Splits a string containing multiple lines of text into a table. |
| **Parameters** | - string - the string you want to process
|
-| **Returns** | |
+| **Returns** | - A table or
nil if the parameter is not a string.
|
+
+#### [lower](#lower)
+| **Signature** | `cp.tools.lower(str) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Converts the supplied string to lowercase. |
+| **Parameters** | - str - The string you want to manipulate
|
+| **Returns** | |
#### [macOSVersion](#macosversion)
| **Signature** | `cp.tools.macOSVersion() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns a the macOS Version as a single string. |
+| **Type** | Function |
+| **Description** | Returns a the macOS Version as a single string. |
| **Parameters** | |
-| **Returns** | - A string containing the macOS version
|
+| **Returns** | - A string containing the macOS version
|
#### [mergeTable](#mergetable)
| **Signature** | `cp.tools.mergeTable(target, ...) -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Gives you the file system volume format of a path. |
-| **Parameters** | - target - The target table
- ... - Any other tables you want to merge into target
|
-| **Returns** | |
-
-#### [modifierMaskToModifiers](#modifiermasktomodifiers)
-| **Signature** | `cp.tools.modifierMaskToModifiers() -> table` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Translate Keyboard Modifiers from Apple's Plist Format into Hammerspoon Format |
-| **Parameters** | |
-| **Returns** | |
-
-#### [modifierMatch](#modifiermatch)
-| **Signature** | `cp.tools.modifierMatch(inputA, inputB) -> boolean` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Compares two modifier tables. |
-| **Parameters** | - inputA - table of modifiers
- inputB - table of modifiers
|
-| **Returns** | - `true` if there's a match otherwise `false`
|
-| **Notes** | - This function only takes into account 'ctrl', 'alt', 'cmd', 'shift'.
|
+| **Type** | Function |
+| **Description** | Merges multiple tables into a target table. |
+| **Parameters** | - target - The target table
- ... - Any other tables you want to merge into target
|
+| **Returns** | |
#### [ninjaDoubleClick](#ninjadoubleclick)
| **Signature** | `cp.tools.ninjaDoubleClick(point[, delay]) -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Performs a mouse double click, but returns the mouse to the original position without the users knowledge. |
+| **Type** | Function |
+| **Description** | Performs a mouse double click, but returns the mouse to the original position without the users knowledge. |
| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
|
-| **Returns** | |
+| **Returns** | |
#### [ninjaMouseAction](#ninjamouseaction)
| **Signature** | `cp.tools.ninjaMouseAction(point, fn) -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Moves the mouse to a point, performs a function, then returns the mouse to the original point. |
+| **Type** | Function |
+| **Description** | Moves the mouse to a point, performs a function, then returns the mouse to the original point. |
| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- fn - A function you want to perform
|
-| **Returns** | |
+| **Returns** | |
#### [ninjaMouseClick](#ninjamouseclick)
| **Signature** | `cp.tools.ninjaMouseClick(point[, delay]) -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Performs a mouse click, but returns the mouse to the original position without the users knowledge. |
+| **Type** | Function |
+| **Description** | Performs a mouse click, but returns the mouse to the original position without the users knowledge. |
+| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
|
+| **Returns** | |
+
+#### [ninjaRightMouseClick](#ninjarightmouseclick)
+| **Signature** | `cp.tools.ninjaRightMouseClick(point[, delay]) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Performs a right mouse click, but returns the mouse to the original position without the users knowledge. |
| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
|
-| **Returns** | |
+| **Returns** | |
#### [numberToWord](#numbertoword)
-| **Signature** | `cp.tools.numberToWord(str) -> string` |
+| **Signature** | `cp.tools.numberToWord(number) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Makes the first letter of a string uppercase. |
-| **Parameters** | - str - The string you want to manipulate
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Converts a number to a string (i.e. 1 becomes "One"). |
+| **Parameters** | - number - A whole number between 0 and 10
|
+| **Returns** | |
+
+#### [optionPressed](#optionpressed)
+| **Signature** | `cp.tools.optionPressed() -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Is the Option Key being pressed? |
+| **Parameters** | |
+| **Returns** | true if the option key is being pressed, otherwise false.
|
+
+#### [playErrorSound](#playerrorsound)
+| **Signature** | `cp.tools.playErrorSound() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Plays the "Funk" error sound. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [readFromFile](#readfromfile)
+| **Signature** | `cp.tools.readFromFile(path) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Read data from file. |
+| **Parameters** | - path - The path of where you want to load the file.
|
+| **Returns** | |
#### [removeFilenameFromPath](#removefilenamefrompath)
| **Signature** | `cp.tools.removeFilenameFromPath(string) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Removes the filename from a path. |
+| **Type** | Function |
+| **Description** | Removes the filename from a path. |
| **Parameters** | |
-| **Returns** | - A string of the path without the filename.
|
+| **Returns** | - A string of the path without the filename.
|
#### [removeFromTable](#removefromtable)
| **Signature** | `cp.tools.removeFromTable(table, element) -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Removes a string from a table of strings |
+| **Type** | Function |
+| **Description** | Removes a string from a table of strings |
| **Parameters** | - table - the table you want to check
- element - the string you want to remove
|
-| **Returns** | |
+| **Returns** | |
+
+#### [replace](#replace)
+| **Signature** | `cp.tools.replace(text, old, new) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | A find and replace feature that doesn't use patterns. |
+| **Parameters** | - text - The string you want to process
- old - The string you want to find
- new - The new string you want to replace the old string with
|
+| **Returns** | |
+
+#### [rescale](#rescale)
+| **Signature** | `cp.tools.rescale(value, inMin, inMax, outMin, outMax) -> number | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Takes an input, rescales it, and provides a new output. |
+| **Parameters** | - value - The value you want to process as a number
- inMin - The minimum value of the input as a number
- inMax - The maximum value of the input as a number
- outMin - The minimum value of the output as a number
- outMax - The maximum value of the output as a number
|
+| **Returns** | - The rescaled value as a number or
nil.
|
+
+#### [rightClick](#rightclick)
+| **Signature** | `cp.tools.rightClick(point[, delay, clickNumber]) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Performs a Right Mouse Click. |
+| **Parameters** | - point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
- clickNumber - The optional number of times you want to perform the click.
|
+| **Returns** | |
#### [rmdir](#rmdir)
| **Signature** | `cp.tools.rmdir(path[, recursive]) -> true | nil, err` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Attempts to remove the directory at the specified path, optionally removing |
-| **Parameters** | - * `path` - The absolute path to remove
- * `recursive` - If `true`, the contents of the directory will be removed first.
|
-| **Returns** | - * `true` if successful, or `nil, err` if there was a problem.
|
+| **Type** | Function |
+| **Description** | Attempts to remove the directory at the specified path, optionally removing |
+| **Parameters** | path - The absolute path to removerecursive - If true, the contents of the directory will be removed first.
|
+| **Returns** | true if successful, or nil, err if there was a problem.
|
#### [round](#round)
| **Signature** | `cp.tools.round(num, numDecimalPlaces) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Rounds a number to a set number of decimal places |
+| **Type** | Function |
+| **Description** | Rounds a number to a set number of decimal places |
| **Parameters** | - num - The number you want to round
- numDecimalPlaces - How many numbers of decimal places (defaults to 0)
|
-| **Returns** | |
+| **Returns** | |
#### [safeFilename](#safefilename)
| **Signature** | `cp.tools.safeFilename(value[, defaultValue]) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns a Safe Filename. |
+| **Type** | Function |
+| **Description** | Returns a Safe Filename. |
| **Parameters** | - value - a string you want to make safe
- defaultValue - the optional default filename to use if the value is not valid
|
-| **Returns** | - A string of the safe filename
|
-| **Notes** | - Returns "filename" is both `value` and `defaultValue` are `nil`.
|
+| **Returns** | - A string of the safe filename
|
+| **Notes** | - Returns "filename" is both
value and defaultValue are nil.
|
+
+#### [shiftPressed](#shiftpressed)
+| **Signature** | `cp.tools.shiftPressed() -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Is the Shift Key being pressed? |
+| **Parameters** | |
+| **Returns** | true if the shift key is being pressed, otherwise false.
|
+
+#### [spairs](#spairs)
+| **Signature** | `cp.tools.spairs(t, order) -> function` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | A customised version of pairs, called `spairs` because it iterates over the table in a sorted order. |
+| **Parameters** | - t - The table to process
- order - The function of how to sort the table.
|
+| **Returns** | |
+| **Notes** | |
#### [split](#split)
| **Signature** | `cp.tools.split(str, pat) -> table` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Splits a string with a pattern. |
+| **Type** | Function |
+| **Description** | Splits a string with a pattern. |
| **Parameters** | - str - The string to split
- pat - The pattern
|
-| **Returns** | |
+| **Returns** | |
#### [splitOnColumn](#splitoncolumn)
| **Signature** | `cp.tools.splitOnColumn() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Splits a string on a column. |
+| **Type** | Function |
+| **Description** | Splits a string on a column. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
+
+#### [startsWith](#startswith)
+| **Signature** | `cp.tools.startsWith(value, startValue) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if a string starts with a value. |
+| **Parameters** | - value - The value to check
- startValue - The value to look for
|
+| **Returns** | true if value starts with the startValue, otherwise false
|
#### [stringMaxLength](#stringmaxlength)
| **Signature** | `cp.tools.stringMaxLength(string, maxLength[, optionalEnd]) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Trims a string based on a maximum length. |
+| **Type** | Function |
+| **Description** | Trims a string based on a maximum length. |
| **Parameters** | - maxLength - The length of the string as a number
- optionalEnd - A string that is applied to the end of the input string if the input string is larger than the maximum length.
|
-| **Returns** | |
+| **Returns** | |
+
+#### [stringToHexString](#stringtohexstring)
+| **Signature** | `cp.tools.stringToHexString(value) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Converts a string to a hex string. |
+| **Parameters** | - value - The string to convert
|
+| **Returns** | |
#### [tableContains](#tablecontains)
| **Signature** | `cp.tools.tableContains(table, element) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Does a element exist in a table? |
+| **Type** | Function |
+| **Description** | Does a element exist in a table? |
| **Parameters** | - table - the table you want to check
- element - the element you want to check for
|
-| **Returns** | |
+| **Returns** | |
#### [tableCount](#tablecount)
| **Signature** | `cp.tools.tableCount(table) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns how many items are in a table. |
+| **Type** | Function |
+| **Description** | Returns how many items are in a table. |
| **Parameters** | - table - The table you want to count.
|
-| **Returns** | - The number of items in the table.
|
+| **Returns** | - The number of items in the table.
|
+| **Notes** | - If something other than a table is supplied, this function will return 0.
|
+
+#### [tableFilter](#tablefilter)
+| **Signature** | `cp.tools.tableFilter(t, matchFn) -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Efficiently filters out all elements from the table `t` which to not match the `matchFn`. |
+| **Parameters** | - t - The
table to filter. - matchFn - A function which will receive the table, the current index, and the target index.
|
+| **Returns** | |
+
+#### [tableMatch](#tablematch)
+| **Signature** | `cp.tools.tableMatch(t1, t2[, ignoreMetatable]) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Compares two tables. |
+| **Parameters** | - t1 - The first table.
- t2 - The second table.
- ignoreMetatable - A boolean that determines whether or not we should ignore the metatable.
|
+| **Returns** | true if t1 and t2 are identical, otherwise false.
|
+
+#### [toRegionalNumber](#toregionalnumber)
+| **Signature** | `cp.tools.toRegionalNumber(value) -> number | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Takes a string and converts it into a number, with the correct |
+| **Parameters** | - value - The value you want to process as a string.
|
+| **Returns** | - The value as a number or
nil.
|
+
+#### [toRegionalNumberString](#toregionalnumberstring)
+| **Signature** | `cp.tools.toRegionalNumberString(value) -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Takes a number and converts it into a string, with the correct |
+| **Parameters** | - value - The value you want to process as a number.
|
+| **Returns** | - The value as a number or
nil.
|
#### [trim](#trim)
| **Signature** | `cp.tools.trim(string) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Trims the whitespaces from a string |
+| **Type** | Function |
+| **Description** | Trims the whitespaces from a string |
| **Parameters** | - string - the string you want to trim
|
-| **Returns** | |
+| **Returns** | |
#### [unescape](#unescape)
| **Signature** | `cp.tools.unescape(str) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Removes any URL encoding in the provided string. |
+| **Type** | Function |
+| **Description** | Removes any URL encoding in the provided string. |
| **Parameters** | - str - the string to decode
|
-| **Returns** | - A string with all "+" characters converted to spaces and all percent encoded sequences converted to their ASCII equivalents.
|
+| **Returns** | - A string with all "+" characters converted to spaces and all percent encoded sequences converted to their ASCII equivalents.
|
+
+#### [upper](#upper)
+| **Signature** | `cp.tools.upper(str) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Converts the supplied string to uppercase. |
+| **Parameters** | - str - The string you want to manipulate
|
+| **Returns** | |
#### [urlQueryStringDecode](#urlquerystringdecode)
| **Signature** | `cp.tools.urlQueryStringDecode() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Decodes a URL Query String |
+| **Type** | Function |
+| **Description** | Decodes a URL Query String |
| **Parameters** | |
-| **Returns** | - Decoded URL Query String as string
|
+| **Returns** | - Decoded URL Query String as string
|
#### [volumeFormat](#volumeformat)
| **Signature** | `cp.tools.volumeFormat(path) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Gives you the file system volume format of a path. |
+| **Type** | Function |
+| **Description** | Gives you the file system volume format of a path. |
| **Parameters** | - path - the path you want to check as a string
|
-| **Returns** | - The `NSURLVolumeLocalizedFormatDescriptionKey` as a string, otherwise `nil`.
|
+| **Returns** | - The
NSURLVolumeLocalizedFormatDescriptionKey as a string, otherwise nil.
|
+
+#### [writeToFile](#writetofile)
+| **Signature** | `cp.tools.writeToFile(path, data) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Write data to a file at a given path. |
+| **Parameters** | - path - The path to the file you want to write to.
- data - The data to write to the file.
|
+| **Returns** | |
+
+### Methods
+
+#### [escapeTilda](#escapetilda)
+| **Signature** | `cp.tools.escapeTilda(input) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Escapes a tilda. |
+| **Parameters** | - input - The string you want to escape.
|
+| **Returns** | |
+
+#### [keyStroke](#keystroke)
+| **Signature** | `cp.tools.keyStroke(modifiers, character, app) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Generates and emits a single keystroke event pair for the supplied keyboard |
+| **Parameters** | - modifiers - A table containing the keyboard modifiers to apply ("fn", "ctrl", "alt", "cmd" or "shift")
- character - A string containing a character to be emitted
- app - The optional
hs.application you want to target
|
+| **Returns** | |
+
+#### [pressSystemKey](#presssystemkey)
+| **Signature** | `cp.tools.pressSystemKey(key) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Virtually presses a system key. |
+| **Parameters** | |
+| **Returns** | - Supported key values are:
- SOUND_UP
- SOUND_DOWN
- MUTE
- BRIGHTNESS_UP
- BRIGHTNESS_DOWN
- CONTRAST_UP
- CONTRAST_DOWN
- POWER
- LAUNCH_PANEL
- VIDMIRROR
- PLAY
- EJECT
- NEXT
- PREVIOUS
- FAST
- REWIND
- ILLUMINATION_UP
- ILLUMINATION_DOWN
- ILLUMINATION_TOGGLE
- CAPS_LOCK
- HELP
- NUM_LOCK
|
diff --git a/api/cp/cp.ui.Alert.md b/api/cp/cp.ui.Alert.md
index 4e7a6a2..ce83226 100644
--- a/api/cp/cp.ui.Alert.md
+++ b/api/cp/cp.ui.Alert.md
@@ -4,6 +4,18 @@
Alert UI Module.
## API Overview
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [new](#new)
## API Documentation
+### Constructors
+
+#### [new](#new)
+| **Signature** | `cp.ui.Alert:new(app) -> Alert` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Alert` instance. It will automatically search the parent's children for Alerts. |
+| **Parameters** | - parent - The parent object.
|
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Button.md b/api/cp/cp.ui.Button.md
index 487c626..2aa075f 100644
--- a/api/cp/cp.ui.Button.md
+++ b/api/cp/cp.ui.Button.md
@@ -1,19 +1,65 @@
# [docs](index.md) » cp.ui.Button
---
-Button Module.
+The `Button` type extends [Element](cp.ui.Element.md) and includes all its
+methods, fields and other properties.
## API Overview
* Functions - API calls offered directly by the extension
- * [new](#new)
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Button](#button)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [title](#title)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [doPress](#dopress)
+ * [press](#press)
## API Documentation
### Functions
-#### [new](#new)
-| **Signature** | `cp.ui.Button:new(axuielement, table) -> Button` |
+#### [matches](#matches)
+| **Signature** | `cp.ui.Button.matches(element) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Creates a new Button |
+| **Type** | Function |
+| **Description** | Checks if the `element` is a `Button`, returning `true` if so. |
+| **Parameters** | - element - The
hs._asm.axuielement to check.
|
+| **Returns** | true if the element is a Button, or false if not.
|
+
+### Constructors
+
+#### [Button](#button)
+| **Signature** | `cp.ui.Button(parent, uiFinder) -> cp.ui.Button` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Button` instance. |
+| **Parameters** | - parent - The parent object. Should have a
UI and isShowing field. - uiFinder - A function which will return the
hs._asm.axuielement the button belongs to, or nil if not available.
|
+| **Returns** | The new Button instance.
|
+
+### Fields
+
+#### [title](#title)
+| **Signature** | `cp.ui.Button.title ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The button title, if available. |
+
+### Methods
+
+#### [doPress](#dopress)
+| **Signature** | `cp.ui.Button:doPress() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will press the button when executed, if available at the time. |
+| **Parameters** | |
+| **Returns** | - The
Statement which will press the button when executed.
|
+
+#### [press](#press)
+| **Signature** | `cp.ui.Button:press() -> self, boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Performs a button press action, if the button is available. |
+| **Parameters** | |
+| **Returns** | - The
Button instance. true if the button was actually pressed successfully.
|
diff --git a/api/cp/cp.ui.Cell.md b/api/cp/cp.ui.Cell.md
new file mode 100644
index 0000000..87a7ccc
--- /dev/null
+++ b/api/cp/cp.ui.Cell.md
@@ -0,0 +1,69 @@
+# [docs](index.md) » cp.ui.Cell
+---
+
+Represents an `AXCell` `axuielement`.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [childrenUI](#childrenui)
+ * [columnIndexRange](#columnindexrange)
+ * [rowIndexRange](#rowindexrange)
+ * [selected](#selected)
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [textValueIs](#textvalueis)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Cell.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `element` is an `AXCell`. |
+
+### Fields
+
+#### [childrenUI](#childrenui)
+| **Signature** | `cp.ui.Cell.childrenUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The list of `axuielement`s which are children of this `Cell`. |
+
+#### [columnIndexRange](#columnindexrange)
+| **Signature** | `cp.ui.Cell.columnIndexRange ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns a table of `{len,loc}`, which indicates if the cell covers multiple columns. |
+
+#### [rowIndexRange](#rowindexrange)
+| **Signature** | `cp.ui.Cell.rowIndexRange ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns a table of `{len,loc}`, which indicates if the cell covers multiple rows. |
+
+#### [selected](#selected)
+| **Signature** | `cp.ui.Cell.selected ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Indicates if the cell is currently selected. |
+
+#### [value](#value)
+| **Signature** | `cp.ui.Cell.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The cell value, if it is a string. |
+
+### Methods
+
+#### [textValueIs](#textvalueis)
+| **Signature** | `cp.ui.Cell.textValueIs(value) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if the cell's text value equals `value`. |
+| **Parameters** | value - The text value to compare.
|
+| **Returns** | true if the cell text value equals the provided value.
|
+
diff --git a/api/cp/cp.ui.CheckBox.md b/api/cp/cp.ui.CheckBox.md
index 67e3401..7f2d50a 100644
--- a/api/cp/cp.ui.CheckBox.md
+++ b/api/cp/cp.ui.CheckBox.md
@@ -3,17 +3,136 @@
Check Box UI Module.
+This represents an `hs._asm.axuielement` with a `AXCheckBox` role.
+It allows checking and modifying the `checked` status like so:
+
+```lua
+myButton:checked() == true -- happens to be checked already
+myButton:checked(false) == false -- update to unchecked.
+myButton.checked:toggle() == true -- toggled back to being checked.
+```
+
+You can also call instances of `CheckBox` as a function, which will return
+the `checked` status:
+
+```lua
+myButton() == true -- still true
+myButton(false) == false -- now false
+```
+
## API Overview
* Functions - API calls offered directly by the extension
- * [new](#new)
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [CheckBox](#checkbox)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [checked](#checked)
+ * [title](#title)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [click](#click)
+ * [doCheck](#docheck)
+ * [doPress](#dopress)
+ * [doUncheck](#douncheck)
+ * [loadLayout](#loadlayout)
+ * [press](#press)
+ * [saveLayout](#savelayout)
+ * [toggle](#toggle)
## API Documentation
### Functions
-#### [new](#new)
-| **Signature** | `cp.ui.CheckBox:new(axuielement, function) -> CheckBox` |
+#### [matches](#matches)
+| **Signature** | `cp.ui.CheckBox.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the provided `hs._asm.axuielement` is a CheckBox. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | true if it's a match, or false if not.
|
+
+### Constructors
+
+#### [CheckBox](#checkbox)
+| **Signature** | `cp.ui.CheckBox(parent, uiFinder) -> cp.ui.CheckBox` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new CheckBox. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | |
+
+### Fields
+
+#### [checked](#checked)
+| **Signature** | `cp.ui.CheckBox.checked ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Indicates if the checkbox is currently checked. |
+
+#### [title](#title)
+| **Signature** | `cp.ui.CheckBox.title ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The button title, if available. |
+
+### Methods
+
+#### [click](#click)
+| **Signature** | `cp.ui.CheckBox:click() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Performs a single mouse click on the checkbox. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [doCheck](#docheck)
+| **Signature** | `cp.ui.CheckBox:doCheck() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will ensure the `CheckBox` is checked. |
+
+#### [doPress](#dopress)
+| **Signature** | `cp.ui.CheckBox:doPress() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will press the button when executed, if available at the time. |
+| **Parameters** | |
+| **Returns** | - The
Statement which will press the button when executed.
|
+
+#### [doUncheck](#douncheck)
+| **Signature** | `cp.ui.CheckBox:doUncheck() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will ensure the `CheckBox` is unchecked. |
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.CheckBox:loadLayout(layout) -> nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Applies the settings in the provided layout table. |
+| **Parameters** | - layout - The table containing layout settings. Usually created by the
saveLayout method.
|
+| **Returns** | |
+
+#### [press](#press)
+| **Signature** | `cp.ui.CheckBox:press() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to press the button. May fail if the `UI` is not available. |
+| **Parameters** | |
+| **Returns** | The CheckBox instance.
|
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.CheckBox:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table containing the layout settings for the checkbox. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [toggle](#toggle)
+| **Signature** | `cp.ui.CheckBox:toggle() -> self` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Creates a new CheckBox |
+| **Type** | Method |
+| **Description** | Toggles the `checked` status of the button. |
+| **Parameters** | |
+| **Returns** | |
diff --git a/api/cp/cp.ui.ColorWell.md b/api/cp/cp.ui.ColorWell.md
new file mode 100644
index 0000000..e937760
--- /dev/null
+++ b/api/cp/cp.ui.ColorWell.md
@@ -0,0 +1,33 @@
+# [docs](index.md) » cp.ui.ColorWell
+---
+
+UI ColorWell.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [ColorWell](#colorwell)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.ColorWell.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [ColorWell](#colorwell)
+| **Signature** | `cp.ui.ColorWell(parent, uiFinder) -> Image` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `ColorWell` instance. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Column.md b/api/cp/cp.ui.Column.md
new file mode 100644
index 0000000..30b1a5e
--- /dev/null
+++ b/api/cp/cp.ui.Column.md
@@ -0,0 +1,57 @@
+# [docs](index.md) » cp.ui.Column
+---
+
+Represents an `AXColumn` `axuielement`.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [index](#index)
+ * [selected](#selected)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [rows](#rows)
+ * [visibleRows](#visiblerows)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Column.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `axuielement` is a `Column`. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | true if the element is a Column.
|
+
+### Fields
+
+#### [index](#index)
+| **Signature** | `cp.ui.Column.index ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The numeric index of this column in the overall container, with `0` being the first item. |
+
+#### [selected](#selected)
+| **Signature** | `cp.ui.Column.selected ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Indicates if the column is currently selected. May be set. |
+
+### Methods
+
+#### [rows](#rows)
+| **Signature** | `cp.ui.Column:rows() -> table of cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` of [Row](cp.ui.Row.md)s contained in the Column. |
+| **Returns** | - The
table, or nil if the column's UI is not available.
|
+
+#### [visibleRows](#visiblerows)
+| **Signature** | `cp.ui.Column:visibleRows() -> table of cp.ui.Rows or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` of [Row](cp.ui.Row.md)s which are currently visible on screen. |
+| **Returns** | - The
table, or nil if the column's UI is not available.
|
+
diff --git a/api/cp/cp.ui.ComboBox.md b/api/cp/cp.ui.ComboBox.md
new file mode 100644
index 0000000..a3277df
--- /dev/null
+++ b/api/cp/cp.ui.ComboBox.md
@@ -0,0 +1,33 @@
+# [docs](index.md) » cp.ui.ComboBox
+---
+
+Combo Box Module.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [ComboBox](#combobox)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.ComboBox.matches(element[, subrole]) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check. - subrole - (optional) If provided, the field must have the specified subrole.
|
+| **Returns** | true if matches otherwise false
|
+
+### Methods
+
+#### [ComboBox](#combobox)
+| **Signature** | `cp.ui.ComboBox(parent, uiFinder, listAdaptorFn, [, getConvertFn[, setConvertFn]]) -> ComboBox` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Creates a new ComboBox. They have a parent and a finder function. |
+| **Parameters** | - parent - The parent object.
- uiFinder - The function will return the
axuielement for the ComboBox. - listAdaptorFn - A function that will recieve a
List and AXUIElement value and return an Element - getConvertFn - (optional) If provided, will be passed the
string value when returning. - setConvertFn - (optional) If provided, will be passed the
number value when setting.
|
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Dialog.md b/api/cp/cp.ui.Dialog.md
new file mode 100644
index 0000000..a4b420e
--- /dev/null
+++ b/api/cp/cp.ui.Dialog.md
@@ -0,0 +1,9 @@
+# [docs](index.md) » cp.ui.Dialog
+---
+
+Represents a [Window](cp.ui.Window.md) which has a `AXSubrole` of `AXDialog`.
+
+## API Overview
+
+## API Documentation
+
diff --git a/api/cp/cp.ui.DisclosureTriangle.md b/api/cp/cp.ui.DisclosureTriangle.md
new file mode 100644
index 0000000..9652ac4
--- /dev/null
+++ b/api/cp/cp.ui.DisclosureTriangle.md
@@ -0,0 +1,138 @@
+# [docs](index.md) » cp.ui.DisclosureTriangle
+---
+
+Disclosure Triangle UI Module.
+
+This represents an `hs._asm.axuielement` with a `AXDisclosureTriangle` role.
+It allows checking and modifying the `opened` status like so:
+
+```lua
+myButton:opened() == true -- happens to be opened already
+myButton:opened(false) == false -- update to unopened.
+myButton.opened:toggle() == true -- toggled back to being opened.
+```
+
+You can also call instances of `DisclosureTriangle` as a function, which will return
+the `opened` status:
+
+```lua
+myButton() == true -- still true
+myButton(false) == false -- now false
+```
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [DisclosureTriangle](#disclosuretriangle)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [opened](#opened)
+ * [title](#title)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [click](#click)
+ * [doClose](#doclose)
+ * [doOpen](#doopen)
+ * [doPress](#dopress)
+ * [loadLayout](#loadlayout)
+ * [press](#press)
+ * [saveLayout](#savelayout)
+ * [toggle](#toggle)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.DisclosureTriangle.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the provided `hs._asm.axuielement` is a DisclosureTriangle. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | true if it's a match, or false if not.
|
+
+### Constructors
+
+#### [DisclosureTriangle](#disclosuretriangle)
+| **Signature** | `cp.ui.DisclosureTriangle(parent, uiFinder) -> cp.ui.DisclosureTriangle` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new DisclosureTriangle. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | - The new
DisclosureTriangle.
|
+
+### Fields
+
+#### [opened](#opened)
+| **Signature** | `cp.ui.DisclosureTriangle.opened ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Indicates if the disclosure triangle is currently opened. |
+
+#### [title](#title)
+| **Signature** | `cp.ui.DisclosureTriangle.title ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The button title, if available. |
+
+### Methods
+
+#### [click](#click)
+| **Signature** | `cp.ui.DisclosureTriangle:click() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Performs a single mouse click on the triangle. |
+| **Parameters** | |
+| **Returns** | - The
DisclosureTriangle instance.
|
+
+#### [doClose](#doclose)
+| **Signature** | `cp.ui.DisclosureTriangle:doClose() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will ensure the `DisclosureTriangle` is unopened. |
+
+#### [doOpen](#doopen)
+| **Signature** | `cp.ui.DisclosureTriangle:doOpen() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will ensure the `DisclosureTriangle` is opened. |
+
+#### [doPress](#dopress)
+| **Signature** | `cp.ui.DisclosureTriangle:doPress() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will press the button when executed, if available at the time. |
+| **Parameters** | |
+| **Returns** | - The
Statement which will press the button when executed.
|
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.DisclosureTriangle:loadLayout(layout) -> nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Applies the settings in the provided layout table. |
+| **Parameters** | - layout - The table containing layout settings. Usually created by the
saveLayout method.
|
+| **Returns** | |
+
+#### [press](#press)
+| **Signature** | `cp.ui.DisclosureTriangle:press() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to press the button. May fail if the `UI` is not available. |
+| **Parameters** | |
+| **Returns** | The DisclosureTriangle instance.
|
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.DisclosureTriangle:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table containing the layout settings. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [toggle](#toggle)
+| **Signature** | `cp.ui.DisclosureTriangle:toggle() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Toggles the `opened` status of the button. |
+| **Parameters** | |
+| **Returns** | - The
DisclosureTriangle instance.
|
+
diff --git a/api/cp/cp.ui.Element.md b/api/cp/cp.ui.Element.md
new file mode 100644
index 0000000..0074ab2
--- /dev/null
+++ b/api/cp/cp.ui.Element.md
@@ -0,0 +1,208 @@
+# [docs](index.md) » cp.ui.Element
+---
+
+A support class for `hs._asm.axuielement` management.
+
+See:
+* [Button](cp.ui.Button.md)
+* [CheckBox](cp.rx.CheckBox.md)
+* [MenuButton](cp.rx.MenuButton.md)
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Element](#element)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [frame](#frame)
+ * [identifier](#identifier)
+ * [isEnabled](#isenabled)
+ * [isShowing](#isshowing)
+ * [position](#position)
+ * [role](#role)
+ * [size](#size)
+ * [subrole](#subrole)
+ * [textValue](#textvalue)
+ * [title](#title)
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [app](#app)
+ * [doLayout](#dolayout)
+ * [doShow](#doshow)
+ * [focus](#focus)
+ * [loadLayout](#loadlayout)
+ * [parent](#parent)
+ * [saveLayout](#savelayout)
+ * [show](#show)
+ * [snapshot](#snapshot)
+ * [valueIs](#valueis)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Element.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Matches to any valid `hs._asm.axuielement`. Sub-types should provide their own `matches` method. |
+| **Parameters** | |
+| **Returns** | true if the element is a valid instance of an hs._asm.axuielement.
|
+
+### Constructors
+
+#### [Element](#element)
+| **Signature** | `cp.ui.Element(parent, uiFinder) -> cp.ui.Element` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Element` with the specified `parent` and `uiFinder`. |
+| **Parameters** | - parent - The parent Element (may be
nil) - uiFinder - The
function or prop that actually provides the current axuielement instance.
|
+| **Returns** | - The new
Element instance.
|
+
+### Fields
+
+#### [frame](#frame)
+| **Signature** | `cp.ui.Element.frame ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the table containing the `x`, `y`, `w`, and `h` values for the `Element` frame, or `nil` if not available. |
+
+#### [identifier](#identifier)
+| **Signature** | `cp.ui.Element.identifier ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `AX` identifier for the element. |
+
+#### [isEnabled](#isenabled)
+| **Signature** | `cp.ui.Element.isEnabled ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns `true` if the `Element` is visible and enabled. |
+
+#### [isShowing](#isshowing)
+| **Signature** | `cp.ui.Element.isShowing ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | If `true`, the `Element` is showing on screen. |
+
+#### [position](#position)
+| **Signature** | `cp.ui.Element.position ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the table containing the `x` and `y` values for the `Element` frame, or `nil` if not available. |
+
+#### [role](#role)
+| **Signature** | `cp.ui.Element.role ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `AX` role name for the element. |
+
+#### [size](#size)
+| **Signature** | `cp.ui.Element.size ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the table containing the `w` and `h` values for the `Element` frame, or `nil` if not available. |
+
+#### [subrole](#subrole)
+| **Signature** | `cp.ui.Element.subrole ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `AX` subrole name for the element. |
+
+#### [textValue](#textvalue)
+| **Signature** | `cp.ui.Element.textValue ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The 'AXValue' of the element, if it is a `string`. |
+
+#### [title](#title)
+| **Signature** | `cp.ui.Element.title ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The 'AXTitle' of the element. |
+
+#### [value](#value)
+| **Signature** | `cp.ui.Element.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The 'AXValue' of the element. |
+
+### Methods
+
+#### [app](#app)
+| **Signature** | `cp.ui.Element:app() -> App` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the app instance. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [doLayout](#dolayout)
+| **Signature** | `cp.ui.Element:doLayout(layout) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a [Statement](cp.rx.go.Statement.md) which will attempt to load the layout based on the parameters |
+| **Parameters** | - layout - a
table of parameters that will be used to layout the element.
|
+| **Returns** | |
+| **Notes** | - By default, to enable backwards-compatibility, this method will simply call the [#loadLayout]. Override it to provide more optimal asynchonous behaviour if required.
- When subclassing, the overriding
doLayout method should call the parent class's doLayout method,then process any custom values from it, like so: lua function MyElement:doLayout(layout) layout = layout or {} return Do(Element.doLayout(self, layout)) :Then(function() self.myConfig = layout.myConfig end) :Label("MyElement:doLayout") end
|
+
+#### [doShow](#doshow)
+| **Signature** | `cp.ui.Element:doShow() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will ensure the Element is showing. |
+
+#### [focus](#focus)
+| **Signature** | `cp.ui.Element:focus() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Set the focus on an element. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.Element:loadLayout(layout) -> nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | When called, the Element (or subclass) will attempt to load the layout based on the parameters |
+| **Parameters** | - layout - a
table of parameters that will be used to layout the element.
|
+| **Notes** | - When subclassing, the overriding
loadLayout method should call the parent's loadLayout method,then process any custom values from it, like so: function MyElement:loadLayout(layout) Element.loadLayout(self, layout) self.myConfig = layout.myConfig end
|
+
+#### [parent](#parent)
+| **Signature** | `cp.ui.Element:parent() -> parent` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the parent object. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.Element:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` containing the current configuration details for this Element (or subclass). |
+| **Notes** | - When subclassing, the overriding
saveLayout method should call the parent's saveLayout method,then add values to it, like so: function MyElement:saveLayout() local layout = Element.saveLayout(self) layout.myConfig = self.myConfig return layout end
|
+
+#### [show](#show)
+| **Signature** | `cp.ui.Element:show() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Shows the Element. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [snapshot](#snapshot)
+| **Signature** | `cp.ui.Element:snapshot([path]) -> hs.image | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Takes a snapshot of the button in its current state as a PNG and returns it. |
+| **Parameters** | - path - (optional) The path to save the file. Should include the extension (should be
.png).
|
+
+#### [valueIs](#valueis)
+| **Signature** | `cp.ui.Element.valueIs(value) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if the current value of this element is the provided value. |
+| **Parameters** | - value - The value to compare to.
|
+| **Returns** | true if the current [#value] is equal to the provided value.
|
+
diff --git a/api/cp/cp.ui.ElementCache.md b/api/cp/cp.ui.ElementCache.md
new file mode 100644
index 0000000..c8cf908
--- /dev/null
+++ b/api/cp/cp.ui.ElementCache.md
@@ -0,0 +1,79 @@
+# [docs](index.md) » cp.ui.ElementCache
+---
+
+Provides caching for [Element](cp.ui.Element.md) subclasses that want to cache children.
+
+## API Overview
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [ElementCache](#elementcache)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [cachedElement](#cachedelement)
+ * [cacheElement](#cacheelement)
+ * [clean](#clean)
+ * [fetchElement](#fetchelement)
+ * [fetchElements](#fetchelements)
+ * [reset](#reset)
+
+## API Documentation
+
+### Constructors
+
+#### [ElementCache](#elementcache)
+| **Signature** | `cp.ui.ElementCache(parent[, createFn])` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates and returns a new `ElementCache`, with the specified parent and function which |
+| **Parameters** | - parent - the parent Element that contains the cached items.
- createFn - a function that will create new
Element subclasses based on cached axuielement values.
|
+| **Returns** | |
+
+### Methods
+
+#### [cachedElement](#cachedelement)
+| **Signature** | `cp.ui.ElementCache:cachedElement(cache, ui) -> cp.ui.Element or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the cached [Element](cp.ui.Element.md), if it is present. |
+| **Parameters** | - ui - The
axuielement it is linked to. If not provided, it will be fetched by calling Element:UI().
|
+| **Returns** | |
+
+#### [cacheElement](#cacheelement)
+| **Signature** | `cp.ui.ElementCache:cacheElement(element[, ui]) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Caches the provided [Element](cp.ui.Element.md). |
+| **Parameters** | - element - The Element
- ui - The
axuielement it is linked to. If not provided, it will be fetched by calling Element:UI().
|
+| **Returns** | |
+
+#### [clean](#clean)
+| **Signature** | `cp.ui.ElementCache:clean()` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Clears the cache of any invalid (aka dead) items. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [fetchElement](#fetchelement)
+| **Signature** | `cp.ui.ElementCache:fetchElement(ui) -> cp.ui.Element or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Retrieves the matching [Element](cp.ui.Element.md) instance from the cache. |
+| **Parameters** | - ui - The
axuielement being fetched for.
|
+| **Returns** | |
+
+#### [fetchElements](#fetchelements)
+| **Signature** | `cp.ui.ElementCache:fetchElements(uis) -> table of cp.ui.Elements or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Fetches a list of [Element](cp.ui.Element.md) instances linked to the provided `axuielement` list. |
+| **Parameters** | - uis - A
table of axuielement values.
|
+| **Returns** | |
+| **Notes** | - If any of the provided
axuielement values are either not from the parent, or no longer valid, a nil value will be stored in the matching index. Note that in that case, this will break useage of ipairs due to leaving holes in the list.
|
+
+#### [reset](#reset)
+| **Signature** | `cp.ui.ElementCache:reset() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Removes all cached items from the cache. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Grid.md b/api/cp/cp.ui.Grid.md
new file mode 100644
index 0000000..257bae2
--- /dev/null
+++ b/api/cp/cp.ui.Grid.md
@@ -0,0 +1,221 @@
+# [docs](index.md) » cp.ui.Grid
+---
+
+Abstract base class for `AX` elements which form a grid, such as [Table2](cp.ui.Table2.md) and [Outline](cp.ui.Outline.md).
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [is](#is)
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Grid](#grid)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [selectedRows](#selectedrows)
+ * [selectedRowsUI](#selectedrowsui)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [childrenUI](#childrenui)
+ * [column](#column)
+ * [columns](#columns)
+ * [columnsUI](#columnsui)
+ * [createColumn](#createcolumn)
+ * [createRow](#createrow)
+ * [doSelectRow](#doselectrow)
+ * [fetchColumn](#fetchcolumn)
+ * [fetchRow](#fetchrow)
+ * [fetchRows](#fetchrows)
+ * [filterRows](#filterrows)
+ * [findCell](#findcell)
+ * [findColumnIndex](#findcolumnindex)
+ * [findRow](#findrow)
+ * [row](#row)
+ * [rows](#rows)
+ * [rowsUI](#rowsui)
+ * [selectRow](#selectrow)
+ * [visitRow](#visitrow)
+
+## API Documentation
+
+### Functions
+
+#### [is](#is)
+| **Signature** | `cp.ui.Grid.is(thing) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `thing` is a `Grid`. |
+| **Parameters** | thing - The thing to check
|
+| **Returns** | true if the thing is a Table instance.
|
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Grid.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `element` is an `Grid`. |
+
+### Constructors
+
+#### [Grid](#grid)
+| **Signature** | `cp.ui.Grid(parent, uiFinder) -> cp.ui.Grid` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Grid` with the specified `parent` and `uiFinder`. |
+| **Parameters** | - parent - The parent instance.
- uiFinder - A
function or a cp.prop which will return the axuielement.
|
+| **Returns** | |
+
+### Fields
+
+#### [selectedRows](#selectedrows)
+| **Signature** | `cp.ui.Grid.selectedRows ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Contains the list of currently-selected [Row](cp.ui.Row.md)s. Can be set. |
+
+#### [selectedRowsUI](#selectedrowsui)
+| **Signature** | `cp.ui.Grid.selectedRowsUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Contains the list of currently-selected row `axuilements`. Can be set. |
+| **Notes** | |
+
+### Methods
+
+#### [childrenUI](#childrenui)
+| **Signature** | `cp.ui.Grid:childrenUI() -> table of axuielements` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` containing the `axuielement`s which are children of the outline. |
+
+#### [column](#column)
+| **Signature** | `cp.ui.Grid:column(index) -> cp.ui.Column or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides the [Column](cp.ui.Column.md) at the specified index, or `nil` if it's not available. |
+
+#### [columns](#columns)
+| **Signature** | `cp.ui.Grid:columns() -> table of cp.ui.Columns` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the list of [Column](cp.ui.Column.md)s. |
+
+#### [columnsUI](#columnsui)
+| **Signature** | `cp.ui.Grid:columnsUI() -> table of axuielements` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` containing the `axuielement`s which are columns of the outline. |
+
+#### [createColumn](#createcolumn)
+| **Signature** | `cp.ui.Grid:createColumn(columnUI) -> cp.ui.Column` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to create a new [Column](cp.ui.Column.md) with the provided `columnUI` `axuielement`. |
+| **Parameters** | - columnUI - the
AXColumn axuielement to create a Column for.
|
+| **Returns** | - The Column or an error if a problem occurred.
|
+| **Notes** | - Subclasses which want to provide a custom Column implementation should override this method.
|
+
+#### [createRow](#createrow)
+| **Signature** | `cp.ui.Grid:createRow(rowUI) -> cp.ui.Row` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to create a new [Row](cp.ui.Row.md) with the provided `rowUI` `axuielement`. |
+| **Parameters** | - rowUI - the
AXRow axuielement to create a Row for.
|
+| **Returns** | - The Row or an error if a problem occurred.
|
+| **Notes** | - Subclasses which want to provide a custom Row implementation should override this method.
|
+
+#### [doSelectRow](#doselectrow)
+| **Signature** | `cp.ui.Grid:doSelectRow(path) -> [Statement](cp.rx.go.Statement.md)` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Selects the row at the sub-level named in the `path` table. |
+| **Parameters** | - path - A
table of names to navigate through to find the Row to select.
|
+| **Returns** | - The selected Row, or
nil if not found.
|
+
+#### [fetchColumn](#fetchcolumn)
+| **Signature** | `cp.ui.Grid:fetchColumn(columnsUI) -> table of cp.ui.Columns` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` of the same length as `columnsUI`. |
+| **Parameters** | - columnsUI - The list of
AXColumn axuielements to find.
|
+| **Returns** | - A
table with the same number of elements, containing the matching Column instances.
|
+
+#### [fetchRow](#fetchrow)
+| **Signature** | `cp.ui.Grid:fetchRow(rowUI) -> cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the [Row](cp.ui.Row.md) that represents the provided `rowUI`, if it is actually present. |
+| **Parameters** | - rowUI - The
axuielement for the AXRow to find a Row for.
|
+| **Returns** | - The Row, or
nil if the rowUI is not available.
|
+
+#### [fetchRows](#fetchrows)
+| **Signature** | `cp.ui.Grid:fetchRows(rowsUI) -> table of cp.ui.Rows` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` of the same length as `rowsUI`. |
+| **Parameters** | - rowsUI - The list of
AXRow axuielements to find.
|
+| **Returns** | - A
table with the same number of elements, containing the matching Row instances.
|
+
+#### [filterRows](#filterrows)
+| **Signature** | `cp.ui.Grid:filterRows(matcherFn) -> table of cp.ui.Rows or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table only containing [Row](cp.ui.Row.md)s which pass the predicate `matcherFn`. |
+| **Parameters** | - matcherFn - the
function that will accept a Row and return a boolean.
|
+| **Returns** | - A
table of Rows, or nil if no UI is currently available.
|
+
+#### [findCell](#findcell)
+| **Signature** | `cp.ui.Grid:findCell(rowNumber, columnId) -> `hs._asm.axuielement` | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Finds a specific [Cell](cp.ui.Cell.md). |
+| **Parameters** | - rowNumber - The row number.
- columnId - The Column ID.
|
+| **Returns** | - A
hs._asm.axuielement object for the cell, or nil if the cell cannot be found.
|
+
+#### [findColumnIndex](#findcolumnindex)
+| **Signature** | `cp.ui.Grid:findColumnIndex(id) -> number | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Finds the Column Index based on an `AXIdentifier` ID. |
+| **Parameters** | - id - The
AXIdentifier of the column index you want to find.
|
+| **Returns** | - A column index as a number, or
nil if no index can be found.
|
+
+#### [findRow](#findrow)
+| **Signature** | `cp.ui.Grid:findRow(matcherFn) -> cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a [Row](cp.ui.Row.md) that has a result of `true` when passed to the `matcherFn` predicate, |
+| **Parameters** | - matcherFn - The function to check the Row with.
|
+| **Returns** | |
+
+#### [row](#row)
+| **Signature** | `cp.ui.Grid:row(index) -> cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides the [Row](cp.ui.Row.md) at the specified index, or `nil` if it's not available. |
+
+#### [rows](#rows)
+| **Signature** | `cp.ui.Grid:rows() -> table of cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` with the list of `cp.ui.Row` elements for the rows. |
+| **Returns** | - A table containing the list of Rows, or
nil if not presently available.
|
+
+#### [rowsUI](#rowsui)
+| **Signature** | `cp.ui.Grid:rowsUI() -> table of axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` containing the `axuielement`s which are rows in the outline. |
+
+#### [selectRow](#selectrow)
+| **Signature** | `cp.ui.Grid:selectRow(path) -> cp.ui.Row` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Selects the row at the sub-level named in the `path` table. |
+| **Parameters** | - path - A
table of names to navigate through to find the Row to select.
|
+| **Returns** | - The selected Row, or
nil if not found.
|
+
+#### [visitRow](#visitrow)
+| **Signature** | `cp.ui.Grid:visitRow(path, actionFn) -> cp.ui.Row` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Visits the row at the sub-level named in the `names` table, and executes the `actionFn`. |
+| **Parameters** | names - The array of names to navigate downactionFn - A function to execute when the target row is found.
|
+| **Returns** | - The row that was visited, or
nil if not.
|
+
diff --git a/api/cp/cp.ui.Group.md b/api/cp/cp.ui.Group.md
new file mode 100644
index 0000000..2f397dc
--- /dev/null
+++ b/api/cp/cp.ui.Group.md
@@ -0,0 +1,42 @@
+# [docs](index.md) » cp.ui.Group
+---
+
+UI Group.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [contents](#contents)
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Group](#group)
+
+## API Documentation
+
+### Functions
+
+#### [contents](#contents)
+| **Signature** | `cp.ui.Group.contents(element) -> axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns the `AXContents` of the element, if it is an `AXGroup`. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | - The list of
axuielements for the AXContents of the AXGroup, or nil.
|
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Group.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [Group](#group)
+| **Signature** | `cp.ui.Group(parent, uiFinder[, contentsClass]) -> Alert` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Group` instance. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Image.md b/api/cp/cp.ui.Image.md
new file mode 100644
index 0000000..04d5273
--- /dev/null
+++ b/api/cp/cp.ui.Image.md
@@ -0,0 +1,23 @@
+# [docs](index.md) » cp.ui.Image
+---
+
+Represents an `AXImage` `axuielement` value.
+
+Extends [Element](cp.ui.Element.md).
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Image.matches(element)` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the provided `axuielement` is an `AXImage`. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | true if it is an AXImage, otherwise false.
|
+
diff --git a/api/cp/cp.ui.List.md b/api/cp/cp.ui.List.md
new file mode 100644
index 0000000..6bf151b
--- /dev/null
+++ b/api/cp/cp.ui.List.md
@@ -0,0 +1,45 @@
+# [docs](index.md) » cp.ui.List
+---
+
+Represents an `AXList` `axuielement` value.
+
+Extends [Element](cp.ui.Element.md).
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [List](#list)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [items](#items)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.List.matches(element)` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the provided `axuielement` is an `AXList`. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | true if it is an AXList, otherwise false.
|
+
+### Constructors
+
+#### [List](#list)
+| **Signature** | `cp.ui.List(parent, uiFinder, itemAdaptorFn)` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new List. |
+| **Parameters** | - parent - The parent table. Should have a
isShowing property. - uiFinder - The
function or cp.prop that provides the current hs._asm.axuielement.
|
+| **Returns** | |
+
+### Methods
+
+#### [items](#items)
+| **Signature** | `cp.ui.List:items() -> table of values` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the children as items, as adapted by the `itemAdaptor` in the constructor |
+
diff --git a/api/cp/cp.ui.Menu.md b/api/cp/cp.ui.Menu.md
new file mode 100644
index 0000000..6686495
--- /dev/null
+++ b/api/cp/cp.ui.Menu.md
@@ -0,0 +1,63 @@
+# [docs](index.md) » cp.ui.Menu
+---
+
+UI for AXMenus.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Menu](#menu)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [cancel](#cancel)
+ * [doSelectItem](#doselectitem)
+ * [doSelectValue](#doselectvalue)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Menu.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [Menu](#menu)
+| **Signature** | `cp.ui.Menu(parent, uiFinder) -> Menu` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Menu` instance. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | |
+
+### Methods
+
+#### [cancel](#cancel)
+| **Signature** | `cp.ui.Menu:cancel() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Closes a menu. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [doSelectItem](#doselectitem)
+| **Signature** | `cp.ui.Menu:doSelectItem(index) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will select an item on the `MenuButton` by index. |
+| **Parameters** | - index - The index number of the item to match.
|
+| **Returns** | |
+
+#### [doSelectValue](#doselectvalue)
+| **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** | - 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
new file mode 100644
index 0000000..61ab48b
--- /dev/null
+++ b/api/cp/cp.ui.MenuButton.md
@@ -0,0 +1,185 @@
+# [docs](index.md) » cp.ui.MenuButton
+---
+
+Menu Button Module.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [MenuButton](#menubutton)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [menuUI](#menuui)
+ * [title](#title)
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [doPress](#dopress)
+ * [doSelectItem](#doselectitem)
+ * [doSelectItemMatching](#doselectitemmatching)
+ * [doSelectValue](#doselectvalue)
+ * [doShowMenu](#doshowmenu)
+ * [getTitle](#gettitle)
+ * [getValue](#getvalue)
+ * [loadLayout](#loadlayout)
+ * [press](#press)
+ * [saveLayout](#savelayout)
+ * [selectItem](#selectitem)
+ * [selectItemMatching](#selectitemmatching)
+ * [setValue](#setvalue)
+ * [show](#show)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.MenuButton.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [MenuButton](#menubutton)
+| **Signature** | `cp.ui.MenuButton(parent, uiFinder) -> MenuButton` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new MenuButton. |
+| **Parameters** | - parent - The parent object. Should have an
isShowing property. - uiFinder - A
cp.prop or function which will return a hs._asm.axuielement, or nil if it's not available.
|
+
+### Fields
+
+#### [menuUI](#menuui)
+| **Signature** | `cp.ui.MenuButton.menuUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `AXMenu` for the MenuButton if it is currently visible. |
+
+#### [title](#title)
+| **Signature** | `cp.ui.MenuButton.title ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the title for the MenuButton. |
+
+#### [value](#value)
+| **Signature** | `cp.ui.MenuButton.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns or sets the current MenuButton value. |
+
+### Methods
+
+#### [doPress](#dopress)
+| **Signature** | `cp.ui.MenuButton:doPress() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that presses the `MenuButton`. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [doSelectItem](#doselectitem)
+| **Signature** | `cp.ui.MenuButton:doSelectItem(index) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will select an item on the `MenuButton` by index. |
+| **Parameters** | - index - The index number of the item to match.
|
+| **Returns** | |
+
+#### [doSelectItemMatching](#doselectitemmatching)
+| **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.
- [altPattern] - An optional alternate pattern to match if the first pattern fails.
|
+| **Returns** | |
+
+#### [doSelectValue](#doselectvalue)
+| **Signature** | `cp.ui.MenuButton:doSelectValue(value) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will select an item on the `MenuButton` by value. |
+| **Parameters** | - value - The value of the item to match.
|
+| **Returns** | |
+
+#### [doShowMenu](#doshowmenu)
+| **Signature** | `cp.ui.MenuButton:doShowMenu() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that presses the `MenuButton` if the menu is not showing. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [getTitle](#gettitle)
+| **Signature** | `cp.ui.MenuButton:getTitle() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the `MenuButton` title. |
+| **Parameters** | |
+| **Returns** | - The
MenuButton title as string, or nil if the title cannot be determined.
|
+
+#### [getValue](#getvalue)
+| **Signature** | `cp.ui.MenuButton:getValue() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the `MenuButton` value. |
+| **Parameters** | |
+| **Returns** | - The
MenuButton value as string, or nil if the value cannot be determined.
|
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.MenuButton:loadLayout(layout) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads a `MenuButton` layout. |
+| **Parameters** | - layout - A table containing the
MenuButton layout settings - created using saveLayout.
|
+| **Returns** | |
+
+#### [press](#press)
+| **Signature** | `cp.ui.MenuButton:press() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Presses the MenuButton. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.MenuButton:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the current `MenuButton` layout to a table. |
+| **Parameters** | |
+| **Returns** | - A table containing the current
MenuButton Layout.
|
+
+#### [selectItem](#selectitem)
+| **Signature** | `cp.ui.MenuButton:selectItem(index) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Select an item on the `MenuButton` by index. |
+| **Parameters** | - index - The index of the item you want to select.
|
+| **Returns** | true if successfully selected, otherwise false.
|
+
+#### [selectItemMatching](#selectitemmatching)
+| **Signature** | `cp.ui.MenuButton:selectItemMatching(pattern) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Select an item on the `MenuButton` by pattern. |
+| **Parameters** | - pattern - A pattern used to select the
MenuButton item.
|
+| **Returns** | true if successfully selected, otherwise false.
|
+
+#### [setValue](#setvalue)
+| **Signature** | `cp.ui.MenuButton:setValue(value) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets the `MenuButton` value. |
+| **Parameters** | - value - The value you want to set the
MenuButton to.
|
+| **Returns** | |
+
+#### [show](#show)
+| **Signature** | `cp.ui.MenuButton:show() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Show's the MenuButton. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Outline.md b/api/cp/cp.ui.Outline.md
new file mode 100644
index 0000000..cb58804
--- /dev/null
+++ b/api/cp/cp.ui.Outline.md
@@ -0,0 +1,126 @@
+# [docs](index.md) » cp.ui.Outline
+---
+
+Represents an `AXOutline` `axuielement`.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Outline](#outline)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [childrenUI](#childrenui)
+ * [columns](#columns)
+ * [columnsUI](#columnsui)
+ * [createColumn](#createcolumn)
+ * [createRow](#createrow)
+ * [fetchColumn](#fetchcolumn)
+ * [fetchRow](#fetchrow)
+ * [fetchRows](#fetchrows)
+ * [filterRows](#filterrows)
+ * [rows](#rows)
+ * [rowsUI](#rowsui)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Outline.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `element` is an `Outline`. |
+
+### Constructors
+
+#### [Outline](#outline)
+| **Signature** | `cp.ui.Outline(parent, uiFinder) -> cp.ui.Outline` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Outline` with the specified `parent` and `uiFinder`. |
+| **Parameters** | - parent - The parent instance.
- uiFinder - A
function or a cp.prop which will return the AXOutline axuielement.
|
+| **Returns** | - The new
Outline instance.
|
+
+### Methods
+
+#### [childrenUI](#childrenui)
+| **Signature** | `cp.ui.Outline:childrenUI() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` containing the `axuielement`s which are children of the outline. |
+
+#### [columns](#columns)
+| **Signature** | `cp.ui.Outline:columns() -> table of cp.ui.Columns` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the list of [Column](cp.ui.Column.md)s in this `Outline`. |
+
+#### [columnsUI](#columnsui)
+| **Signature** | `cp.ui.Outline:columnsUI() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` containing the `axuielement`s which are columns of the outline. |
+
+#### [createColumn](#createcolumn)
+| **Signature** | `cp.ui.Outline:createColumn(columnUI) -> cp.ui.Column` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to create a new [Column](cp.ui.Column.md) with the provided `columnUI` `axuielement`. |
+| **Parameters** | - columnUI - the
AXColumn axuielement to create a Column for.
|
+| **Returns** | - The Column or an error if a problem occurred.
|
+| **Notes** | - Subclasses which want to provide a custom Column implementation should override this method.
|
+
+#### [createRow](#createrow)
+| **Signature** | `cp.ui.Outline:createRow(rowUI) -> cp.ui.Row` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to create a new [Row](cp.ui.Row.md) with the provided `rowUI` `axuielement`. |
+| **Parameters** | - rowUI - the
AXRow axuielement to create a Row for.
|
+| **Returns** | - The Row or an error if a problem occurred.
|
+| **Notes** | - Subclasses which want to provide a custom Row implementation should override this method.
|
+
+#### [fetchColumn](#fetchcolumn)
+| **Signature** | `cp.ui.Outline:fetchColumn(columnsUI) -> table of cp.ui.Columns` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` of the same length as `columnsUI`. |
+| **Parameters** | - columnsUI - The list of
AXColumn axuielements to find.
|
+| **Returns** | - A
table with the same number of elements, containing the matching Column instances.
|
+
+#### [fetchRow](#fetchrow)
+| **Signature** | `cp.ui.Outline:fetchRow(rowUI) -> cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the [Row](cp.ui.Row.md) that represents the provided `rowUI`, if it is actually present |
+| **Parameters** | - rowUI - The
axuielement for the AXRow to find a Row for.
|
+| **Returns** | - The Row, or
nil if the rowUI is not in this Outline.
|
+
+#### [fetchRows](#fetchrows)
+| **Signature** | `cp.ui.Outline:fetchRows(rowsUI) -> table of cp.ui.Rows` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` of the same length as `rowsUI`. |
+| **Parameters** | - rowsUI - The list of
AXRow axuielements to find.
|
+| **Returns** | - A
table with the same number of elements, containing the matching Row instances.
|
+
+#### [filterRows](#filterrows)
+| **Signature** | `cp.ui.Outline:filterRows(matcherFn) -> table of cp.ui.Rows or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a table only containing [Row](cp.ui.Row.md)s which pass the predicate `matcherFn`. |
+| **Parameters** | - matcherFn - the
function that will accept a Row and return a boolean.
|
+| **Returns** | - A
table of Rows, or nil if no UI is currently available.
|
+
+#### [rows](#rows)
+| **Signature** | `cp.ui.Outline:rows() -> table of cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` with the list of `cp.ui.Row` elements for the rows. |
+| **Returns** | - A table containing the list of Rows in the
Outline, or nil if the Outline is not presently available.
|
+
+#### [rowsUI](#rowsui)
+| **Signature** | `cp.ui.Outline:rowsUI() -> table of axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Provides a `table` containing the `axuielement`s which are rows in the outline. |
+
diff --git a/api/cp/cp.ui.PopUpButton.md b/api/cp/cp.ui.PopUpButton.md
index 56e4538..efbf897 100644
--- a/api/cp/cp.ui.PopUpButton.md
+++ b/api/cp/cp.ui.PopUpButton.md
@@ -5,15 +5,130 @@ Pop Up Button Module.
## API Overview
* Functions - API calls offered directly by the extension
- * [new](#new)
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [PopUpButton](#popupbutton)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [menuUI](#menuui)
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [doPress](#dopress)
+ * [doSelectItem](#doselectitem)
+ * [doSelectValue](#doselectvalue)
+ * [getValue](#getvalue)
+ * [loadLayout](#loadlayout)
+ * [press](#press)
+ * [saveLayout](#savelayout)
+ * [selectItem](#selectitem)
+ * [setValue](#setvalue)
## API Documentation
### Functions
-#### [new](#new)
-| **Signature** | `cp.ui.PopUpButton:new(axuielement, function) -> PopUpButton` |
+#### [matches](#matches)
+| **Signature** | `cp.ui.PopUpButton.matches(element) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Creates a new PopUpButton |
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [PopUpButton](#popupbutton)
+| **Signature** | `cp.ui.PopUpButton(parent, uiFinder) -> cp.ui.PopUpButton` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new PopUpButton. |
+| **Parameters** | - parent - The parent table. Should have a
isShowing property. - uiFinder - The
function or cp.prop that provides the current hs._asm.axuielement.
|
+| **Returns** | - The new
PopUpButton instance.
|
+
+### Fields
+
+#### [menuUI](#menuui)
+| **Signature** | `cp.ui.PopUpButton.menuUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `AXMenu` for the PopUpMenu if it is currently visible. |
+
+#### [value](#value)
+| **Signature** | `cp.ui.PopUpButton.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns or sets the current `PopUpButton` value. |
+
+### Methods
+
+#### [doPress](#dopress)
+| **Signature** | `cp.ui.PopUpButton:doPress() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that presses the `PopUpButton`. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [doSelectItem](#doselectitem)
+| **Signature** | `cp.ui.PopUpButton:doSelectItem(index) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will select an item on the `PopUpButton` by index. |
+| **Parameters** | - index - The index number of the item you want to select.
|
+| **Returns** | |
+
+#### [doSelectValue](#doselectvalue)
+| **Signature** | `cp.ui.PopUpButton:doSelectValue(value) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will select an item on the `PopUpButton` by value. |
+| **Parameters** | - value - The value of the item to match.
|
+| **Returns** | |
+
+#### [getValue](#getvalue)
+| **Signature** | `cp.ui.PopUpButton:getValue() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the `PopUpButton` value. |
+| **Parameters** | |
+| **Returns** | - The
PopUpButton value as string, or nil if the value cannot be determined.
|
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.PopUpButton:loadLayout(layout) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads a `PopUpButton` layout. |
+| **Parameters** | - layout - A table containing the
PopUpButton layout settings - created using saveLayout.
|
+| **Returns** | |
+
+#### [press](#press)
+| **Signature** | `cp.ui.PopUpButton:press() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Presses the `PopUpButton`. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.PopUpButton:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the current `PopUpButton` layout to a table. |
+| **Parameters** | |
+| **Returns** | - A table containing the current
PopUpButton Layout.
|
+
+#### [selectItem](#selectitem)
+| **Signature** | `cp.ui.PopUpButton:selectItem(index) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Select an item on the `PopUpButton` by index. |
+| **Parameters** | - index - The index of the item you want to select.
|
+| **Returns** | |
+
+#### [setValue](#setvalue)
+| **Signature** | `cp.ui.PopUpButton:setValue(value) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets the `PopUpButton` value. |
+| **Parameters** | - value - The value you want to set the
PopUpButton to.
|
+| **Returns** | |
diff --git a/api/cp/cp.ui.Popover.md b/api/cp/cp.ui.Popover.md
new file mode 100644
index 0000000..092b83c
--- /dev/null
+++ b/api/cp/cp.ui.Popover.md
@@ -0,0 +1,45 @@
+# [docs](index.md) » cp.ui.Popover
+---
+
+UI Group.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Popover](#popover)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [hide](#hide)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Popover.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [Popover](#popover)
+| **Signature** | `cp.ui.Popover(parent, uiFinder) -> Popover` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Popover` instance. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | |
+
+### Methods
+
+#### [hide](#hide)
+| **Signature** | `cp.ui.Popover:hide() -> Popover` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Hides a popover. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.PropertyRow.md b/api/cp/cp.ui.PropertyRow.md
new file mode 100644
index 0000000..05188b1
--- /dev/null
+++ b/api/cp/cp.ui.PropertyRow.md
@@ -0,0 +1,191 @@
+# [docs](index.md) » cp.ui.PropertyRow
+---
+
+Represents a single property row, typically in a Property Inspector.
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [intersectBuffer](#intersectbuffer)
+* Functions - API calls offered directly by the extension
+ * [isParent](#isparent)
+ * [matches](#matches)
+ * [parentUIFinder](#parentuifinder)
+ * [prepareParent](#prepareparent)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [PropertyRow](#propertyrow)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [label](#label)
+ * [labelUI](#labelui)
+ * [propertiesUI](#propertiesui)
+ * [reset](#reset)
+ * [UI](#ui)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [app](#app)
+ * [children](#children)
+ * [doHide](#dohide)
+ * [doShow](#doshow)
+ * [extend](#extend)
+ * [hide](#hide)
+ * [labelKeys](#labelkeys)
+ * [parent](#parent)
+ * [show](#show)
+
+## API Documentation
+
+### Constants
+
+#### [intersectBuffer](#intersectbuffer)
+| **Signature** | `cp.ui.PropertyRow.intersectBuffer` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | Defines the buffer for intersections with the `labelUI`. |
+
+### Functions
+
+#### [isParent](#isparent)
+| **Signature** | `cp.ui.PropertyRow.isParent(parent) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `parent` has been prepared via [prepareParent](#prepareParent). |
+| **Parameters** | |
+| **Returns** | true if the parent is prepared.
|
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.PropertyRow.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the provided `axuielement` could be a property row. |
+| **Parameters** | - element - The element to check.
|
+| **Returns** | true if the element could be a property row.
|
+
+#### [parentUIFinder](#parentuifinder)
+| **Signature** | `cp.ui.PropertyRow.parentUIFinder(parent) -> cp.prop` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns the `cp.prop` which finds the `hs._asm.axuielement` that contains property rows from the parent. |
+| **Parameters** | - parent - The parent which has a finder assigned.
|
+| **Returns** | - The
cp.prop which provides access to the finder, or nil.
|
+
+#### [prepareParent](#prepareparent)
+| **Signature** | `cp.ui.PropertyRow.prepareParent(parent, uiFinder) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Call this to make `parent` table ready to be a parent of `PropertyRow`s. |
+| **Parameters** | - parent - The parent table.
- uiFinder - The function or cp.prop which will be called to find the parent UI element. Functions will be passed the
parent when being executed.
|
+| **Returns** | |
+
+### Constructors
+
+#### [PropertyRow](#propertyrow)
+| **Signature** | `cp.ui.PropertyRow(parent, labelKey[, index]) -> cp.ui.PropertyRow` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `PropertyRow` with the specified parent and label key. |
+| **Parameters** | - parent - The parent object.
- labelKey - The key of the label that the row will map to.
- index - The row number with the same label to get. Defaults to
1.
|
+| **Returns** | - The new
PropertyRow instance.
|
+
+### Fields
+
+#### [label](#label)
+| **Signature** | `cp.ui.PropertyRow.label ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The label of the property row, in the current langauge. |
+
+#### [labelUI](#labelui)
+| **Signature** | `cp.ui.PropertyRow.labelUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `axuielement` for the label UI. |
+
+#### [propertiesUI](#propertiesui)
+| **Signature** | `cp.ui.PropertyRow.propertiesUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The `axuielement` from the parent that contains the properties. |
+
+#### [reset](#reset)
+| **Signature** | `cp.ui.PropertyRow.reset ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The `reset` button for the row, which may or may not actually exist. |
+
+#### [UI](#ui)
+| **Signature** | `cp.ui.PropertyRow.UI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `axuielement` for the row. |
+
+### Methods
+
+#### [app](#app)
+| **Signature** | `cp.ui.PropertyRow:app() -> App` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the app instance. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [children](#children)
+| **Signature** | `cp.ui.PropertyRow:children() -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets a table of children for the Property Row. |
+| **Parameters** | |
+| **Returns** | - A table of children or
nil.
|
+
+#### [doHide](#dohide)
+| **Signature** | `cp.ui.PropertyRow:doHide() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will attempt to hide the `PropertyRow`. |
+| **Returns** | |
+
+#### [doShow](#doshow)
+| **Signature** | `cp.ui.PropertyRow:doShow() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that shows the `PropertyRow`. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [extend](#extend)
+| **Signature** | `cp.ui.PropertyRow:extend(extendFn) -> cp.ui.PropertyRow` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | This method will call the provided function, passing it the current `PropertyRow`. |
+| **Parameters** | - extendFn - A
function that will be passed the current row.
|
+| **Returns** | - The same
PropertyRow instance.
|
+
+#### [hide](#hide)
+| **Signature** | `cp.ui.PropertyRow:hide() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Hides the `PropertyRow`. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [labelKeys](#labelkeys)
+| **Signature** | `cp.ui.PropertyRow:labelKeys() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the key of the label that the row will map to. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [parent](#parent)
+| **Signature** | `cp.ui.PropertyRow:parent() -> parent` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the parent object. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [show](#show)
+| **Signature** | `cp.ui.PropertyRow:show() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Shows the `PropertyRow`. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.RadioButton.md b/api/cp/cp.ui.RadioButton.md
index d414900..a58b040 100644
--- a/api/cp/cp.ui.RadioButton.md
+++ b/api/cp/cp.ui.RadioButton.md
@@ -3,17 +3,137 @@
Radio Button Module.
+This represents an `hs._asm.axuielement` with a `AXRadioButton` role.
+It allows checking and modifying the `checked` status like so:
+
+```lua
+myButton:checked() == true -- happens to be checked already
+myButton:checked(false) == false -- update to unchecked.
+myButton.checked:toggle() == true -- toggled back to being checked.
+```
+
+You can also call instances of `RadioButton` as a function, which will return
+the `checked` status:
+
+```lua
+myButton() == true -- still true
+myButton(false) == false -- now false
+```
+
## API Overview
* Functions - API calls offered directly by the extension
- * [new](#new)
+ * [matches](#matches)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [checked](#checked)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [doCheck](#docheck)
+ * [doLayout](#dolayout)
+ * [doPress](#dopress)
+ * [doToggle](#dotoggle)
+ * [doUncheck](#douncheck)
+ * [loadLayout](#loadlayout)
+ * [press](#press)
+ * [RadioButton](#radiobutton)
+ * [saveLayout](#savelayout)
+ * [toggle](#toggle)
## API Documentation
### Functions
-#### [new](#new)
-| **Signature** | `cp.ui.RadioButton:new(axuielement, function) -> RadioButton` |
+#### [matches](#matches)
+| **Signature** | `cp.ui.RadioButton.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the provided `hs._asm.axuielement` is a RadioButton. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | true if it's a match, or false if not.
|
+
+### Fields
+
+#### [checked](#checked)
+| **Signature** | `cp.ui.RadioButton.checked ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Indicates if the checkbox is currently checked. |
+
+### Methods
+
+#### [doCheck](#docheck)
+| **Signature** | `cp.ui.RadioButton:doCheck() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will check the button value when executed, if available at the time. |
+| **Parameters** | |
+| **Returns** | - The
Statement which will toggle the button when executed.
|
+
+#### [doLayout](#dolayout)
+| **Signature** | `cp.ui.RadioButton:doLayout(layout) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a [Statement](cp.rx.go.Statement.md) that will apply the layout provided, if possible. |
+| **Parameters** | - layout - the
table containing the layout configuration. Usually created via the [#saveLayout] method.
|
+| **Returns** | |
+
+#### [doPress](#dopress)
+| **Signature** | `cp.ui.RadioButton:doPress() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will press the button when executed, if available at the time. |
+| **Parameters** | |
+| **Returns** | - The
Statement which will press the button when executed.
|
+
+#### [doToggle](#dotoggle)
+| **Signature** | `cp.ui.RadioButton:doToggle() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will toggle the button value when executed, if available at the time. |
+| **Parameters** | |
+| **Returns** | - The
Statement which will toggle the button when executed.
|
+
+#### [doUncheck](#douncheck)
+| **Signature** | `cp.ui.RadioButton:doUncheck() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will uncheck the button value when executed, if available at the time. |
+| **Parameters** | |
+| **Returns** | - The
Statement which will toggle the button when executed.
|
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.RadioButton:loadLayout(layout) -> nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Processes the `layout` table to restore this to match the provided `layout`. |
+| **Parameters** | - layout - the table of state values to restore to.
|
+
+#### [press](#press)
+| **Signature** | `cp.ui.RadioButton:press() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to press the button. May fail if the `UI` is not available. |
+| **Parameters** | |
+| **Returns** | The RadioButton instance.
|
+
+#### [RadioButton](#radiobutton)
+| **Signature** | `cp.ui.RadioButton(axuielement, function) -> RadioButton` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Creates a new RadioButton. |
+| **Parameters** | - parent - The parent object.
- finderFn - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.RadioButton:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `table` with the button's current state. This can be passed to [#loadLayout] |
+| **Returns** | - The table of the layout state.
|
+
+#### [toggle](#toggle)
+| **Signature** | `cp.ui.RadioButton:toggle() -> self` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Creates a new RadioButton |
+| **Type** | Method |
+| **Description** | Toggles the `checked` status of the button. |
+| **Parameters** | |
+| **Returns** | - The
RadioButton instance.
|
diff --git a/api/cp/cp.ui.RadioGroup.md b/api/cp/cp.ui.RadioGroup.md
new file mode 100644
index 0000000..253ab6b
--- /dev/null
+++ b/api/cp/cp.ui.RadioGroup.md
@@ -0,0 +1,114 @@
+# [docs](index.md) » cp.ui.RadioGroup
+---
+
+Represents an `AXRadioGroup`, providing utility methods.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [RadioGroup](#radiogroup)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [optionCount](#optioncount)
+ * [options](#options)
+ * [optionsUI](#optionsui)
+ * [selectedOption](#selectedoption)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [doNextOption](#donextoption)
+ * [doPreviousOption](#dopreviousoption)
+ * [doSelectOption](#doselectoption)
+ * [nextOption](#nextoption)
+ * [previousOption](#previousoption)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.RadioGroup.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the provided `axuielement` is a RadioGroup. |
+| **Parameters** | - element - The element to check.
|
+| **Returns** | true if the element is a RadioGroup.
|
+
+### Constructors
+
+#### [RadioGroup](#radiogroup)
+| **Signature** | `cp.ui.RadioGroup(parent, uiFinder[, createOptionFn]) -> cp.ui.RadioGroup` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new RadioGroup. |
+| **Parameters** | - parent - The parent table.
- uiFinder - The function which will find the
axuielement representing the RadioGroup. - createOptionFn - If provided a function that receives the
RadioGroup and an axuielement for a given option within the group.
|
+| **Returns** | - The new
RadioGroup instance.
|
+
+### Fields
+
+#### [optionCount](#optioncount)
+| **Signature** | `cp.ui.RadioGroup.optionCount ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The number of options in the group. |
+
+#### [options](#options)
+| **Signature** | `cp.ui.RadioGroup.options ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | A `table` containing `cp.ui.Element` available in the radio group. |
+| **Returns** | |
+
+#### [optionsUI](#optionsui)
+| **Signature** | `cp.ui.RadioGroup.optionsUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | A `cp.prop` containing `table` of `axuielement` options available in the radio group. |
+| **Returns** | |
+
+#### [selectedOption](#selectedoption)
+| **Signature** | `cp.ui.RadioGroup.selectedOption ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The currently selected option number. |
+
+### Methods
+
+#### [doNextOption](#donextoption)
+| **Signature** | `cp.ui.RadioGroup:doNextOption() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that selects the next option in the group. |
+| **Parameters** | |
+| **Returns** | - The
Statement, that resolves to true if successful or sends an error if not.
|
+
+#### [doPreviousOption](#dopreviousoption)
+| **Signature** | `cp.ui.RadioGroup:doPreviousOption() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that selects the previous option in the group. |
+| **Parameters** | |
+| **Returns** | - The
Statement, which resolves to true if successful or sends an error if not..
|
+
+#### [doSelectOption](#doselectoption)
+| **Signature** | `cp.ui.RadioGroup:doSelectOption(index) -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) which will attempt to select the option at the specified `index`. |
+| **Parameters** | - index - The index to select. Must be between 1 and optionCount.
|
+| **Returns** | - The
Statement, which will resolve to true if successful or send an error if not.
|
+
+#### [nextOption](#nextoption)
+| **Signature** | `cp.ui.RadioGroup:nextOption() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Selects the next option in the group. Cycles from the last to the first option. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [previousOption](#previousoption)
+| **Signature** | `cp.ui.RadioGroup:previousOption() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Selects the previous option in the group. Cycles from the first to the last item. |
+| **Parameters** | |
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Row.md b/api/cp/cp.ui.Row.md
new file mode 100644
index 0000000..4b064b8
--- /dev/null
+++ b/api/cp/cp.ui.Row.md
@@ -0,0 +1,79 @@
+# [docs](index.md) » cp.ui.Row
+---
+
+Represents an `AXRow` `axuielement`.
+
+## API Overview
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Row](#row)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [disclosing](#disclosing)
+ * [disclosureLevel](#disclosurelevel)
+ * [index](#index)
+ * [selected](#selected)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [disclosedByRow](#disclosedbyrow)
+ * [disclosedRows](#disclosedrows)
+ * [matches](#matches)
+
+## API Documentation
+
+### Constructors
+
+#### [Row](#row)
+| **Signature** | `cp.ui.Row(parent, uiFinder) -> cp.ui.Row` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Row` instance with the specified `parent` and `uiFinder`. |
+| **Parameters** | - parent - the parent
Element. - uiFinder - a
function or cp.prop containing the axuielement
|
+| **Returns** | |
+
+### Fields
+
+#### [disclosing](#disclosing)
+| **Signature** | `cp.ui.Row.disclosing ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Indicates if the `Row` is disclosing other `Rows`. |
+
+#### [disclosureLevel](#disclosurelevel)
+| **Signature** | `cp.ui.Row.disclosureLevel ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The depth of disclosure. `0` is the top level. |
+
+#### [index](#index)
+| **Signature** | `cp.ui.Row.index ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The numeric index of this row in the overall container, with `0` being the first item. |
+
+#### [selected](#selected)
+| **Signature** | `cp.ui.Row.selected ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Indicates if the row is currently selected. May be set. |
+
+### Methods
+
+#### [disclosedByRow](#disclosedbyrow)
+| **Signature** | `cp.ui.Row:disclosedByRow() -> cp.ui.Row` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | The `Row` which is disclosing this `Row`. |
+
+#### [disclosedRows](#disclosedrows)
+| **Signature** | `cp.ui.Row:disclosedRows() -> table of cp.ui.Row or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | If available, returns a table of [Row](cp.ui.Row.md)s that are disclosed by this `Row`. |
+| **Returns** | - The
table of Rows, or nil.
|
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Row.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if the element is a `Row`. |
+| **Parameters** | - element - the
axuielement to check.
|
+| **Returns** | true if it matches, otherwise false.
|
+
diff --git a/api/cp/cp.ui.ScrollArea.md b/api/cp/cp.ui.ScrollArea.md
index 0c37a39..8fe9a5f 100644
--- a/api/cp/cp.ui.ScrollArea.md
+++ b/api/cp/cp.ui.ScrollArea.md
@@ -4,6 +4,181 @@
Scroll Area Module.
## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [ScrollArea](#scrollarea)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [contentsUI](#contentsui)
+ * [horizontalScrollBar](#horizontalscrollbar)
+ * [selectedChildrenUI](#selectedchildrenui)
+ * [verticalScrollBar](#verticalscrollbar)
+ * [viewFrame](#viewframe)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [childrenUI](#childrenui)
+ * [deselectAll](#deselectall)
+ * [loadLayout](#loadlayout)
+ * [saveLayout](#savelayout)
+ * [selectAll](#selectall)
+ * [selectChild](#selectchild)
+ * [selectChildAt](#selectchildat)
+ * [shiftHorizontalBy](#shifthorizontalby)
+ * [shiftHorizontalTo](#shifthorizontalto)
+ * [shiftVerticalBy](#shiftverticalby)
+ * [shiftVerticalTo](#shiftverticalto)
+ * [showChild](#showchild)
+ * [showChildAt](#showchildat)
## API Documentation
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.ScrollArea.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [ScrollArea](#scrollarea)
+| **Signature** | `cp.ui.ScrollArea(parent, uiFinder) -> cp.ui.ScrollArea` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `ScrollArea`. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A
function or cp.prop which will return the hs._asm.axuielement when available.
|
+| **Returns** | |
+
+### Fields
+
+#### [contentsUI](#contentsui)
+| **Signature** | `cp.ui.ScrollArea.contentsUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `axuielement` representing the Scroll Area Contents, or `nil` if not available. |
+
+#### [horizontalScrollBar](#horizontalscrollbar)
+| **Signature** | `cp.ui.ScrollArea.horizontalScrollBar ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The horizontal [ScrollBar](cp.ui.ScrollBar.md). |
+
+#### [selectedChildrenUI](#selectedchildrenui)
+| **Signature** | `cp.ui.ScrollArea.selectedChildrenUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `axuielement` representing the Scroll Area Selected Children, or `nil` if not available. |
+
+#### [verticalScrollBar](#verticalscrollbar)
+| **Signature** | `cp.ui.ScrollArea.verticalScrollBar ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The vertical [ScrollBar](cp.ui.ScrollBar.md). |
+
+#### [viewFrame](#viewframe)
+| **Signature** | `cp.ui.ScrollArea.viewFrame ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | A `cp.prop` reporting the Scroll Area frame as a hs.geometry.rect. |
+
+### Methods
+
+#### [childrenUI](#childrenui)
+| **Signature** | `cp.ui.ScrollArea:childrenUI(filterFn) -> hs._asm.axuielement | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the `axuielement` representing the Scroll Area Contents, or `nil` if not available. |
+| **Parameters** | - filterFn - The function which checks if the child matches the requirements.
|
+
+#### [deselectAll](#deselectall)
+| **Signature** | `cp.ui.ScrollArea:deselectAll() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Deselect all children in a scroll area. |
+| **Parameters** | |
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.ScrollArea:loadLayout(layout) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads a Scroll Area layout. |
+| **Parameters** | - layout - A table containing the ScrollArea layout settings, typically created using saveLayout.
|
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.ScrollArea:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the current Scroll Area layout to a table. |
+| **Parameters** | |
+| **Returns** | - A table containing the current Scroll Area Layout.
|
+
+#### [selectAll](#selectall)
+| **Signature** | `cp.ui.ScrollArea:selectAll(childrenUI) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Select all children in a scroll area. |
+| **Parameters** | - childrenUI - A table of
hs._asm.axuielement objects.
|
+
+#### [selectChild](#selectchild)
+| **Signature** | `cp.ui.ScrollArea:selectChild(childUI) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Select a specific child within a Scroll Area. |
+| **Parameters** | - childUI - The
hs._asm.axuielement object of the child you want to select.
|
+
+#### [selectChildAt](#selectchildat)
+| **Signature** | `cp.ui.ScrollArea:selectChildAt(index) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Select a child element in a Scroll Area given a specific index. |
+| **Parameters** | - index - The index of the child you want to select.
|
+
+#### [shiftHorizontalBy](#shifthorizontalby)
+| **Signature** | `cp.ui.ScrollArea:shiftHorizontalBy(amount) -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to shift the horizontal scroll bar by the specified amount. |
+| **Parameters** | - amount - The amount to shift
|
+| **Returns** | - The actual value of the horizontal scroll bar.
|
+
+#### [shiftHorizontalTo](#shifthorizontalto)
+| **Signature** | `cp.ui.ScrollArea:shiftHorizontalTo(value) -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to shift the horizontal scroll bar to the specified value. |
+| **Parameters** | - value - The new value (typically between
0 and 1).
|
+| **Returns** | - The actual value of the horizontal scroll bar.
|
+
+#### [shiftVerticalBy](#shiftverticalby)
+| **Signature** | `cp.ui.ScrollArea:shiftVerticalBy(amount) -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to shift the vertical scroll bar by the specified amount. |
+| **Parameters** | - amount - The amount to shift
|
+| **Returns** | - The actual value of the vertical scroll bar.
|
+
+#### [shiftVerticalTo](#shiftverticalto)
+| **Signature** | `cp.ui.ScrollArea:shiftVerticalTo(value) -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to shift the vertical scroll bar to the specified value. |
+| **Parameters** | - value - The new value (typically between
0 and 1).
|
+| **Returns** | - The actual value of the vertical scroll bar.
|
+
+#### [showChild](#showchild)
+| **Signature** | `cp.ui.ScrollArea:showChild(childUI) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Show's a child element in a Scroll Area. |
+| **Parameters** | - childUI - The
hs._asm.axuielement object of the child you want to show.
|
+
+#### [showChildAt](#showchildat)
+| **Signature** | `cp.ui.ScrollArea:showChildAt(index) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Show's a child element in a Scroll Area given a specific index. |
+| **Parameters** | - index - The index of the child you want to show.
|
+
diff --git a/api/cp/cp.ui.ScrollBar.md b/api/cp/cp.ui.ScrollBar.md
new file mode 100644
index 0000000..379692a
--- /dev/null
+++ b/api/cp/cp.ui.ScrollBar.md
@@ -0,0 +1,113 @@
+# [docs](index.md) » cp.ui.ScrollBar
+---
+
+Provides access to `AXScrollBar` `axuielement` values.
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [HORIZONTAL_ORIENTATION](#horizontal_orientation)
+ * [VERTICAL_ORIENTATION](#vertical_orientation)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [ScrollBar](#scrollbar)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [hidden](#hidden)
+ * [horizontal](#horizontal)
+ * [orientation](#orientation)
+ * [value](#value)
+ * [vertical](#vertical)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [loadLayout](#loadlayout)
+ * [matches](#matches)
+ * [saveLayout](#savelayout)
+ * [shiftValueBy](#shiftvalueby)
+
+## API Documentation
+
+### Constants
+
+#### [HORIZONTAL_ORIENTATION](#horizontal_orientation)
+| **Signature** | `cp.ui.ScrollBar.HORIZONTAL_ORIENTATION ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The value for `AXOrientation` when it is horizontal. |
+
+#### [VERTICAL_ORIENTATION](#vertical_orientation)
+| **Signature** | `cp.ui.ScrollBar.VERTICAL_ORIENTATION ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The value for `AXOrientation` when it is vertical. |
+
+### Constructors
+
+#### [ScrollBar](#scrollbar)
+| **Signature** | `cp.ui.ScrollBar(parent, uiFinder) -> cp.ui.ScrollBar` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `ScrollBar` instance with the specified `parent` and `uiFinder`. |
+| **Parameters** | - parent - the parent object.
- uiFinder - a
function or cp.prop that provides the AXScrollBar axuielement.
|
+| **Returns** | |
+
+### Fields
+
+#### [hidden](#hidden)
+| **Signature** | `cp.ui.ScrollBar.hidden ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Is `true` if the `ScrollBar` is currently hidden. |
+
+#### [horizontal](#horizontal)
+| **Signature** | `cp.ui.ScrollBar.horizontal ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Is `true` if the `ScrollBar` is horizontal, otherwise `false`. |
+
+#### [orientation](#orientation)
+| **Signature** | `cp.ui.ScrollBar.orientation ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The `AXOrientation` string. |
+
+#### [value](#value)
+| **Signature** | `cp.ui.ScrollBar.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Is the numeric scroll value, typically between `0.0` and `1.0`. May be set. |
+
+#### [vertical](#vertical)
+| **Signature** | `cp.ui.ScrollBar.vertical ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Is `true` if the `ScrollBar` is vertical, otherwise `false`. |
+
+### Methods
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.ScrollBar:loadLayout(layout)` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads the provided `layout` table of configuration parameters. |
+| **Parameters** | - layout - the table of parameters.
|
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.ScrollBar.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if the element is a `ScrollBar`. |
+| **Parameters** | - element - The
axuielement being matched.
|
+| **Returns** | true if matches, otherwise false.
|
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.ScrollBar:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the `ScrollBar` layout configuration. |
+| **Returns** | - a
table with the configuration parameters.
|
+
+#### [shiftValueBy](#shiftvalueby)
+| **Signature** | `cp.ui.ScrollBar:shiftValueBy(amount) -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to shift the value by the specified amount. |
+| **Parameters** | - amount - The amount to shift by.
|
+| **Returns** | - The new value, or
nil if not available.
|
+
diff --git a/api/cp/cp.ui.SearchField.md b/api/cp/cp.ui.SearchField.md
new file mode 100644
index 0000000..dbf2d25
--- /dev/null
+++ b/api/cp/cp.ui.SearchField.md
@@ -0,0 +1,33 @@
+# [docs](index.md) » cp.ui.SearchField
+---
+
+A [TextField](cp.ui.TextField.md) with a subrole of `AXSearchField`.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matchesSearch](#matchessearch)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [SearchField](#searchfield)
+
+## API Documentation
+
+### Functions
+
+#### [matchesSearch](#matchessearch)
+| **Signature** | `cp.ui.SearchField.matchesSearch(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element is a `AXTextField` with a subrole of `AXSearchField`. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches, otherwise false.
|
+
+### Methods
+
+#### [SearchField](#searchfield)
+| **Signature** | `cp.ui.SearchField(parent, uiFinder[, convertFn]) -> cp.ui.SearchField` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Creates a new SearchField. They have a parent and a finder function. |
+| **Parameters** | - parent - The parent object.
- uiFinder - The function will return the
axuielement for the SearchField. - convertFn - (optional) If provided, will be passed the
string value when returning.
|
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Sheet.md b/api/cp/cp.ui.Sheet.md
new file mode 100644
index 0000000..ac14fee
--- /dev/null
+++ b/api/cp/cp.ui.Sheet.md
@@ -0,0 +1,132 @@
+# [docs](index.md) » cp.ui.Sheet
+---
+
+Sheet UI Module.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Sheet](#sheet)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [cancel](#cancel)
+ * [default](#default)
+ * [title](#title)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [containsText](#containstext)
+ * [doCancel](#docancel)
+ * [doDefault](#dodefault)
+ * [doHide](#dohide)
+ * [doPress](#dopress)
+ * [hide](#hide)
+ * [pressCancel](#presscancel)
+ * [pressDefault](#pressdefault)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Sheet.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [Sheet](#sheet)
+| **Signature** | `cp.ui.Sheet(parent, uiFinder) -> Sheet` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Sheet` instance. |
+| **Parameters** | - parent - The parent object.
- uiFinder - The UI, either a
cp.prop or a function.
|
+| **Returns** | |
+
+### Fields
+
+#### [cancel](#cancel)
+| **Signature** | `cp.ui.Sheet.cancel ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The cancel [Button](cp.ui.Button.md) for the `Sheet`. |
+
+#### [default](#default)
+| **Signature** | `cp.ui.Sheet.default ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The default [Button](cp.ui.Button.md) for the `Sheet`. |
+
+#### [title](#title)
+| **Signature** | `cp.ui.Sheet.title ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Gets the title of the sheet. |
+
+### Methods
+
+#### [containsText](#containstext)
+| **Signature** | `cp.ui.Sheet:containsText(value[, plain]) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Checks if there are any child text elements containing the exact text or pattern, from beginning to end. |
+| **Parameters** | - textPattern - The text pattern to check.
- plain - If
true, the text will be compared exactly, otherwise it will be considered to be a pattern. Defaults to false.
|
+| **Returns** | true if an element's AXValue matches the text pattern exactly.
|
+
+#### [doCancel](#docancel)
+| **Signature** | `cp.ui.Sheet:doCancel() -> cp.rx.go.Statement ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to hide the Sheet (if visible) by pressing the [Cancel](#cancel) button. |
+| **Parameters** | |
+| **Returns** | - A Statement to execute, resolving to
true if the button was present and clicked, otherwise false.
|
+
+#### [doDefault](#dodefault)
+| **Signature** | `cp.ui.Sheet:doDefault() -> cp.rx.go.Statement ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to press the `default` [Button](cp.ui.Button.md). |
+| **Parameters** | |
+| **Returns** | - A Statement to execute, resolving to
true if the button was present and clicked, otherwise false.
|
+
+#### [doHide](#dohide)
+| **Signature** | `cp.ui.Sheet:doHide() -> cp.rx.go.Statement ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to hide the Sheet (if visible) by pressing the [Cancel](#cancel) button. |
+| **Parameters** | |
+| **Returns** | - A Statement to execute, resolving to
true if the button was present and clicked, otherwise false.
|
+
+#### [doPress](#dopress)
+| **Signature** | `cp.ui.Sheet:doPress(buttonFromLeft) -> cp.rx.go.Statement ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to press the indicated button from left-to-right, if it can be found. |
+| **Parameters** | - buttonFromLeft - The number of the button from left-to-right.
|
+| **Returns** | - a Statement to execute, resolving in
true if the button was found and pressed, otherwise false.
|
+
+#### [hide](#hide)
+| **Signature** | `cp.ui.Sheet:hide() -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Hides the sheet by pressing the "Cancel" button, if it exists. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [pressCancel](#presscancel)
+| **Signature** | `cp.ui.Sheet:pressCancel() -> self, boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Presses the Cancel button. |
+| **Parameters** | |
+| **Returns** | - The
Sheet object. true if successful, otherwise false.
|
+
+#### [pressDefault](#pressdefault)
+| **Signature** | `cp.ui.Sheet:pressDefault() -> self, boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Presses the Default button. |
+| **Parameters** | |
+| **Returns** | - The
Sheet object. true if successful, otherwise false.
|
+
diff --git a/api/cp/cp.ui.Slider.md b/api/cp/cp.ui.Slider.md
index 314fa07..868d7fe 100644
--- a/api/cp/cp.ui.Slider.md
+++ b/api/cp/cp.ui.Slider.md
@@ -5,15 +5,137 @@ Slider Module.
## API Overview
* Functions - API calls offered directly by the extension
- * [new](#new)
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Slider](#slider)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [maxValue](#maxvalue)
+ * [minValue](#minvalue)
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [decrement](#decrement)
+ * [getMaxValue](#getmaxvalue)
+ * [getMinValue](#getminvalue)
+ * [getValue](#getvalue)
+ * [increment](#increment)
+ * [loadLayout](#loadlayout)
+ * [saveLayout](#savelayout)
+ * [setValue](#setvalue)
+ * [shiftValue](#shiftvalue)
## API Documentation
### Functions
-#### [new](#new)
-| **Signature** | `cp.ui.Slider:new(axuielement, function) -> Slider` |
+#### [matches](#matches)
+| **Signature** | `cp.ui.Slider.matches(element) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Creates a new Slider |
+| **Type** | Function |
+| **Description** | Checks if the provided `hs._asm.axuielement` is a Slider. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | true if it's a match, or false if not.
|
+
+### Constructors
+
+#### [Slider](#slider)
+| **Signature** | `cp.ui.Slider(parent, uiFinder) -> cp.ui.Slider` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new Slider |
+| **Parameters** | - parent - The parent object. Should have an
isShowing property. - uiFinder - The function which returns an
hs._asm.axuielement for the slider, or nil.
|
+| **Returns** | |
+
+### Fields
+
+#### [maxValue](#maxvalue)
+| **Signature** | `cp.ui.Slider.maxValue ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Gets the maximum value of the slider. |
+
+#### [minValue](#minvalue)
+| **Signature** | `cp.ui.Slider.minValue ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Gets the minimum value of the slider. |
+
+#### [value](#value)
+| **Signature** | `cp.ui.Slider.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Sets or gets the value of the slider. |
+
+### Methods
+
+#### [decrement](#decrement)
+| **Signature** | `cp.ui.Slider:decrement() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Decrements the slider by one step. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [getMaxValue](#getmaxvalue)
+| **Signature** | `cp.ui.Slider:getMaxValue() -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the maximum value of the slider. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [getMinValue](#getminvalue)
+| **Signature** | `cp.ui.Slider:getMinValue() -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the minimum value of the slider. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [getValue](#getvalue)
+| **Signature** | `cp.ui.Slider:getValue() -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the value of the slider. |
+| **Parameters** | |
+| **Returns** | - The value of the slider as a number.
|
+
+#### [increment](#increment)
+| **Signature** | `cp.ui.Slider:increment() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Increments the slider by one step. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.Slider:loadLayout(layout) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads a Slider layout. |
+| **Parameters** | - layout - A table containing the Slider layout settings - created using [saveLayout](#saveLayout].
|
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.Slider:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the current Slider layout to a table. |
+| **Parameters** | |
+| **Returns** | - A table containing the current Slider Layout.
|
+
+#### [setValue](#setvalue)
+| **Signature** | `cp.ui.Slider:setValue(value) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets the value of the slider. |
+| **Parameters** | - value - The value you want to set the slider to as a number.
|
+| **Returns** | |
+
+#### [shiftValue](#shiftvalue)
+| **Signature** | `cp.ui.Slider:shiftValue(value) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Shifts the value of the slider. |
+| **Parameters** | - value - The value you want to shift the slider by as a number.
|
+| **Returns** | |
diff --git a/api/cp/cp.ui.SplitGroup.md b/api/cp/cp.ui.SplitGroup.md
new file mode 100644
index 0000000..52f0796
--- /dev/null
+++ b/api/cp/cp.ui.SplitGroup.md
@@ -0,0 +1,33 @@
+# [docs](index.md) » cp.ui.SplitGroup
+---
+
+Split Group UI.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [SplitGroup](#splitgroup)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.SplitGroup.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [SplitGroup](#splitgroup)
+| **Signature** | `cp.ui.SplitGroup(parent, uiFinder) -> cp.ui.SplitGroup` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new Split Group. |
+| **Parameters** | - parent - The parent object.
- uiFinder - The
function or cp.prop which returns an hs._asm.axuielement for the Split Group, or nil.
|
+| **Returns** | - A new
SplitGroup instance.
|
+
diff --git a/api/cp/cp.ui.Splitter.md b/api/cp/cp.ui.Splitter.md
new file mode 100644
index 0000000..c626d72
--- /dev/null
+++ b/api/cp/cp.ui.Splitter.md
@@ -0,0 +1,50 @@
+# [docs](index.md) » cp.ui.Splitter
+---
+
+Represents an `AXSplitter`.
+
+## API Overview
+* Constants - Useful values which cannot be changed
+ * [HORIZONTAL_ORIENTATION](#horizontal_orientation)
+ * [VERTICAL_ORIENTATION](#vertical_orientation)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [horizontal](#horizontal)
+ * [orientation](#orientation)
+ * [vertical](#vertical)
+
+## API Documentation
+
+### Constants
+
+#### [HORIZONTAL_ORIENTATION](#horizontal_orientation)
+| **Signature** | `cp.ui.Splitter.HORIZONTAL_ORIENTATION ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The value for `AXOrientation` when it is horizontal. |
+
+#### [VERTICAL_ORIENTATION](#vertical_orientation)
+| **Signature** | `cp.ui.Splitter.VERTICAL_ORIENTATION ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constant |
+| **Description** | The value for `AXOrientation` when it is vertical. |
+
+### Fields
+
+#### [horizontal](#horizontal)
+| **Signature** | `cp.ui.Splitter.horizontal ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Is `true` if the `Splitter` is horizontal, otherwise `false`. |
+
+#### [orientation](#orientation)
+| **Signature** | `cp.ui.Splitter.orientation ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The `AXOrientation` string. |
+
+#### [vertical](#vertical)
+| **Signature** | `cp.ui.Splitter.vertical ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Is `true` if the `Splitter` is vertical, otherwise `false`. |
+
diff --git a/api/cp/cp.ui.StaticText.md b/api/cp/cp.ui.StaticText.md
new file mode 100644
index 0000000..2a48b2b
--- /dev/null
+++ b/api/cp/cp.ui.StaticText.md
@@ -0,0 +1,70 @@
+# [docs](index.md) » cp.ui.StaticText
+---
+
+Static Text Module.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [clear](#clear)
+ * [loadLayout](#loadlayout)
+ * [saveLayout](#savelayout)
+ * [StaticText](#statictext)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.StaticText.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the element is a Static Text element. |
+| **Parameters** | - element - The
axuielement to check.
|
+| **Returns** | - If
true, the element is a Static Text element.
|
+
+### Fields
+
+#### [value](#value)
+| **Signature** | `cp.ui.StaticText.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The current value of the text field. |
+
+### Methods
+
+#### [clear](#clear)
+| **Signature** | `cp.ui.StaticText:clear() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Clears the value of a Static Text box. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.StaticText:loadLayout(layout) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads a Static Text layout. |
+| **Parameters** | - layout - A table containing the Static Text layout settings - created using
cp.ui.StaticText:saveLayout().
|
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.StaticText:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the current Static Text layout to a table. |
+| **Parameters** | |
+| **Returns** | - A table containing the current Static Text Layout.
|
+
+#### [StaticText](#statictext)
+| **Signature** | `cp.ui.StaticText(parent, uiFinder[, convertFn]) -> StaticText` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Creates a new StaticText. They have a parent and a finder function. |
+| **Parameters** | - parent - The parent object.
- uiFinder - The function will return the
axuielement for the StaticText. - convertFn - (optional) If provided, will be passed the
string value when returning.
|
+| **Returns** | |
+
diff --git a/api/cp/cp.ui.Table.md b/api/cp/cp.ui.Table.md
index 36bac8b..43d4f55 100644
--- a/api/cp/cp.ui.Table.md
+++ b/api/cp/cp.ui.Table.md
@@ -14,18 +14,31 @@ Represents an AXTable in the Apple Accessibility UX API.
* [matchesContent](#matchescontent)
* [visitRow](#visitrow)
* 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
- * [columnsUI](#columnsui)
+ * [Table](#table)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [contentUI](#contentui)
* [horizontalScrollBarUI](#horizontalscrollbarui)
* [isFocused](#isfocused)
- * [isShowing](#isshowing)
- * [parent](#parent)
+ * [verticalScrollBarUI](#verticalscrollbarui)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [columnsUI](#columnsui)
+ * [deselectAll](#deselectall)
+ * [deselectRow](#deselectrow)
+ * [deselectRowAt](#deselectrowat)
+ * [findCellUI](#findcellui)
+ * [findColumnIndex](#findcolumnindex)
+ * [loadLayout](#loadlayout)
* [rowsUI](#rowsui)
+ * [saveLayout](#savelayout)
+ * [selectAll](#selectall)
+ * [selectedRowsUI](#selectedrowsui)
+ * [selectRow](#selectrow)
+ * [selectRowAt](#selectrowat)
+ * [showRow](#showrow)
+ * [showRowAt](#showrowat)
+ * [toCSV](#tocsv)
* [topRowsUI](#toprowsui)
- * [UI](#ui)
- * [uncached](#uncached)
- * [verticalScrollBarUI](#verticalscrollbarui)
+ * [viewFrame](#viewframe)
## API Documentation
@@ -34,154 +47,237 @@ Represents an AXTable in the Apple Accessibility UX API.
#### [cellTextValue](#celltextvalue)
| **Signature** | `cp.ui.Table.cellTextValue(cell) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the cell's text value. |
-| **Parameters** | - `cell` - The cell to check
|
-| **Returns** | - The combined text value of the cell.
|
+| **Type** | Function |
+| **Description** | Returns the cell's text value. |
+| **Parameters** | |
+| **Returns** | - The combined text value of the cell.
|
#### [cellTextValueIs](#celltextvalueis)
| **Signature** | `cp.ui.Table.cellTextValueIs(cell, value) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the cell's text value equals `value`. |
-| **Parameters** | - `cell` - The cell to check
- `value` - The text value to compare.
|
-| **Returns** | - `true` if the cell text value equals the provided `value`.
|
+| **Type** | Function |
+| **Description** | Checks if the cell's text value equals `value`. |
+| **Parameters** | cell - The cell to checkvalue - The text value to compare.
|
+| **Returns** | true if the cell text value equals the provided value.
|
#### [discloseRow](#discloserow)
| **Signature** | `cp.ui.Table.discloseRow(row) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Discloses the row, if possible. |
-| **Parameters** | - `row` - The row to disclose
|
-| **Returns** | - `true` if the row is disclosable and is now expanded.
|
+| **Type** | Function |
+| **Description** | Discloses the row, if possible. |
+| **Parameters** | row - The row to disclose
|
+| **Returns** | true if the row is disclosable and is now expanded.
|
#### [findRow](#findrow)
| **Signature** | `cp.ui.Table.findRow(rows, names) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Finds the row at the sub-level named in the `names` table and returns it. |
-| **Parameters** | - `rows` - The array of rows to process.
- `names` - The array of names to navigate down
|
-| **Returns** | - The row that was visited, or `nil` if not.
|
+| **Type** | Function |
+| **Description** | Finds the row at the sub-level named in the `names` table and returns it. |
+| **Parameters** | rows - The array of rows to process.names - The array of names to navigate down
|
+| **Returns** | - The row that was visited, or
nil if not.
|
#### [is](#is)
| **Signature** | `cp.ui.Table.is(thing) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the `thing` is a `Table`. |
-| **Parameters** | - `thing` - The thing to check
|
-| **Returns** | - `true` if the thing is a `Table` instance.
|
+| **Type** | Function |
+| **Description** | Checks if the `thing` is a `Table`. |
+| **Parameters** | thing - The thing to check
|
+| **Returns** | true if the thing is a Table instance.
|
#### [matches](#matches)
| **Signature** | `cp.ui.Table.matches(element)` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the element is a valid table. |
-| **Parameters** | - `element` - The element to check.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Checks if the element is a valid table. |
+| **Parameters** | element - The element to check.
|
+| **Returns** | |
#### [matchesContent](#matchescontent)
| **Signature** | `cp.ui.Table.matchesContent(element) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the `element` is a valid table content element. |
-| **Parameters** | - `element` - The element to check
|
-| **Returns** | - `true` if the element is a valid content element.
|
+| **Type** | Function |
+| **Description** | Checks if the `element` is a valid table content element. |
+| **Parameters** | element - The element to check
|
+| **Returns** | true if the element is a valid content element.
|
#### [visitRow](#visitrow)
| **Signature** | `cp.ui.Table.visitRow(rows, names) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Selects the row at the sub-level named in the `names` table. |
-| **Parameters** | - `rows` - The array of rows to process.
- `names` - The array of names to navigate down
|
-| **Returns** | - The row that was visited, or `nil` if not.
|
+| **Type** | Function |
+| **Description** | Selects the row at the sub-level named in the `names` table. |
+| **Parameters** | rows - The array of rows to process.names - The array of names to navigate down
|
+| **Returns** | - The row that was visited, or
nil if not.
|
### Constructors
-#### [new](#new)
-| **Signature** | `cp.ui.Table.new(parent, finder) -> Table` |
+#### [Table](#table)
+| **Signature** | `cp.ui.Table(parent, uiFinder) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new Table. |
+| **Parameters** | parent - The parent object.uiFinder - A function or cp.prop which will return the axuielement that this table represents.
|
+| **Returns** | |
+
+### Fields
+
+#### [contentUI](#contentui)
+| **Signature** | `cp.ui.Table.contentUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns the `axuielement` that contains the actual rows. |
+
+#### [horizontalScrollBarUI](#horizontalscrollbarui)
+| **Signature** | `cp.ui.Table.horizontalScrollBarUI ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Creates a new Table. |
-| **Parameters** | - `parent` - The parent object.
- `finder` - A function which will return the `axuielement` that this table represents.
|
+| **Type** | Field |
+| **Description** | The horizontal scroll bar UI element, if present. |
+
+#### [isFocused](#isfocused)
+| **Signature** | `cp.ui.Table.isFocused ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns `true` if the table is focused by the user. |
+
+#### [verticalScrollBarUI](#verticalscrollbarui)
+| **Signature** | `cp.ui.Table.verticalScrollBarUI ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The vertical scroll bar UI element, if present. |
### Methods
#### [columnsUI](#columnsui)
| **Signature** | `cp.ui.Table:columnsUI() -> table of axuielements | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Return a list of column headers, if present. |
+| **Type** | Method |
+| **Description** | Return a list of column headers, if present. |
| **Parameters** | |
-| **Returns** | - Table of column headers. If the table is visible but no column headers are defined, an empty table is returned. If it's not visible, `nil` is returned.
|
+| **Returns** | - Table of column headers. If the table is visible but no column headers are defined, an empty table is returned. If it's not visible,
nil is returned.
|
-#### [horizontalScrollBarUI](#horizontalscrollbarui)
-| **Signature** | `cp.ui.Table:horizontalScrollBarUI() -> axuielement | nil` |
+#### [deselectAll](#deselectall)
+| **Signature** | `cp.ui.Table:deselectAll(rowUI) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Finds the horizontal scroll bar UI element, if present. |
-| **Parameters** | |
-| **Returns** | - The UI element, or `nil`.
|
+| **Type** | Method |
+| **Description** | Deselects the specified rows. If `rowsUI` is `nil`, then all rows will be deselected. |
+| **Parameters** | - rowUI - A table of
hs._asm.axuielement objects for the rows you want to deselect.
|
-#### [isFocused](#isfocused)
-| **Signature** | `cp.ui.Table:isFocused() -> boolean` |
+#### [deselectRow](#deselectrow)
+| **Signature** | `cp.ui.Table:deselectRow(rowUI) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Checks if the table is focused by the user. |
-| **Parameters** | |
-| **Returns** | - `true` if the element is focused.
|
+| **Type** | Method |
+| **Description** | Deselect a specific row. |
+| **Parameters** | - rowUI - The
hs._asm.axuielement object of the row you want to deselect.
|
-#### [isShowing](#isshowing)
-| **Signature** | `cp.ui.Table:isShowing() -> boolean` |
+#### [deselectRowAt](#deselectrowat)
+| **Signature** | `cp.ui.Table:deselectRowAt(index) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Checks if the table is visible. |
-| **Parameters** | |
-| **Returns** | - `true` if the element is visible.
|
+| **Type** | Method |
+| **Description** | Deselects a row at a specific index. |
+| **Parameters** | - index - The index of the row you wish to deselect.
|
-#### [parent](#parent)
-| **Signature** | `cp.ui.Table:parent() -> value` |
+#### [findCellUI](#findcellui)
+| **Signature** | `cp.ui.Table:findCellUI(rowNumber, columnId) -> `hs._asm.axuielement` | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | The table's parent, as provided in the constructor. |
-| **Parameters** | |
-| **Returns** | |
+| **Type** | Method |
+| **Description** | Finds a specific Cell UI. |
+| **Parameters** | - rowNumber - The row number.
- columnId - The Column ID.
|
+| **Returns** | - A
hs._asm.axuielement object for the cell, or nil if the cell cannot be found.
|
+
+#### [findColumnIndex](#findcolumnindex)
+| **Signature** | `cp.ui.Table:findColumnIndex(id) -> number | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Finds the Column Index based on an `AXIdentifier` ID. |
+| **Parameters** | - id - The
AXIdentifier of the column index you want to find.
|
+| **Returns** | - A column index as a number, or
nil if no index can be found.
|
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.Table:loadLayout(layout) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads a Table layout. |
+| **Parameters** | - layout - A table containing the Table layout settings - created using
cp.ui.Table:saveLayout().
|
+| **Returns** | |
#### [rowsUI](#rowsui)
| **Signature** | `cp.ui.Table:rowsUI([filterFn]) -> table of axuielements | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns the list of rows in the table. An optional filter function may be provided. |
-| **Parameters** | - `filterFn` - An optional function that will be called to check if individual rows should be included. If not provided, all rows are returned.
|
-| **Returns** | - Table of rows. If the table is visible but no rows match, it will be an empty table, otherwise it will be `nil`.
|
+| **Type** | Method |
+| **Description** | Returns the list of rows in the table. An optional filter function may be provided. |
+| **Parameters** | filterFn - An optional function that will be called to check if individual rows should be included. If not provided, all rows are returned.
|
+| **Returns** | - Table of rows. If the table is visible but no rows match, it will be an empty table, otherwise it will be
nil.
|
-#### [topRowsUI](#toprowsui)
-| **Signature** | `cp.ui.Table:topRowsUI(filterFn) -> table of axuielements | nil` |
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.Table:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the current Table layout to a table. |
+| **Parameters** | |
+| **Returns** | - A table containing the current Table Layout.
|
+
+#### [selectAll](#selectall)
+| **Signature** | `cp.ui.Table:selectAll(rowUI) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns a list of top-level rows in the table. An optional filter function may be provided. |
-| **Parameters** | - `filterFn` - An optional function that will be called to check if individual rows should be included. If not provided, all rows are returned.
|
-| **Returns** | - Table of rows. If the table is visible but no rows match, it will be an empty table, otherwise it will be `nil`.
|
+| **Type** | Method |
+| **Description** | Selects the specified rows. If `rowsUI` is `nil`, then all rows will be selected. |
+| **Parameters** | - rowUI - A table of
hs._asm.axuielement objects for the rows you want to select.
|
-#### [UI](#ui)
-| **Signature** | `cp.ui.Table:UI() -> axuielement | nil` |
+#### [selectedRowsUI](#selectedrowsui)
+| **Signature** | `cp.ui.Table:selectedRowsUI() -> table of axuielements | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns the `axuielement` that contains the actual rows. |
+| **Type** | Method |
+| **Description** | Return a table of selected row UIs. |
| **Parameters** | |
-| **Returns** | - The content UI element, or `nil`.
|
+| **Returns** | - Table of
hs._asm.axuielement objects, or nil if none could be found.
|
+
+#### [selectRow](#selectrow)
+| **Signature** | `cp.ui.Table:selectRow(rowUI) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Select a specific row. |
+| **Parameters** | - rowUI - The
hs._asm.axuielement object of the row you want to select.
|
-#### [uncached](#uncached)
-| **Signature** | `cp.ui.Table:uncached() -> Table` |
+#### [selectRowAt](#selectrowat)
+| **Signature** | `cp.ui.Table:selectRowAt(index) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Calling this will force the table to look up the `axuielement` on demand, rather than caching the result. |
+| **Type** | Method |
+| **Description** | Select a row at a specific index. |
+| **Parameters** | - index - The index of the row you wish to select.
|
+
+#### [showRow](#showrow)
+| **Signature** | `cp.ui.Table:showRow(rowUI) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Shows a specific row. |
+| **Parameters** | - rowUI - The
hs._asm.axuielement object of the row you want to show.
|
+
+#### [showRowAt](#showrowat)
+| **Signature** | `cp.ui.Table:showRowAt(index) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Shows a row at a specific index. |
+| **Parameters** | - index - The index of the row you wish to show.
|
+
+#### [toCSV](#tocsv)
+| **Signature** | `cp.ui.Table:toCSV() -> string | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the contents of the table and formats it as a CSV string. |
| **Parameters** | |
+| **Returns** | - A string or
nil if an error occurs.
|
-#### [verticalScrollBarUI](#verticalscrollbarui)
-| **Signature** | `cp.ui.Table:verticalScrollBarUI() -> axuielement | nil` |
+#### [topRowsUI](#toprowsui)
+| **Signature** | `cp.ui.Table:topRowsUI(filterFn) -> table of axuielements | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a list of top-level rows in the table. An optional filter function may be provided. |
+| **Parameters** | filterFn - An optional function that will be called to check if individual rows should be included. If not provided, all rows are returned.
|
+| **Returns** | - Table of rows. If the table is visible but no rows match, it will be an empty table, otherwise it will be
nil.
|
+
+#### [viewFrame](#viewframe)
+| **Signature** | `cp.ui.Table:viewFrame() -> hs.geometry rect` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Finds the vertical scroll bar UI element, if present. |
+| **Type** | Method |
+| **Description** | Returns the Table frame. |
| **Parameters** | |
-| **Returns** | - The UI element, or `nil`.
|
diff --git a/api/cp/cp.ui.TextArea.md b/api/cp/cp.ui.TextArea.md
new file mode 100644
index 0000000..e3a4741
--- /dev/null
+++ b/api/cp/cp.ui.TextArea.md
@@ -0,0 +1,71 @@
+# [docs](index.md) » cp.ui.TextArea
+---
+
+UI Text Area.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [TextArea](#textarea)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [focused](#focused)
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [append](#append)
+ * [prepend](#prepend)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.TextArea.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check.
|
+| **Returns** | true if matches otherwise false
|
+
+### Constructors
+
+#### [TextArea](#textarea)
+| **Signature** | `cp.ui.TextArea(parent, uiFinder) -> TextArea` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `TextArea` instance. |
+| **Parameters** | - parent - The parent object.
- uiFinder - A function which will return the
hs._asm.axuielement when available.
|
+| **Returns** | |
+
+### Fields
+
+#### [focused](#focused)
+| **Signature** | `cp.ui.TextArea.focused ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Whether or not the Text Area if focused. |
+
+#### [value](#value)
+| **Signature** | `cp.ui.TextArea.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The current value of the text field. |
+
+### Methods
+
+#### [append](#append)
+| **Signature** | `cp.ui.TextArea:append(moreText) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Appends `moreText` to the end of the current value, returning the combined text value. If no text is currently set, `moreText` becomes the value. |
+| **Parameters** | - moreText - The text to add.
|
+| **Returns** | - The combined
string value.
|
+
+#### [prepend](#prepend)
+| **Signature** | `cp.ui.TextArea:prepend(moreText) -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Appends `moreText` to the beginning of the current value, returning the combined text value. If no text is currently set, `moreText` becomes the value. |
+| **Parameters** | - moreText - The text to add.
|
+| **Returns** | - The combined
string value.
|
+
diff --git a/api/cp/cp.ui.TextField.md b/api/cp/cp.ui.TextField.md
index 487b96a..f005b8a 100644
--- a/api/cp/cp.ui.TextField.md
+++ b/api/cp/cp.ui.TextField.md
@@ -5,15 +5,105 @@ Text Field Module.
## API Overview
* Functions - API calls offered directly by the extension
- * [new](#new)
+ * [matches](#matches)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [value](#value)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [clear](#clear)
+ * [doConfirm](#doconfirm)
+ * [doFocus](#dofocus)
+ * [forceFocus](#forcefocus)
+ * [getValue](#getvalue)
+ * [loadLayout](#loadlayout)
+ * [saveLayout](#savelayout)
+ * [setValue](#setvalue)
+ * [TextField](#textfield)
## API Documentation
### Functions
-#### [new](#new)
-| **Signature** | `cp.ui.TextField:new(axuielement, function) -> TextField` |
+#### [matches](#matches)
+| **Signature** | `cp.ui.TextField.matches(element[, subrole]) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Creates a new TextField |
+| **Type** | Function |
+| **Description** | Checks to see if an element matches what we think it should be. |
+| **Parameters** | - element - An
axuielementObject to check. - subrole - (optional) If provided, the field must have the specified subrole.
|
+| **Returns** | true if matches otherwise false
|
+
+### Fields
+
+#### [value](#value)
+| **Signature** | `cp.ui.TextField.value ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The current value of the text field. |
+
+### Methods
+
+#### [clear](#clear)
+| **Signature** | `cp.ui.TextField:clear() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Clears the value of a Text Field. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [doConfirm](#doconfirm)
+| **Signature** | `cp.ui.TextField:doConfirm() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will confirm the current text value. |
+
+#### [doFocus](#dofocus)
+| **Signature** | `cp.ui.TextField:doFocus() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | A [Statement](cp.rx.go.Statement.md) that will attempt to focus on the current `TextField`. |
+
+#### [forceFocus](#forcefocus)
+| **Signature** | `cp.ui.TextField:forceFocus()` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Configures the TextField to force a focus on the field before editing. |
+
+#### [getValue](#getvalue)
+| **Signature** | `cp.ui.TextField:getValue() -> string` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Gets the value of the Text Field. |
+| **Parameters** | |
+| **Returns** | - The value of the Text Field as a string.
|
+
+#### [loadLayout](#loadlayout)
+| **Signature** | `cp.ui.TextField:loadLayout(layout) -> none` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Loads a Text Field layout. |
+| **Parameters** | - layout - A table containing the Text Field layout settings - created using
cp.ui.TextField:saveLayout().
|
+| **Returns** | |
+
+#### [saveLayout](#savelayout)
+| **Signature** | `cp.ui.TextField:saveLayout() -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Saves the current Text Field layout to a table. |
+| **Parameters** | |
+| **Returns** | - A table containing the current Text Field Layout.
|
+
+#### [setValue](#setvalue)
+| **Signature** | `cp.ui.TextField:setValue(value) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Sets the value of the Text Field. |
+| **Parameters** | - value - The value you want to set the Text Field to as a string.
|
+| **Returns** | |
+
+#### [TextField](#textfield)
+| **Signature** | `cp.ui.TextField(parent, uiFinder[, convertFn]) -> TextField` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Creates a new TextField. They have a parent and a finder function. |
+| **Parameters** | - parent - The parent object.
- uiFinder - The function will return the
axuielement for the TextField. - getConvertFn - (optional) If provided, will be passed the
string value when returning. - setConvertFn - (optional) If provided, will be passed the
number value when setting.
|
+| **Returns** | |
diff --git a/api/cp/cp.ui.Toolbar.md b/api/cp/cp.ui.Toolbar.md
new file mode 100644
index 0000000..807acd3
--- /dev/null
+++ b/api/cp/cp.ui.Toolbar.md
@@ -0,0 +1,62 @@
+# [docs](index.md) » cp.ui.Toolbar
+---
+
+Toolbar Module.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [matches](#matches)
+* Constructors - API calls which return an object, typically one that offers API methods
+ * [Toolbar](#toolbar)
+* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [overflowButton](#overflowbutton)
+ * [selectedTitle](#selectedtitle)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [doSelect](#doselect)
+
+## API Documentation
+
+### Functions
+
+#### [matches](#matches)
+| **Signature** | `cp.ui.Toolbar.matches(element) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `element` is a `Button`, returning `true` if so. |
+| **Parameters** | - element - The
hs._asm.axuielement to check.
|
+| **Returns** | true if the element is a Button, or false if not.
|
+
+### Constructors
+
+#### [Toolbar](#toolbar)
+| **Signature** | `cp.ui.Toolbar(parent, uiFinder) -> cp.ui.Toolbar` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `Toolbar` instance, given the specified `parent` and `uiFinder` |
+| **Parameters** | - parent - The parent object.
- uiFinder - The
cp.prop or function that finds the hs._asm.axuielement that represents the Toolbar.
|
+| **Returns** | - The new
Toolbar instance.
|
+
+### Fields
+
+#### [overflowButton](#overflowbutton)
+| **Signature** | `cp.ui.Toolbar.overflowButton ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The "overflow" button which appears if there are more toolbar items |
+
+#### [selectedTitle](#selectedtitle)
+| **Signature** | `cp.ui.Toolbar.selectedTitle ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The title of the first selected item, if available. |
+
+### Methods
+
+#### [doSelect](#doselect)
+| **Signature** | `cp.ui.Toolbar:doSelect(title) -> Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `Statement` that will select the toolbar item with the specified title. |
+| **Parameters** | - title - The title to select, if present.
|
+| **Returns** | - A
Statement that when executed returns true if the item was found and selected, otherwise false.
|
+
diff --git a/api/cp/cp.ui.Window.md b/api/cp/cp.ui.Window.md
index a86a00f..b9d724f 100644
--- a/api/cp/cp.ui.Window.md
+++ b/api/cp/cp.ui.Window.md
@@ -5,114 +5,181 @@ A Window UI element.
## API Overview
* Functions - API calls offered directly by the extension
+ * [findSectionUI](#findsectionui)
* [matches](#matches)
* Constructors - API calls which return an object, typically one that offers API methods
- * [new](#new)
+ * [Window](#window)
* Fields - Variables which can only be accessed from an object returned by a constructor
+ * [alert](#alert)
* [exists](#exists)
* [focused](#focused)
* [frame](#frame)
- * [fullScreen](#fullscreen)
* [hsWindow](#hswindow)
* [id](#id)
+ * [isFullScreen](#isfullscreen)
+ * [isShowing](#isshowing)
* [minimized](#minimized)
* [UI](#ui)
* [visible](#visible)
* Methods - API calls which can only be made on an object returned by a constructor
* [close](#close)
+ * [doClose](#doclose)
+ * [doFocus](#dofocus)
+ * [findSectionUI](#findsectionui)
* [focus](#focus)
+ * [notifier](#notifier)
+ * [snapshot](#snapshot)
## API Documentation
### Functions
+#### [findSectionUI](#findsectionui)
+| **Signature** | `cp.ui.Window.findSectionUI(windowUI, sectionID) -> hs._asm.axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Finds the `axuielement` for the specified `sectionID`, if present in the provided `axuielement` `windowUI`. |
+| **Parameters** | - windowUI - The
AXWindow axuielement to search in. - sectionID - The string value for the
SectionUniqueID.
|
+| **Returns** | - The matching
axuielement, or nil.
|
+
#### [matches](#matches)
| **Signature** | `cp.ui.Window.matches(element) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the provided element is a valid window. |
+| **Type** | Function |
+| **Description** | Checks if the provided element is a valid window. |
### Constructors
-#### [new](#new)
-| **Signature** | `cp.ui.Window:new(finderFn) -> Window` |
+#### [Window](#window)
+| **Signature** | `cp.ui.Window(cpApp, uiProp) -> Window` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Constructor |
-| **Description** | Creates a new Window |
-| **Parameters** | - `finderFn` - a function which will provide the `axuielement` for the window to work with.
|
-| **Returns** | |
+| **Type** | Constructor |
+| **Description** | Creates a new Window |
+| **Parameters** | cpApp - a cp.app for the application the Window belongs to.uiProp - a cp.prop that returns the hs._asm.axuielement for the window.
|
+| **Returns** | |
### Fields
+#### [alert](#alert)
+| **Signature** | `cp.ui.Window.alert ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Provides access to any 'Alert' windows on the Window. |
+
#### [exists](#exists)
| **Signature** | `cp.ui.Window.exists ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | Returns `true` if the window exists. It may not be visible. |
+| **Type** | Field |
+| **Description** | Returns `true` if the window exists. It may not be visible. |
#### [focused](#focused)
| **Signature** | `cp.ui.Window.focused ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | Is `true` if the window has mouse/keyboard focused. |
+| **Type** | Field |
+| **Description** | Is `true` if the window has mouse/keyboard focused. |
#### [frame](#frame)
| **Signature** | `cp.ui.Window.frame ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | The `hs.geometry` rect value describing the window's position. |
-
-#### [fullScreen](#fullscreen)
-| **Signature** | `cp.ui.Window.fullScreen ` |
-| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | Returns `true` if the window is full-screen. |
+| **Type** | Field |
+| **Description** | The `hs.geometry` rect value describing the window's position. |
#### [hsWindow](#hswindow)
| **Signature** | `cp.ui.Window.hsWindow ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | The `hs.window` instance for the window, or `nil` if it can't be found. |
+| **Type** | Field |
+| **Description** | The `hs.window` instance for the window, or `nil` if it can't be found. |
#### [id](#id)
-| **Signature** | `cp.ui.Window.id ` |
+| **Signature** | `cp.ui.Window.id ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | The window title, or `nil` if the window is not currently visible. |
+
+#### [isFullScreen](#isfullscreen)
+| **Signature** | `cp.ui.Window.isFullScreen ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Field |
+| **Description** | Returns `true` if the window is full-screen. |
+
+#### [isShowing](#isshowing)
+| **Signature** | `cp.ui.Window.isShowing ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | The unique ID for the window. |
+| **Type** | Field |
+| **Description** | Indicates if the `Window` is currently showing on screen. |
#### [minimized](#minimized)
| **Signature** | `cp.ui.Window.minimized ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | Returns `true` if the window exists and is minimised. |
+| **Type** | Field |
+| **Description** | Returns `true` if the window exists and is minimised. |
#### [UI](#ui)
-| **Signature** | `cp.ui.Window.UI ` |
+| **Signature** | `cp.ui.Window.UI ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | Returns the `axuielement` UI for the window, or `nil` if it can't be found. |
+| **Type** | Field |
+| **Description** | The UI `axuielement` for the Window. |
#### [visible](#visible)
| **Signature** | `cp.ui.Window.visible ` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Field |
-| **Description** | Returns `true` if the window is visible on a screen. |
+| **Type** | Field |
+| **Description** | Returns `true` if the window is visible on a screen. |
### Methods
#### [close](#close)
-| **Signature** | `cp.ui.Window.close() -> boolean` |
+| **Signature** | `cp.ui.Window:close() -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Attempts to close the window. |
-| **Parameters** | |
-| **Returns** | - * `true` if the window was successfully closed.
|
+| **Type** | Method |
+| **Description** | Attempts to close the window. |
+| **Parameters** | |
+| **Returns** | true if the window was successfully closed.
|
+
+#### [doClose](#doclose)
+| **Signature** | `cp.ui.Window:doClose() -> cp.rx.go.Statement ` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a [Statement](cp.rx.go.Statement.md) that will attempt to close the window, if it is visible. |
+| **Parameters** | |
+| **Returns** | - The
Statement to execute, resolving to true if the window is closed successfully, or false if not.
|
+
+#### [doFocus](#dofocus)
+| **Signature** | `cp.ui.Window:doFocus() -> cp.rx.go.Statement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a [Statement](cp.rx.go.Statement.md) will attempt to focus on the window, if it is visible. |
+| **Parameters** | |
+| **Returns** | - The
Statement to execute, which resolves to true if the window was successfully focused, or false if not.
|
+
+#### [findSectionUI](#findsectionui)
+| **Signature** | `cp.ui.Window:findSectionUI(sectionID) -> hs._asm.axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Looks for th section with the specified `SectionUniqueID` value and returns the matching `axuielement` value. |
+| **Parameters** | - sectionID - The string for the section ID.
|
+| **Returns** | - The matching
axuielement, or nil.
|
#### [focus](#focus)
-| **Signature** | `cp.ui.Window.focus() -> boolean` |
+| **Signature** | `cp.ui.Window:focus() -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Attempts to focus the window. |
+| **Parameters** | |
+| **Returns** | true if the window was successfully focused.
|
+
+#### [notifier](#notifier)
+| **Signature** | `cp.ui.Window:notifier() -> cp.ui.notifier` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns a `notifier` that is tracking the application UI element. It has already been started. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [snapshot](#snapshot)
+| **Signature** | `cp.ui.Window:snapshot([path]) -> hs.image | nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Attempts to focus the window. |
-| **Parameters** | |
-| **Returns** | - * `true` if the window was successfully focused.
|
+| **Type** | Method |
+| **Description** | Takes a snapshot of the UI in its current state as a PNG and returns it. |
+| **Parameters** | - path - (optional) The path to save the file. Should include the extension (should be
.png).
|
diff --git a/api/cp/cp.ui.axutils.md b/api/cp/cp.ui.axutils.md
index 774730d..6bfbe35 100644
--- a/api/cp/cp.ui.axutils.md
+++ b/api/cp/cp.ui.axutils.md
@@ -1,16 +1,25 @@
# [docs](index.md) » cp.ui.axutils
---
-Utility functions to support `hs._asm.axuielement`
+Utility functions to support `hs._asm.axuielement`.
## API Overview
* Functions - API calls offered directly by the extension
* [cache](#cache)
* [childAtIndex](#childatindex)
+ * [childFromBottom](#childfrombottom)
* [childFromLeft](#childfromleft)
* [childFromRight](#childfromright)
* [childFromTop](#childfromtop)
+ * [childInColumn](#childincolumn)
+ * [childIndex](#childindex)
* [childMatching](#childmatching)
+ * [children](#children)
+ * [childrenAbove](#childrenabove)
+ * [childrenBelow](#childrenbelow)
+ * [childrenInColumn](#childrenincolumn)
+ * [childrenInLine](#childreninline)
+ * [childrenInNextLine](#childreninnextline)
* [childrenMatching](#childrenmatching)
* [childrenWith](#childrenwith)
* [childrenWithRole](#childrenwithrole)
@@ -18,121 +27,325 @@ Utility functions to support `hs._asm.axuielement`
* [childWithDescription](#childwithdescription)
* [childWithID](#childwithid)
* [childWithRole](#childwithrole)
+ * [childWithTitle](#childwithtitle)
+ * [compareBottomToTop](#comparebottomtotop)
+ * [compareLeftToRight](#comparelefttoright)
+ * [compareRightToLeft](#comparerighttoleft)
+ * [compareTopToBottom](#comparetoptobottom)
+ * [hasAttributeValue](#hasattributevalue)
+ * [hasChild](#haschild)
* [isValid](#isvalid)
+ * [prop](#prop)
+ * [role](#role)
+ * [snapshot](#snapshot)
+ * [valueOf](#valueof)
+ * [withAttributeValue](#withattributevalue)
+ * [withRole](#withrole)
+ * [withTitle](#withtitle)
+ * [withValue](#withvalue)
## API Documentation
### Functions
#### [cache](#cache)
-| **Signature** | `cp.ui.axutils.cache(source, key, finderFn, [verifyFn]) -> axuielement` |
+| **Signature** | `cp.ui.axutils.cache(source, key, finderFn[, verifyFn]) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the cached value at the `source[key]` is a valid axuielement. If not |
-| **Parameters** | - source - the table containing the cache
- key - the key the value is cached under
- finderFn - the function which will return the element if not found.
- [verifyFn] - an optional function which will check the cached element to verify it is still valid.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Checks if the cached value at the `source[key]` is a valid axuielement. If not |
+| **Parameters** | - source - the table containing the cache
- key - the key the value is cached under
- finderFn - the function which will return the element if not found.
- [verifyFn] - an optional function which will check the cached element to verify it is still valid.
|
+| **Returns** | |
#### [childAtIndex](#childatindex)
-| **Signature** | `cp.ui.axutils.childAtIndex(element, index, compareFn) -> axuielement` |
+| **Signature** | `cp.ui.axutils.childAtIndex(element, index, compareFn[, matcherFn]) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Searches for the child element which is at number `index` when sorted using the `compareFn`. |
-| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
- compareFn - a function to compare the elements.
|
-| **Returns** | - The child, or `nil` if the index is larger than the number of children.
|
+| **Type** | Function |
+| **Description** | Searches for the child element which is at number `index` when sorted using the `compareFn`. |
+| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
- compareFn - a function to compare the elements.
- matcherFn - an optional function which is passed each child and returns
true if the child should be processed.
|
+| **Returns** | - The child, or
nil if the index is larger than the number of children.
|
+
+#### [childFromBottom](#childfrombottom)
+| **Signature** | `cp.ui.axutils.childFromBottom(element, index) -> axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Searches for the child element which is at number `index` when sorted bottom-to-top. |
+| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
- matcherFn - an optional function which is passed each child and returns
true if the child should be processed.
|
+| **Returns** | - The child, or
nil if the index is larger than the number of children.
|
#### [childFromLeft](#childfromleft)
-| **Signature** | `cp.ui.axutils.childFromLeft(element, index) -> axuielement` |
+| **Signature** | `cp.ui.axutils.childFromLeft(element, index[, matcherFn]) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Searches for the child element which is at number `index` when sorted left-to-right. |
-| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
|
-| **Returns** | - The child, or `nil` if the index is larger than the number of children.
|
+| **Type** | Function |
+| **Description** | Searches for the child element which is at number `index` when sorted left-to-right. |
+| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
- matcherFn - an optional function which is passed each child and returns
true if the child should be processed.
|
+| **Returns** | - The child, or
nil if the index is larger than the number of children.
|
#### [childFromRight](#childfromright)
-| **Signature** | `cp.ui.axutils.childFromRight(element, index) -> axuielement` |
+| **Signature** | `cp.ui.axutils.childFromRight(element, index[, matcherFn]) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Searches for the child element which is at number `index` when sorted right-to-left. |
-| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
|
-| **Returns** | - The child, or `nil` if the index is larger than the number of children.
|
+| **Type** | Function |
+| **Description** | Searches for the child element which is at number `index` when sorted right-to-left. |
+| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
- matcherFn - an optional function which is passed each child and returns
true if the child should be processed.
|
+| **Returns** | - The child, or
nil if the index is larger than the number of children.
|
#### [childFromTop](#childfromtop)
-| **Signature** | `cp.ui.axutils.childFromTop(element, index) -> axuielement` |
+| **Signature** | `cp.ui.axutils.childFromTop(element, index[, matcherFn]) -> axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Searches for the child element which is at number `index` when sorted top-to-bottom. |
+| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
- matcherFn - an optional function which is passed each child and returns
true if the child should be processed.
|
+| **Returns** | - The child, or
nil if the index is larger than the number of children.
|
+
+#### [childInColumn](#childincolumn)
+| **Signature** | `cp.ui.axutils.childInColumn(element, role, startIndex, childIndex) -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Finds the children for an element, then checks to see if they match the supplied |
+| **Parameters** | - element - The element to retrieve the children from.
- role - The required role as a string.
- startIndex - A number which defines the index of the first element to use.
- childIndex - A number which defines the index of the element to return.
|
+| **Returns** | - The
axuielement if it matches, otherwise nil.
|
+
+#### [childIndex](#childindex)
+| **Signature** | `cp.ui.axutils.childIndex(element) -> number or nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Searches for the child element which is at number `index` when sorted top-to-botom. |
-| **Parameters** | - element - the axuielement or array of axuielements
- index - the index number of the child to find.
|
-| **Returns** | - The child, or `nil` if the index is larger than the number of children.
|
+| **Type** | Function |
+| **Description** | Finds the index of the specified child element, if it is present. If not, `nil` is returned. |
+| **Parameters** | - element - The
axuielement to find the index of.
|
+| **Returns** | - The index (
1 or higher) of the element, or nil if it was not found.
|
#### [childMatching](#childmatching)
-| **Signature** | `cp.ui.axutils.childMatching(element, matcherFn) -> axuielement` |
+| **Signature** | `cp.ui.axutils.childMatching(element, matcherFn[, index]) -> axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | This searches for the first child of the specified element for which the provided function returns `true`. |
+| **Parameters** | - element - the axuielement
- matcherFn - the function which checks if the child matches the requirements.
- index - the number of matching child to return. Defaults to
1.
|
+| **Returns** | - The first matching child, or nil if none was found
|
+
+#### [children](#children)
+| **Signature** | `cp.ui.axutils.children(element[, compareFn]) -> table` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Finds the children for the element. If it is an `hs._asm.axuielement`, it will |
+| **Parameters** | - element - The element to retrieve the children of.
- compareFn - Optional function to use to sort the order of the returned children.
|
+| **Returns** | |
+
+#### [childrenAbove](#childrenabove)
+| **Signature** | `cp.ui.axutils.childrenAbove(element, bottomElement) -> table of axuielement or nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Finds the list of `axuielement` children from the `element` which are above the specified `bottomElement`. |
+| **Parameters** | - element - The
axuielement to find the children of. - topElement - The
axuielement that the other children must be above.
|
+| **Returns** | - The table of
axuielements that are above, or nil if the element is not available.
|
+
+#### [childrenBelow](#childrenbelow)
+| **Signature** | `cp.ui.axutils.childrenBelow(element, topElement) -> table of axuielement or nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for the first child of the specified element for which the provided function returns `true`. |
-| **Parameters** | - element - the axuielement
- matcherFn - the function which checks if the child matches the requirements.
|
-| **Returns** | - The first matching child, or nil if none was found
|
+| **Type** | Function |
+| **Description** | Finds the list of `axuielement` children from the `element` which are below the specified `topElement`. |
+| **Parameters** | - element - The
axuielement to find the children of. - topElement - The
axuielement that the other children must be below.
|
+| **Returns** | - The table of
axuielements that are below, or nil if the element is not available.
|
+
+#### [childrenInColumn](#childrenincolumn)
+| **Signature** | `cp.ui.axutils.childrenInColumn(element, role, startIndex) -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Finds the children for an element, then checks to see if they match the supplied |
+| **Parameters** | - element - The element to retrieve the children from.
- role - The required role as a string.
- startIndex - A number which defines the index of the first element to use.
|
+| **Returns** | - The table of
axuielement objects, otherwise nil.
|
+
+#### [childrenInLine](#childreninline)
+| **Signature** | `cp.ui.axutils.childrenInLine(element) -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets a table of children that are all in the same family and line as the |
+| **Parameters** | - element - The base element.
|
+| **Returns** | - The table of
axuielement objects, otherwise nil.
|
+
+#### [childrenInNextLine](#childreninnextline)
+| **Signature** | `cp.ui.axutils.childrenInNextLine(element) -> table | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Gets a table of children that are in the next line in relation to the supplied |
+| **Parameters** | - element - The base element.
|
+| **Returns** | - The table of
axuielement objects, otherwise nil.
|
#### [childrenMatching](#childrenmatching)
| **Signature** | `cp.ui.axutils.childrenMatching(element, matcherFn) -> { axuielement }` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for all children of the specified element for which the provided |
-| **Parameters** | - element - the axuielement
- matcherFn - the function which checks if the child matches the requirements.
|
-| **Returns** | - All matching children, or `nil` if none was found
|
+| **Type** | Function |
+| **Description** | This searches for all children of the specified element for which the provided |
+| **Parameters** | - element - the axuielement
- matcherFn - the function which checks if the child matches the requirements.
|
+| **Returns** | - All matching children, or
nil if none was found
|
#### [childrenWith](#childrenwith)
| **Signature** | `cp.ui.axutils.childrenWith(element, name, value) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for all children of the specified element which has an attribute with the matching name and value. |
-| **Parameters** | - element - the axuielement
- name - the name of the attribute
- value - the value of the attribute
|
-| **Returns** | - All matching children, or `nil` if none was found
|
+| **Type** | Function |
+| **Description** | This searches for all children of the specified element which has an attribute with the matching name and value. |
+| **Parameters** | - element - the axuielement
- name - the name of the attribute
- value - the value of the attribute
|
+| **Returns** | - All matching children, or
nil if none was found
|
#### [childrenWithRole](#childrenwithrole)
| **Signature** | `cp.ui.axutils.childrenWithRole(element, value) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for all children of the specified element which has an `AXRole` attribute with the matching value. |
-| **Parameters** | - element - the axuielement
- value - the value of the attribute
|
-| **Returns** | - All matching children, or `nil` if none was found
|
+| **Type** | Function |
+| **Description** | This searches for all children of the specified element which has an `AXRole` attribute with the matching value. |
+| **Parameters** | - element - the axuielement
- value - the value of the attribute
|
+| **Returns** | - All matching children, or
nil if none was found
|
#### [childWith](#childwith)
| **Signature** | `cp.ui.axutils.childWith(element, name, value) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for the first child of the specified element which has an attribute with the matching name and value. |
-| **Parameters** | - element - the axuielement
- name - the name of the attribute
- value - the value of the attribute
|
-| **Returns** | - The first matching child, or nil if none was found
|
+| **Type** | Function |
+| **Description** | This searches for the first child of the specified element which has an attribute with the matching name and value. |
+| **Parameters** | - element - the axuielement
- name - the name of the attribute
- value - the value of the attribute
|
+| **Returns** | - The first matching child, or nil if none was found
|
#### [childWithDescription](#childwithdescription)
| **Signature** | `cp.ui.axutils.childWithDescription(element, value) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for the first child of the specified element which has `AXDescription` with the specified value. |
-| **Parameters** | - element - the axuielement
- value - the value
|
-| **Returns** | - The first matching child, or `nil` if none was found
|
+| **Type** | Function |
+| **Description** | This searches for the first child of the specified element which has `AXDescription` with the specified value. |
+| **Parameters** | - element - the axuielement
- value - the value
|
+| **Returns** | - The first matching child, or
nil if none was found
|
#### [childWithID](#childwithid)
| **Signature** | `cp.ui.axutils.childWithID(element, value) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for the first child of the specified element which has `AXIdentifier` with the specified value. |
-| **Parameters** | - element - the axuielement
- value - the value
|
-| **Returns** | - The first matching child, or `nil` if none was found
|
+| **Type** | Function |
+| **Description** | This searches for the first child of the specified element which has `AXIdentifier` with the specified value. |
+| **Parameters** | - element - the axuielement
- value - the value
|
+| **Returns** | - The first matching child, or
nil if none was found
|
#### [childWithRole](#childwithrole)
| **Signature** | `cp.ui.axutils.childWithRole(element, value) -> axuielement` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | This searches for the first child of the specified element which has `AXRole` with the specified value. |
-| **Parameters** | - element - the axuielement
- value - the value
|
-| **Returns** | - The first matching child, or `nil` if none was found
|
+| **Type** | Function |
+| **Description** | This searches for the first child of the specified element which has `AXRole` with the specified value. |
+| **Parameters** | - element - the axuielement
- value - the value
|
+| **Returns** | - The first matching child, or
nil if none was found
|
+
+#### [childWithTitle](#childwithtitle)
+| **Signature** | `cp.ui.axutils.childWithTitle(element, value) -> axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | This searches for the first child of the specified element which has `AXTitle` with the specified value. |
+| **Parameters** | - element - the axuielement
- value - the value
|
+| **Returns** | - The first matching child, or
nil if none was found
|
+
+#### [compareBottomToTop](#comparebottomtotop)
+| **Signature** | `cp.ui.axutils.compareBottomToTop(a, b) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns `true` if element `a` is below element `b`. May be used with `table.sort`. |
+| **Returns** | |
+
+#### [compareLeftToRight](#comparelefttoright)
+| **Signature** | `cp.ui.axutils.compareLeftToRight(a, b) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns `true` if element `a` is left of element `b`. May be used with `table.sort`. |
+| **Returns** | |
+
+#### [compareRightToLeft](#comparerighttoleft)
+| **Signature** | `cp.ui.axutils.compareRightToLeft(a, b) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns `true` if element `a` is right of element `b`. May be used with `table.sort`. |
+| **Returns** | |
+
+#### [compareTopToBottom](#comparetoptobottom)
+| **Signature** | `cp.ui.axutils.compareTopToBottom(a, b) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns `true` if element `a` is above element `b`. May be used with `table.sort`. |
+| **Returns** | |
+
+#### [hasAttributeValue](#hasattributevalue)
+| **Signature** | `cp.ui.axutils.hasAttributeValue(element, name, value) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks to see if an element has a specific value. |
+| **Parameters** | - element - the
axuielement - name - the name of the attribute
- value - the value of the attribute
|
+| **Returns** | true if the element has the supplied attribute value, otherwise false.
|
+
+#### [hasChild](#haschild)
+| **Signature** | `cp.ui.axutils.hasChild(element, matcherFn) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the axuielement has a child that passes the `matcherFn`. |
+| **Parameters** | - element - the
axuielement to check. - matcherFn - the
function that accepts an axuielement and returns a boolean
|
+| **Returns** | true if any child matches, otherwise false.
|
#### [isValid](#isvalid)
| **Signature** | `cp.ui.axutils.isValid(element) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Checks if the axuilelement is still valid - that is, still active in the UI. |
-| **Parameters** | - element - the axuielement
|
-| **Returns** | - `true` if the element is valid.
|
+| **Type** | Function |
+| **Description** | Checks if the axuilelement is still valid - that is, still active in the UI. |
+| **Parameters** | - element - the axuielement
|
+| **Returns** | true if the element is valid.
|
+
+#### [prop](#prop)
+| **Signature** | `cp.ui.axutils.prop(uiFinder, attributeName[, settable]) -> cp.prop` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Creates a new `cp.prop` which will find the `hs._asm.axuielement` via the `uiFinder` and |
+| **Parameters** | - uiFinder - the
cp.prop or function which will retrieve the current hs._asm.axuielement. - attributeName - the
AX atrribute name the property links to. - settable - Defaults to
false. If true, the property will also be settable.
|
+| **Returns** | - The
cp.prop for the attribute.
|
+| **Notes** | - If the
uiFinder is a cp.prop, it will be monitored for changes, making the resulting prop "live".
|
+
+#### [role](#role)
+| **Signature** | `cp.ui.axutils.match.role(roleName) -> function` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns a `match` function that will return true if the `axuielement` has the specified `AXRole`. |
+| **Parameters** | - roleName - The role to check for.
|
+| **Returns** | function(element) -> boolean that checks the AXRole is roleName
|
+
+#### [snapshot](#snapshot)
+| **Signature** | `cp.ui.axutils.snapshot(element[, filename]) -> hs.image` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Takes a snapshot of the specified `axuielement` and returns it. |
+| **Parameters** | - element - The
axuielement to snap. - filename - (optional) The path to save the image as a PNG file.
- elementFrame - (optional) The hs.geometry frame of what you want to capture
|
+| **Returns** | - An
hs.image file, or nil if the element could not be snapped.
|
+
+#### [valueOf](#valueof)
+| **Signature** | `cp.ui.axutils.valueOf(element, name[, default]) -> anything` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns the named `AX` attribute value, or the `default` if it is empty. |
+| **Parameters** | - element - the
axuielement to retrieve the attribute value for. - attribute - The attribute name (e.g. "AXValue")
- default - (optional) if provided, this will be returned if the attribute is
nil.
|
+| **Returns** | - The attribute value, or the
default if none is found.
|
+
+#### [withAttributeValue](#withattributevalue)
+| **Signature** | `cp.ui.axutils.withAttributeValue(element, name, value) -> hs._asm.axuielement | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the element has an attribute value with the specified `name` and `value`. |
+| **Parameters** | - element - The element to check
- name - The name of the attribute to check
- value - The value of the attribute
|
+| **Returns** | - The
axuielement if it matches, otherwise nil.
|
+
+#### [withRole](#withrole)
+| **Signature** | `cp.ui.axutils.withRole(element, role) -> hs._asm.axuielement | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the element has an "AXRole" attribute with the specified `role`. |
+| **Parameters** | - element - The element to check
- role - The required role
|
+| **Returns** | - The
axuielement if it matches, otherwise nil.
|
+
+#### [withTitle](#withtitle)
+| **Signature** | `cp.ui.axutils.withTitle(element, title) -> hs._asm.axuielement | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the element has an "AXTitle" attribute with the specified `title`. |
+| **Parameters** | - element - The element to check
- title - The required title
|
+| **Returns** | - The
axuielement if it matches, otherwise nil.
|
+
+#### [withValue](#withvalue)
+| **Signature** | `cp.ui.axutils.withValue(element, value) -> hs._asm.axuielement | nil` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the element has an "AXValue" attribute with the specified `value`. |
+| **Parameters** | - element - The element to check
- value - The required value
|
+| **Returns** | - The
axuielement if it matches, otherwise nil.
|
diff --git a/api/cp/cp.ui.notifier.md b/api/cp/cp.ui.notifier.md
new file mode 100644
index 0000000..a5ff804
--- /dev/null
+++ b/api/cp/cp.ui.notifier.md
@@ -0,0 +1,138 @@
+# [docs](index.md) » cp.ui.notifier
+---
+
+Supports long-lived 'AX' notifiers. Configure the application to watch, the
+function that provides the `axuielement` and then register for the type of
+notification to watch, along with a function that will get triggered.
+
+For example:
+
+```lua
+local notifier = require("cp.ui.notifier")
+local function finder() ... end -- returns the axuielement
+local o = notifier.new("com.apple.FinalCut", finder)
+o:watchFor("AXValueChanged", function(notifier, element, notification, details) ... end)
+o:start()
+```
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [notifiersForBundleID](#notifiersforbundleid)
+* 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
+ * [app](#app)
+ * [bundleID](#bundleid)
+ * [currentElement](#currentelement)
+ * [debugging](#debugging)
+ * [pid](#pid)
+ * [reset](#reset)
+ * [start](#start)
+ * [update](#update)
+ * [watchAll](#watchall)
+ * [watchFor](#watchfor)
+
+## API Documentation
+
+### Functions
+
+#### [notifiersForBundleID](#notifiersforbundleid)
+| **Signature** | `cp.ui.notifier.notifiersForBundleID(bundleID) -> table of cp.ui.notifier` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Returns the list of `cp.ui.notifier` instances that have been created for the specified `Bundle ID`. |
+| **Parameters** | - bundleID - The application Bundle ID being observed. E.g. "com.apple.FinalCut".
|
+| **Returns** | - A table of
cp.ui.notifier instances.
|
+
+### Constructors
+
+#### [new](#new)
+| **Signature** | `cp.ui.notifier.new(bundleID, elementFinderFn) -> cp.ui.notifier` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Constructor |
+| **Description** | Creates a new `cp.ui.notifier` instance with the specified bundle ID and |
+| **Parameters** | - bundleID - The application Bundle ID being observed. E.g. "com.apple.FinalCut".
- elementFinderFn - The function that will return the
axuielement to observe.
|
+| **Returns** | - A new
cp.ui.notifier instance.
|
+
+### Methods
+
+#### [app](#app)
+| **Signature** | `cp.ui.notifier:app() -> hs.application` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the current `hs.application` instance for the app this notifier tracks. |
+| **Parameters** | |
+| **Returns** | - The running
hs.application for the notifier's bundleID, or nil.
|
+
+#### [bundleID](#bundleid)
+| **Signature** | `cp.ui.notifier:bundleID()` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the application 'bundle ID' that this notifier is tracking. |
+| **Parameters** | |
+| **Returns** | - The application 'bundle ID' string (e.g. "com.apple.FinalCut")
|
+
+#### [currentElement](#currentelement)
+| **Signature** | `cp.ui.notifier:currentElement() -> hs._asm.axuielement` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the current `axuielement` being observed. |
+| **Parameters** | |
+| **Returns** | - The
axuielement, or nil if not available.
|
+
+#### [debugging](#debugging)
+| **Signature** | `cp.ui.notifier:debugging([enabled]) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Enables/disables and reports current debugging status. |
+| **Parameters** | - enabled - If
true, debugging notifications will be emitted. If false, it will be disabled. If not provided, no change is made.
|
+| **Returns** | true if currently debugging, false otherwise.
|
+
+#### [pid](#pid)
+| **Signature** | `cp.ui.notifier:pid() -> number` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Returns the PID for the application being observed, or `nil` if it's not running. |
+| **Parameters** | |
+| **Returns** | |
+
+#### [reset](#reset)
+| **Signature** | `cp.ui.notifier:reset() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Resets the notifier |
+
+#### [start](#start)
+| **Signature** | `cp.ui.notifier:start() -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Stops notifying watchers when events happen. |
+| **Parameters** | |
+| **Returns** | - The
cp.ui.notifier instance.
|
+
+#### [update](#update)
+| **Signature** | `cp.ui.notifier:update([force]) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Updates any watchers to use the current `axuielement`. |
+| **Parameters** | - force - If
true, the notifier will be updated even if the element has not changed since the last update. Defaults to false.
|
+| **Returns** | - The
cp.ui.notifier instance.
|
+
+#### [watchAll](#watchall)
+| **Signature** | `cp.ui.notifier:watchAll(callbackFn) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Registers the callback as a watcher for all standard notifications for the current `axuielement`. |
+| **Parameters** | - callbackFn - the function to call when the notification happens.
|
+| **Returns** | - The
cp.ui.notifier instance.
|
+| **Notes** | - This should generally just be used for debugging purposes. It's best to use
watchFor[#watchFor] in most cases. - The callback function should expect 3 arguments and return none. The arguments passed to the callback will be as follows:
- the
hs._asm.axuielement object for the accessibility element which generated the notification. - a string with the notification type.
- A table containing key-value pairs with more information about the notification, if provided. Commonly this will be an empty table.
|
+
+#### [watchFor](#watchfor)
+| **Signature** | `cp.ui.notifier:watchFor(notification, callbackFn) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Registers a function to get called whenever the specified notification type is triggered |
+| **Parameters** | - notifications - The
string or table of strings with the notification type(s) to watch for (e.g. "AXValueChanged"). - callbackFn - The function to call when the matching notification is happens.
|
+| **Returns** | - The
cp.ui.notifier instance.
|
+| **Notes** | - The callback function should expect 3 arguments and return none. The arguments passed to the callback will be as follows:
- the
hs._asm.axuielement object for the accessibility element which generated the notification. - a string with the notification type.
- A table containing key-value pairs with more information about the notification, if provided. Commonly this will be an empty table.
|
+
diff --git a/api/cp/cp.utf16.be.md b/api/cp/cp.utf16.be.md
index aa24474..2b994dd 100644
--- a/api/cp/cp.utf16.be.md
+++ b/api/cp/cp.utf16.be.md
@@ -18,40 +18,40 @@ A pure-LUA implementation of UTF-16 decoding with big-endian ordering.
#### [char](#char)
| **Signature** | `cp.utf16.be.char(...) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Receives zero or more integers, converts each one to its corresponding UTF-16 byte sequence and returns a string with the concatenation of all these sequences. |
-| **Parameters** | - `...` - The list of UCL codepoint integers to convert.
|
-| **Returns** | - All the codepoints converted to UTF-16, concatonated into a string.
|
+| **Type** | Function |
+| **Description** | Receives zero or more integers, converts each one to its corresponding UTF-16 byte sequence and returns a string with the concatenation of all these sequences. |
+| **Parameters** | ... - The list of UCL codepoint integers to convert.
|
+| **Returns** | - All the codepoints converted to UTF-16, concatonated into a string.
|
#### [codepoint](#codepoint)
| **Signature** | `cp.utf16.be.codepoint(s [, i [, j]]) -> integer...` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the codepoints (as integers) from all characters in `s` that start between byte position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises an error if it meets any invalid byte sequence. |
-| **Parameters** | - `s` - The string
- `i` - The starting index. Defaults to `1`.
- `j` - The ending index. Defaults to `i`.
|
-| **Returns** | - a list of codepoint integers for all characters in the matching range.
|
+| **Type** | Function |
+| **Description** | Returns the codepoints (as integers) from all characters in `s` that start between byte position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises an error if it meets any invalid byte sequence. |
+| **Parameters** | s - The stringi - The starting index. Defaults to 1.j - The ending index. Defaults to i.
|
+| **Returns** | - a list of codepoint integers for all characters in the matching range.
|
#### [codes](#codes)
| **Signature** | `cp.utf16.be.codes(s) -> iterator` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns values so that the construction |
-| **Parameters** | - `s` - The string to iterate through.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Returns values so that the construction |
+| **Parameters** | s - The string to iterate through.
|
+| **Returns** | |
#### [len](#len)
| **Signature** | `cp.utf16.be.len (s [, i [, j]]) -> number | boolean, number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the number of UTF-16 characters in string `s` that start between positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte. |
-| **Parameters** | - `s` - The UTF-16 string
- `i` - The starting index. Defaults to `1`.
- `j` - The ending index. Defaults to `-1`.
|
-| **Returns** | - the length, or `false` and the first invalid byte index.
|
+| **Type** | Function |
+| **Description** | Returns the number of UTF-16 characters in string `s` that start between positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte. |
+| **Parameters** | s - The UTF-16 stringi - The starting index. Defaults to 1.j - The ending index. Defaults to -1.
|
+| **Returns** | - the length, or
false and the first invalid byte index.
|
#### [offset](#offset)
| **Signature** | `cp.utf16.be.offset (s, n [, i]) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting from position `i`) starts. A negative `n` gets characters before position `i`. The default for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the `n`-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. |
-| **Parameters** | - `s` - The string
- `n` - The character number to find.
- `i` - The initial position to start from.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting from position `i`) starts. A negative `n` gets characters before position `i`. The default for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the `n`-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. |
+| **Parameters** | s - The stringn - The character number to find.i - The initial position to start from.
|
+| **Returns** | |
diff --git a/api/cp/cp.utf16.le.md b/api/cp/cp.utf16.le.md
index a2f9105..b079bec 100644
--- a/api/cp/cp.utf16.le.md
+++ b/api/cp/cp.utf16.le.md
@@ -19,48 +19,48 @@ A pure-LUA implementation of UTF-16 decoding with little-endian ordering.
#### [char](#char)
| **Signature** | `cp.utf16.le.char(...) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Receives zero or more integers, converts each one to its corresponding UTF-16 byte sequence and returns a string with the concatenation of all these sequences. |
-| **Parameters** | - `...` - The list of UCL codepoint integers to convert.
|
-| **Returns** | - All the codepoints converted to UTF-16, concatonated into a string.
|
+| **Type** | Function |
+| **Description** | Receives zero or more integers, converts each one to its corresponding UTF-16 byte sequence and returns a string with the concatenation of all these sequences. |
+| **Parameters** | ... - The list of UCL codepoint integers to convert.
|
+| **Returns** | - All the codepoints converted to UTF-16, concatonated into a string.
|
#### [codepoint](#codepoint)
| **Signature** | `cp.utf16.le.codepoint(s [, i [, j]]) -> integer...` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the codepoints (as integers) from all characters in `s` that start between byte position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises an error if it meets any invalid byte sequence. |
-| **Parameters** | - `s` - The string
- `i` - The starting index. Defaults to `1`.
- `j` - The ending index. Defaults to `i`.
|
-| **Returns** | - a list of codepoint integers for all characters in the matching range.
|
+| **Type** | Function |
+| **Description** | Returns the codepoints (as integers) from all characters in `s` that start between byte position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises an error if it meets any invalid byte sequence. |
+| **Parameters** | s - The stringi - The starting index. Defaults to 1.j - The ending index. Defaults to i.
|
+| **Returns** | - a list of codepoint integers for all characters in the matching range.
|
#### [codes](#codes)
| **Signature** | `cp.utf16.le.codes(s) -> iterator` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns values so that the construction |
-| **Parameters** | - `s` - The string to iterate through.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Returns values so that the construction |
+| **Parameters** | s - The string to iterate through.
|
+| **Returns** | |
#### [len](#len)
| **Signature** | `cp.utf16.len (bigEndian, s [, i [, j]]) -> number | boolean, number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the number of UTF-16 characters in string `s` that start between positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte. |
-| **Parameters** | - `bigEndian` - If true, the string is 'big-endian'.
- `s` - The UTF-16 string
- `i` - The starting index. Defaults to `1`.
- `j` - The ending index. Defaults to `-1`.
|
-| **Returns** | - the length, or `false` and the first invalid byte index.
|
+| **Type** | Function |
+| **Description** | Returns the number of UTF-16 characters in string `s` that start between positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte. |
+| **Parameters** | bigEndian - If true, the string is 'big-endian'.s - The UTF-16 stringi - The starting index. Defaults to 1.j - The ending index. Defaults to -1.
|
+| **Returns** | - the length, or
false and the first invalid byte index.
|
#### [len](#len)
| **Signature** | `cp.utf16.le.len (s [, i [, j]]) -> number | boolean, number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the number of UTF-16 characters in string `s` that start between positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte. |
-| **Parameters** | - `s` - The UTF-16 string
- `i` - The starting index. Defaults to `1`.
- `j` - The ending index. Defaults to `-1`.
|
-| **Returns** | - the length, or `false` and the first invalid byte index.
|
+| **Type** | Function |
+| **Description** | Returns the number of UTF-16 characters in string `s` that start between positions `i` and `j` (both inclusive). The default for `i` is 1 and for `j` is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte. |
+| **Parameters** | s - The UTF-16 stringi - The starting index. Defaults to 1.j - The ending index. Defaults to -1.
|
+| **Returns** | - the length, or
false and the first invalid byte index.
|
#### [offset](#offset)
| **Signature** | `cp.utf16.le.offset (s, n [, i]) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting from position `i`) starts. A negative `n` gets characters before position `i`. The default for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the `n`-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. |
-| **Parameters** | - `s` - The string
- `n` - The character number to find.
- `i` - The initial position to start from.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting from position `i`) starts. A negative `n` gets characters before position `i`. The default for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the `n`-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. |
+| **Parameters** | s - The stringn - The character number to find.i - The initial position to start from.
|
+| **Returns** | |
diff --git a/api/cp/cp.utf16.md b/api/cp/cp.utf16.md
index 5f90465..e84a4f7 100644
--- a/api/cp/cp.utf16.md
+++ b/api/cp/cp.utf16.md
@@ -21,32 +21,32 @@ A pure-LUA implementation of UTF-16 decoding
#### [char](#char)
| **Signature** | `cp.utf16.char(bigEndian, ...) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Receives zero or more integers, converts each one to its corresponding UTF-16 byte sequence and returns a string with the concatenation of all these sequences. |
-| **Parameters** | - `bigEndian` - If `true`, the output will list the 'big' bytes first
- `...` - The list of UCL codepoint integers to convert.
|
-| **Returns** | - All the codepoints converted to UTF-16, concatonated into a string.
|
+| **Type** | Function |
+| **Description** | Receives zero or more integers, converts each one to its corresponding UTF-16 byte sequence and returns a string with the concatenation of all these sequences. |
+| **Parameters** | bigEndian - If true, the output will list the 'big' bytes first... - The list of UCL codepoint integers to convert.
|
+| **Returns** | - All the codepoints converted to UTF-16, concatonated into a string.
|
#### [codepoint](#codepoint)
| **Signature** | `cp.utf16.codepoint(bigEndian, s [, i [, j]]) -> integer...` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the codepoints (as integers) from all characters in `s` that start between byte position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises an error if it meets any invalid byte sequence. |
-| **Parameters** | - `bigEndian` - (optional) If set to `true`, the string is encoded in 'big-endian' format.
- `s` - The string
- `i` - The starting index. Defaults to `1`.
- `j` - The ending index. Defaults to `i`.
|
-| **Returns** | - a list of codepoint integers for all characters in the matching range.
|
+| **Type** | Function |
+| **Description** | Returns the codepoints (as integers) from all characters in `s` that start between byte position `i` and `j` (both included). The default for `i` is 1 and for `j` is `i`. It raises an error if it meets any invalid byte sequence. |
+| **Parameters** | bigEndian - (optional) If set to true, the string is encoded in 'big-endian' format.s - The stringi - The starting index. Defaults to 1.j - The ending index. Defaults to i.
|
+| **Returns** | - a list of codepoint integers for all characters in the matching range.
|
#### [codes](#codes)
| **Signature** | `cp.utf16.codes(bigEndian, s) -> iterator` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns values so that the construction |
-| **Parameters** | - `bigEndian` - If `true`, the provided string is in 'big-endian' encoding.
- `s` - The string to iterate through.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Returns values so that the construction |
+| **Parameters** | bigEndian - If true, the provided string is in 'big-endian' encoding.s - The string to iterate through.
|
+| **Returns** | |
#### [offset](#offset)
| **Signature** | `cp.utf16.offset (bigEndian, s, n [, i]) -> number` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting from position `i`) starts. A negative `n` gets characters before position `i`. The default for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the `n`-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. |
-| **Parameters** | - `bigEndian` - If `true`, the encoding is 'big-endian'. Defaults to `false`
- `s` - The string
- `n` - The character number to find.
- `i` - The initial position to start from.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Returns the position (in bytes) where the encoding of the `n`-th character of `s` (counting from position `i`) starts. A negative `n` gets characters before position `i`. The default for `i` is 1 when `n` is non-negative and `#s + 1` otherwise, so that `utf8.offset(s, -n)` gets the offset of the `n`-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. |
+| **Parameters** | bigEndian - If true, the encoding is 'big-endian'. Defaults to falses - The stringn - The character number to find.i - The initial position to start from.
|
+| **Returns** | |
diff --git a/api/cp/cp.watcher.md b/api/cp/cp.watcher.md
index 3e4c9c9..9a60d83 100644
--- a/api/cp/cp.watcher.md
+++ b/api/cp/cp.watcher.md
@@ -48,50 +48,50 @@ Then, whenever `thing.update(xxx)` is called, the watcher will output `"New valu
#### [new](#new)
| **Signature** | `cp.watcher.new(...) -> watcher` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Constructs a new watcher instance. |
-| **Parameters** | - `...` - The list of event name strings supported by the watcher.
|
-| **Returns** | |
+| **Type** | Function |
+| **Description** | Constructs a new watcher instance. |
+| **Parameters** | ... - The list of event name strings supported by the watcher.
|
+| **Returns** | |
### Methods
#### [events](#events)
| **Signature** | `cp.watcher:events()` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns a list of the event names supported by this watcher. |
+| **Type** | Method |
+| **Description** | Returns a list of the event names supported by this watcher. |
| **Parameters** | |
-| **Returns** | - The table of event names.
|
+| **Returns** | - The table of event names.
|
#### [getCount](#getcount)
| **Signature** | `cp.watcher:getCount()` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Returns the number of watchers currently registered. |
+| **Type** | Method |
+| **Description** | Returns the number of watchers currently registered. |
| **Parameters** | |
-| **Returns** | |
+| **Returns** | |
#### [notify](#notify)
| **Signature** | `cp.watcher:notify(type, ...) -> nil` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Notifies watchers of the specified event type. |
-| **Parameters** | - `type` - The event type to notify. Must be one of the supported events.
- `...` - These parameters are passed directly to the event watcher functions.
|
-| **Returns** | |
+| **Type** | Method |
+| **Description** | Notifies watchers of the specified event type. |
+| **Parameters** | type - The event type to notify. Must be one of the supported events.... - These parameters are passed directly to the event watcher functions.
|
+| **Returns** | |
#### [unwatch](#unwatch)
| **Signature** | `cp.watcher:unwatch(id) -> boolean` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Removes the watchers which were added with the specified ID. |
-| **Parameters** | - `id` - The unique ID returned from `watch`.
|
-| **Returns** | - `true` if a watcher with the specified ID exists and was successfully removed.
|
+| **Type** | Method |
+| **Description** | Removes the watchers which were added with the specified ID. |
+| **Parameters** | id - The unique ID returned from watch.
|
+| **Returns** | true if a watcher with the specified ID exists and was successfully removed.
|
#### [watch](#watch)
| **Signature** | `cp.watcher:watch(events) -> id` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Method |
-| **Description** | Adds a watcher for the specified events. |
-| **Parameters** | - `events` - A table of functions, one for each event to watch.
|
-| **Returns** | - * A unique ID that can be passed to `unwatch` to stop watching.
|
+| **Type** | Method |
+| **Description** | Adds a watcher for the specified events. |
+| **Parameters** | events - A table of functions, one for each event to watch.
|
+| **Returns** | - A unique ID that can be passed to
unwatch to stop watching.
|
diff --git a/api/cp/cp.web.block.md b/api/cp/cp.web.block.md
new file mode 100644
index 0000000..b84d5bc
--- /dev/null
+++ b/api/cp/cp.web.block.md
@@ -0,0 +1,21 @@
+# [docs](index.md) » cp.web.block
+---
+
+Block.
+
+## API Overview
+* Functions - API calls offered directly by the extension
+ * [is](#is)
+
+## API Documentation
+
+### Functions
+
+#### [is](#is)
+| **Signature** | `cp.web.block.is(value) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `value` is an `cp.web.block`. |
+| **Parameters** | - value - the value to check
|
+| **Returns** | true if it is an HTML block, or false otherwise.
|
+
diff --git a/api/cp/cp.web.generate.md b/api/cp/cp.web.generate.md
index 5d0fcf1..c85a07b 100644
--- a/api/cp/cp.web.generate.md
+++ b/api/cp/cp.web.generate.md
@@ -20,56 +20,56 @@ Functions for Generating HTML UI Items
#### [button](#button)
| **Signature** | `cp.web.generate.button() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates a HTML Button |
+| **Type** | Function |
+| **Description** | Generates a HTML Button |
| **Parameters** | - data - Table containing the data you want to display on the Checkbox
- customTrigger - Custom label used for JavaScript Callback
- customWidth - Number to set the width of the button to
- customID - Overrides the random HTML ID
|
-| **Returns** | - String containing the HTML
|
+| **Returns** | - String containing the HTML
|
#### [checkbox](#checkbox)
| **Signature** | `cp.web.generate.checkbox() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates a HTML Checkbox |
+| **Type** | Function |
+| **Description** | Generates a HTML Checkbox |
| **Parameters** | - data - Table containing the data you want to display on the Checkbox
- customTrigger - Custom label used for JavaScript Callback
- customID - Custom ID used for the HTML objects
|
-| **Returns** | - String containing the HTML
|
+| **Returns** | - String containing the HTML
|
#### [dropdown](#dropdown)
| **Signature** | `cp.web.generate.dropdown() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates a HTML Dropdown |
+| **Type** | Function |
+| **Description** | Generates a HTML Dropdown |
| **Parameters** | - title - Title to put in front of the Dropdown. Can be "".
- data - Table containing the data you want to display on the Checkbox
- customTrigger - Custom label used for JavaScript Callback
|
-| **Returns** | - String containing the HTML
|
+| **Returns** | - String containing the HTML
|
#### [heading](#heading)
| **Signature** | `cp.web.generate.heading() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates a HTML Heading |
+| **Type** | Function |
+| **Description** | Generates a HTML Heading |
| **Parameters** | - data - Table containing the data you want to display on the Checkbox
|
-| **Returns** | - String containing the HTML
|
+| **Returns** | - String containing the HTML
|
#### [javascript](#javascript)
-| **Signature** | `cp.web.generate.javascript(script, context) -> cp.web.html.block` |
+| **Signature** | `cp.web.generate.javascript(script, context) -> cp.web.html` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates a HTML Heading |
+| **Type** | Function |
+| **Description** | Generates a HTML Heading |
| **Parameters** | - data - Table containing the data you want to display on the Checkbox
|
-| **Returns** | - String containing the HTML
|
+| **Returns** | - String containing the HTML
|
#### [setWebviewLabel](#setwebviewlabel)
| **Signature** | `cp.web.generate.setWebviewLabel() -> none` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Sets the WebView Label |
+| **Type** | Function |
+| **Description** | Sets the WebView Label |
| **Parameters** | - value - WebView Label as string
|
-| **Returns** | |
+| **Returns** | |
#### [text](#text)
| **Signature** | `cp.web.generate.text() -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates a blank HTML |
+| **Type** | Function |
+| **Description** | Generates a blank HTML |
| **Parameters** | - data - Table containing the data you want to display.
|
-| **Returns** | - String containing the HTML
|
+| **Returns** | - String containing the HTML
|
diff --git a/api/cp/cp.web.html.md b/api/cp/cp.web.html.md
index ee740bc..73255c7 100644
--- a/api/cp/cp.web.html.md
+++ b/api/cp/cp.web.html.md
@@ -9,37 +9,72 @@ Examples:
```lua
local html = require "cp.web.html"
-print html.p "Hello world!" -- "Hello world!
"
-print html.p { class = "custom" } "Hello world!" -- "Hello world!
"
+print html.p "Hello world!" -- "Hello world!
"
+print html.p { class = "custom" } "Hello world!" -- "Hello world!
"
print html.p { class = "custom" } (
- html.b "Bold" .. " and " .. html.i "italic" .. "."
+ html.b "Bold" .. " and " .. html.i "italic" .. "."
)
-- "Bold and italic.
"
-print html("1 < 2") -- "1 < 2" (escaped)
-print html("1 < 2", true) -- "1 < 2" (unescaped)
-print html.p ("bold", true) -- "bold
"
+print html("1 < 2") -- "1 < 2" (escaped)
+print html("1 < 2", true) -- "1 < 2" (unescaped)
+print html.p ("bold", true) -- "bold
"
```
Be aware that concatonating with ".." can behave unexpectedly in some cases. For example:
```lua
local name = "world!"
-print html.p "Hello " .. name -- "Hello
world!"
+print html.p "Hello " .. name -- "Hello
world!"
```
The `"Hello"` gets inserted into the `p` tag, but the `name` gets concatonated after the closing tag.
To get the `name` inside the `p` tag, we need to put brackets around the content:
```lua
-print html.p ("Hello " .. name) -- "Hello world!
"
+print html.p ("Hello " .. name) -- "Hello world!
"
```
Any tag name can be generated, along with any attribute. The results are correctly escaped.
There are two 'special' tag names:
- * `CDATA` - will generate a `<![CDATA[ ... ]]>` section with the content contained.
- * `__` - (double underscore) will generate a `<!-- ... -->` comment block.
+ * `CDATA` - will generate a `<![CDATA[ ... ]]>` section with the content contained.
+ * `__` - (double underscore) will generate a `<!-- ... -->` comment block.
## API Overview
+* Functions - API calls offered directly by the extension
+ * [is](#is)
+* Methods - API calls which can only be made on an object returned by a constructor
+ * [append](#append)
+ * [prepend](#prepend)
## API Documentation
+### Functions
+
+#### [is](#is)
+| **Signature** | `cp.web.html.is(value) -> boolean` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Function |
+| **Description** | Checks if the `value` is an `cp.web.html` block. |
+| **Parameters** | - value - the value to check
|
+| **Returns** | true if it is an HTML block, or false otherwise.
|
+
+### Methods
+
+#### [append](#append)
+| **Signature** | `cp.web.html:append(newContent[, escaped]) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Appends the content. If specified, the `escaped` value will override any default escaping for the content type. |
+| **Parameters** | - newContent - The content to append to the contents of the HTML block.
- escaped - May be set to override default escaping for the content.
|
+| **Returns** | - The same HTML block instance.
|
+| **Notes** | - The
newContent may be almost any value. The default handling is below: cp.web.html instance: Any other HTML block can be added. Default escaping: false. function: Functions will be executed every time the HTML block is converted to a string. Default escaping: whatever the default is for the returned value. list: Tables which are lists will be iterrated and each item will be evaluated each time the HTML block is converted to a string. Default escaping: the default for each item. everything else: Converted to a string via the tostring function. Default escaping: true.
|
+
+#### [prepend](#prepend)
+| **Signature** | `cp.web.html:prepend(newContent[, escaped]) -> self` |
+| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| **Type** | Method |
+| **Description** | Prepends the content. If specified, the `escaped` value will override any default escaping for the content type. |
+| **Parameters** | - newContent - The content to prepend to the contents of the HTML block.
- escaped - May be set to override default escaping for the content.
|
+| **Returns** | - The same HTML block instance.
|
+| **Notes** | - The
newContent may be almost any value. The default handling is below: cp.web.html instance: Any other HTML block can be added. Default escaping: false. function: Functions will be executed every time the HTML block is converted to a string. Default escaping: whatever the default is for the returned value. list: Tables which are lists will be iterrated and each item will be evaluated each time the HTML block is converted to a string. Default escaping: the default for each item. everything else: Converted to a string via the tostring function. Default escaping: true.
|
+
diff --git a/api/cp/cp.web.text.md b/api/cp/cp.web.text.md
index d25e89a..1424b6f 100644
--- a/api/cp/cp.web.text.md
+++ b/api/cp/cp.web.text.md
@@ -15,16 +15,16 @@ Functions for managing text on the web.
#### [escapeXML](#escapexml)
| **Signature** | `cp.web.text.escapeXML(s) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Escapes a string |
+| **Type** | Function |
+| **Description** | Escapes a string |
| **Parameters** | - s - The string you want to escape
|
-| **Returns** | - The string, escaped for XML.
|
+| **Returns** | - The string, escaped for XML.
|
#### [unescapeXML](#unescapexml)
| **Signature** | `cp.web.text.unescapeXML(s) -> string` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Unescapes a string from XML encoding. |
+| **Type** | Function |
+| **Description** | Unescapes a string from XML encoding. |
| **Parameters** | - s - The string you want to unescape
|
-| **Returns** | |
+| **Returns** | |
diff --git a/api/cp/cp.web.ui.md b/api/cp/cp.web.ui.md
index 6ff0bf7..854d2cf 100644
--- a/api/cp/cp.web.ui.md
+++ b/api/cp/cp.web.ui.md
@@ -13,6 +13,7 @@ and if functions are provided, they are re-evaluated every time the element is g
* [javascript](#javascript)
* [password](#password)
* [select](#select)
+ * [style](#style)
* [template](#template)
* [textbox](#textbox)
* Constructors - API calls which return an object, typically one that offers API methods
@@ -26,82 +27,90 @@ and if functions are provided, they are re-evaluated every time the element is g
#### [heading](#heading)
| **Signature** | `cp.web.ui.heading(params) -> cp.web.html` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Creates a `cp.web.html` element for a heading with a specific level |
-| **Parameters** | - `params` - The parameters table. Details below.
|
-| **Returns** | - `cp.web.html` element representing the heading.
|
-| **Notes** | - The `params` table has the following fields:
- ** `text` - The string (or function) containing the text of the heading.
- ** `level` - The heading level (or function) (1-7). Defaults to 3.
- ** `class` - The CSS class (or function) for the heading tag.
|
+| **Type** | Function |
+| **Description** | Creates a `cp.web.html` element for a heading with a specific level |
+| **Parameters** | params - The parameters table. Details below.
|
+| **Returns** | cp.web.html element representing the heading.
|
+| **Notes** | - The
params table has the following fields: text - The string (or function) containing the text of the heading. level - The heading level (or function) (1-7). Defaults to 3. ** class - The CSS class (or function) for the heading tag.
|
#### [img](#img)
| **Signature** | `cp.web.ui.img(params) -> cp.web.html` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates a `cp.web.html` `img` element. |
-| **Parameters** | - `params` - A table or function returning a table with the checkbox data.
|
-| **Returns** | - A `cp.web.html` with the select defined.
|
-| **Notes** | - The `params` table has the following supported fields:
- ** `src` - The source of the image. If this points to a local file, it will be encoded as Base64.
- ** `class` - A string, (or function returning a string) with the CSS class for the element.
- ** `width` - The width of the image.
- ** `height` - The height of the image.
|
+| **Type** | Function |
+| **Description** | Generates a `cp.web.html` `img` element. |
+| **Parameters** | params - A table or function returning a table with the checkbox data.
|
+| **Returns** | - A
cp.web.html with the select defined.
|
+| **Notes** | - The
params table has the following supported fields: src - The source of the image. If this points to a local file, it will be encoded as Base64. class - A string, (or function returning a string) with the CSS class for the element. width - The width of the image. height - The height of the image.
|
#### [javascript](#javascript)
-| **Signature** | `cp.web.ui.javascript(script, context) -> cp.web.html` |
+| **Signature** | `cp.web.ui.javascript(script[, context][, naked]) -> cp.web.html` |
| -----------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| **Type** | Function |
-| **Description** | Generates an HTML script element which will execute the provided |
-| **Parameters** | - script - String containing the JavaScript to execute.
- context - Table containing any values to inject into the script.
|
-| **Returns** | - a `cp.web.html` element representing the JavaScript block.
|
+| **Type** | Function |
+| **Description** | Generates an HTML script element which will execute the provided |
+| **Parameters** |