docs » hs.axuielement

This module allows you to access the accessibility objects of running applications, their windows, menus, and other user interface elements that support the OS X accessibility API.

This module works through the use of axuielementObjects, which is the Hammerspoon representation for an accessibility object. An accessibility object represents any object or component of an OS X application which can be manipulated through the OS X Accessibility API -- it can be an application, a window, a button, selected text, etc. As such, it can only support those features and objects within an application that the application developers make available through the Accessibility API.

In addition to the formal methods described in this documentation, dynamic methods exist for accessing element attributes and actions. These will differ somewhat between objects as the specific attributes and actions will depend upon the accessibility object's role and purpose, but the following outlines the basics.

Getting and Setting Attribute values:

Iteration over Attributes:

Iteration over Child Elements (AXChildren):

Actions (hs.axuielement:actionNames):

ParameterizedAttributes:

Submodules

API Overview

API Documentation

Constants

actions
Signature hs.axuielement.actions[]
Type Constant
Description A table of common accessibility object action names, provided for reference.
Notes
Source extensions/axuielement/internal.m
attributes
Signature hs.axuielement.attributes[]
Type Constant
Description A table of common accessibility object attribute names which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as keys in the match criteria argument.
Notes
Source extensions/axuielement/internal.m
orientations
Signature hs.axuielement.orientations[]
Type Constant
Description A table of orientation types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXOrientation" in the match criteria argument.
Notes
Source extensions/axuielement/internal.m
parameterizedAttributes
Signature hs.axuielement.parameterizedAttributes[]
Type Constant
Description A table of common accessibility object parameterized attribute names, provided for reference.
Notes
Source extensions/axuielement/internal.m
roles
Signature hs.axuielement.roles[]
Type Constant
Description A table of common accessibility object roles which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXRole" in the match criteria argument.
Notes
Source extensions/axuielement/internal.m
rulerMarkers
Signature hs.axuielement.rulerMarkers[]
Type Constant
Description A table of ruler marker types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXMarkerType" in the match criteria argument.
Notes
Source extensions/axuielement/internal.m
sortDirections
Signature hs.axuielement.sortDirections[]
Type Constant
Description A table of sort direction types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXSortDirection" in the match criteria argument.
Notes
Source extensions/axuielement/internal.m
subroles
Signature hs.axuielement.subroles[]
Type Constant
Description A table of common accessibility object subroles which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for "AXSubrole" in the match criteria argument.
Notes
Source extensions/axuielement/internal.m
units
Signature hs.axuielement.units[]
Type Constant
Description A table of measurement unit types which may be used with [hs.axuielement:elementSearch](#elementSearch) or [hs.axuielement:matchesCriteria](#matchesCriteria) as attribute values for attributes which specify measurement unit types (e.g. "AXUnits", "AXHorizontalUnits", and "AXVerticalUnits") in the match criteria argument.
Notes
Source extensions/axuielement/internal.m

Functions

searchCriteriaFunction
Signature hs.axuielement.searchCriteriaFunction(criteria) -> function
Type Function
Description Returns a function for use with [hs.axuielement:elementSearch](#elementSearch) that uses [hs.axuielement:matchesCriteria](#matchesCriteria) with the specified criteria.
Parameters
Returns
Source extensions/axuielement/init.lua

Constructors

applicationElement
Signature hs.axuielement.applicationElement(applicationObject) -> axuielementObject
Type Constructor
Description Returns the top-level accessibility object for the application specified by the `hs.application` object.
Parameters
  • 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.
Returns
  • an axuielementObject for the application specified
Notes
  • if 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.
Source extensions/axuielement/internal.m
applicationElementForPID
Signature hs.axuielement.applicationElementForPID(pid) -> axuielementObject
Type Constructor
Description Returns the top-level accessibility object for the application with the specified process ID.
Parameters
  • pid - the process ID of the application.
Returns
  • an axuielementObject for the application specified, or nil if it cannot be determined
Source extensions/axuielement/internal.m
systemElementAtPosition
Signature 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 test
  • y - the y coordinate of the screen location to test
  • pointTable - 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.
Returns
  • an axuielementObject for the object at the specified coordinates, or nil if no object could be identified.
Notes
Source extensions/axuielement/init.lua
systemWideElement
Signature hs.axuielement.systemWideElement() -> axuielementObject
Type Constructor
Description Returns an accessibility object that provides access to system attributes.
Parameters
  • None
Returns
  • the axuielementObject for the system attributes
Source extensions/axuielement/internal.m
windowElement
Signature hs.axuielement.windowElement(windowObject) -> axuielementObject
Type Constructor
Description Returns the accessibility object for the window specified by the `hs.window` object.
Parameters
  • 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.
Returns
  • an axuielementObject for the window specified
Notes
  • if 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.
Source extensions/axuielement/internal.m

Methods

actionDescription
Signature hs.axuielement:actionDescription(action) -> string | nil, errString
Type Method
Description Returns a localized description of the specified accessibility object's action.
Parameters
Returns
  • a string containing a description of the object's action, nil if no description is available, or nil and an error string if an accessibility error occurred
Notes
  • The action descriptions are provided by the target application; as such their accuracy and usefulness rely on the target application's developers.
Source extensions/axuielement/internal.m
actionNames
Signature hs.axuielement:actionNames() -> table | nil, errString
Type Method
Description Returns a list of all the actions the specified accessibility object can perform.
Parameters
  • None
Returns
  • an array of the names of all actions supported by the axuielementObject or nil and an error string if an accessibility error occurred
Notes
  • Common action names can be found in the hs.axuielement.actions table; however, this method will list only those names which are supported by this object, and is not limited to just those in the referenced table.
Source extensions/axuielement/internal.m
allAttributeValues
Signature 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.
Returns
  • a table with key-value pairs corresponding to the attributes of the accessibility object or nil and an error string if an accessibility error occurred
Notes
  • if 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.
  • To include attributes which exist but are currently unset, you need to specify includeErrors as true.
    • attributes for which no value is currently assigned will be given a table value with the following key-value pairs:
      • _code = -25212
      • error = "Requested value does not exist"
Source extensions/axuielement/internal.m
allDescendantElements
Signature hs.axuielement:allDescendantElements(callback, [withParents]) -> elementSearchObject
Type Method
Description Query the accessibility object for all child accessibility objects and their descendants
Parameters
  • 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.
Returns
Notes
  • This method is syntactic sugar for hs.axuielement:elementSearch(callback, { [includeParents = withParents] }). Please refer to hs.axuielement:elementSearch for details about the returned object and callback arguments.
Source extensions/axuielement/init.lua
asHSApplication
Signature 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
  • None
Returns
  • if the element refers to an application, return an hs.application object for the element ; otherwise return nil
Notes
  • An element is considered an application by this method if it has an AXRole of AXApplication and has a process identifier (pid).
Source extensions/axuielement/internal.m
asHSWindow
Signature hs.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
  • None
Returns
  • if the element refers to a window, return an hs.window object for the element ; otherwise return nil
Notes
  • An element is considered a window by this method if it has an AXRole of AXWindow.
Source extensions/axuielement/internal.m
attributeNames
Signature hs.axuielement:attributeNames() -> table | nil, errString
Type Method
Description Returns a list of all the attributes supported by the specified accessibility object.
Parameters
  • None
Returns
  • an array of the names of all attributes supported by the axuielementObject or nil and an error string if an accessibility error occurred
Notes
  • Common attribute names can be found in the hs.axuielement.attributes tables; however, this method will list only those names which are supported by this object, and is not limited to just those in the referenced table.
Source extensions/axuielement/internal.m
attributeValue
Signature hs.axuielement:attributeValue(attribute) -> value | nil, errString
Type Method
Description Returns the value of an accessibility object's attribute.
Parameters
Returns
  • the current value of the attribute, nil if the attribute has no value, or nil and an error string if an accessibility error occurred
Source extensions/axuielement/internal.m
attributeValueCount
Signature hs.axuielement:attributeValueCount(attribute) -> integer | nil, errString
Type Method
Description Returns the count of the array of an accessibility object's attribute value.
Parameters
Returns
  • the number of items in the value for the attribute, if it is an array, or nil and an error string if an accessibility error occurred
Source extensions/axuielement/internal.m
buildTree
Signature hs.axuielement:buildTree(callback, [depth], [withParents]) -> elementSearchObject
Type Method
Description Captures all of the available information for the accessibility object and its descendants and returns it in a table for inspection.
Parameters
  • 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.
Returns
Notes
  • The format of the 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.
Source extensions/axuielement/init.lua
copy
Signature hs.axuielement:copy() -> axuielementObject
Type Method
Description Return a duplicate userdata reference to the Accessibility object.
Parameters
  • None
Returns
  • a new userdata object representing a new reference to the Accessibility object.
Source extensions/axuielement/internal.m
elementAtPosition
Signature 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 tes
  • y - the y coordinate of the screen location to test
  • pointTable - 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.
Returns
  • an axuielementObject for the object at the specified coordinates, or nil and an error string if no object could be identified or an accessibility error occurred
Notes
Source extensions/axuielement/internal.m
elementSearch
Signature hs.axuielement:elementSearch(callback, [criteria], [namedModifiers]) -> elementSearchObject
Type Method
Description Search for and generate a table of the accessibility elements for the attributes and descendants of this object based on the specified criteria.
Parameters
  • 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.
Returns
  • an elementSearchObject which contains metamethods allowing you to check to see if the process has completed and cancel it early if desired. The methods include:
    • 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.
Notes
  • This method utilizes coroutines to keep Hammerspoon responsive, but may be slow to complete if 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.
Source extensions/axuielement/init.lua
isAttributeSettable
Signature hs.axuielement:isAttributeSettable(attribute) -> boolean | nil, errString
Type Method
Description Returns whether the specified accessibility object's attribute can be modified.
Parameters
Returns
  • a boolean value indicating whether or not the value of the parameter can be modified or nil and an error string if an accessibility error occurred
Source extensions/axuielement/internal.m
isValid
Signature hs.axuielement:isValid() -> boolean | nil, errString
Type Method
Description Returns whether the specified accessibility object is still valid.
Parameters
  • None
Returns
  • a boolean value indicating whether or not the accessibility object is still valid or nil and an error string if any other accessibility error occurred
Notes
  • an accessibilityObject can become invalid for a variety of reasons, including but not limited to the element referred to no longer being available (e.g. an element referring to a window or one of its descendants that has been closed) or the application terminating.
Source extensions/axuielement/internal.m
matchesCriteria
Signature hs.axuielement:matchesCriteria(criteria) -> boolean
Type Method
Description Returns true if the axuielementObject matches the specified criteria or false if it does not.
Parameters
  • criteria - the criteria to compare against the accessibility object
Returns
  • true if the axuielementObject matches the criteria, false if it does not.
Notes
  • the criteria argument must be one of the following:
    • a single string, specifying the value the element's AXRole attribute must equal for a positive match
Source extensions/axuielement/init.lua
parameterizedAttributeNames
Signature hs.axuielement:parameterizedAttributeNames() -> table | nil, errString
Type Method
Description Returns a list of all the parameterized attributes supported by the specified accessibility object.
Parameters
  • None
Returns
  • an array of the names of all parameterized attributes supported by the axuielementObject or nil and an error string if an accessibility error occurred
Source extensions/axuielement/internal.m
parameterizedAttributeValue
Signature hs.axuielement:parameterizedAttributeValue(attribute, parameter) -> value | nil, errString
Type Method
Description Returns the value of an accessibility object's parameterized attribute.
Parameters
Returns
  • the current value of the parameterized attribute, nil if the parameterized attribute has no value, or nil and an error string if an accessibility error occurred
Notes
  • The specific parameter required for a each parameterized attribute is different and is often application specific thus requiring some experimentation. Notes regarding identified parameter types and thoughts on some still being investigated will be provided in the Hammerspoon Wiki, hopefully shortly after this module becomes part of a Hammerspoon release.
Source extensions/axuielement/internal.m
path
Signature hs.axuielement:path() -> table
Type Method
Description Returns a table of axuielements tracing this object through its parent objects to the root for this element, most likely an application object or the system wide object.
Parameters
  • None
Returns
  • a table containing this object and 0 or more parent objects representing the path from the root object to this element.
Notes
  • this object will always exist as the last element in the table (e.g. at table[#table]) with its most immediate parent at #table - 1, etc. until the rootmost object for this element is reached at index position 1.
Source extensions/axuielement/init.lua
performAction
Signature hs.axuielement:performAction(action) -> axuielement | false | nil, errString
Type Method
Description Requests that the specified accessibility object perform the specified action.
Parameters
Returns
  • if the requested action was accepted by the target, returns the axuielementObject; if the requested action was rejected, returns false; otherwise returns nil and an error string if an accessibility error occurred
Notes
  • The return value only suggests success or failure, but is not a guarantee. The receiving application may have internal logic which prevents the action from occurring at this time for some reason, even though this method returns success (the axuielementObject). Contrawise, the requested action may trigger a requirement for a response from the user and thus appear to time out, causing this method to return false or nil.
Source extensions/axuielement/internal.m
pid
Signature hs.axuielement:pid() -> integer | nil, errString
Type Method
Description Returns the process ID associated with the specified accessibility object.
Parameters
  • None
Returns
  • the process ID for the application to which the accessibility object ultimately belongs or nil and an error string if an accessibility error occurred
Source extensions/axuielement/internal.m
setAttributeValue
Signature hs.axuielement:setAttributeValue(attribute, value) -> axuielementObject | nil, errString
Type Method
Description Sets the accessibility object's attribute to the specified value.
Parameters
Returns
  • the axuielementObject on success; nil and an error string if the attribute could not be set or an accessibility error occurred.
Source extensions/axuielement/internal.m
setTimeout
Signature hs.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.
Returns
  • the axuielementObject or nil and an error string if an accessibility error occurred
Notes
  • To change the global timeout affecting all queries on elements which do not have a specific timeout set, use this method on the systemwide element (see hs.axuielement.systemWideElement.
  • Changing the timeout value for an axuielement object only changes the value for that specific element -- other axuieleement objects that may refer to the identical accessibiity item are not affected.
Source extensions/axuielement/internal.m