Initial documentation, first draft

UI Actions
1

This is a work in progress. Let me know if you’re missing something. Once I’m happy with it, it’ll be split up and moved into the Knowledge Base.

Symbol explanation:

  • Names of actions are prefixed with “▲”
  • Names of object are prefixed with “●”

Overall concepts

Return values (“objects”)

Many UIA Shortcuts actions return objects which aren’t simple YES/NO, string or number values – they contain certain properties about themselves as key-value pairs. Each of those object represents a “thing” in macOS:

  • an app
  • a window
  • a menu item

For example, ▲ Get App will return an ● App object that contains the list of the app’s windows, or whether the app is currently frontmost.

CleanShot 2024-06-04 at 14.18.56@2x
CleanShot 2024-06-04 at 14.18.56@2x1920×1652 140 KB

Also, many window-related actions return ● Window objects that contain infos about the underlying window, such as min/max state, the type of window it is (floating or standard), its size etc.

CleanShot 2024-06-04 at 14.19.16@2x
CleanShot 2024-06-04 at 14.19.16@2x1920×1644 141 KB

More on these objects in a moment.

Action types

Each of UIA’s actions belongs to one of four categories:

  • Lookups (▲ Get Windows, ▲ Get App, etc.) will only return one/many objects, but they’ll never do anything with them.
  • Filters accept lists of objects of a type, and return a subset of the input.
  • Tests accept one or more objects, check them for a predicate, and return a YES/NO (boolean). For example: ▲ Is this window …? (… minimized, etc.)
  • Performers only do something. They’ll accept one or more objects where necessary (e.g., ▲ Minimize Window needs a ● Window to work with), but they also might not (e.g., when simulating key presses).

In some rare cases an action might do more than one thing, for convenience’s sake. For example, ▲ Select Menu Item allows you to specify the menu item’s title, which means it combines lookup and performer – it just makes sense there.

Usually, I’ll try to avoid that, though. :wink:

Objects

All result objects are static snapshots. This is important. For example, when an action returns a window, its properties will not change even when the original window is manipulated.

● App

This object represents a currently running application. Its properties are:

  • Name: Its localized name (e.g., “Preview” (en) or “Vorschau” (de))
  • Main Window: ● Window
  • Windows: a list of ● Window
  • Focused Window: ● Window
  • Is Frontmost?: YES/NO
  • Is Hidden?: YES/NO

The window-related properties might be empty if the app doesn’t have any open windows.

● Window

This object represents an app’s window. Its properties are:

  • App: ● App, i.e. its parent
  • Window Type: “standard window”, “floating window”
  • Is Main Window?: YES/NO
  • Is Focused Window?: YES/NO
  • Is Modal Window?: YES/NO
  • Is Minimized?: YES/NO
  • Is Maximized?: YES/NO
  • Is FullScreen?: YES/NO
  • Width: Number
  • Height: Number
  • Position X: Number
  • Position Y: Number

● Menu Item

This object represents a (sub)menu or menu item. Its properties are:

  • App: ● App, i.e. its parent
  • Menu Path: The path of the menu item, separated by greater-than characters, e.g. “Edit > Control Flow > Repeat”
  • Menu Path Segments: a list of text elements, e.g. “Edit”, “Control Flow”, “Repeat”

Actions

All actions are documented. In the Shortcuts editor, either click on the Ⓘ icon that is shown on hover for each action in the right sidebar, or right-click any action already placed in your workflow and select “Show Info”.

TO BE CONTINUED