notifier

Last updated 8 months ago

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:
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​
Constructors - API calls which return an object, typically one that offers API methods
​new​
Methods - API calls which can only be made on an object returned by a constructor
​app​
​bundleID​
​currentElement​
​debugging​
​pid​
​reset​
​start​
​update​
​watchAll​
​watchFor​
API Documentation
Functions
​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​
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​
Signature
cp.ui.notifier:app() -> hs.application
Type
Method
Description
Returns the current hs.application instance for the app this notifier tracks.
Parameters
None
Returns
The running hs.application for the notifier's bundleID, or nil.
​bundleID​
Signature
cp.ui.notifier:bundleID()
Type
Method
Description
Returns the application 'bundle ID' that this notifier is tracking.
Parameters
None
Returns
The application 'bundle ID' string (e.g. "com.apple.FinalCut")
​currentElement​
Signature
cp.ui.notifier:currentElement() -> hs._asm.axuielement
Type
Method
Description
Returns the current axuielement being observed.
Parameters
None
Returns
The axuielement, or nil if not available.
​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​
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
None
Returns
The PID, or nil.
​reset​
Signature
cp.ui.notifier:reset() -> self
Type
Method
Description
Resets the notifier
​start​
Signature
cp.ui.notifier:start() -> self
Type
Method
Description
Stops notifying watchers when events happen.
Parameters
None
Returns
The cp.ui.notifier instance.
​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​
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​
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.

MenuButton

PopUpButton

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.

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.

Signature	`cp.ui.notifier:app() -> hs.application`
Type	Method
Description	Returns the current `hs.application` instance for the app this notifier tracks.
Parameters	None
Returns	The running `hs.application` for the notifier's `bundleID`, or `nil`.

Signature	`cp.ui.notifier:bundleID()`
Type	Method
Description	Returns the application 'bundle ID' that this notifier is tracking.
Parameters	None
Returns	The application 'bundle ID' string (e.g. "com.apple.FinalCut")

Signature	`cp.ui.notifier:currentElement() -> hs._asm.axuielement`
Type	Method
Description	Returns the current `axuielement` being observed.
Parameters	None
Returns	The `axuielement`, or `nil` if not available.

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.

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	None
Returns	The PID, or `nil`.

Signature	`cp.ui.notifier:reset() -> self`
Type	Method
Description	Resets the notifier

Signature	`cp.ui.notifier:start() -> self`
Type	Method
Description	Stops notifying watchers when events happen.
Parameters	None
Returns	The `cp.ui.notifier` instance.

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.

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.

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.

notifier

API Overview

API Documentation

Functions

​notifiersForBundleID​

Constructors

​new​

Methods

​app​

​bundleID​

​currentElement​

​debugging​

​pid​

​reset​

​start​

​update​

​watchAll​

​watchFor​

notifiersForBundleID

new

app

bundleID

currentElement

debugging

pid

reset

start

update

watchAll

watchFor