Internationalisation
Bundled Plugins API
Element
A support class for hs._asm.axuielement management.
See:

API Overview

API Documentation

Functions

matches

Signature
cp.ui.Element.matches(element) -> boolean
Type
Function
Description
Matches to any valid hs._asm.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._asm.axuielement.

Constructors

Element

Signature
cp.ui.Element(parent, uiFinder) -> cp.ui.Element
Type
Constructor
Description
Creates a new Element with the specified parent and uiFinder.
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.

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.
Signature
cp.ui.Element.identifier <cp.prop: string; read-only>
Type
Field
Description
Returns the AX identifier for the element.

isEnabled

Signature
cp.ui.Element.isEnabled <cp.prop: boolean; read-only>
Type
Field
Description
Returns true if the Element is visible and enabled.

isShowing

Signature
cp.ui.Element.isShowing <cp.prop: boolean; read-only; live?>
Type
Field
Description
If true, the Element is showing on screen.

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.

role

Signature
cp.ui.Element.role <cp.prop: string; read-only>
Type
Field
Description
Returns the AX role name for the element.

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.

subrole

Signature
cp.ui.Element.subrole <cp.prop: string; read-only>
Type
Field
Description
Returns the AX subrole name for the element.

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.

title

Signature
cp.ui.Element.title <cp.prop: string; read-only, live?>
Type
Field
Description
The 'AXTitle' of the element.

value

Signature
cp.ui.Element.value <cp.prop: anything; live?>
Type
Field
Description
The 'AXValue' of the element.

Methods

app

Signature
cp.ui.Element:app() -> App
Type
Method
Description
Returns the app instance.
Parameters
  • None
Returns
  • App

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
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 function MyElement:doLayout(layout) layout = layout or {} return Do(Element.doLayout(self, layout)) :Then(function() self.myConfig = layout.myConfig end) :Label("MyElement:doLayout") end

doShow

Signature
cp.ui.Element:doShow() -> cp.rx.go.Statement
Type
Method
Description
Returns a Statement that will ensure the Element is showing.

focus

Signature
cp.ui.Element:focus() -> self
Type
Method
Description
Set the focus on an element.
Parameters
  • None
Returns
  • self
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
Parameters
  • layout - a table of parameters that will be used to layout the element.
Notes
  • When subclassing, the overriding loadLayout method should call the parent's loadLayout method,then process any custom values from it, like so: function MyElement:loadLayout(layout) Element.loadLayout(self, layout) self.myConfig = layout.myConfig end

parent

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

show

Signature
cp.ui.Element:show() -> self
Type
Method
Description
Shows the Element.
Parameters
  • None
Returns
  • self

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. | | Parameters |
  • path - (optional) The path to save the file. Should include the extension (should be .png).
|

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