cp.ui.axutils.md

docs » cp.ui.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.

|