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

© Copyright 2025 LateNite Films Pty Ltd. All rights reserved.