diff --git a/docs/recipes.md b/docs/recipes.md index 4e8d70cb..6f6be52d 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -165,6 +165,23 @@ A shell `cp` is simpler. Use this when the copy must go through Finder. - Control Center closes when another app takes focus, which makes the snapshot stale. Reopen it and inspect again. - Some modules, such as Display on a Mac with an external monitor, open a detail view first: click the module, then inspect again. +## Zoom or rotate instead of pinching + +There is no pinch or rotate gesture. Use the app's own command: it acts on an exact target, and you can read the result back. + +1. `desktop_menus` with the app target, and look for zoom and rotate items in **View**, and rotate items in **Tools** or **Image**. Common items are **Zoom In**, **Zoom Out**, **Actual Size** and **Zoom to Fit** in Preview, Safari, Maps and Photos, and **Rotate Left** and **Rotate Right** in Preview and Photos *(unverified: titles and menus vary by app and macOS version)*. Each item shows its shortcut. +2. `desktop_menu` with the app target and that item's exact `path`. Expect `completed`. Repeat it to zoom further, observing between steps. +3. If the app has no menu item, use the shortcut on the window: inspect, then `desktop_key` with `=` and `command` to zoom in, `-` and `command` to zoom out, and `0` and `command` for actual size, against that snapshot. In Preview, `l` with `command` rotates left and `r` with `command` rotates right *(unverified)*. Pass `repeat` to press a key several times against one snapshot. + +**Verify:** inspect the window. The zoom level often shows in a toolbar control, in the window title or in a status bar, and a rotated image changes its bounds. A menu item that became disabled, such as **Zoom In** at the largest size, means there is nothing further to do. + +**Goes wrong:** + +- Some apps use Command-Shift-= or Command-+ for Zoom In. Read the shortcut from `desktop_menus` rather than guessing it. +- Command-scroll and Control-scroll zoom only in some apps and only with the feature turned on, so they aren't a general substitute. +- Maps and other canvas views may not report the zoom level anywhere. Compare screenshots with `desktop_inspect` in pixels mode instead. +- Safari's View > Zoom In zooms the page. Pinch zoom in Safari magnifies the view instead, and no tool reproduces that. + ## Fill a web form end to end 1. `desktop_open` with `item: {url: "https://example.com/form"}` and optionally `application: {bundle_id: "com.apple.Safari"}`. diff --git a/docs/tools.md b/docs/tools.md index 332da0ae..3c9e5254 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -155,6 +155,7 @@ An action refused because its window was minimized after inspection reports `WIN - **Confirmed insertion outside text fields.** Where `desktop_insert` can't observe a text control with a readable selection, such as terminals, canvases and custom views, it types the text instead, and the result is `unknown`, because nothing can read back what the receiver did with it. Typed insertion can't contain newlines or tabs. - **Confirmed drops between windows.** A drag into another window or app, or any drag with modifier keys, is always reported as `unknown`, because nothing can confirm the drop. A path can't cross into another window: a drag between windows is one straight line. - **Moving a window to another Space.** Since macOS 14.5 only the Dock can move windows between Spaces, so there is no tool for it. To do it by hand, open Mission Control with `desktop_system_key` (`control`, `up`), inspect it, and drag the window onto the other Space with a foreground `desktop_drag`. The result is `unknown`; check with `desktop_spaces`. +- **Pinch and rotate gestures.** Magnify and rotate trackpad gestures can be posted only through undocumented event fields. Even then they reach some apps but not others, such as Chrome. Use the app's zoom and rotate menu items or their shortcuts instead; see [Zoom or rotate instead of pinching](recipes.md#zoom-or-rotate-instead-of-pinching). - **Automatic retries.** By design, nothing is retried. After a `refused` or `unknown` result, observe again before deciding whether to act. - **Remote Macs.** The tools act on the Mac running the host app, on macOS 15 or later.