cp.ui.notifier.md

docs » 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
• 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.