An auto tiler for macOS
parcel docs mouse-controls.md
4.6 kB · 71 lines
Markdown
at main

Mouse controls #

Setup does not require a mouse lesson or shortcut practice. These controls work with either automatic or manual arrangement. Change gestures in Settings → Mouse; use Retile in the menu to arrange windows when Automatic tiling is off.

Enable Shortcut Hints to reveal Primary, Focus, Move to, and Float or Tile when the pointer rests on the grip in the margin above a tiled window. The controls open at the pointer and stay until it has been outside them for two seconds. Floating windows use their title strip. Hold Option for Always float. Action icons show the operation; configured shortcuts appear below their labels. Unbound actions omit the shortcut. Open Window Controls… from the menu to use the same controls with a keyboard.

Float moves a window out of the arrangement, centers it at a readable size, and raises it over the tiled windows. Its grip stays available for Tile; Primary and Focus are unavailable while it floats. Tile fits it back into the current arrangement, allowing two columns to become three again. App minimum sizes still apply. Modifier-based free movement keeps the frame you choose.

Window controls are on demand by default. Use the configured Window Controls shortcut or Window Controls… in Parcel’s menu. Stacked Windows… opens Tab View; stack-next and stack-previous switch members without changing the arrangement. With Shortcut Hints enabled, a stacked tile’s grip has a wide selected tab and small dots for its other windows. Click a segment to switch windows, or drag it to another tile to move that window into its stack. Escape cancels the move. The popover adds app icons and names for stacks; its arrows select the previous or next member. A single-window tile has no tab row. Optional persistent stack controls use existing gaps and never reduce window space. Choose their visibility in Settings → Appearance with appearance.stack-controls.

Dragging a tiled window by its title bar shows numbered destinations. Hover to preview the resulting arrangement, then release to apply it. Dropping onto an occupied tile swaps the two tile groups, keeping their tabs and selected windows together. Column widths adapt to the groups’ minimum sizes. Drag an individual tab segment instead when you want to move only that window into another stack. A Full height destination is offered when the window can become a full-height primary tile. Escape cancels the arrangement change. These targets appear during a window drag; ordinary content drags remain with the app.

Native resizing changes layout proportions while preserving the outer bounds. Shared-edge drags adjust the neighboring tiles together. A modifier drop near a shared divider also adjusts its ratio. Double-click in the actual gap resets sizes; double-click inside window content stays with the app. Minimum sizes still apply.

Settings → Mouse configures the modifiers for moving anywhere with a left drag and resizing with a right drag. Committing either makes a tiled window floating; Escape restores its tile. These modifier-button combinations are reserved for Parcel, including clicks without movement; Parcel does not replay them into the app. Choose different modifiers if an app uses the same combination. Each completed gesture is one undo action; cancelling an edge drag leaves no undo entry. Mouse config keys use dashes; underscore spellings warn and are ignored.

Direct moves may span displays or sit partly off-screen, while at least 40 points of the title strip stay reachable on a visible display. The final app-accepted frame is committed only after Accessibility readback. Floating windows preview snaps at exposed display edges, not shared boundaries; Escape skips the snap. Ordinary content drags keep Escape in the app. Motion off and Reduce Motion remove animated decoration.

mouse.focus-follows-mouse is off by default, with no hover monitors installed. When enabled, Parcel waits mouse.focus-delay seconds for the pointer to settle and pauses for mouse.typing-cooldown after typing, modifier changes, or scrolling. Open menus and popovers, drags, and suspended Spaces block hover focus. The pointer must still rest on the same visible window when the dwell finishes. prcl run hover-focus-toggle persists the switch.

If macOS times out the mouse input connection, Parcel stops mouse controls and shows a notice instead of repeatedly reconnecting. Restart Parcel once it is responsive. Clicks that cannot be safely attributed stay with the app.