Scoot

Meet Scoot, your friendly cursor teleportation and actuation tool.

Scoot helps you efficiently move your mouse cursor, using keyboard shortcuts!

For updates, follow @mjrusso on Twitter.

<img src="https://github.com/mjrusso/scoot/actions/workflows/main_test.yml/badge.svg" alt="build status"></a>

<p align="center"> <img src="./Assets/card.png" alt="Scoot, MacOS Cursor Actuator" /> </p>

---

<img align="right" width="128" alt="Scoot App Icon" src="./Scoot/Assets.xcassets/AppIcon.appiconset/512.png" />

Scoot is a tiny utility app that provides fast, keyboard-driven control over the mouse pointer. Scoot lets you move your mouse—and click and drag, too—all from the comfort of your keyboard.

Scoot supports two primary navigation modes: element-based, and grid-based.

• Element-based navigation: MacOS accessibility APIs are used to find user interface elements, such as buttons and links, on the user's screen. (In this mode, Scoot will look for elements in the focused window of the frontmost app.) Here, for example, Scoot has identified the only link on the page ("More information..."), and assigned it the key sequence "aa":

<p align="center"> <img src="./Assets/Examples/element-nav.png" alt="Scoot using the element-based navigation mode" /> </p>

• Grid-based navigation: all connected screens are subdivided into a grid of equally-sized cells.

<p align="center"> <img src="./Assets/Examples/grid-nav.png" alt="Scoot using the grid-based navigation mode" /> </p>

Each location is identified by a unique character sequence, making each element (or cell) uniquely addressable with the keyboard — simply type the associated key sequence to teleport your mouse cursor to that location.

Scoot also supports moving the mouse cursor using text editing keyboard shortcuts that you're likely already familiar with (specifically, those for moving the insertion point). Scoot supports standard MacOS text editing shortcuts, as well as Emacs and vi keybindings. For a full breakdown, see the usage documentation.

There's also a supplementary usage mode:

• Freestyle: a freeform usage mode that offers no special navigation assistance. It's like using the grid-based navigation mode, but without bringing up the grid.

Freestyle mode is particularly handy for those cases where you want to quickly nudge the cursor using the (re-purposed) text editing keyboard shortcuts, and would prefer to not have the grid or element-based views on screen.

About

• This project started as an experiment: an attempt to craft a keyboard-driven mouse movement utility that's efficient, and (more importantly) that users will actually want to use. It has met that bar, at least for the primary author. (Scoot may not be for you, and that's totally fine!)

• Scoot is not intended to replace the mouse or trackpad entirely. It's here to augment them.

• Scoot runs on MacOS 11 (Big Sur), and 12 (Monterey).

