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 2026 LateNite Films Pty Ltd. All rights reserved.