Internationalisation
Bundled Plugins API
axutils
Utility functions to support hs._asm.axuielement.

API Overview

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.
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.
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.
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.
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.
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.
| 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.
|
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.
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
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.
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.
| 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.
|
| 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.
|
| 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.
|
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
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
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
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
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
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
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
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.
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.
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.
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.
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.
| 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.
|
Last modified 1mo ago
Export as PDF
Copy link