# 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:

• object.attribute is a shortcut for object:attributeValue(attribute)
• object.attribute = value is a shortcut for object:setAttributeValue(attribute, value)
  • If detecting accessibility errors that may occur is necessary, you must use the formal methods hs.axuielement:attributeValue and hs.axuielement:setAttributeValue
  • Note that setting an attribute value is not guaranteed to work with either method:
    • internal logic within the receiving application may decline to accept the newly assigned value
    • an accessibility error may occur
    • the element may not be settable (surprisingly this does not return an error, even when hs.axuielement:isAttributeSettable returns false for the attribute specified)
  • If you require confirmation of the change, you will need to check the value of the attribute with one of the methods described above after setting it.

Iteration over Attributes:

• 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)
  • If detecting accessibility errors that may occur is necessary, you must use one of the formal approaches hs.axuielement:allAttributeValues or hs.axuielement:attributeNames and hs.axuielement:attributeValue
  • By default, hs.axuielement:allAttributeValues will not include key-value pairs for which the attribute (key) exists for the element but has no assigned value (nil) at the present time. This is because the value of nil prevents the key from being retained in the table returned. See hs.axuielement:allAttributeValues for details and a workaround.

Iteration over Child Elements (AXChildren):

• for i,v in ipairs(object) do ... end is a shortcut for for i,v in pairs(object:attributeValue("AXChildren") or {}) do ... end
  • Note that 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]
  • If detecting accessibility errors that may occur is necessary, you must use the formal method hs.axuielement:attributeValue to get the "AXChildren" attribute.

Actions (hs.axuielement:actionNames):

• object:do<action>() is a shortcut for object:performAction(action)
  • See hs.axuielement:performAction for a description of the return values and hs.axuielement:actionNames to get a list of actions that the element supports.

ParameterizedAttributes:

