#cp.fn.ax

A collection of useful functions for working with AX.

You may also find functions in cp.fn and cp.fn.table useful.

#API Overview

Functions - API calls offered directly by the extension

areAligned
attribute
bottomToTop
bottomUp
cache
childMatching
children
childrenMatching
childrenTopDown
childWith
hasAttributeValue
hasRole
init
initElements
isUIElement
isValid
leftToRight
matchesIf
narrowToWide
performAction
prop
rightToLeft
setAttribute
shortToTall
topDown
topToBottom
topToBottomBaseAligned
uielement
uielementList

#API Documentation

#Functions

#areAligned


Signature	`cp.fn.ax.areAligned(a, b) -> boolean`
Type	Function
Description	Returns `true` if element `a` is aligned with element `b`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is aligned with `b`.
Notes	Two elements are considered to be aligned if the interesection if their heights are at least 50% of the height of both elements.
Examples	None
Source	src/extensions/cp/fn/ax.lua line 205

#attribute


Signature	`cp.fn.ax.attribute(name) -> function(uivalue) -> any \| nil`
Type	Function
Description	Returns a function which will return the `AX` value of the given `name` from the given `value`.
Parameters	name - The name of the attribute to get. Eg. `"AXValue"`.
Returns	A function which will return the `AX` value of the given `name` from the given `uivalue`. This is safe to use as a cp.prop:mutate getter, since it will resolve the `original` value before getting the named attribute.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 118

#bottomToTop


Signature	`cp.fn.ax.bottomToTop(a, b) -> boolean`
Type	Function
Description	Returns `true` if element `a` is below element `b`. May be used with `table.sort`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is below `b`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 426

#bottomUp


Signature	`cp.fn.ax.bottomUp(a, b) -> boolean`
Type	Function
Description	The reverse of `topDown`, ordering from linearly from bottom-to-top, right-to-left
Parameters	a - The first `axuielement` to compare. b - The second `axuielement` to compare.
Returns	`true` if `a` is below or to the right of `b` in the UI, `false` otherwise.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 519

#cache


Signature	`cp.fn.ax.cache(source, key, finderFn, [verifyFn]) -> cachedValue`
Type	Function
Description	A combinator which 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 `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`. Example: ```lua ax.cache(self, "_ui", MyElement.matches)( fn.table.get(1) -- return the first child of the element. ) 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/fn/ax.lua line 158

#childMatching


Signature	`cp.fn.ax.childMatching(predicate[, index][, comparator]) -> function(uivalue) -> axuielement \| nil`
Type	Function
Description	Returns a function that will return the first child of the given `uivalue` that matches the given `predicate`.
Parameters	predicate - A function that will be called with the child `axuielement` and should return `true` if the child matches. index - An optional number that will be used to determine the child to return. Defaults to `1`. comparator - An optional function that will be called with the child `axuielement` and should return `true` if the child matches. Defaults to `cp.fn.ax.topDown`.
Returns	A function that will return the first child of the given `uivalue` that matches the given `predicate`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 274

#children


Signature	`cp.fn.ax.children(value) -> table \| nil`
Type	Function
Description	Returns the children of the given `value`.
Parameters	value - The value to get the children from.
Returns	The children of the given `value` or `nil`.
Notes	If it is a `table` with a `AXChildren` field, the `AXChildren` field is returned. If it is a `table` with a `UI` field, the `UI` field is called and the result is returned. If it is a `table` with a `children` function, it is called and the result is returned. If it is a `table` with a `children` field, the `children` field is returned. Otherwise, if it's any `table`, that table is returned.
Examples	None
Source	src/extensions/cp/fn/ax.lua line 232

#childrenMatching


Signature	`cp.fn.ax.childrenMatching(predicate[, comparator]) -> table of axuielement \| nil`
Type	Function
Description	Returns the children of the given `uivalue` that match the given `predicate`.
Parameters	predicate - The predicate to match. comparator - An optional comparator to use. Defaults to topDown.
Returns	A table of `axuielement`s that match the given `predicate`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 259

#childrenTopDown


Signature	`cp.fn.ax.childrenTopDown(value) -> table \| nil`
Type	Function
Description	Returns the children of the given `value` sorted in topDown order.
Parameters	value - The value to get the children from.
Returns	The children of the given `value`, sorted topDown, or `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 629

