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
• childFromLeft
• childFromRight
• childFromTop
• childMatching
• childrenMatching
• childrenWith
• childrenWithRole
• childWith
• childWithDescription
• childWithID
• childWithRole
• isValid

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) -> 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.
Returns	The child, or nil if the index is larger than the number of children.

childFromLeft

Signature	cp.ui.axutils.childFromLeft(element, index) -> 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.
Returns	The child, or nil if the index is larger than the number of children.

childFromRight

Signature	cp.ui.axutils.childFromRight(element, index) -> 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.
Returns	The child, or nil if the index is larger than the number of children.

childFromTop

Signature	cp.ui.axutils.childFromTop(element, index) -> axuielement
Type	Function
Description	Searches for the child element which is at number index when sorted top-to-botom.
Parameters	element - the axuielement or array of axuielements index - the index number of the child to find.
Returns	The child, or nil if the index is larger than the number of children.

childMatching

Signature	cp.ui.axutils.childMatching(element, matcherFn) -> 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.
Returns	The first matching child, or nil if none was found

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

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.