Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Customizing Mouseless

The config editor

  • To open the config editor, choose Edit config... from the Mouseless menu (in the Mac menu/status bar, or Windows system tray), OR press Tab while the overlay is visible
  • Many tooltips are available for in-context guidance. To see them, hover over:
    • The label on many fields
    • Some built-in presets
    • The info icons next to some sections
    • The info icon at the bottom-left of the config editor
  • Changes you make are applied automatically
  • On Windows, the config editor is searchable via ctrl+F
  • To save, hit the save button (or press cmd+S on Mac)
  • To save/load presets, or restore saved or defaults use the kebab menus in the section/subsection headers
    • To update or delete a user preset, right-click it to show a context menu
  • To restored saved or default values for a single field, right-click the field to show a context menu
  • Use the kebab menu at bottom to import a config file, export a config file, or restore defaults for the entire config

Field editing tips

  • You can press Enter in a text field to make it validate / take effect. Leaving the text field with Tab or the mouse also works.
  • Colors can be copied and pasted (with ctrl+C and ctrl+V (command on Mac)) while focused, or by dragging and dropping from one to another. The copied format is hex (e.g. #4e6c95).

Manually managing config files

  • You can choose Open config folder from the Mouseless menu, and edit/duplicate/delete files at will. config.yaml is the one loaded at app startup.
    • NOTE: if the config.yaml file is removed, or modified in such a way that it has invalid syntax or values, the default config values will be used the next time the app is started.

NOTE: the information for each field that follows is largely the same as is found in the in-app tooltips

Grid (overlay) options

The dimensions and content of an overlay is determined by a 'grid config'.

  • To add or remove a grid config, use the + / - buttons under the lowest grid config.

Grid config fields:

  • Level _ columns: The number of cells across the X dimension at this level.
  • Level _ rows: The number of cells along the Y dimension at this level
  • Level _ keys (in preview): The keys you press to select a cell at this level. They wrap to multiple rows if necessary. Note: If left blank for level 2 or subgrid, the keys from level 1 will be used.
  • Mouse action keys (in v0.3): The keys you press to select a cell. They get mapped to each level of the main grid, mapping to multiple rows if necessary.
  • Subgrid action keys (in v0.3): The keys mapped across the rows of the subgrid, that you can press to execute a mouse action.
  • Always show subgrid: Shows a subgrid in every cell, all the time, which can make it easier to know ahead of time which sub-cell you'll want to click. This comes at the cost of more visual noise, however. Currently only available whengrid line style is set to lines.
  • Hold Subgrid Key For Nudge (in preview): When on, holding a subgrid key allows you to use the subgrid nudge commands to move the cursor, then release the subgrid key to execute the action. Note: This is a beta feature. Some bugs may be present.
  • Nudges per cell (in preview): Determines nudge size. I.e. if set to 4, then 4 nudges will move the cursor to the same point in next subgrid cell.

Monitor assignment fields:

  • Monitor assignment mode: Controls how grid configs are assigned to monitors.
    • auto: the first grid config gets assigned to horizontal monitors, and the second gets assigned to vertical monitors.
    • single: the first grid config gets assigned to all monitors.
    • custom: grid configs are mapped by name, via the custom monitor assignments field.
  • Custom monitor assignments: List of grid config names, separated by comma+space (e.g. A, B). The first is assigned to the primary monitor, the second to the second monitor, and so on.

Behavior options

Overlay / cursor:

  • Initial overlay monitor: The monitor that the overlay will appear on when shown.
  • Initial action location (in preview): Determines where mouse actions are executed (via execute mouse action) when no cell is selected. Note: the with_keyboard_focus option may not work correctly on MacOS at this time.
  • Grid action level (in preview): Determines the grid level that mouse actions get executed at (i.e. how many keypresses it takes). Use the cycle grid action level command to change this value while the overlay is up.
    • subgrid: When a leaf cell is selected, a subgrid is shown and Subgrid keys are used to execute an action.
    • 2 or 1: When a cell at the given level is selected, a mouse action is executed immediately, at its center.
  • Hide cursor on click: When on, the cursor moves out of the way after a click is executed.
  • Hide location: The corner or edge of the clicked screen that the cursor will move to. You can choose any edge (top/bottom/left/right) or corner (top_left/top_right/bottom_left/bottom_right).

Movement / timing:

  • Move duration (ms): The time taken to move the mouse cursor during move and drag actions.
  • Move system cursor with virtual (experimental): When this is on, the system cursor will smoothly move as you select a cell, following the virtual cursor.
    • Note: in v0.3, when input is entered quickly, this feature may cause mouse actions to execute along the movement path instead of the destination -- this should be fixed in the latest 0.4 preview version.
  • Multi-action timeout (ms): For double and triple clicks, this sets the maximum time that can pass between keypresses before it no longer triggers a native double or triple click. Note: This is called Multi-click threshold in v0.4 preview.
  • Tap threshold (ms): For tap-triggered keybindings, this is the maximum time a key can be down before its no longer considered a tap.

Wheel mode ('Free mode' in preview):

  • Base wheel speed: The amount scrolled each tick during wheel up/down/left/right commands. Measured in pixels on Mac, lines on Windows.
  • Wheel speed multiplier: This multiplier gets applied:
    • to the fast mouse wheel actions
    • when hold for speed increase is active
    • when multiple keys for the same direction are pressed.
  • Wheel step size: The amount scrolled each time a wheel step command is executed.
  • Wheel step size large: The amount scrolled each time a wheel step _ large command is executed.
  • Wheel mode auto off (seconds): If no scroll actions are done for this many seconds, free mode will turn off. Set to0 to disable.
  • Wheel easing factor (in preview): Controls the smoothness / acceleration of wheel movement. 0.05 = loose, 0.1 = natural, 0.2 = snappy, 0.4 = instant. Note: this is currently affected by screen refresh rate, but this will be fixed soon.
  • Base move speed (px) (in preview): The amount the mouse cursor moves each tick during move up/down/left/right commands.
  • Move speed multiplier (in preview): Movement speed is multiplied by this amount for each hold for speed increase hotkey held.
  • Movement easing factor (in preview): Controls the smoothness / acceleration of cursor movement. 0.05 = loose, 0.1 = natural, 0.2 = snappy, 0.4 = instant. Note: this is currently affected by screen refresh rate, but this will be fixed soon.

Misc:

  • Send escape after global alt tap (Windows): Simulates a press of the Escape key after certain global commands (e.g. show overlay, enter free mode) are triggered by an AltLeft/Right tap. Helps to deactivate the focused app's menu bar (which typically activates when Alt is tapped).,

Style / Appearance options

Base:

  • Master opacity: Overall opacity of the overlay. Multiplicative with other opacities -- e.g. if master opacity is 0.5 and and background opacity is 0.8, the final background opacity will be 0.4 (40%).
  • Background color: The color/opacity of the background, including underneath the highlight.
  • Highlight color: The color given to the currently active cell(s) of the overlay.
  • Show initial highlight: When on, the highlight will be shown before any cells are selected, covering the entire overlay. Useful when background opacity is zero.

Grid:

  • Grid line style: Note: Currently, Always show subgrid is only available for the lines style.
  • Grid line width (px): Note: Subgrid lines use this value only if grid line style is dots, otherwise they are assigned 1.
  • Grid line color: The color/opacity of the main grid lines.
  • Subgrid line color: The color/opacity of the subgrid lines.

Text:

  • Font (in preview): The font used in the overlay. You can use the cycle font command to change this while the overlay is up.
  • Font weight (in preview): Controls the boldness/lightness of the text. The actual effect varies by font.
  • Y offset: Moves the text up/down, by an amount scaled to the font size. This helps correct positioning for fonts that are not vertically centered.
  • Font size multiplier: Scales the size of the characters within the main grid.
  • Subgrid font size multiplier: Scales the size of the characters within the subgrid.
  • Char spacing strategy: Sets how the spacing of characters within a cell is adjusted: cell_width_relative, font_size_relative, or evenly_spaced.
  • Char spacing cell width ratio: 0 -> characters will be approximately touching edge-to-edge 1 -> characters will be evenly spaced across cells
  • Char spacing font size ratio: 0 -> characters will be approximately touching edge-to-edge 1 -> characters will be about as far apart as an uppercase character is tall
  • Text color: The opacity value here gets applied to a layer with the text and text shadow combined, so that the shadow doesn't show through the text.
  • Subgrid text color: "The opacity value here gets applied to a layer with the text and text shadow combined, so that the shadow doesn't show through the text.
  • Text shadow rgba: The opacity value here is in addition to what gets applied by the text color opacity (e.g. if both are 0.5, the shadow opacity is effectively 0.25).

Cursor:

  • Cursor size: The size (width and height) of the virtual cursor, in pixels.
  • Cursor color: The color/opacity of the virtual cursor in its default state.
  • Cursor right button color: The color/opacity of the virtual cursor when hold for right button is active or cycle button has been used to set the button to right.
  • Cursor move color: The color/opacity of the virtual cursor when hold for move is active or cycle action has been used to set the action to move.
  • Cursor drag color: The color/opacity of the virtual cursor when hold for drag is active or cycle action has been used to set the action to drag.
  • Cursor other color: The color/opacity of the virtual cursor when not in one of the states above.