Using Mouseless

Note: these docs currently show the default keybindings. If a command is unassigned by default, the command name is used instead.

To view/edit the keybindings and other options, press Tab (edit config command) while the overlay is showing, OR choose Edit config... from the Mouseless menu in the status bar (Mac) / system tray (Windows) / window header bar (Linux).

Clicking, moving, and dragging

With free mode

Free mode allows for relative movement, with no overlay needed to move, click, or drag.

Activating / deactivating

To activate free mode, use the enter free mode command or toggle free mode command (OptionLeft tap on Mac, ControlLeft tap on Windows and Linux).

To exit free mode, use the exit free mode or toggle free mode command.

Auto-off

By default, free mode turns off automatically after 10 seconds without usage (adjustable via the Free mode auto off option; set to 0 to disable).

Actions in free mode

While free mode is on:

• to move, use I, K, J, and L
• to click or click+drag, use Space (left mouse button), R (right), E (middle), Q (back), and W (forward) as if they were mouse buttons
• to increase movement (or wheel) speed, use S, D, and F – the more of them you hold, the greater the increase
• to decrease movement (or wheel) speed, hold A

With the overlay

Showing/hiding the overlay

• To show the overlay, tap the CommandLeft (ShiftLeft on Windows and Linux) key (show overlay command)
  • Note: this is a tap command by default, so you must press and release the key relatively quickly for it to register (< 0.2 seconds by default, see Tap vs keydown for more info)
• To hide the overlay press the Escape key (hide overlay command)

Actions in overlay mode

• To click:

  • while the overlay is showing, type the two characters of any given cell to choose that cell
  • then press Space to click at the center of the cell, where the virtual cursor is (execute mouse action command)
    • OR press any character you see in a sub-cell to click at that sub-cell
  • you can press Space any time the overlay is up to click where the virtual cursor is (or where the system cursor is if no cell has been selected and Initial action location is set to system_cursor)

• To right click:

  • hold the Shift key (CommandRight on Mac) key while pressing the final key of a click action (hold for right button command)
  • use the cycle mouse button command to choose right, then execute a mouse action

• To use other mouse buttons, use the appropriate hold for command, or the cycle mouse button command, in the same way as described above for right clicking

• To double-click or triple-click, either:

  • press the final key of a click action multiple times within the multi-click threshold
  • use the cycle click count command

• To click-and-drag / drag-and-drop, use the hold for drag command, i.e.:

  • to begin the drag: hold the AltLeft key (CommandLeft on Mac) key while pressing the execute mouse action hotkey or a subgrid key
    • the overlay will remain up for you to choose the point you want to drag to or drop at
    • to drag to a point (without releasing the drag), hold the AltLeft key (CommandLeft on Mac) on subsequent execute mouse action / subgrid key presses
    • to cancel a drag (release at the system cursor), press Escape (release hold/drag command)
  • to release/drop: enter in a click-coordinate as normal, without holding the hold for drag hotkey

• Click-and-drag alternative: you can also use the cycle mouse action command to set the action to be performed. During a drag, it cycles between drag and drop.

• To move the mouse cursor:

  • tap AltLeft (OptionLeft on Mac) while the overlay is up (execute mouse move command)
  • hold the key assigned to the hold for move command during the final keypress of a a mouse action
  • use the cycle_mouse_action command to set the action to move

• To repeat the last action executed, use the repeat last mouse action command

Extra precision: Cursor nudges

If you need to click or move to small targets in between subgrid points, you can use ‘nudges’ as follows.

1. Ensure the hold subgrid key for nudge setting is ON in each grid config in the Grid Options section of the config editor.
2. Ensure the Subgrid nudge commands are assigned keys in the Keymap section. The default values give each command both a left-hand keybinding and a right-hand keybinding (assuming a QWERTY layout), so that nudges can be executed regardless of which subgrid key is held.
3. To execute a nudge:

• Activate the overlay, and select a cell to bring up the subgrid.
• Instead of tapping a subgrid key to immediately execute a click, hold the subgrid key nearest to your target.
• While this key is held, use the subgrid nudge hotkeys to move the cursor.
• When the cursor is in the desired location, simply release the subgrid key you’ve been holding to execute the click.

4. The nudge size / precision can be adjusted with the nudges per cell setting in the Grid Options section.

Global mouse buttons

These commands execute mouse button presses without the overlay, typically with a mouse or other pointing device still controlling cursor movement.

Use cases include:

• clicking while maintaining precise cursor position/movement
• preventing/alleviating repetitive strain injury
• user preference over other clicking mechanisms

To use these commands, in the Keybindings -> Global mouse buttons section of the config editor, assign a key or key combo that won’t interfere with your regular keyboard usage. All five mouse buttons (left, right, middle, back, and forward) can be assigned to. After assigning, you should then be able to use keyboard keys as mouse buttons, without having to bring up the overlay or activate free mode.

Modifier clicks (or other actions)

Modifier clicks are available in both overlay and free mode.

If a modifier key is held during a mouse action, and isn’t assigned to a hold for command, a native mod+mouse event will be simulated. In other words, to execute a shift+click (e.g. to select a group of items in file explorer):

• Select a cell in the overlay, or position the mouse cursor in free mode
• Hold shift
• Execute the mouse action (e.g. by pressing Space or a subgrid char)
• Then release shift

Note: Some Linux distros may have only partial or no modifier click functionality. More testing to come, and reports are welcome.

Wheel / scrolling

To use the mouse wheel, tap the OptionLeft key on Mac or ControlLeft key on Windows and Linux (toggle free mode command) to enter and exit free mode.

While in free mode, use:

• M, ,, ., and / to scroll up/down/left/right
• S, D, and F to increase the speed (the more pressed, the greater the increase)
• A to decrease the speed

There are also fast, step (precise increment, responds to autorepeat when held), and step large commands, and on Mac and Windows there are jump to top/bottom/left/right to jump to the edge of a scrollable area.

To adjust scrolling speed / step sizes, as well as auto off duration, see the Free mode subsection of the Behavior section in the config editor.

See here for the rest of the free mode controls / capabilities.

Multiple monitor usage

• To move the overlay between monitors, tap the ShiftLeft or ShiftRight keys while the overlay is visible.

• To assign different grid configs to different monitors:

  • In the Grid Options section of the config editor, use the + and - buttons to add/remove grid configs
  • With monitor assignment mode set to auto, the first grid config will be assigned to monitors with a horizontal aspect ratio, and the second will be assigned to monitors with a vertical aspect ratio
  • For more customized assignment, set monitor assignment mode to custom, and use the custom monitor assignments field to assign grid_config names to specific monitors

Menu/gui actions

• To open the config editor, press the Tab key while the overlay is up (edit config command)
• To close dialogs, tooltips, etc, press the the Escape key (close ui element command)