#childWith


Signature	`cp.fn.ax.childWith(attribute, value) -> function(uivalue) -> axuielement \| nil`
Type	Function
Description	Returns a function that will return the first child of the given `uivalue` that has the given `attribute` set to `value`.
Parameters	attribute - The attribute to check. value - The value to check.
Returns	A function that will return the first child of the given `uivalue` that has the given `attribute` set to `value`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 296

#hasAttributeValue


Signature	`cp.fn.ax.hasAttributeValue(attribute, value) -> function(uivalue) -> boolean`
Type	Function
Description	Returns a function that returns `true` if the given `uivalue` has the given `attribute` set to the `value`.
Parameters	attribute - The attribute to check for. value - The value to check for.
Returns	A function that accepts an `axuielement` uivalue which in turn returns `true` if the `uivalue` has the given `attribute` set to the `value`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 327

#hasRole


Signature	`cp.fn.ax.hasRole(role) -> function(uivalue) -> boolean`
Type	Function
Description	Returns a function that returns `true` if the given `uivalue` has the given `AXRole`.
Parameters	role - The role to check for.
Returns	A function that accepts an `axuielement` uivalue which in turn returns `true` if the `uivalue` has the given `AXRole`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 347

#init


Signature	`cp.fn.ax.init(elementType, ...) -> function(parent, uiFinder) -> cp.ui.Element`
Type	Function
Description	Creates a function that will create a new `cp.ui.Element` of the given `elementType` with the given `parent` and `uiFinder`.
Parameters	elementType - The type of `cp.ui.Element` to create. ... - Any additional arguments to pass to the `elementType` constructor.
Returns	A function that will create a new `cp.ui.Element` of the given `elementType` with the given `parent` and `uiFinder`.
Notes	Any additional arguments will be passed to the `elementType` constructor after the `parent` and `uiFinder`. If any of the additional arguments are a `function`, they will be called with the `parent` and `uiFinder` as the first two arguments when being passed into the constructor.
Examples	None
Source	src/extensions/cp/fn/ax.lua line 533

#initElements


Signature	`cp.fn.ax.initElements(parent, elementsUiFinder, elementInits) -> table of cp.ui.Element`
Type	Function
Description	Creates a table of `cp.ui.Element`s of the given `elementInits` with the given `parent` and `uiFinder`. Any additional elements provided by `elementsUiFinder` which don't have a matching `elementInits` will be ignored.
Parameters	parent - The parent `cp.ui.Element` to use for the created `cp.ui.Element`s. elementsUiFinder - A `function` or `cp.prop` that will return a table of `axuielement`s to use as the elements for the created `cp.ui.Element`s. elementInits - A table of `function`s that will create `cp.ui.Element`s.
Returns	A table of `cp.ui.Element`s.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 568

#isUIElement


Signature	`cp.fn.ax.isUIElement(value) -> boolean`
Type	Function
Description	Checks to see if the `value` is an `axuielement`
Parameters	value - The value to check
Returns	`true` if the value is an `axuielement`
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 28

#isValid


Signature	`cp.fn.ax.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/fn/ax.lua line 358

#leftToRight


Signature	`cp.fn.ax.leftToRight(a, b) -> boolean`
Type	Function
Description	Returns `true` if element `a` is left of element `b`. May be used with `table.sort`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is left of `b`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 378

#matchesIf


Signature	`cp.fn.ax.matchesIf(...) -> function(value) -> boolean`
Type	Function
Description	Creates a `function` which will return `true` if the `value` is either an `axuielement`, an Element, or a `callable` (function) that returns an `axuielement` that matches the predicate.
Parameters	... - Any number of predicates, all of which must return a `truthy` value for the `value` to match.
Returns	A `function` which will return `true` if the `value` is a match.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 609

#narrowToWide


Signature	`cp.fn.ax.narrowToWide(a, b) -> boolean`
Type	Function
Description	Returns `true` if element `a` is narrower than element `b`. May be used with `table.sort`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is narrower than `b`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 468

#performAction


Signature	`cp.fn.ax.performAction(action) -> function(uivalue) -> axuielement \| false \| nil, errString`
Type	Function
Description	Performs the given `action` on the given `uivalue`.
Parameters	action - The action to perform (e.g. "AXPress")
Returns	A function that accepts an `axuielement` uivalue which in turn returns the result of performing the action.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 308

#prop


Signature	`cp.fn.ax.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/fn/ax.lua line 587

