axutils

​
Utility functions to support hs._asm.axuielement.
API Overview
Functions - API calls offered directly by the extension
​cache​
​childAtIndex​
​childFromBottom​
​childFromLeft​
​childFromRight​
​childFromTop​
​childInColumn​
​childIndex​
​childMatching​
​children​
​childrenAbove​
​childrenBelow​
​childrenInColumn​
​childrenInLine​
​childrenInNextLine​
​childrenMatching​
​childrenWith​
​childrenWithRole​
​childWith​
​childWithDescription​
​childWithID​
​childWithRole​
​childWithTitle​
​compareBottomToTop​
​compareLeftToRight​
​compareRightToLeft​
​compareTopToBottom​
​hasAttributeValue​
​hasChild​
​isValid​
​prop​
​role​
​snapshot​
​valueOf​
​withAttributeValue​
​withRole​
​withTitle​
​withValue​
API Documentation
Functions
​cache​
Signature
cp.ui.axutils.cache(source, key, finderFn[, verifyFn]) -> axuielement
Type
Function
Description
Checks if the cached value at the source[key] is a valid axuielement. If not
Parameters
source - the table containing the cache
key - the key the value is cached under
finderFn - the function which will return the element if not found.
[verifyFn] - an optional function which will check the cached element to verify it is still valid.
Returns
The valid cached value.
​childAtIndex​
Signature
cp.ui.axutils.childAtIndex(element, index, compareFn[, matcherFn]) -> axuielement
Type
Function
Description
Searches for the child element which is at number index when sorted using the compareFn.
Parameters
element - the axuielement or array of axuielements
index - the index number of the child to find.
compareFn - a function to compare the elements.
matcherFn - an optional function which is passed each child and returns true if the child should be processed.
Returns
The child, or nil if the index is larger than the number of children.
​childFromBottom​
Signature
cp.ui.axutils.childFromBottom(element, index) -> axuielement
Type
Function
Description
Searches for the child element which is at number index when sorted bottom-to-top.
Parameters
element - the axuielement or array of axuielements
index - the index number of the child to find.
matcherFn - an optional function which is passed each child and returns true if the child should be processed.
Returns
The child, or nil if the index is larger than the number of children.
​childFromLeft​
Signature
cp.ui.axutils.childFromLeft(element, index[, matcherFn]) -> axuielement
Type
Function
Description
Searches for the child element which is at number index when sorted left-to-right.
Parameters
element - the axuielement or array of axuielements
index - the index number of the child to find.
matcherFn - an optional function which is passed each child and returns true if the child should be processed.
Returns
The child, or nil if the index is larger than the number of children.
​childFromRight​
Signature
cp.ui.axutils.childFromRight(element, index[, matcherFn]) -> axuielement
Type
Function
Description
Searches for the child element which is at number index when sorted right-to-left.
Parameters
element - the axuielement or array of axuielements
index - the index number of the child to find.
matcherFn - an optional function which is passed each child and returns true if the child should be processed.
Returns
The child, or nil if the index is larger than the number of children.
​childFromTop​
Signature
cp.ui.axutils.childFromTop(element, index[, matcherFn]) -> axuielement
Type
Function
Description
Searches for the child element which is at number index when sorted top-to-bottom.
Parameters
element - the axuielement or array of axuielements
index - the index number of the child to find.
matcherFn - an optional function which is passed each child and returns true if the child should be processed.
Returns
The child, or nil if the index is larger than the number of children.
​childInColumn​
| Signature | cp.ui.axutils.childInColumn(element, role, startIndex, childIndex) -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Finds the children for an element, then checks to see if they match the supplied | | Parameters |
element - The element to retrieve the children from.
role - The required role as a string.
startIndex - A number which defines the index of the first element to use.
childIndex - A number which defines the index of the element to return.
| | Returns |
The axuielement if it matches, otherwise nil.
|
​childIndex​
Signature
cp.ui.axutils.childIndex(element) -> number or nil
Type
Function
Description
Finds the index of the specified child element, if it is present. If not, nil is returned.
Parameters
element - The axuielement to find the index of.
Returns
The index (1 or higher) of the element, or nil if it was not found.
​childMatching​
Signature
cp.ui.axutils.childMatching(element, matcherFn[, index]) -> axuielement
Type
Function
Description
This searches for the first child of the specified element for which the provided function returns true.
Parameters
element - the axuielement
matcherFn - the function which checks if the child matches the requirements.
index - the number of matching child to return. Defaults to 1.
Returns
The first matching child, or nil if none was found
​children​
Signature
cp.ui.axutils.children(element[, compareFn]) -> table
Type
Function
Description
Finds the children for the element. If it is an hs._asm.axuielement, it will
Parameters
element - The element to retrieve the children of.
compareFn - Optional function to use to sort the order of the returned children.
Returns
a table of children
​childrenAbove​
Signature
cp.ui.axutils.childrenAbove(element, bottomElement) -> table of axuielement or nil
Type
Function
Description
Finds the list of axuielement children from the element which are above the specified bottomElement.
Parameters
element - The axuielement to find the children of.
topElement - The axuielement that the other children must be above.
Returns
The table of axuielements that are above, or nil if the element is not available.
​childrenBelow​
Signature
cp.ui.axutils.childrenBelow(element, topElement) -> table of axuielement or nil
Type
Function
Description
Finds the list of axuielement children from the element which are below the specified topElement.
Parameters
element - The axuielement to find the children of.
topElement - The axuielement that the other children must be below.
Returns
The table of axuielements that are below, or nil if the element is not available.
​childrenInColumn​
| Signature | cp.ui.axutils.childrenInColumn(element, role, startIndex) -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Finds the children for an element, then checks to see if they match the supplied | | Parameters |
element - The element to retrieve the children from.
role - The required role as a string.
startIndex - A number which defines the index of the first element to use.
| | Returns |
The table of axuielement objects, otherwise nil.
|
​childrenInLine​
| Signature | cp.ui.axutils.childrenInLine(element) -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Gets a table of children that are all in the same family and line as the | | Parameters |
element - The base element.
| | Returns |
The table of axuielement objects, otherwise nil.
|
​childrenInNextLine​
| Signature | cp.ui.axutils.childrenInNextLine(element) -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Gets a table of children that are in the next line in relation to the supplied | | Parameters |
element - The base element.
| | Returns |
The table of axuielement objects, otherwise nil.
|
​childrenMatching​
Signature
cp.ui.axutils.childrenMatching(element, matcherFn) -> { axuielement }
Type
Function
Description
This searches for all children of the specified element for which the provided
Parameters
element - the axuielement
matcherFn - the function which checks if the child matches the requirements.
Returns
All matching children, or nil if none was found
​childrenWith​
Signature
cp.ui.axutils.childrenWith(element, name, value) -> axuielement
Type
Function
Description
This searches for all children of the specified element which has an attribute with the matching name and value.
Parameters
element - the axuielement
name - the name of the attribute
value - the value of the attribute
Returns
All matching children, or nil if none was found
​childrenWithRole​
Signature
cp.ui.axutils.childrenWithRole(element, value) -> axuielement
Type
Function
Description
This searches for all children of the specified element which has an AXRole attribute with the matching value.
Parameters
element - the axuielement
value - the value of the attribute
Returns
All matching children, or nil if none was found
​childWith​
Signature
cp.ui.axutils.childWith(element, name, value) -> axuielement
Type
Function
Description
This searches for the first child of the specified element which has an attribute with the matching name and value.
Parameters
element - the axuielement
name - the name of the attribute
value - the value of the attribute
Returns
The first matching child, or nil if none was found
​childWithDescription​
Signature
cp.ui.axutils.childWithDescription(element, value) -> axuielement
Type
Function
Description
This searches for the first child of the specified element which has AXDescription with the specified value.
Parameters
element - the axuielement
value - the value
Returns
The first matching child, or nil if none was found
​childWithID​
Signature
cp.ui.axutils.childWithID(element, value) -> axuielement
Type
Function
Description
This searches for the first child of the specified element which has AXIdentifier with the specified value.
Parameters
element - the axuielement
value - the value
Returns
The first matching child, or nil if none was found
​childWithRole​
Signature
cp.ui.axutils.childWithRole(element, value) -> axuielement
Type
Function
Description
This searches for the first child of the specified element which has AXRole with the specified value.
Parameters
element - the axuielement
value - the value
Returns
The first matching child, or nil if none was found
​childWithTitle​
Signature
cp.ui.axutils.childWithTitle(element, value) -> axuielement
Type
Function
Description
This searches for the first child of the specified element which has AXTitle with the specified value.
Parameters
element - the axuielement
value - the value
Returns
The first matching child, or nil if none was found
​compareBottomToTop​
Signature
cp.ui.axutils.compareBottomToTop(a, b) -> boolean
Type
Function
Description
Returns true if element a is below element b. May be used with table.sort.
Returns
true if a is below b.
​compareLeftToRight​
Signature
cp.ui.axutils.compareLeftToRight(a, b) -> boolean
Type
Function
Description
Returns true if element a is left of element b. May be used with table.sort.
Returns
true if a is left of b.
​compareRightToLeft​
Signature
cp.ui.axutils.compareRightToLeft(a, b) -> boolean
Type
Function
Description
Returns true if element a is right of element b. May be used with table.sort.
Returns
true if a is right of b.
​compareTopToBottom​
Signature
cp.ui.axutils.compareTopToBottom(a, b) -> boolean
Type
Function
Description
Returns true if element a is above element b. May be used with table.sort.
Returns
true if a is above b.
​hasAttributeValue​
Signature
cp.ui.axutils.hasAttributeValue(element, name, value) -> boolean
Type
Function
Description
Checks to see if an element has a specific value.
Parameters
element - the axuielement
name - the name of the attribute
value - the value of the attribute
Returns
true if the element has the supplied attribute value, otherwise false.
​hasChild​
Signature
cp.ui.axutils.hasChild(element, matcherFn) -> boolean
Type
Function
Description
Checks if the axuielement has a child that passes the matcherFn.
Parameters
element - the axuielement to check.
matcherFn - the function that accepts an axuielement and returns a boolean
Returns
true if any child matches, otherwise false.
​isValid​
Signature
cp.ui.axutils.isValid(element) -> boolean
Type
Function
Description
Checks if the axuilelement is still valid - that is, still active in the UI.
Parameters
element - the axuielement
Returns
true if the element is valid.
​prop​
Signature
cp.ui.axutils.prop(uiFinder, attributeName[, settable]) -> cp.prop
Type
Function
Description
Creates a new cp.prop which will find the hs._asm.axuielement via the uiFinder and
Parameters
uiFinder - the cp.prop or function which will retrieve the current hs._asm.axuielement.
attributeName - the AX atrribute name the property links to.
settable - Defaults to false. If true, the property will also be settable.
Returns
The cp.prop for the attribute.
Notes
If the uiFinder is a cp.prop, it will be monitored for changes, making the resulting prop "live".
​role​
Signature
cp.ui.axutils.match.role(roleName) -> function
Type
Function
Description
Returns a match function that will return true if the axuielement has the specified AXRole.
Parameters
roleName - The role to check for.
Returns
function(element) -> boolean that checks the AXRole is roleName
​snapshot​
Signature
cp.ui.axutils.snapshot(element[, filename]) -> hs.image
Type
Function
Description
Takes a snapshot of the specified axuielement and returns it.
Parameters
element - The axuielement to snap.
filename - (optional) The path to save the image as a PNG file.
elementFrame - (optional) The hs.geometry frame of what you want to capture
Returns
An hs.image file, or nil if the element could not be snapped.
​valueOf​
Signature
cp.ui.axutils.valueOf(element, name[, default]) -> anything
Type
Function
Description
Returns the named AX attribute value, or the default if it is empty.
Parameters
element - the axuielement to retrieve the attribute value for.
attribute - The attribute name (e.g. "AXValue")
default - (optional) if provided, this will be returned if the attribute is nil.
Returns
The attribute value, or the default if none is found.
​withAttributeValue​
| Signature | cp.ui.axutils.withAttributeValue(element, name, value) -> hs._asm.axuielement | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Checks if the element has an attribute value with the specified name and value. | | Parameters |
element - The element to check
name - The name of the attribute to check
value - The value of the attribute
| | Returns |
The axuielement if it matches, otherwise nil.
|
​withRole​
| Signature | cp.ui.axutils.withRole(element, role) -> hs._asm.axuielement | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Checks if the element has an "AXRole" attribute with the specified role. | | Parameters |
element - The element to check
role - The required role
| | Returns |
The axuielement if it matches, otherwise nil.
|
​withTitle​
| Signature | cp.ui.axutils.withTitle(element, title) -> hs._asm.axuielement | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Checks if the element has an "AXTitle" attribute with the specified title. | | Parameters |
element - The element to check
title - The required title
| | Returns |
The axuielement if it matches, otherwise nil.
|
​withValue​
| Signature | cp.ui.axutils.withValue(element, value) -> hs._asm.axuielement | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Checks if the element has an "AXValue" attribute with the specified value. | | Parameters |
element - The element to check
value - The required value
| | Returns |
The axuielement if it matches, otherwise nil.
|

