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