#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:

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

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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 160

#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 a function that returns the element being observed.
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.
Notes	The function has a signature of `function() -> hs.axuielement`. It simply returns the current element being observed, or `nil` if none is available. The function will be called multiple times over the life of the notifier.
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 126

#Methods

#app


Signature	`cp.ui.notifier:app() -> hs.application`
Type	Method
Description	Returns the current `hs.application` instance for the app this notifier tracks. May be `nil` if the application is not running.
Parameters	None
Returns	The running `hs.application` for the notifier's `bundleID`, or `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 294

#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")
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 281

#currentElement


Signature	`cp.ui.notifier:currentElement() -> hs.axuielement`
Type	Method
Description	Returns the current `axuielement` being observed.
Parameters	None
Returns	The `axuielement`, or `nil` if not available.
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 173

#debugging


Signature	`cp.ui.notifier:debugging([enabled]) -> boolean`
Type	Method
Description	Enables/disables and reports current debugging status. When enabled, a message will be output for each known notification received.
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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 619

#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`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 329

#reset


Signature	`cp.ui.notifier:reset() -> self`
Type	Method
Description	Resets the notifier
Parameters	None
Returns	Self
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 581

#start


Signature	`cp.ui.notifier:start() -> self`
Type	Method
Description	Stops notifying watchers when events happen.
Parameters	None
Returns	The `cp.ui.notifier` instance.
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 564

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 489

#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.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.
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 234

#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 for the current `axuielement`.
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.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.
Examples	None
Source	src/extensions/cp/ui/notifier.lua line 186