Internationalisation
Bundled Plugins API
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:
1
local notifier = require("cp.ui.notifier")
2
local function finder() ... end -- returns the axuielement
3
local o = notifier.new("com.apple.FinalCut", finder)
4
o:watchFor("AXValueChanged", function(notifier, element, notification, details) ... end)
5
o:start()
Copied!

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.
Last modified 1mo ago