# cp.ui.Element

A support class for hs.axuielement management.

See:

# API Overview

Functions - API calls offered directly by the extension

  • isTypeOf
  • matches

Constructors - API calls which return an object, typically one that offers API methods

  • Element

Fields - Variables which can only be accessed from an object returned by a constructor

  • frame
  • identifier
  • isEnabled
  • isFocused
  • isShowing
  • position
  • role
  • size
  • subrole
  • textValue
  • title
  • value

Methods - API calls which can only be made on an object returned by a constructor

  • app
  • attributeValue
  • defineBuilder
  • doFocus
  • doHighlight
  • doLayout
  • doPerformAction
  • doSetAttributeValue
  • doShow
  • focus
  • highlight
  • loadLayout
  • parent
  • performAction
  • saveLayout
  • setAttributeValue
  • show
  • snapshot
  • valueIs

# API Documentation

# Functions

# isTypeOf

Signature cp.ui.Element:isTypeOf(thing) -> boolean
Type Function
Description Checks if the thing is an Element. If called on subclasses, it will check if the thing is an instance of the subclass.
Parameters
  • thing - The thing to check
Returns
  • true if the thing is a Element instance.
Notes
  • This is a type method, not an instance method or a type function. It is called with : on the type itself,
  • not an instance. For example Element:isTypeOf(value)
Examples None
Source src/extensions/cp/ui/Element.lua line 86

# matches

Signature cp.ui.Element.matches(element) -> boolean
Type Function
Description Matches to any valid hs.axuielement. Sub-types should provide their own matches method.
Parameters
  • The element to check
Returns
  • true if the element is a valid instance of an hs.axuielement.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 103

# Constructors

# Element

Signature cp.ui.Element(parent, uiFinder) -> cp.ui.Element
Type Constructor
Description Creates a new Element with the specified parent and uiFinder. The uiFinder may be either a function that returns an axuielement, or a cp.prop.
Parameters
  • parent - The parent Element (may be nil)
  • uiFinder - The function or prop that actually provides the current axuielement instance.
Returns
  • The new Element instance.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 121

# Fields

# frame

Signature cp.ui.Element.frame <cp.prop: table; read-only; live?>
Type Field
Description Returns the table containing the x, y, w, and h values for the Element frame, or nil if not available.
Notes None
Source src/extensions/cp/ui/Element.lua line 386

# identifier

Signature cp.ui.Element.identifier <cp.prop: string; read-only>
Type Field
Description Returns the AX identifier for the element.
Notes None
Source src/extensions/cp/ui/Element.lua line 372

# isEnabled

Signature cp.ui.Element.isEnabled <cp.prop: boolean; read-only>
Type Field
Description Returns true if the Element is visible and enabled.
Notes None
Source src/extensions/cp/ui/Element.lua line 379

# isFocused

Signature cp.ui.Element.isFocused <cp.prop: boolean; read-only?; live?>
Type Field
Description Returns true if the AXFocused attribute is true. Not always a reliable way to determine focus however.
Notes None
Source src/extensions/cp/ui/Element.lua line 393

# isShowing

Signature cp.ui.Element.isShowing <cp.prop: boolean; read-only; live?>
Type Field
Description If true, the Element is showing on screen.
Notes None
Source src/extensions/cp/ui/Element.lua line 194

# position

Signature cp.ui.Element.position <cp.prop: table; read-only; live?>
Type Field
Description Returns the table containing the x and y values for the Element frame, or nil if not available.
Notes None
Source src/extensions/cp/ui/Element.lua line 400

# role

Signature cp.ui.Element.role <cp.prop: string; read-only>
Type Field
Description Returns the AX role name for the element.
Notes None
Source src/extensions/cp/ui/Element.lua line 358

# size

Signature cp.ui.Element.size <cp.prop: table; read-only; live?>
Type Field
Description Returns the table containing the w and h values for the Element frame, or nil if not available.
Notes None
Source src/extensions/cp/ui/Element.lua line 408

# subrole

Signature cp.ui.Element.subrole <cp.prop: string; read-only>
Type Field
Description Returns the AX subrole name for the element.
Notes None
Source src/extensions/cp/ui/Element.lua line 365

# textValue

Signature cp.ui.Element.textValue <cp.prop: string; read-only; live?>
Type Field
Description The 'AXValue' of the element, if it is a string.
Notes None
Source src/extensions/cp/ui/Element.lua line 164

