Getting Accessibility Elements

The hs.axuielement module provides a variety of tools for exploring applications. This document focuses on describing some of the methods and functions for getting accessibility objects so that you can work with them. For a discussion of how to query and manipulate these objects, you should also refer to Element Attributes and Actions.

Using the System Wide Element

The system wide element is a special element that can be used to identify the currently active application and focused element. It can also be used when trying to determine the element at a specific coordinate on the screen.

You can access the system wide element as follows:

swe = hs.axuielement.systemWideElement()

The system wide element has two attributes that provide information about the currently active application and focused element:

• "AXFocusedApplication" - accessing this attribute as swe.AXFocusedApplication will return the axuielement object for the currently focused (frontmost) application.
• "AXFocusedUIElement" - accessing this attribute as swe.AXFocusedUIElement will return the axuielement object for the element with the current focus within the frontmost application. Usually this will be the window that is currently considered key or active.

Another use of the system wide element is to determine what element is at a specific set of screen coordinates:

element = hs.axuielement.systemElementAtPosition(hs.mouse.getAbsolutePosition())

This will return the element directly underneath the mouse cursor, no matter what application it belongs to. It should be noted that the Finder application provides the screen's desktop image, so if there is no element from any application at the specified coordinates, it will be an element from the Finder that is returned.

More on identifying elements by position

The hs.axuielement.systemElementAtPosition(...) function is actually a shutcut for hs.axuielement.systemWideElement():elementAtPosition(...).

You can also use the hs.axuielement:elementAtPosition method on an application element -- this will limit the possible element returned to that specific application, even if there are other applications with windows or other elements covering it. If there is no application element at the specified coordinates, than the application element itself will be returned.

The example given above used the hs.mouse module to get the current position of the moise pointer, but you can specify and point in screen coordinates by using a table with x and y keys specifying a lotacion in screen coordinates, e.g. { x = 100, y = 100 }.

Getting Application and Window elements directly

Hammerspoon already has many ways of getting running application and window objects for use by the hs.application and hs.window modules. For convienence, the following functions and methods allow converting between these modules and hs.axuielement:

• hs.axuielement.applicationElement(app) - if app is an hs.application object, this function will return an accessibilityObject representing the same application. For convienence, if app is a string or number, it is passed to hs.application.find and the first result is used to return the application accessibilityObject.
• hs.axuielement.windowElement(win) - if win is an hs.window object, this function will return an accssibilityObject representing the same window. For convienence, if win is a string or number, it is passed to hs.window.find and the first result is used to return the window accessibilityObject.
• hs.axuielement:asHSApplication() - if the accessibilityObject has a role of AXApplication, this method will return an hs.application object for the same application; otherwise it returns nil.
• hs.axuielement:asHSWindow() - if the accessibilityObject has a role of AXWindow, this method will return an hs.window object for the same window; otherwise it returns nil.

Searching for a specific element

hs.axuielement:elementSearch is a powerful method for searching for specific elements within an application or subtree of an application. A proper discussion of this method is beyond the scope of this document, but will be described in detail in Searching for Specific Elements. It should be considered a work in progress at the moment and may be of limited value right now, but this will hopefully change soon.

For further information

• hs.axuielement module documentation
• Some examples, not as well documented as I'd like yet, but useful nontheless.
• Searching for Specific Elements -- right now this is just a buch of code snippits with no documentation; it should be considered incomplete and possibly misleading at present
• Element Attributes and Actions