• object:<attribute>WithParameter(value) is a shortcut for `object:parameterizedAttributeValue(attribute, value)

  • See hs.axuielement:parameterizedAttributeValue for a description of the return values and hs.axuielement:parameterizedAttributeNames to get a list of parameterized values that the element supports

  • The specific value 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.

---

# Submodules

• hs.axuielement.axtextmarker
• hs.axuielement.observer

---

# API Overview

Constants - Useful values which cannot be changed

• actions
• attributes
• orientations
• parameterizedAttributes
• roles
• rulerMarkers
• sortDirections
• subroles
• units

Functions - API calls offered directly by the extension

• searchCriteriaFunction

Constructors - API calls which return an object, typically one that offers API methods

• applicationElement
• applicationElementForPID
• systemElementAtPosition
• systemWideElement
• windowElement

Methods - API calls which can only be made on an object returned by a constructor

• actionDescription
• actionNames
• allAttributeValues
• allDescendantElements
• asHSApplication
• asHSWindow
• attributeNames
• attributeValue
• attributeValueCount
• buildTree
• childrenWithRole
• copy
• elementAtPosition
• elementSearch
• isAttributeSettable
• isValid
• matchesCriteria
• parameterizedAttributeNames
• parameterizedAttributeValue
• path
• performAction
• pid
• setAttributeValue
• setTimeout

---

# API Documentation

# Constants

# actions

---

# attributes

---

# orientations

---

# parameterizedAttributes

---

# roles

---

# rulerMarkers

---

# sortDirections

---

# subroles

---

# units

---

# Functions

# searchCriteriaFunction

---

# Constructors

# applicationElement

---

# applicationElementForPID

---

# systemElementAtPosition

---

# systemWideElement

---

# windowElement

---

# Methods

# actionDescription

---

# actionNames

---

# allAttributeValues

---

# allDescendantElements

---

# asHSApplication

---

# asHSWindow

---

# attributeNames

---

# attributeValue

---

# attributeValueCount

---

# buildTree

---

# childrenWithRole

---

# copy

---

# elementAtPosition

---

# 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. The following are also recognized, but may impact the speed of the search, the responsiveness of Hammerspoon, or the format of the results in ways that limit further filtering and are not recommended except when you know that you require them:asTree - an optional boolean, default false, and ignored if criteria is specified and non-empty, objectOnly is true, or count is specified. This modifier specifies whether the search results should return as an array table of tables containing each element's details (false) or as a tree where in which the root node details are the key-value pairs of the returned table and descendant elements are likewise described in subtables attached to the attribute name they belong to (true). This format is primarily for debugging and exploratory purposes and may not be arranged for easy programatic evaluation.includeParents - a boolean, default false, specifying whether or not parent attributes (AXParent and AXTopLevelUIElement) should be examined during the search. Note that in most cases, setting this value to true will end up traversing the entire Accessibility structure for the target application and may significantly slow down the search.noCallback - an optional boolean, default false, and ignored if callback is not also nil, allowing you to specify nil as the callback when set to true. This feature requires setting this named argument to true and specifying the callback field as nil because starting a query from an element with a lot of descendants WILL block Hammerspoon and slow down the responsiveness of your computer (I've seen blocking for over 5 minutes in extreme cases) and should be used only when you know you are starting from close to the end of the element hierarchy.objectOnly - an optional boolean, default true, specifying whether each result in the final table will be the accessibility element discovered (true) or a table containing details about the element include the attribute names, actions, etc. for the element (false). This latter format is primarily for debugging and exploratory purposes and may not be arranged for easy programatic evaluation.

| | 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 (described 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.
• If asTree is false or not specified, the following additional methods will be available:
• elementSearchObject:filter(criteria, [callback]) -> filterObject
• returns a new table containing elements in the search results that match the specified criteria.
• criteria - a required 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.
• callback - an optional callback which should expect two arguments and return none. If a callback is specified, the callback will receive two arguments, a msg indicating how the callback ended (the message format matches the style defined for this method) and the filterObject which contains the matching elements.
• The filterObject returned by this method and passed to the callback, if defined, will support the following methods as defined here: cancel, filter, isRunning, matched, runTime, and visited.
• elementSearchObject:next() - if the search was cancelled or reached the count of matches specified, this method will continue the search where it left off. The elementSearchObject returned when the callback is next invoked will have up to count items added to the existing results (calls to next are cumulative for the total results captured in the elementSearchObject). The third argument to the callback will be the number of items added to the search results, not the number of items in the search results.

| | 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.
• The search performed is a breadth-first search, so in general earlier elements in the results table will be "closer" in the Accessibility hierarchy to the starting point than later elements.
• The elementSearchObject returned by this method and the results passed in as the second argument to the callback function are the same object -- you can use either one in your code depending upon which makes the most sense. Results that match the criteria function are added to the elementSearchObject as they are found, so if you examine the object/table returned by this method and determine that you have located the element or elements you require before the callback has been invoked, you can safely invoke the cancel method to end the search early.
• The exception to this is when asTree is true and objectsOnly is false and the search criteria is nil -- see hs.axuielement:buildTree. In this case, the results passed to the callback will be equal to elementSearchObject[1].
• If objectsOnly is specified as false, it may take some time after cancel is invoked for the mapping of element attribute tables to the descendant elements in the results set -- this is a by product of the need to iterate through the results to match up all of the instances of each element to it's attribute table.
• hs.axuielement:allDescendantElements is syntactic sugar for hs.axuielement:elementSearch(callback, { [includeParents = withParents] })
• hs.axuielement:buildTree is syntactic sugar for hs.axuielement:elementSearch(callback, { objectOnly = false, asTree = true, [depth = depth], [includeParents = withParents] })

| | Examples | None | | Source | extensions/axuielement/axuielement.lua line 766 |

---

# isAttributeSettable

---

# isValid

---

# matchesCriteria

---

# parameterizedAttributeNames

---

# parameterizedAttributeValue

---

# path

---

# performAction

---

# pid

---

# setAttributeValue

---

# setTimeout

---

---