notifier

Last updated 4 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

API Documentation

Functions

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")

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.