CommandPost API - Previous

Alert

Next - CommandPost API

Button

Last modified 1mo ago

Export as PDF

Copy link

Contents

API Overview

API Documentation

Functions

API Overview

API Documentation

Functions

​cache​

​childAtIndex​

​childFromBottom​

​childFromLeft​

​childFromRight​

​childFromTop​

​childInColumn​

​childIndex​

​childMatching​

​children​

​childrenAbove​

​childrenBelow​

​childrenInColumn​

​childrenInLine​

​childrenInNextLine​

​childrenMatching​

​childrenWith​

​childrenWithRole​

​childWith​

​childWithDescription​

​childWithID​

​childWithRole​

​childWithTitle​

​compareBottomToTop​

​compareLeftToRight​

​compareRightToLeft​

​compareTopToBottom​

​hasAttributeValue​

​hasChild​

​isValid​

​prop​

​role​

​snapshot​

​valueOf​

​withAttributeValue​

​withRole​

​withTitle​

​withValue​

cache

childAtIndex

childFromBottom

childFromLeft

childFromRight

childFromTop

childInColumn

childIndex

childMatching

children

childrenAbove

childrenBelow

childrenInColumn

childrenInLine

childrenInNextLine

childrenMatching

childrenWith

childrenWithRole

childWith

childWithDescription

childWithID

childWithRole

childWithTitle

compareBottomToTop

compareLeftToRight

compareRightToLeft

compareTopToBottom

hasAttributeValue

hasChild

isValid

prop

role

snapshot

valueOf

withAttributeValue

withRole

withTitle

withValue