Choose from a context menu
Opens an element's right-click menu through accessibility and chooses an item by its title, submenus included, without moving the pointer.
In locator's menu choose item
Details #
Half of what a Mac app can do lives only in a right-click menu: Mark as Read, Download, Copy Link, Open in New Tab, Reveal in Finder. This step asks the element for its menu, finds the menu that appears, and presses the item with the title you gave. It never moves the pointer, so the app does not have to be under it, and the menu is never left open.
item is one title ("Mark as Read") or a path through submenus (["Services", "Open in Terminal"]). Titles match like menu items: exact, then prefix, then substring, ignoring case and accents, and /regex/ works. A greyed-out item fails with "Mark as Read is disabled here" instead of being pressed. A missing item cancels the menu and the failure lists the items it saw, with the nearest one.
With no item, the step reads the menu instead: it returns items, each with title, path, enabled, hasSubmenu, and mark and shortcut when the menu shows them, then closes the menu. A macro can show the list in a prompt, and an agent can read it before it chooses.
The step reports pressed (the titles it walked), enabled, method (how the menu was opened) and menuIn (where it was found). The Activity note says, for example, "chose Services ▸ Open in Terminal (opened with AXShowMenu, menu under the app, 85 ms)".
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
locator | locator | Yes | The element to open the menu of. Required. | |
allowClick | yes / no | Allow a right click at the element's centre as the last way to open the menu. Off by default. | ||
app | text | The app to look in, by bundle id. Defaults to the locator's app, otherwise the front app. | ||
fuzzy | yes / no | When true, a locator match between 40% and 70% is accepted too, with a "fuzzy match" warning. | ||
into | text | A variable that receives the chosen path (Services ▸ Open in Terminal), or, when reading, the list of item paths. | ||
item | any value | The title to choose, or a list of titles down through submenus. Leave it out to read the menu's items instead. |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
- In the row's menu choose “Mark as Read”
- In Downloads row's menu choose “Services ▸ New Terminal at Folder”
Gotchas #
The element has to exist. Like click, the step waits for the locator, then asks it for a menu. It does not select the item first; if the menu depends on a selection, click the row before.
Items that appear later. Some menus fill in after they open (Share, Open With). The step reads the menu as it is when it first has items; if yours is slow, add a short wait step before it or choose by the path of the submenu, which waits for the submenu itself.
Reading is not free. The list form opens the menu for a moment on screen.
How the menu is opened #
AXShowMenu, the accessibility action for "show the contextual menu", when the element offers it.
⌃⏎, the system's keyboard key for a context menu, after focusing the element. It is sent only while the app is in front, so the key can never reach another app.
A right click at the element's centre, only when
allowClickis true. This is the one way that moves the pointer, which is why it is opt-in and visible in the macro.
The menu is looked for for up to a second after each try: first under the element, then under its window, then anywhere in the app (AppKit hangs context menus on the app). Any failure after the menu opened cancels it; so does stopping the run while it is open.
See also #
Click with button: right for apps that draw their own menus, Choose menu item and Choose menu item by name for the menu bar.