# title

Signature cp.ui.Element.title <cp.prop: string; read-only, live?>
Type Field
Description The 'AXTitle' of the element.
Notes None
Source src/extensions/cp/ui/Element.lua line 187

# value

Signature cp.ui.Element.value <cp.prop: anything; live?>
Type Field
Description The 'AXValue' of the element.
Notes None
Source src/extensions/cp/ui/Element.lua line 157

# Methods

# app

Signature cp.ui.Element:app() -> App
Type Method
Description Returns the app instance.
Parameters
  • None
Returns
  • App
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 429

# attributeValue

Signature cp.ui.Element:attributeValue(id) -> anything, true | nil, false
Type Method
Description Attempts to retrieve the specified AX attribute value, if the UI is available.
Parameters
  • id - The AX attribute to retrieve.
Returns
  • The current value for the attribute, or nil if the UI is not available, followed by true if the UI is present and was called.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 265

# defineBuilder

Signature cp.ui.Element:defineBuilder(...) -> cp.ui.Element
Type Method
Description Defines a new Builder class on this Element with the specified additional argument names.
Parameters
  • ... - The names for the methods which will collect extra arguments to pass to the Element constructor.
Returns
  • The same Element class instance.
Notes
  • The order of the argument names here is the order in which they will be passed to the Element constructor, no matter what
  • order they are called on the Builder itself.
  • Once defined, the class can be accessed via the static <Element Name>.Builder of the Element subclass.
  • For example, if you have a cp.ui.Element subclass named MyElement, with an extra alpha and beta constructor argument, you can do this:
  • lua</li><li> -- The class definition</li><li> local MyElement = Element:subclass("cp.ui.MyElement"):defineBuilder("withAlpha", "withBeta")</li><li> -- The constructor</li><li> function MyElement.Builder:initialize(parent, uiFinder, alpha, beta)</li><li> Element.initialize(self, parent, uiFinder)</li><li> self.alpha = alpha</li><li> self.beta = beta</li><li> end</li><li> -- Create a callable `MyClass.Builder` instance</li><li> local myElementBuilder = MyElement:withAlpha(1):withBeta(2)</li><li> -- alternately, same result:</li><li> local myElementBuilder = MyElement:withBeta(2):withAlpha(1)</li><li> -- Alternately, same result:</li><li> local myElementBuilder = MyElement.Builder():withAlpha(1):withBeta(2)</li><li> -- Create an instance of `MyClass`:</li><li> local myElement = myElementBuilder(parent, uiFinder)</li><li>
Examples None
Source src/extensions/cp/ui/Element.lua line 33

# doFocus

Signature cp.ui.Element:doFocus() -> cp.rx.go.Statement
Type Method
Description A Statement that attempts to set the focus on the element.
Parameters
  • None
Returns
  • The Statement.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 251

# doHighlight

Signature cp.ui.Element:doHighlight([color], [duration]) -> cp.rx.go.Statement
Type Method
Description Returns a Statement which will attempt to highlight the Element with the specified color and duration.
Parameters
  • color - The hs.drawing color to use. (defaults to red)
  • duration - The number of seconds to highlight for. (defaults to 3 seconds)
Returns
  • The Statement which will perform the action.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 462

# doLayout

