# cp.ui.Element A support class for `hs.axuielement` management. See: * [Button](cp.ui.Button.md) * [CheckBox](cp.rx.CheckBox.md) * [MenuButton](cp.rx.MenuButton.md) --- ## API Overview **Functions** - _API calls offered directly by the extension_ * [isTypeOf](#istypeof) * [matches](#matches) **Constructors** - _API calls which return an object, typically one that offers API methods_ * [Element](#element) **Fields** - _Variables which can only be accessed from an object returned by a constructor_ * [frame](#frame) * [identifier](#identifier) * [isEnabled](#isenabled) * [isFocused](#isfocused) * [isShowing](#isshowing) * [position](#position) * [role](#role) * [size](#size) * [subrole](#subrole) * [textValue](#textvalue) * [title](#title) * [value](#value) **Methods** - _API calls which can only be made on an object returned by a constructor_ * [app](#app) * [attributeValue](#attributevalue) * [defineBuilder](#definebuilder) * [doFocus](#dofocus) * [doHighlight](#dohighlight) * [doLayout](#dolayout) * [doPerformAction](#doperformaction) * [doSetAttributeValue](#dosetattributevalue) * [doShow](#doshow) * [focus](#focus) * [highlight](#highlight) * [loadLayout](#loadlayout) * [parent](#parent) * [performAction](#performaction) * [saveLayout](#savelayout) * [setAttributeValue](#setattributevalue) * [show](#show) * [snapshot](#snapshot) * [valueIs](#valueis) --- ## API Documentation #### Functions ### [isTypeOf](#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** | | | **Returns** | | | **Notes** | | | **Examples** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 86](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L86) | --- ### [matches](#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** | | | **Returns** | | | **Notes** | None | | **Examples** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 103](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L103) | --- #### Constructors ### [Element](#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](cp.prop.md). | | **Parameters** | | | **Returns** | | | **Notes** | None | | **Examples** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 121](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L121) | --- #### Fields ### [frame](#frame) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.frame ` | | **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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L386) | --- ### [identifier](#identifier) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.identifier ` | | **Type** | Field | | **Description** | Returns the `AX` identifier for the element. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 372](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L372) | --- ### [isEnabled](#isenabled) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.isEnabled ` | | **Type** | Field | | **Description** | Returns `true` if the `Element` is visible and enabled. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 379](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L379) | --- ### [isFocused](#isfocused) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.isFocused ` | | **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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L393) | --- ### [isShowing](#isshowing) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.isShowing ` | | **Type** | Field | | **Description** | If `true`, the `Element` is showing on screen. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 194](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L194) | --- ### [position](#position) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.position ` | | **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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L400) | --- ### [role](#role) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.role ` | | **Type** | Field | | **Description** | Returns the `AX` role name for the element. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 358](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L358) | --- ### [size](#size) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.size ` | | **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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L408) | --- ### [subrole](#subrole) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.subrole ` | | **Type** | Field | | **Description** | Returns the `AX` subrole name for the element. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 365](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L365) | --- ### [textValue](#textvalue) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.textValue ` | | **Type** | Field | | **Description** | The 'AXValue' of the element, if it is a `string`. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 164](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L164) | --- ### [title](#title) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.title ` | | **Type** | Field | | **Description** | The 'AXTitle' of the element. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 187](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L187) | --- ### [value](#value) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element.value ` | | **Type** | Field | | **Description** | The 'AXValue' of the element. | | **Notes** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 157](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L157) | --- #### Methods ### [app](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L429) | --- ### [attributeValue](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L265) | --- ### [defineBuilder](#definebuilder) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element:defineBuilder(...) -> cp.ui.Element` | | **Type** | Method | | **Description** | Defines a new [Builder](cp.ui.Builder.md) 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 `.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
  • -- The class definition
  • local MyElement = Element:subclass("cp.ui.MyElement"):defineBuilder("withAlpha", "withBeta")
  • -- The constructor
  • function MyElement.Builder:initialize(parent, uiFinder, alpha, beta)
  • Element.initialize(self, parent, uiFinder)
  • self.alpha = alpha
  • self.beta = beta
  • end
  • -- Create a callable `MyClass.Builder` instance
  • local myElementBuilder = MyElement:withAlpha(1):withBeta(2)
  • -- alternately, same result:
  • local myElementBuilder = MyElement:withBeta(2):withAlpha(1)
  • -- Alternately, same result:
  • local myElementBuilder = MyElement.Builder():withAlpha(1):withBeta(2)
  • -- Create an instance of `MyClass`:
  • local myElement = myElementBuilder(parent, uiFinder)
  • ```
| | **Examples** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 33](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L33) | --- ### [doFocus](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L251) | --- ### [doHighlight](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L462) | --- ### [doLayout](#dolayout) | | | | --------------------------------------------|-------------------------------------------------------------------------------------| | **Signature** | `cp.ui.Element:doLayout(layout) -> cp.rx.go.Statement` | | **Type** | Method | | **Description** | Returns a [Statement](cp.rx.go.Statement.md) 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](cp.rx.go.Statement.md) 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
  • ```
| | **Examples** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 574](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L574) | --- ### [doPerformAction](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L339) | --- ### [doSetAttributeValue](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L319) | --- ### [doShow](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L206) | --- ### [focus](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L238) | --- ### [highlight](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L507) | --- ### [loadLayout](#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:
  • ```
  • function MyElement:loadLayout(layout)
  • Element.loadLayout(self, layout)
  • self.myConfig = layout.myConfig
  • end
  • ```
| | **Examples** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 547](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L547) | --- ### [parent](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L416) | --- ### [performAction](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L301) | --- ### [saveLayout](#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:
  • ```
  • function MyElement:saveLayout()
  • local layout = Element.saveLayout(self)
  • layout.myConfig = self.myConfig
  • return layout
  • end
  • ```
| | **Examples** | None | | **Source** | [src/extensions/cp/ui/Element.lua line 523](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L523) | --- ### [setAttributeValue](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L282) | --- ### [show](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L221) | --- ### [snapshot](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L443) | --- ### [valueIs](#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](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/ui/Element.lua#L174) | --- ---