Skip to content

Choose a tag to compare

@github-actions github-actions released this 15 Nov 15:23

New features and improvements

  • A new configuration built around UI hints: in neverclick.properties, UI hints do all the work. From any app, a combo such as Ctrl+Enter shows vision hints on every screen. The hint that you type then gets a click, a text selection or a drag. Before you type a hint, the arrows and the digits move the hotspots of all the hints. While the hints show, hold ? to show the cheatsheet. See neverclick.md for the documentation. The Neverclick project inspired this configuration.

    mousemaster-neverclick.mp4
  • Overlay styles: each color, font, box, border, glow and shadow of the hints is a property, so you can give the hints any look. To start from an example, see the styles in overlay-styles.md. A style is a parent mode that sets only the look. Each shipped configuration takes the look of its hint modes from a style mode: _hint-style-mode, _ui-hint-style-mode or _recursive-hint-style-mode. To use a style, add the lines of its file to your configuration, then put its mode in place of the style mode:

    ui-hint-mode=_indicator-mode _violet-style-mode

    A property that you set in your hint mode changes the style: ui-hint-mode.overlay.font-size=12.

    vision-hints-github.mp4
  • One overlay for grids and hints: the grid and the hints are now one overlay, with one set of properties: <mode>.overlay.* (#118). A grid is an overlay without selection-keys. Thus a grid gets the gradients, rounded borders and shadows of the hints, and a hint grid can shrink and move as a grid does. shrink-overlay and move-overlay-to act on each overlay: a grid puts its cells in the new area, UI hints scan the new area, and position history hints show the positions in it. area=last-overlay-area shows an overlay in the area of the overlay before it.

    hint-mode.overlay.grid-cell-sizing=fit
    hint-mode.overlay.grid-max-row-count=2
    hint-mode.overlay.grid-max-column-count=2
    hint-mode.overlay.selection-keys=hintkey
    hint-mode.select=+hintkey
    hint-mode.shrink-overlay.up=+up
  • The target: the overlay now moves its own point, the target. With mouse-follows-target=false, the mouse stays where it is until move-to.target. Thus a mode can select a point in a UI element, not only its center, and no menu or tooltip opens during the selection. move-target-to and move-to take the edges and the center of a cell (cell-top, cell-center, ...), overlay-center and last-selected-hint. start-move-target and nudge-target move the target as start-move and nudge move the mouse.

    ui-hint-mode.to.refine-mode=+hintkey
    refine-mode.overlay.area=last-selected-hint-cell
    refine-mode.overlay.grid-cell-sizing=fit
    refine-mode.overlay.grid-max-row-count=2
    refine-mode.overlay.grid-max-column-count=2
    refine-mode.overlay.mouse-follows-target=false
    refine-mode.move-target-to.cell-top=+up
    refine-mode.move-to.target=+space
    mousemaster-refine-selection-pdf.mp4
  • Hotspots: the hotspot of a hint is the point where a selection of the hint puts the target. hotspots.cell-x-percent and hotspots.cell-y-percent move the hotspots of all the hints across their cells, and nudge-hotspots and start-move-hotspots move them by pixels. The overlay shows a moved hotspot as a box, with a line from its hint (hotspot-box-* and hotspot-line-*).

    hint-mode.hotspots.cell-x-percent=0.5 | +1 -> 0 | +2 -> 0.125 | +3 -> 0.25
    hint-mode.nudge-hotspots.left=+leftarrow
    hint-mode.overlay.hotspot-box-opacity=1
    hint-mode.overlay.hotspot-line-opacity=1
  • UI hints show their elements: ui-element-box-* draws the box of each element behind its hint, with a fill, a border and a shadow. last-selected-hint-cell is the element of the last selected UI hint: an overlay or an indicator layer can cover it.

    ui-hint-mode.overlay.ui-element-box-border-color=#2EA043
    ui-hint-mode.overlay.ui-element-box-border-opacity=1
    ui-hint-mode.overlay.ui-element-box-border-thickness=2
  • Label order and length: ui-order sets which UI hints get the shortest labels: the hints from an edge of the screen (left-to-right for a taskbar on the left), the hints nearest to the mouse (mouse), or a random order that does not change. label-length=equal gives all the labels the same length, with the first keys for the first hints.

    ui-hint-mode.overlay.ui-order=left-to-right
    ui-hint-mode.overlay.label-length=equal
  • Vision hints: on 17 test screenshots, the default density now finds 96% of the clickable targets instead of 89%, and a scan takes about a third of the time. The default vision-density is now 6. The new density 1 ignores plain text and keeps the icons, the buttons and the fields. A link in a sentence gets its own hint, small icons get hints, and card outlines and separators get no hints. vision-min-size removes the vision hints of thin lines, such as the bars beside the taskbar icons (#115).

    ui-hint-mode.overlay.vision-min-size=3
  • Indicator layers on the target and the hints: a layer can now be at the target, the last-selected-hint, the active-window-center, a corner of the screen (active-screen-top-left, ...), or each position of a position history. With end-position, a layer runs between two points, such as a line from a hint to the target. With area, a layer covers an area, such as the element of the last selected UI hint. follow applies to each position, and overlay.z puts the overlay between the layers. Each layer casts its own shadow.

    refine-mode.element-indicator.shape=rectangle
    refine-mode.element-indicator.area=last-selected-hint-cell
    refine-mode.line-indicator.shape=line
    refine-mode.line-indicator.position=last-selected-hint
    refine-mode.line-indicator.end-position=target
  • Saved hints: a configuration can now let you select several UI hints, then click them all with one action. For example, to check several boxes in a list, a configuration can mark each hint that you type, with a line to the next one. When you press Enter, it clicks the boxes in the order that you typed them. For this, a position history now saves the target and the hint at that position. toggle-save saves the target, or removes it if it is saved. saved-hints and the saved- properties give the saved hints their own look, and a saved hint stays when the keys that you type hide the other hints.

    ui-hint-mode.toggle-save.click-position-history=_{markkey} +hintkey
    ui-hint-mode.overlay.saved-hints=click-position-history
    ui-hint-mode.overlay.saved-box-color=#FFFFFF
    mousemaster-saved-hints-checkboxes.mp4
  • Animations that overlap: with overlap=true, an animation that starts again lets a copy of the old run play to its end. In the shipped configurations, each click of a double-click now shows its full burst. The burst is also wider and lands with a bounce, a held button bursts again when you release it, and a glow fades out in its color.

    click-burst-animation.overlap=true
  • Gradients and shadows: each overlay color now takes a gradient: the background, the font, the label outlines and shadows, and the decorations. in-turn gives each hint or group the next color of the list, with no blend. The UI element boxes and the hotspots cast shadows, and last-selected-hint-box-center-color gives an indicator layer the color at the center of the selected hint.

    hint-mode.overlay.box-color=per-group in-turn #E06C75 #98C379 #61AFEF
  • Keys by the character they type: a key name can be a character that the active layout types with shift or altgr. On us-qwerty, +A is a pressed with shift, and +questionmark is / pressed with shift. Thus the neo-mousekeys cheatsheets now show while you hold ?, not t (#107). questionmark, asterisk, lessthan, greaterthan and numpadenter are new key names. On macOS, a text shows the alt and win keys as ⌥ and ⌘.

  • Screens of different scales: each speed and length is in pixels at a 100% scale, on Windows and on macOS. On a macOS screen at 200%, the mouse no longer moves at half the speed. An indicator layer takes the scale of the screen that it is on. On macOS, the hints, the indicator and the mouse moves are at the correct place on each screen. On Windows, render-as-cursor takes the cursor size of each screen.

  • Faster painting: the hints and their shadows are painted on all the cores, and only what changed is painted again. The indicator layers that change are drawn apart from the layers that do not. The indicator and the hints that change together show in the same frame. On Windows, mousemaster runs at above-normal priority, and the executable is built with profile-guided optimization.

  • Upgrading: a configuration of Build 95 still loads. mousemaster reads the old names as the new ones, and logs a warning that gives each new name. The main ones:

    • hint. and grid. are overlay., grid-area and ui-area are area, layout-*-count is group-*-count, prefix-box-* is group-box-*, and cell-*-padding is box-*-padding.
    • select and deselect (the old undo) are commands of the mode: hint-mode.select=+hintkey. A command comes right after the mode: normal-mode.start.click-burst-animation.
    • snap and move-to-grid-center are move-to, shrink-grid is shrink-overlay, move-grid is move-overlay-to, and mouse-movement is mouse-follows-target and target-follows-overlay-center.
    • screen-center is active-screen-center, ishintmeshempty is isoverlayempty, follow-mouse is follow, and the *-animation-* properties of the overlay and the zoom are transition-* and fade-*.

    Three changes can need an edit. vision-density has new steps: the old default, 4, is now 6. smooth-jump-velocity is in pixels at a 100% scale: on a 200% screen, divide it by 2 to keep its speed.

  • Fixes:

    • With Num Lock on, the numpad digits are numpad0 to numpad9, not home, uparrow, pageup and the other navigation keys (#116).
    • The UI hints no longer show below the taskbar or the active window (#113).
    • A window border next to the taskbar no longer joins the taskbar icons into one vision hint (#113).
    • A layer at the mouse stays at the pointer when an app shows a large cursor of its own, such as a drag image (#112).
    • With render-as-cursor, each cursor shape shows the indicator after an animation, and the indicator no longer flashes when it moves from the cursor to its window (#111).
    • Vision hints no longer detect the cursor.
    • After a configuration reload, the first hints no longer show empty, and a hidden cursor shows again.
    • When two branches of a property apply, the rightmost branch always gives the value.
    • With two parent modes, a value from the second parent is no longer replaced by a default.
    • In a mode with stop-commands-from-previous-mode=true, such as idle-mode, a property change no longer releases the mouse buttons or stops the moves.
    • render-as-cursor and exclude-from-capture no longer enable the unnamed indicator layer.
    • An animation draws its last frame.
    • On macOS, a double-click from mousemaster is now a double-click for the apps: they got two single clicks. The indicator no longer zooms in from the center of the screen when it shows.
  • Also: none gives a command no combo, and the mode does not take the combos of its parent for that command: normal-mode.press.middle=none. A grid with area-center=mouse or area-center=target moves with that point. A change during a transition continues from where the transition is, and does not start again. The configuration reference is rewritten, with a table for each set of properties. logback and jsoup are upgraded to versions without known vulnerabilities.

Installation on Windows

  1. Download mousemaster.exe (a portable executable).
  2. Download one of the existing configuration files:
    • neo-mousekeys-ijkl.properties: IJKL moves the mouse, with grids, hints and UI hints (see documentation)
    • neverclick.properties: vision hints on every screen to click, select text and drag (see documentation)
    • neru.properties: recursive hints, each key narrows the area to one cell (see documentation)
    • neo-mousekeys-wasd.properties: neo-mousekeys-ijkl with WASD (see documentation)
    • warpd.properties: the keys and modes of warpd (HJKL) (see documentation)
    • mouseable.properties: the keys and modes of mouseable (HJKL) (see documentation)
    • author.properties: my playground, not recommended for production use: everything with the right hand only (see documentation)
  3. Place the executable and the configuration file in the same directory.
  4. Rename the configuration file to mousemaster.properties.
  5. Run mousemaster.exe: make sure to run it as administrator if you want the mousemaster overlay to be displayed on top of everything else.
  6. Feel free to open a GitHub Issue or join the Discord if you need help creating your own configuration. If you have ideas for a better configuration that you would like to share, I'd love to hear from you.
  7. If you enjoy mousemaster, consider making a donation or stop by the Discord to show your support!

Installation on macOS

mousemaster reads the keyboard through the Karabiner virtual HID device, so that driver and a few permissions are needed.

  1. Install Karabiner-Elements, which installs the virtual HID device, and allow its system extension when macOS asks.
  2. Download and unzip mousemaster-macos.zip, then put mousemaster.app in /Applications.
  3. mousemaster is not signed or notarized, and macOS refuses to start a quarantined app that is not notarized. A browser download marks it as quarantined, so clear that before the first launch: xattr -dr com.apple.quarantine /Applications/mousemaster.app. Or let macOS refuse it once, then allow it under System Settings > Privacy & Security > Security, where an Open Anyway button appears for it.
  4. Download one of the configuration files above, place it in /Applications next to mousemaster.app, and rename it to mousemaster.properties.
  5. Run it from a terminal, as root, which the virtual HID device requires. The configuration is read from the working directory, so start it from where you put it: cd /Applications && sudo mousemaster.app/Contents/MacOS/mousemaster
  6. Grant the permissions macOS asks for, under System Settings > Privacy & Security, then quit and relaunch:
    • Input Monitoring, to read the keys you press. Always needed.
    • Accessibility, only for UI hints (overlay.type=ui-accessibility).
    • Screen Recording, only for zoom (mode.zoom) and vision UI hints (overlay.type=ui-vision).

License

mousemaster.exe and mousemaster.app embed Qt and QtJambi, used under the GNU Lesser General Public License. Run mousemaster with --licenses for the third-party notices and the full license texts.