• Scoot is an AppKit app, written in Swift. (There's still some Carbon in here, too! [Yes][carbon-events], [really][carbon-accessibility].)

• Scoot complements mouse-related accessibility tools that ship as part of MacOS, such as [Mouse Keys][mouse-keys] and other [accessibility shortcuts][mac-accessibility-shortcuts], in addition to mouse emulation provided via keyboard firmware ([QMK][qmk-mouse-keys], for example).

Usage

To activate Scoot in the element-based navigation mode, use the ⇧⌘J global keyboard shortcut. Alternatively, to activate Scoot in the grid-based navigation mode, use the ⇧⌘K global keyboard shortcut. And for freestyle mode, use the ⇧⌘L global keyboard shortcut. (These shortcuts can be customized.)

As long as Scoot is running, any of these hotkeys will bring the app to the foreground, and activate the requested mode.

When Scoot is in the foreground:

• You can jump directly to a cell (a UI element, or a location in the grid, depending on the active navigation mode). Each cell is marked with a label (e.g. “aaa”, “aas”, “aad”); type the characters, one letter at a time, and, as soon as a complete sequence is entered, the mouse cursor will move directly to the center of the corresponding cell. (This approach, including the use of a char-based decision tree, is heavily inspired by [avy][avy].)

  • If you make a mistake while entering a label, hit the escape key (⎋) to cancel and start over. (Alternatively, you can type ⌘. or C-G.)
  • This feature is not available in freestyle mode, which does not present any special UI, or otherwise offer any navigation assistance via a char-based decision tree.

• You can also move the cursor via the standard Mac keyboard shortcuts for [moving the insertion point][mac-keyboard-shortcuts-text]. (This means that keyboard shortcuts intended for navigating around in a document have been re-purposed to control movement on a 2-dimensional grid. Some liberties have been taken with this mapping; hopefully you find these keybindings intuitive.) This feature works in all modes (element-based, grid-based, and freestyle).

  • The equivalent standard Emacs keybindings should also work out-of-the-box, if you have them configured system-wide (for example, via [Karabiner-Elements][karabiner-elements] [[complex modification][karabiner-elements-emacs-mod]], or by augmenting the [system defaults][emacs-keyboard-shortcuts-osx] [[DefaultKeyBinding.dict][defaultkeybinding.dict], [Cocoa Text System][cocoa-text-system], [Text System Defaults and Key Bindings][apple-dev-text-system]]).
  • The equivalent vi bindings are also (optionally) available; see keybindings for details.

• You can click with the left mouse button (at the current cursor location) by hitting the Return (↵) key.

• You can hold the left mouse button down by pressing =. (To release the button, press ↵.)

  • To perform a drag-and-drop operation: situate the cursor above the object you want to drag and press =, then move the mouse cursor to the desired drag destination (using one or more of the mechanisms that Scoot makes available), and then press ↵ to perform the drop.

• You can double-click with the left mouse button (at the current cursor location) by hitting the Shift and Return keys together (⇧↵).

• You can scroll, by pressing the Shift key in conjunction with the arrow key (↑, ↓, ←, →) pointing in the desired scroll direction.

After clicking, any overlaid UI elements (such as the element view, or the grid) will automatically hide. You can also hide these UI elements (and send Scoot to the background) at any time by pressing ⌘H.

Scoot includes a menu bar icon (an illustration of a Vespa-inspired scooter).

<img align="right" width="256" alt="Scoot Menu Bar Icon" src="./Assets/menu-bar-icon.png" />

• When Scoot is not active (i.e., running in the background), the icon will render in an outlined mode.
• When Scoot is in the foreground, the icon will render with a fill (see screenshot), to make it clearer that Scoot is currently active. (This shouldn't generally be a concern, but it is especially handy when you're in freestyle mode.)
• Additional options are exposed when clicking on the menu bar icon, including a help menu item — which currently opens this README in the user's default browser.

Scoot is fully compatible with Spaces (and can be used in conjunction with apps that are running in native fullscreen mode).

Scoot also works on systems with multiple connected displays.

<p align="center"> <img src="./Assets/Examples/grid-multiple-displays.jpg" alt="Using Scoot with multiple connected displays" /> </p>

If you use multiple displays, and experience an issue with Scoot's windows drawing in an incorrect location when the app launches (e.g. all Scoot windows appearing on the same display), please post your findings in this issue, and note the value of your “Displays have separate Spaces” checkbox in Mission Control. If you do happen to find yourself in this state, you should be able to fix the window arrangement by clicking Scoot's menu bar icon, then “Debug”, and finally “Rebuild Jump Windows”.

To customize Scoot's settings, click Scoot's menu bar icon, then “Preferences…”, or type ⌘, while Scoot is in the foreground. In addition to modifying keybindings, it is also possible to modify Scoot's appearance (including font sizes, colours, opacity, etc.).

Keybindings

Not sure what these symbols mean? See the [symbol reference][what-are-those-mac-symbols], and [Emacs key notation][emacs-key-notation].

Global Keybindings

Global keybindings are always active, as long as Scoot is currently running.

| Default Shortcut | Description | |------------------|----------------------------------------------------------| | ⇧⌘J | Use element-based navigation (bring Scoot to foreground) | | ⇧⌘K | Use grid-based navigation (bring Scoot to foreground) | | ⇧⌘L | Use freestyle mode (bring Scoot to foreground) |

All global keybindings are fully customizable. To modify the keybindings, click Scoot's menu bar icon, then “Preferences…”, and select the “Keybindings” tab.

Local Keybindings

Local keybindings are only active when Scoot is active (i.e., when Scoot is in the foreground).

Note that vi keybindings are not enabled by default, and must be explicitly toggled on (click Scoot's menu bar icon, then “Preferences…”, select the “Keybindings” tab, and then change the keybinding mode). Emacs keybindings (and most system keybindings) are disabled when vi keybindings are active.

General

| Shortcut | Alternate | Description | |-----------|-----------|-------------------------------------------------------------------------------------------------------------------| |