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

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

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

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

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

axutils

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​

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

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.

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

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`

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.

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.