#cp.ui.axutils

Utility functions to support hs.axuielement.

#Submodules

#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
hasAttributeValue
hasChild
isValid
prop
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 it will call the provided `finderFn()` function (with no arguments), cache the result and return it.
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.
Notes	If the optional `verifyFn` is provided, it will be called to check that the cached value is still valid. It is passed a single parameter (the axuielement) and is expected to return `true` or `false`.
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 654

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 385

#childFromBottom


Signature	`cp.ui.axutils.childFromBottom(element, index, matcherFn) -> 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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 528

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 483

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 498

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 513

#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 role. It then compares the vertical position data of all matching children and returns an element defined by the `childIndex`, which lines up vertially with the element defined by the `startIndex`.
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`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 133

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 603

#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`. The function will receive one parameter - the current child.
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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 354

#children


Signature	`cp.ui.axutils.children(element[, compareFn]) -> table`
Type	Function
Description	Finds the children for the element. If it is an `hs.axuielement`, it will attempt to get the `AXChildren` attribute. If it is a table with a `children` function, that will get called. If no children exist, an empty table will be returned.
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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 149

#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`. If the `element` is `nil`, `nil` is returned. If the `topElement` is `nil` all children are returned.
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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 197

#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`. If the `element` is `nil`, `nil` is returned. If the `topElement` is `nil` all children are returned.
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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 183

#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 role. It then compares the vertical position data of all matching children and returns a table with only the elements that line up to the element defined by the startIndex.
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`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 93

#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 supplied element.
Parameters	element - The base element.
Returns	The table of `axuielement` objects, otherwise `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 39

#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 element. Scrollbars will be ignored.
Parameters	element - The base element.
Returns	The table of `axuielement` objects, otherwise `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 65

#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 function returns `true`. The function will receive one parameter - the current child.
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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 572

#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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 543

#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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 558

#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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 283

#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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 340

#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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 298

#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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 312

#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
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 326

#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`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 211

#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`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 589

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 624

#prop


Signature	`cp.ui.axutils.prop(uiFinder, attributeName[, settable]) -> cp.prop`
Type	Function
Description	Creates a new `cp.prop` which will find the `hs.axuielement` via the `uiFinder` and get/set the value (if settable is `true`).
Parameters	uiFinder - the `cp.prop` or `function` which will retrieve the current `hs.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".
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 761

#snapshot


Signature	`cp.ui.axutils.snapshot(element, filename, elementFrame) -> hs.image`
Type	Function
Description	Takes a snapshot of the specified `axuielement` and returns it. If the `filename` is provided it also saves the file to the specified location.
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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 689

#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.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 22

#withAttributeValue


Signature	`cp.ui.axutils.withAttributeValue(element, name, value) -> hs.axuielement \| nil`
Type	Function
Description	Checks if the element has an attribute value with the specified `name` and `value`. If so, the element is returned, otherwise `nil`.
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`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 226

#withRole


Signature	`cp.ui.axutils.withRole(element, role) -> hs.axuielement \| nil`
Type	Function
Description	Checks if the element has an "AXRole" attribute with the specified `role`. If so, the element is returned, otherwise `nil`.
Parameters	element - The element to check role - The required role
Returns	The `axuielement` if it matches, otherwise `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 241

#withTitle


Signature	`cp.ui.axutils.withTitle(element, title) -> hs.axuielement \| nil`
Type	Function
Description	Checks if the element has an "AXTitle" attribute with the specified `title`. If so, the element is returned, otherwise `nil`.
Parameters	element - The element to check title - The required title
Returns	The `axuielement` if it matches, otherwise `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 269

#withValue


Signature	`cp.ui.axutils.withValue(element, value) -> hs.axuielement \| nil`
Type	Function
Description	Checks if the element has an "AXValue" attribute with the specified `value`. If so, the element is returned, otherwise `nil`.
Parameters	element - The element to check value - The required value
Returns	The `axuielement` if it matches, otherwise `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/ui/axutils.lua line 255