Signature cp.ui.Element:doLayout(layout) -> cp.rx.go.Statement
Type Method
Description Returns a Statement which will attempt to load the layout based on the parameters provided by the layout table. This table should generally be generated via the [#saveLayout] method.
Parameters
  • layout - a table of parameters that will be used to layout the element.
Returns
Notes
  • By default, to enable backwards-compatibility, this method will simply call the [#loadLayout]. Override it to provide more optimal asynchonous behaviour if required.
  • When subclassing, the overriding doLayout method should call the parent class's doLayout method,
  • then process any custom values from it, like so:
  • lua</li><li> function MyElement:doLayout(layout)</li><li> layout = layout or {}</li><li> return Do(Element.doLayout(self, layout))</li><li> :Then(function()</li><li> self.myConfig = layout.myConfig</li><li> end)</li><li> :Label("MyElement:doLayout")</li><li> end</li><li>
Examples None
Source src/extensions/cp/ui/Element.lua line 574

# doPerformAction

Signature cp.ui.Element:doPerformAction(id) -> cp.rx.go.Statement
Type Method
Description Returns a Statement which will attempt to perform the action with the specified id (eg. "AXCancel")
Parameters
  • id - The string for the AX action to perform.
Returns
  • The Statement which will perform the action.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 339

# doSetAttributeValue

Signature cp.ui.Element:doSetAttributeValue(id, value) -> cp.rx.go.Statement
Type Method
Description Returns a Statement which will attempt to update the specified AX attribute to the new value.
Parameters
  • id - The string for the AX action to perform.
  • value - The new value to set.
Returns
  • The Statement which will perform the action and resolve to true if the UI is available and set, otherwise false.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 319

# doShow

Signature cp.ui.Element:doShow() -> cp.rx.go.Statement
Type Method
Description Returns a Statement that will ensure the Element is showing. By default, will ask the parent to show, if the parent is available.
Parameters
  • None
Returns
  • A Statement
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 206

# focus

Signature cp.ui.Element:focus() -> self, boolean
Type Method
Description Attempt to set the focus on the element.
Parameters
  • None
Returns
  • self, boolean - the boolean indicates if the focus was set.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 238

# highlight

Signature cp.ui.Element:highlight([color], [duration]) -> cp.ui.Element
Type Method
Description Highlights the Element with the specified color and duration.
Parameters
  • color - The hs.drawing color to use. (defaults to red)
  • duration - The number of seconds to highlight for. (defaults to 3 seconds)
Returns
  • the same Element instance.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 507

# loadLayout

Signature cp.ui.Element:loadLayout(layout) -> nil
Type Method
Description When called, the Element (or subclass) will attempt to load the layout based on the parameters provided by the layout table. This table should generally be generated via the [#saveLayout] method.
Parameters
  • layout - a table of parameters that will be used to layout the element.
Returns
  • None
Notes
  • When subclassing, the overriding loadLayout method should call the parent's loadLayout method,
  • then process any custom values from it, like so:
  • </li><li> function MyElement:loadLayout(layout)</li><li> Element.loadLayout(self, layout)</li><li> self.myConfig = layout.myConfig</li><li> end</li><li>
Examples None
Source src/extensions/cp/ui/Element.lua line 547

# parent

Signature cp.ui.Element:parent() -> parent
Type Method
Description Returns the parent object.
Parameters
  • None
Returns
  • parent
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 416

# performAction

Signature cp.ui.Element:performAction(id) -> boolean
Type Method
Description Attempts to perform the specified AX action, if the UI is available.
Parameters
  • id - The AX action to perform.
Returns
  • true if the UI is available and the action was performed, otherwise false.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 301

# saveLayout

Signature cp.ui.Element:saveLayout() -> table
Type Method
Description Returns a table containing the current configuration details for this Element (or subclass).
Parameters
  • None
Returns
  • None
Notes
  • When subclassing, the overriding saveLayout method should call the parent's saveLayout method,
  • then add values to it, like so:
  • </li><li> function MyElement:saveLayout()</li><li> local layout = Element.saveLayout(self)</li><li> layout.myConfig = self.myConfig</li><li> return layout</li><li> end</li><li>
Examples None
Source src/extensions/cp/ui/Element.lua line 523

# setAttributeValue

Signature cp.ui.Element:setAttributeValue(id, value) -> self, boolean
Type Method
Description If the UI is available, set the named AX attribute to the value.
Parameters
  • id - The AX id to set.
  • value - The new value.
Returns
  • The Element instance, then true if the UI is available and the value was set, otherwise false.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 282

# show

Signature cp.ui.Element:show() -> self
Type Method
Description Shows the Element.
Parameters
  • None
Returns
  • self
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 221

# snapshot

Signature cp.ui.Element:snapshot([path]) -> hs.image | nil
Type Method
Description Takes a snapshot of the button in its current state as a PNG and returns it. If the path is provided, the image will be saved at the specified location.
Parameters
  • path - (optional) The path to save the file. Should include the extension (should be .png).
Returns
  • The hs.image that was created.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 443

# valueIs

Signature cp.ui.Element.valueIs(value) -> boolean
Type Method
Description Checks if the current value of this element is the provided value.
Parameters
  • value - The value to compare to.
Returns
  • true if the current [#value] is equal to the provided value.
Notes None
Examples None
Source src/extensions/cp/ui/Element.lua line 174

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