v1.1.0

This release has important fixes on every platform and adds significant new features including label mode (Mac, Windows, X11, and GNOME Wayland envs (others coming soon)), custom actions, a revamped settings window with a dark theme, and auto-translation of defaults and presets to non-QWERTY layouts.

Feedback always appreciated! (Mac Windows Linux)

Upgrading from v1.1.0-preview.1? 🅿️ marks changes since that release, including the Notes for preview.1 users section.

Cheat sheet: To see new features/defaults in action quickly on an existing config, right-click these settings, then Restore default:

• New features:
  • Keymap > Toggle label mode (beta)
  • Style > Char background color
• New defaults
  • Style > Font: Jost (default)
  • Behavior > Free mode auto off (seconds): 0 (disabled, was 10)
  • (On Wayland) Behavior > Initial overlay monitor: with_mouse

An upcoming release will streamline this process in-app.

Enhancements

App window

• Revamped UI, integrated app window
  • Settings categories now have separate pages
  • App window theme on the General page: system, light, or dark
  • cmd+F / ctrl+F search works across pages
• Import/Export config now available on Linux and Windows (from kebab menu at bottom of settings window, already present on Mac; #577, thanks @DaveuRrr)
• 🅿️ Find widget (cmd+F / ctrl+F) improvements (#639, thanks @DerRockWolf)
  • Reaches settings in collapsed Keymap groups
  • Pressing cmd+F / ctrl+F again while open selects text
  • Closing with Escape focuses the current match's field
  • Restores prior state on reopen
• 🅿️ Because grid and label mode both use an overlay, the keymap's Overlay section is now called Grid mode, and the toggle/show/hide overlay commands are now toggle/enter/exit grid mode

Custom actions

Custom actions allow you to trigger arbitrary settings changes via hotkey.

Currently there are three types:

• set value: sets the setting to one value
• cycle value: steps through a list of values; Cycle mode: wrap, reflect, or stop
• adjust number: creates an increase/decrease pair of actions; when invoked, the value moves by Step and clamps to Min and Max
  • a reset action is also created when Reset value is set

To create a custom action, either:

• right-click a setting and choose Add custom action

OR

• click + action at top of the Keymap page in the Custom section and choose a target setting

Other fields:

• When: determines in what context an action can be invoked; global, overlay, free_mode, label_mode, or no_mode
• Message: the toast message shown when it runs — off, default (the setting's name and new value), or custom text

Label mode (beta)

Places a label on each clickable element in the frontmost app. Type the label to click the element.

Available on: Mac, Windows, X11, and GNOME on Wayland -- more Wayland environments will be worked on very soon

• On GNOME: log out and back in once after installing, so the Mouseless GNOME Shell extension loads

Actions: toggle label mode, enter label mode, and exit label mode

• Deep links: toggle-label-mode, enter-label-mode, and exit-label-mode
• existing hold for and cycle commands pick the mouse action, button, and click count, as they do with the grid
  • Note: dragging is not yet implemented
• an unbound ctrl, alt, or cmd/win held while typing a label is applied to the click, e.g. to open a link in a new tab
  • A modifier bound to a hold for action runs that action instead

Settings

• Style > Labels > BG color, text color, font size, alignment
• Behavior > Labels > Label characters
  • 🅿️ Defaults to ASDFGHJKLXCVBN, so labels stay at 2 characters or fewer for up to 196 elements, and characters should remain alphabetic across languages/layouts
• 🅿️ On Mac: Behavior > Labels > Label menu bar determines whether an app's menu bar receives labels

Usage notes / known issues:

• Windows: in Chromium and Electron apps, the first show may label only the app header
• Linux
  • the first use turns on AT-SPI accessibility (IsEnabled), which Chromium, Electron, and Firefox apps need to expose their elements
  • to improve responsiveness, buttons, toggle buttons, and links in GTK 4 apps are clicked with the cursor, which moves onto them, rather than pressed through accessibility
  • in Chromium and Electron apps, labels sit a little right of and below their elements
  • in some apps running under XWayland, labels can appear well away from their elements
  • X11: GTK 4 apps get no labels

Keyboard layouts

Note, Windows and X11 existing users: if Keyboard layout under Behavior > Keyboard is blank, keys work as in 1.0 until you click Update beside it, then Save; then the behavior described below applies

• New installs now read your layout on first start, as macOS and Wayland already did

• Default grid keys, default keybindings, and built-in presets are now translated to your selected keyboard layout when they are loaded, so intended key positions are preserved, e.g. WASD becomes ZQSD on AZERTY
  • Translation also occurs when you click the Update layout button. You can always click the 'restore saved settings' button at the bottom of the window if you don't like the result.
  • You can disable translation by unchecking Translate defaults/presets to layout in Behavior > Keyboard; then QWERTY versions will always load
• A warning now appears under Level N keys, Subgrid keys, and Label characters when your layout can't type one of the keys
• The grid now distinguishes non-alpha shifted characters, e.g. so / and ? can both be assigned at the same level (#554, thanks @wanyann)
  • If only one is present, it will be matched regardless of whether shift is held
  • Letters are unaffected: A is inaccessible if a is at the same level

Grid, overlay, and toast

• Toast window now appears on the screen with the mouse (in free mode) or overlay (#318, thanks @elizabeth-descript)
• Added Char background feature for enhanced contrast / legibility (#612, thanks @gihrig @msmouse)
• Added Reverse level 2 keys on right half feature, for left/right-hand symmetry in certain configurations (thanks @MErkinSag)
• New bundled fonts: Jost (default), Jost Italic, QuicheSans
  • Known issue, Linux: The cairo overlay (the default on NVIDIA) draws these fonts in the system's sans font

Input (Windows and Wayland)

• Alt tap and Win/Super tap commands no longer trigger native behavior (app menu, start menu or desktop overview)
  • Mouseless 'masks' the tap by injecting a keypress before the modifier release
    • The Modifier tap mask key setting determines which key gets injected; default is auto (an unused virtual keycode on Windows, F14 on Linux)
  • The native behavior is still available: just hold the modifier for longer than tap threshold
  • The Send 'Escape' after global 'Alt tap' command is now deprecated and removed from Linux; on Windows, it applies only when the mask key is unassigned
  • 🅿️ On Windows, Ctrl+Shift tap is also masked (switches system keyboard layout by default)

Diagnostics

• Debug logging now shows when Mouseless triggers mouse button up/down events (does not log the events' screen position)

Fixes - all platforms

Free mode and drag

• Fixed hold for drag sending mousedown events when continuing a drag via holding, which kept the next drag from starting in some apps
• Fixed free mode timing out while hold for free mode was held, which let keys pressed afterward reach the app with the hold key's modifier
• Fixed free mode toast disappearing when overlay hidden (Windows and Linux, #600, thanks @DerRockWolf)
• Fixed a key assigned to wheel commands ignoring its next press after hold for free mode was released

Overlay and grid

• Fixed direct mouse-button commands (right click, back mouse button, forward mouse button) firing instead of selecting a grid cell when their key is also a grid label (#617, thanks @tadsn3w)
• Fixed subgrid nudge keys doing nothing while a hold for key bound to a modifier was held, e.g. hold for drag (#603, thanks @DerRockWolf)
• Fixed the overlay getting stuck on when opened through a deep link while Mouseless is disabled (#584, thanks @NextMerge)
  • Deep links that would show the overlay or enter free mode are now ignored while Mouseless is disabled
• Subgrid nudge: eliminated lag when nudges entered rapidly

Config file

• The settings UI now reports when it can't write the config or presets to disk, naming the target file and the reason, with a button that copies the details (#599, thanks @DerRockWolf)
  • Your unsaved changes are kept instead of cleared
• Config and presets files are now written atomically, so a save interrupted by a disk error leaves the previous file rather than an empty one
• A config or presets file that can't be loaded is now kept as config.yaml.invalid.bak or presets.yaml.invalid.bak before Mouseless falls back to defaults, so a later save no longer replaces it
• Fixed config files that can't be written during a version migration being reported as a config that failed to load
• Fixed a config with an invalid keyboard_layout falling back to entire default config; only that entry is reset now

License

• Fixed license check retry logic when the network isn't ready at login (#597, thanks @kchristidis)
• You can now change your license key from the tools menu (useful e.g. for upgrading from subscription to lifetime)

Fixes - macOS

Startup, updates, and config

• Fixed startup issues causing keyboard to be unresponsive when launched at system start
  • If you removed Mouseless as a Login Item due to this bug, you can restore it now
  • Fixed missing secure input icon and made startup failure handling more graceful/robust (#589, #632, thanks @TyceHerrman, @antoniorodr, and @shpoont)
• Fixed issue where update checker wouldn't retry after network not initially available
• Closing the welcome window before you start a trial or activate now quits Mouseless, instead of leaving it running in background

Overlay and toast

• Fixed grid mode sometimes accepting no cell selections until Mouseless was restarted (#472, thanks @ronnyworm)
• Toast window and free mode indicator now show over a fullscreen app

Input, free mode, and drag

• 🅿️ Fixed toggle free mode not exiting free mode while Secure Input is active
• 🅿️ Fixed issues with Mouseless being overly sensitive to rapid screen update events on HDR screens while free mode indicator is enabled (#643, thanks @haikesan)
  • Fixed system-wide typing stalls, label mode exiting, grid refreshing, and excessive logging
• Fixed the first modifier tap after some shortcuts being ignored, e.g. a cmd tap to show the overlay after cmd+shift+]
  • A workaround for extra modifier events sent by Karabiner-Elements now applies only to keys that come through Karabiner, and only to a tap within 700ms of a shortcut Karabiner handled itself
• Fixed cases where modifier-bound actions switched to non-modifier-bound actions while held (e.g. shift+ArrowUp running ArrowUp's action after a moment) (#628, #547, thanks @tadsn3w)
• Fixed pressing the A grid key twice to double-click also typing "a"
• Fixed drag and drop sometimes failing when Move system cursor with virtual is on
• Fixed issue where system cursor errantly moved and clamped at edges in pointer-locked situations
• Free mode movement now works in situations where an app only reads unaccelerated event attributes (e.g. some games; pointer lock demo above is one example)

Deep links

• 🅿️ Partially fixed Mouseless taking focus when activated by a deep link, which can cause click to not reach target app (thanks Lê Hùng Luận)
  • Mouseless now hands focus back to other app
  • Full fix coming soon (no focus change will happen at all)

Fixes - Windows

• 🅿️ Master opacity (Style) and the increase/decrease master opacity actions (Keymap) are now available in the settings window (#638, thanks @ksbrar)
  • Master opacity's value is migrated to 1, as the setting was not active in 1.0 and earlier (and its value was effectively 1)
• Switching your system layout no longer moves cells to other keys, e.g. German's Z cell stays on its key after switching to US (#521, thanks @markifi)
• Fixed text copied by Mouseless (version info, diagnostics, error details) starting with an invisible character
• Fixed the settings window opening without keyboard focus from a hotkey or deep link
• Webview2 runtime
  • Mouseless now explains when the runtime is missing, rather than failing with an unhandled exception
  • A 'Fixed Version WebView2' runtime placed in a WebView2Runtime folder beside mouseless.exe is now picked up, so a machine with no internet access can run without the Evergreen runtime
    • Setup: WebView2 Runtime

Fixes - Linux

Input

• Fixed keys typed on the overlay reaching the app when Move system cursor with virtual and Free mode after move are both on

  • Over USB, this needs a new udev rule: run step 2 of Method 1 again, or step 4 of Method 2, in Enabling keyboard/mouse access on Wayland

• --list-input-devices now shows what each device can do (keyboard, pointer, wheel, etc.)

• 🅿️ Fixed Free mode after move turning free mode on only for the first move when is Move system cursor with virtual on with the webview overlay renderer (#620, thanks @msmouse)

• 🅿️ Fixed free mode's keys also typing into the focused app after a grid move made while free mode was on, with Free mode after move on

• 🅿️ Keyboards plugged in after startup can now work with Method 2 of Enabling keyboard/mouse access on Wayland: run its new step 5 (#577, thanks @lasseleegaard)

• Dead keys now work as grid keys and hotkeys, as their own character, e.g. ^ on German and ' on US International

  • A config from 1.0 needs you to click the Update button first

• Wayland

  • Fixed pointer events from combined keyboard+pointer devices being swallowed (#627, #577, thanks @twiggshub, @NikhilAlapati, and @Bouhtouch)
  • Fixed a hold for action's modifier reaching the app while held (#594, thanks @DerRockWolf)
  • Fixed exit free mode hotkey leaking through to underlying app (#624, thanks @jorikvanveen and @HarrisRamosBaroni)
  • When Excluded input devices matches every keyboard, an alert now says so and Mouseless keeps running, picking the keyboard up once its entry is removed; before, it showed "No Keyboards Found" and quit
  • Fixed a crash when the keyboard layout is read during sessions without XWayland (#596, thanks @DerRockWolf)
  • Fixed Mouseless intermittently dropping a keyboard and no longer responding to it
  • Fixed Clear keyboard state not releasing a stuck drag, e.g. one left by a key release missed during an app switch or sleep/wake

• X11

  • Fixed incorrect mappings for media and numpad keys
  • With two layouts configured, keys are now read in the active one; before, the first was always used, e.g. EurKEY's ' read as German's ä (#467, thanks @lgloor)

Overlay monitor and toast

• Wayland: with_mouse now works for Initial overlay monitor (#604, thanks @DerRockWolf)
  • On niri it follows keyboard focus
• GNOME: the toast now follows the active workspace (#606, thanks @HarrisRamosBaroni)
• Fixed the toast sometimes appearing under the overlay
• 🅿️ Fixed pixelated grid text on scaled displays, e.g. 200%, with the cairo overlay renderer, the default on NVIDIA (#639, thanks @NikhilAlapati)

Settings window

• Fixed blank Settings pages on affected NVIDIA Flatpak installations (#635, #577, thanks @Andlon and @virtual256)
  • If you previously set use_dmabuf: false in debug_options, remove that override to use this fix

Diagnostics

• 🅿️ Fixed the Flatpak's --diagnostics output and log naming the Flatpak runtime, e.g. "GNOME 50", instead of your distro
• 🅿️ --diagnostics now shows the desktop environment, e.g. KDE or GNOME
• 🅿️ Fixed Copy state diagnostics showing "Copied diagnostics to clipboard" when the copy failed
• 🅿️ In the Flatpak, copying to the clipboard isn't supported yet; a failed copy now says so, instead of asking you to install xclip or xsel
• 🅿️ --list-input-devices now lists devices Mouseless can't read, marked unreadable, instead of leaving them out
• 🅿️ Logging now warns when Mouseless can't read a keyboard

🅿️ Notes for preview.1 users

This whole section applies to v1.1.0-preview.1 users, in addition to the 🅿️ changes above.

Settings window

• Renamed Alt/Win tap mask key to Modifier tap mask key
  • On Wayland, auto now uses F14 instead of F24
  • Single digits still name keys; use a leading zero, e.g. 01 or 001, for keycode 1
• Empty Custom groups in the Keymap no longer look clickable
• Keymap groups with no commands on your platform are no longer shown

Label mode changes

• Added XCVBN to the default Label characters
  • Configs still using the old default are updated, including defaults translated to the assigned keyboard layout
• Shift now works as a label-click modifier when it isn't bound to a hold for action
• Labels that start with the same character are now spread out (reduces overlap after first keypress)
• Linux: shift+ControlLeft tap is now the default toggle label mode binding

Mac fixes

• Fixed close UI element (Escape by default) not closing Mouseless's own alerts
• Removed the Secure Input alert at system login (secure input sometimes stays active for up to ~6 seconds); the status icon will show a padlock while it's active (#637, thanks @skovtunenko)

Windows fixes

• Fixed the Settings window stealing focus from startup alerts
• Fixed startup errors closing the app before their alert appeared
• Fixed Master opacity (Style) and the increase/decrease master opacity actions (Keymap) not being shown in the settings window (#638, thanks @ksbrar)

Linux fixes

• Fixed the grid staying small in the upper-left corner when label mode was the first thing used after starting, with the webview overlay renderer, the default without NVIDIA
• Fixed the Flatpak's GNOME Shell extension installing to incorrect location, so labels never showed even after logging out and back in (#639, thanks @mikaelmantel)
  • Startup logs no longer call the extension enabled before GNOME Shell has loaded it
• Wayland: Fixed the pointer of a combined keyboard+pointer device moving slower or faster while Mouseless runs (#627, thanks @fiskhest)
  • USB devices need the new udev rule: rerun step 2 of Method 1 or step 4 of Method 2 in Enabling keyboard/mouse access on Wayland
  • Hyprland per-device settings need a second device block for the virtual device shown by hyprctl devices; see Pointer speed troubleshooting