object.attribute
is a shortcut for object:attributeValue(attribute)
object.attribute = value
is a shortcut for object:setAttributeValue(attribute, value)
for k,v in pairs(object) do ... end
is a shortcut for for k,_ in ipairs(object:attributeNames()) do local v = object:attributeValue(k) ; ... end
or for k,v in pairs(object:allAttributeValues()) do ... end
(though see note below)nil
prevents the key from being retained in the table returned. See hs.axuielement:allAttributeValues for details and a workaround.for i,v in ipairs(object) do ... end
is a shortcut for for i,v in pairs(object:attributeValue("AXChildren") or {}) do ... end
object:attributeValue("AXChildren")
may return nil if the object does not have the AXChildren
attribute; the shortcut does not have this limitation.#object
is a shortcut for #object:attributeValue("AXChildren")
object[i]
is a shortcut for object:attributeValue("AXChildren")[i]
object:do<action>()
is a shortcut for object:performAction(action)
object:<attribute>WithParameter(value)
is a shortcut for `object:parameterizedAttributeValue(attribute, value)hs.axuielement.actions[]
hs.axuielement.actions
hs.axuielement.attributes[]
hs.axuielement.attributes
hs.axuielement.orientations[]
hs.axuielement.orientations
hs.axuielement.parameterizedAttributes[]
hs.axuielement.parameterizedAttributes
hs.axuielement.roles[]
hs.axuielement.roles
hs.axuielement.rulerMarkers[]
hs.axuielement.rulerMarkers
hs.axuielement.sortDirections[]
hs.axuielement.sortDirections
hs.axuielement.subroles[]
hs.axuielement.subroles
hs.axuielement.units[]
hs.axuielement.units
hs.axuielement.searchCriteriaFunction(criteria) -> function
hs.axuielement.applicationElement(applicationObject) -> axuielementObject
hs.application
object.applicationObject
- the hs.application
object for the Application or a string or number which will be passed to hs.application.find
to get an hs.application
object.applicationObject
is a string or number, only the first item found with hs.application.find
will be used by this function to create an axuielementObject.hs.axuielement.applicationElementForPID(pid) -> axuielementObject
pid
- the process ID of the application.hs.axuielement.systemElementAtPosition(x, y | pointTable) -> axuielementObject
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Constructor | | Description | Returns the accessibility object at the specified position on the screen. The top-left corner of the primary screen is 0, 0. | | Parameters |x
- the x coordinate of the screen location to testy
- the y coordinate of the screen location to testpointTable
- the x and y coordinates of the screen location to test, provided as a point-table, like the one returned by hs.mouse.getAbsolutePosition
. A point-table is a table with key-value pairs for keys x
and y
.hs.axuielement.systemWideElement():elementAtPosition(...)
.hs.axuielement.systemWideElement() -> axuielementObject
hs.axuielement.windowElement(windowObject) -> axuielementObject
hs.window
object.windowObject
- the hs.window
object for the window or a string or number which will be passed to hs.window.find
to get an hs.window
object.windowObject
is a string or number, only the first item found with hs.window.find
will be used by this function to create an axuielementObject.hs.axuielement:actionDescription(action) -> string | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a localized description of the specified accessibility object's action. | | Parameters |hs.axuielement:actionNames() -> table | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a list of all the actions the specified accessibility object can perform. | | Parameters |hs.axuielement:allAttributeValues([includeErrors]) -> table | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a table containing key-value pairs for all attributes of the accessibility object. | | Parameters |includeErrors
- an optional boolean, default false, that specifies whether attribute names which generate an error when retrieved are included in the returned results.includeErrors
is not specified or is false, then attributes which exist for the element, but currently have no value assigned, will not appear in the table. This is because Lua treats a nil value for a table's key-value pair as an instruction to remove the key from the table, if it currently exists.includeErrors
as true._code
= -25212error
= "Requested value does not exist"hs.axuielement:allDescendantElements(callback, [withParents]) -> elementSearchObject
callback
- a required function which should expect two arguments: a msg
string specifying how the search ended, and a table containing the discovered descendant elements. msg
will be "completed" when the traversal has completed normally and will contain a string starting with "**" if it terminates early for some reason (see Notes: section for more information)withParents
- an optional boolean, default false, indicating that the parent of objects (and their descendants) should be collected as well.hs.axuielement:elementSearch(callback, { [includeParents = withParents] })
. Please refer to hs.axuielement:elementSearch for details about the returned object and callback arguments.hs.axuielement:asHSApplication() -> hs.application object | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | If the element referes to an application, return an hs.application
object for the element. | | Parameters |hs.application
object for the element ; otherwise return nilhs.axuielement:asHSWindow() -> hs.window object | nil
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | If the element referes to a window, return an hs.window
object for the element. | | Parameters |hs.window
object for the element ; otherwise return nilhs.axuielement:attributeNames() -> table | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a list of all the attributes supported by the specified accessibility object. | | Parameters |hs.axuielement:attributeValue(attribute) -> value | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the value of an accessibility object's attribute. | | Parameters |hs.axuielement:attributeValueCount(attribute) -> integer | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the count of the array of an accessibility object's attribute value. | | Parameters |hs.axuielement:buildTree(callback, [depth], [withParents]) -> elementSearchObject
callback
- a required function which should expect two arguments: a msg
string specifying how the search ended, and a table containing the recorded information. msg
will be "completed" when the search has completed normally (or reached the specified depth) and will contain a string starting with "**" if it terminates early for some reason (see Notes: section for more information)depth
- an optional integer, default math.huge
, specifying the maximum depth from the initial accessibility object that should be visited to identify descendant elements and their attributes.withParents
- an optional boolean, default false, specifying whether or not an element's (or descendant's) attributes for AXParent
and AXTopLevelUIElement
should also be visited when identifying additional elements to include in the results table.results
table passed to the callback for this method is primarily for debugging and exploratory purposes and may not be arranged for easy programatic evaluation.hs.axuielement:copy() -> axuielementObject
hs.axuielement:elementAtPosition(x, y | pointTable) -> axuielementObject | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the accessibility object at the specified position on the screen. The top-left corner of the primary screen is 0, 0. | | Parameters |x
- the x coordinate of the screen location to tesy
- the y coordinate of the screen location to testpointTable
- the x and y coordinates of the screen location to test, provided as a point-table, like the one returned by hs.mouse.getAbsolutePosition
. A point-table is a table with key-value pairs for keys x
and y
.hs.axuielement:elementSearch(callback, [criteria], [namedModifiers]) -> elementSearchObject
callback
- a (usually) required function which will receive the results of this search. The callback should expect three arguments and return none. The arguments to the callback function will be msg
, a string specifying how the search ended and results
, the elementSearchObject containing the requested results, and the number of items added to the results (see count
in namedModifiers
). msg
will be "completed" if the search completes normally, or a string starting with "**" if it is terminated early (see Returns: and Notes: for more details).criteria
- an optional function which should accept one argument (the current element being examined) and return true if it should be included in the results or false if it should be rejected. See hs.axuielement.searchCriteriaFunction to create a search function that uses hs.axuielement:matchesCriteria for evaluation.namedModifiers
- an optional table specifying key-value pairs that further modify or control the search. This table may contain 0 or more of the following keys:count
- an optional integer, default math.huge
, specifying the maximum number of matches to collect before ending the search and invoking the callback. You can continue the search to find additional elements by invoking elementSearchObject:next()
(described below in the Returns
section) on the return value of this method, or on the results argument passed to the callback.depth
- an optional integer, default math.huge
, specifying the maximum number of steps (descendants) from the initial accessibility element the search should visit. If you know that your desired element(s) are relatively close to your starting element, setting this to a lower value can significantly speed up the search.elementSearchObject:cancel([reason])
- cancels the current search and invokes the callback with the partial results already collected. If you specify reason
, the msg
argument for the callback will be ** <reason>
; otherwise it will be "** cancelled".elementSearchObject:isRunning()
- returns true if the search is currently ongoing or false if it has completed or been cancelled.elementSearchObject:matched()
- returns an integer specifying the number of elements which have already been found that meet the specified criteria function.elementSearchObject:runTime()
- returns an integer specifying the number of seconds spent performing this search. Note that this is not an accurate measure of how much time a given search will always take because the time will be greatly affected by how much other activity is occurring within Hammerspoon and on the users computer. Resuming a cancelled search or a search which invoked the callback because it reached count
items with the next
method (descibed below) will cause this number to begin increasing again to provide a cumulative total of time spent performing the search; time between when the callback is invoked and the next
method is invoked is not included.elementSearchObject:visited()
- returns an integer specifying the number of elements which have been examined during the search so far.includeParents
is true, if you do not specify depth
, or if you start from an element that has a lot of descendants (e.g. the application element for a web browser). This is dependent entirely upon how many active accessibility elements the target application defines and where you begin your search and cannot reliably be determined up front, so you may need to experiment to find the best balance for your specific requirements.hs.axuielement:isAttributeSettable(attribute) -> boolean | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns whether the specified accessibility object's attribute can be modified. | | Parameters |hs.axuielement:isValid() -> boolean | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns whether the specified accessibility object is still valid. | | Parameters |hs.axuielement:matchesCriteria(criteria) -> boolean
criteria
- the criteria to compare against the accessibility objectcriteria
argument must be one of the following:hs.axuielement:parameterizedAttributeNames() -> table | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns a list of all the parameterized attributes supported by the specified accessibility object. | | Parameters |hs.axuielement:parameterizedAttributeValue(attribute, parameter) -> value | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the value of an accessibility object's parameterized attribute. | | Parameters |parameter
- the parameter required by the paramaterized attribute.hs.axuielement:path() -> table
table[#table]
) with its most immediate parent at #table - 1
, etc. until the rootmost object for this element is reached at index position 1.hs.axuielement:performAction(action) -> axuielement | false | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Requests that the specified accessibility object perform the specified action. | | Parameters |hs.axuielement:pid() -> integer | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the process ID associated with the specified accessibility object. | | Parameters |hs.axuielement:setAttributeValue(attribute, value) -> axuielementObject | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Sets the accessibility object's attribute to the specified value. | | Parameters |value
- the value to assign to the attributehs.axuielement:setTimeout(value) -> axuielementObject | nil, errString
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Sets the timeout value used accessibility queries performed from this element. | | Parameters |value
- the number of seconds for the new timeout value. Must be 0 or positive.