cp.ui.Element.md

docs » cp.ui.Element

---

A support class for hs._asm.axuielement management.

See:

• Button
• CheckBox
• MenuButton

API Overview

• Functions - API calls offered directly by the extension
• 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
• isShowing
• position
• role
• size
• subrole
• textValue
• title
• value
• Methods - API calls which can only be made on an object returned by a constructor
• app
• doLayout
• doShow
• focus
• loadLayout
• parent
• saveLayout
• show
• snapshot
• valueIs

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.

identifier

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	The Statement to execute.
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

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

saveLayout

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.