#rightToLeft


Signature	`cp.fn.ax.rightToLeft(a, b) -> boolean`
Type	Function
Description	Returns `true` if element `a` is right of element `b`. May be used with `table.sort`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is right of `b`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 394

#setAttribute


Signature	`cp.fn.ax.setAttribute(name) -> function(newValue, uivalue) -> nil`
Type	Function
Description	Returns a function which will set the `AX` value of `uivalue` (if present) the given `name` from the given `value`. If the `uivalue` is not present, it will not attempt to set the new value.
Parameters	name - The name of the attribute to set. Eg. `"AXValue"`.
Returns	A function which will set the `AX` value of the given `name` from the given `uivalue`. The `newValue` will be passed to the `setAttributeValue` method of the `uivalue`. The `uivalue` will attempt to be resolved via uielement. This is safe to use as a cp.prop:mutate setter, since it will take the `newValue` and `uivalue` in the correct order and resolve the `uivalue`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 137

#shortToTall


Signature	`cp.fn.ax.shortToTall(a, b) -> boolean`
Type	Function
Description	Returns `true` if element `a` is shorter than element `b`. May be used with `table.sort`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is shorter than `b`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 484

#topDown


Signature	`cp.fn.ax.topDown(a, b) -> boolean`
Type	Function
Description	Compares two `axuielement` values, ordering them linearly, from top-to-bottom, left-to-right. See the Notes section for more information.
Parameters	a - The first `axuielement` to compare. b - The second `axuielement` to compare.
Returns	`true` if `a` is above or to the left of `b` in the UI, `false` otherwise.
Notes	1. If both elements intersect vertically by more than 50% their heights, they are considered to be on the same line. 2. If not on the same line, the element whose bottom edge is highest is before the other. 3. If they are both still equal, the left-most element is before the other. 4. If they are both still equal, the shortest element is before the other. 5. If they are both still equal, the narrowest element is before the other.
Examples	None
Source	src/extensions/cp/fn/ax.lua line 500

#topToBottom


Signature	`cp.fn.ax.topToBottom(a, b) -> boolean`
Type	Function
Description	Returns `true` if element `a` is above element `b`. May be used with `table.sort`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is above `b`.
Notes	None
Examples	None
Source	src/extensions/cp/fn/ax.lua line 410

#topToBottomBaseAligned


Signature	`cp.fn.ax.topToBottomBaseAligned(a, b) -> boolean`
Type	Function
Description	Returns `true` if the base of element `a` is above the base of element `b`, based on linear vertical alignment. May be used with `table.sort`.
Parameters	a - The first element b - The second element
Returns	`true` if `a` is above `b`.
Notes	Two elements are considered to be aligned if the intersection of the height is at least 50% of the height of both elements.
Examples	None
Source	src/extensions/cp/fn/ax.lua line 442

#uielement


Signature	`cp.fn.ax.uielement(uivalue) -> axuielement \| nil`
Type	Function
Description	Returns the axuielement for the given `uivalue`.
Parameters	uivalue - The value to get the `axuielement` from.
Returns	The `axuielement` for the given `value` or `nil`.
Notes	If the `value` is an `axuielement`, it is returned. If the `value` is a table with a callable `UI` field, the `UI` field is called and the result is returned. If the `value` is callable, it is called and the result is returned. Otherwise, `nil` is returned.
Examples	None
Source	src/extensions/cp/fn/ax.lua line 41

#uielementList


Signature	`cp.fn.ax.uielementList(value) -> table of axuielement \| nil`
Type	Function
Description	Returns the `axuielement` list for the given `value`, if available.
Parameters	value - The value to get the `axuielement` list from.
Returns	The `axuielement` list for the given `value` or `nil`.
Notes	If the `value` is a `table` with a `UI` field, the `UI` field is called and the result is returned if it is a list. If the `value` is callable (i.e. a `function`), it is called and the result is returned if it is a list. If the `value` is a `table`, it is returned. Otherwise, `nil` is returned.
Examples	None
Source	src/extensions/cp/fn/ax.lua line 69