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, choose Edit config... from the Mouseless menu in the status bar / system tray, OR press Tab (edit config command) while the overlay is showing.

The overlay

  • To show the overlay, tap the CommandLeft (AltLeft on Windows) 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, without executing a mouse action, press the Escape key (hide overlay command)

Clicking, moving, and dragging

With the overlay

  • 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, e.g. before entering any characters, to click where the virtual cursor is

  • 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, 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-action timeout threshold (renamed to multi-click threshold in preview)
    • use the cycle click count command

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

    • hold the AltLeft key (CommandLeft on Mac) key while pressing the final key to begin the drag
    • the overlay will remain up for you to choose the point you want to drag to or drop at
    • to release/drop, enter in a click-coordinate as normal
    • to drag to a point (without release/drop), hold the AltLeft key (CommandLeft on Mac) on the final press again
    • to cancel a drag (release at the system cursor), press Escape (release hold/drag command)

  • 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

With free mode (in preview)

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

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

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

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

While free mode is on:

  • to move, use I, K, J, and L
  • to click or click+drag, use Space (left mouse button), V (right), and C as if they were mouse buttons
  • to increase movement (or wheel) speed, use A, S, D, and F -- the more of them you hold, the greater the increase
  • to decrease movement (or wheel) speed, hold ShiftLeft

Global mouse buttons (beta)

Note: In v0.3, these are called Mouse buttons w/o overlay.

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 + click (or other actions)

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 (e.g. ctrl+click for right click, cmd+click to open link new tab).

Note: currently, modifiers assigned to wheel-related hold for commands will prevent this, but this will be fixed soon.

Wheel / scrolling

Note: In v0.4 (currently in preview), wheel mode has been replaced by free mode, where M, ,, ., and / are the keybindings for wheel up/down/left/right. See here for the rest of the free mode instructions.

To use the mouse wheel, tap the OptionLeft key on Mac or ControlLeft key on Windows (toggle wheel mode command) to enter and exit wheel mode -- currently, this must be done without the overlay showing, but support for using wheel mode with the overlay showing will be added soon.

While in wheel mode, use J, K, L, and ; to scroll up/down/left/right, and hold CommandLeft to increase the speed (there is also a hold for speed decrease command). There are also fast, step (precise increment, responds to autorepeat when held), and step large commands, as well as 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 Wheel subsection of the Behavior section in the config editor.

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
  • 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)