Skip to content

Latest commit

 

History

History
1218 lines (945 loc) · 43.5 KB

configuration-reference.md

File metadata and controls

1218 lines (945 loc) · 43.5 KB

mousemaster configuration reference

This document provides a comprehensive reference for all configuration options available in mousemaster.

Contents

Key aliases

A key alias is a way to give a name to one or more keys:

key-alias.exit=q p
key-alias.clickthendisable=.
key-alias.up=w

The alias can be then used as part of a combo:

normal-mode.to.idle-mode=+exit

This combo can be completed by either pressing q or p.

The complete available key list can be found in key-list.md.

Combos

Combos are sequences of key presses and releases that trigger commands in mousemaster. Understanding combo syntax is essential for creating effective configurations.

Basic combo syntax

  1. Key press: +key indicates a key press. For example, +leftctrl +e means leftctrl must be pressed, then e must be pressed.

    normal-mode.to.hint-mode=+f

  2. Key release: -key indicates a key release. For example, -leftctrl corresponds to releasing the leftctrl key.

    normal-mode.release.left=-leftbutton

  3. Non-eaten key press: #key is similar to +key but the key press event is not "eaten" by mousemaster - other applications will also receive the event.

    normal-mode.press.left=#leftbutton

Combo duration

  1. Default duration: +leftctrl is equivalent to +leftctrl-0, meaning leftctrl must be pressed for at least 0ms, with no upper limit.

  2. Custom duration: you can specify custom durations:

    • +leftctrl-0-500: Press leftctrl for 0-500ms. mousemaster won't consider the combo successful if you press leftctrl for longer than 500ms.
    • +leftctrl-1000: Press leftctrl for at least 1000ms, with no upper limit

  3. Default duration configuration: change the default combo move duration with:

    default-combo-move-duration-millis=150

Combo preconditions

  1. Pressed key precondition: _{leftctrl} +e has two parts:

    • Precondition (_{leftctrl}): leftctrl must be pressed before the combo sequence
    • Sequence (+e): press e

    The precondition key (leftctrl) will not be eaten by mousemaster.

    normal-mode.press.left=_{leftctrl} +leftbutton

  2. Not-pressed key precondition: ^{leftctrl} +e means leftctrl must not be pressed when the combo sequence is performed.

    normal-mode.to.idle-mode=^{leftctrl} +q

  3. Multiple keys in precondition: you can specify multiple keys in a precondition using the pipe symbol:

    normal-mode.press.left=_{none | leftctrl | leftshift leftalt} +leftbutton

    This means either no modifier key is pressed, or leftctrl is pressed, or leftshift and leftalt are pressed.

  4. Keys from previous combos: keys that are part of a previous combo don't need to be specified again in subsequent combos.

    # This combo eats leftctrl, leftalt, and space when pressed
normal-mode.to.normal-mode=#leftshift | +leftctrl | +leftalt | +space

# This combo requires space to be held, then hint key to be pressed
# It works even if leftctrl, leftalt, or leftshift are also being held
normal-mode.to.hint-mode=_{space} +hint

    In this example:

    • The first combo doesn't change the mode but "eats" leftctrl, leftalt and space.
    • Any key press that is part of a previous combo doesn't need to be specified again in subsequent combos
    • As long as those keys remain pressed, they don't need to be specified in combos that don't care whether they are pressed

    This behavior allows for complex key combinations where modifier keys can be pressed in any order without breaking the combo sequence.

Complex combo examples

# Press e while holding leftctrl
normal-mode.to.hint-mode=_{leftctrl} +e

# Press and release leftshift
normal-mode.move-to-grid-center=+leftshift -leftshift

# Press a, then press b while still holding a, then release a
normal-mode.to.idle-mode=+a +b -b -a

Multi-combo

One command can be assigned multiple combo. As soon as one of the combos is completed, then the command is executed. The combos must be separated by |:

normal-mode.to.idle-mode=+exit | -clickthendisable

Any-order move set

An any-order move set {...} groups moves that can occur in any order. It is expanded into all possible orderings at parse time.

# Release leftctrl and f in any order
normal-mode.to.idle-mode=+leftctrl +f {-f -leftctrl}

This is equivalent to:

normal-mode.to.idle-mode=+leftctrl +f -f -leftctrl | +leftctrl +f -leftctrl -f

Modes

Modes are a fundamental concept in mousemaster. Each mode represents a different state of the application with its own set of key bindings and behaviors.

Mode basics

  • Most properties are defined per-mode (e.g., normal-mode.indicator.enabled=true)
  • The only mode that exists by default is idle-mode (when mousemaster is inactive)
  • You must define all other modes yourself
  • Each mode can have its own key combos, mouse settings, and visual indicators

Mode properties

Properties for a mode are defined using the format:

mode-name.property-category.property-name=value

For example:

normal-mode.indicator.enabled=true
normal-mode.mouse.initial-velocity=1600
hint-mode.hint.type=grid

Property inheritance

Modes can inherit properties from other modes to avoid duplication. For example, if normal-mode has defined indicator settings:

normal-mode.indicator.enabled=true
normal-mode.indicator.idle-color=#FF0000
normal-mode.indicator.move-color=#FF0000
normal-mode.indicator.wheel-color=#FFFF00
normal-mode.indicator.mouse-press-color=#00FF00
normal-mode.indicator.left-mouse-press-color=#00FF00
normal-mode.indicator.middle-mouse-press-color=#00FF00
normal-mode.indicator.right-mouse-press-color=#00FF00

You can make another mode inherit these settings:

slow-mode.indicator=normal-mode.indicator

This applies all indicator properties from normal-mode to slow-mode. You can still override specific properties:

slow-mode.indicator=normal-mode.indicator
slow-mode.indicator.idle-color=#0000FF  # Override just this property

Common mode types

While you can create any modes you need, these are common in many configurations:

  • idle-mode: mousemaster is inactive (default mode when mousemaster starts)
  • normal-mode: Basic mouse control mode
  • grid-mode: For grid-based navigation
  • hint1-mode and hint2-mode: For hint-based navigation

Example mode configuration

# Define how to enter normal-mode from idle-mode
idle-mode.to.normal-mode=_{leftctrl} +e

# Define mouse movement in normal-mode
normal-mode.start-move.up=+i
normal-mode.start-move.down=+k
normal-mode.start-move.left=+j
normal-mode.start-move.right=+l
normal-mode.stop-move.up=-i
normal-mode.stop-move.down=-k
normal-mode.stop-move.left=-j
normal-mode.stop-move.right=-l

# Define mouse speed in normal-mode
normal-mode.mouse.initial-velocity=1600
normal-mode.mouse.max-velocity=2200
normal-mode.mouse.acceleration=1500

# Define how to exit back to idle-mode
normal-mode.to.idle-mode=+q

Switching modes

idle-mode.to.normal-mode=_{leftctrl} +e
normal-mode.to.idle-mode=+q

Combos can be initiated in one mode and continued in another.

normal-mode.press.left=+a
normal-mode.to.click-mode=+a
click-mode.release.left=+a -a

In the above example, pressing a triggers a press of the left mouse button and switches to the mode named click-mode. In click-mode, releasing a triggers a release of the left mouse button. If we add the property:

normal-mode.break-combo-preparation=+a

Then, the release command in click-mode will only be triggered if the user presses a again then releases it. This happens because the +a combo preparation initiated in normal-mode was broken.

Mode history

idle-mode.push-mode-to-history-stack=true
hint2-2-mode.to.previous-mode-from-history-stack=+rightalt -rightalt
  • If push-mode-to-history-stack is true for a mode, the mode will be added to the mode history as soon as the current mode is switched to that mode.
  • The last mode added to the history stack can be referred to in a mode switch (to) command with previous-mode-from-history-stack.

Mode timeout

normal-mode.timeout.duration-millis=5000
normal-mode.timeout.mode=idle-mode
normal-mode.timeout.only-if-idle=true
  • The current mode can be automatically changed to another mode after a certain duration.
  • If only-if-idle is true, then the timeout will be triggered only if the mouse is not being used.

Standalone mode properties

idle-mode.stop-commands-from-previous-mode=true
normal-mode.mode-after-unhandled-key-press=idle-mode
  • If stop-commands-from-previous-mode is true for a mode, and if the previous mode was executing a command such as a mouse button press, then the command will be stopped (the mouse button will be released) as soon as the current mode is switched to that mode.
  • mode-after-unhandled-key-press is for switching to a mode whenever a key that is not part of any combo is pressed.

Mouse properties

normal-mode.mouse.initial-velocity=1600
normal-mode.mouse.max-velocity=2200
normal-mode.mouse.acceleration=1500
normal-mode.mouse.smooth-jump-enabled=true
normal-mode.mouse.smooth-jump-velocity=30000
  • The velocity and acceleration are defined in pixel per second and pixel per square second.
  • Whenever mousemaster sets the position of the mouse, the mouse will be teleported to the target position. Smooth jumping is for avoiding the instantaneous teleportation and move the mouse with a continuous movement instead. The jump speed is controlled with smooth-jump-velocity.

Wheel (scrolling) properties

normal-mode.wheel.initial-velocity=1500
normal-mode.wheel.max-velocity=2000
normal-mode.wheel.acceleration=500

Indicator properties

The indicator is a small polygon displayed next to the cursor. Each indicator property can be customized per mouse state (idle, move, wheel, mouse-press, etc.) and per mode.

Non-idle states inherit from the idle state. The left-mouse-press, middle-mouse-press, and right-mouse-press states inherit from mouse-press, which itself inherits from idle.

Per-state property syntax

Properties use the format <mode>.indicator.<state>.<property>:

normal-mode.indicator.idle.color=#FF0000
normal-mode.indicator.move.color=#FF0000
normal-mode.indicator.wheel.color=#FFFF00
normal-mode.indicator.mouse-press.color=#00FF00
normal-mode.indicator.left-mouse-press.color=#00FF00
normal-mode.indicator.middle-mouse-press.color=#00FF00
normal-mode.indicator.right-mouse-press.color=#00FF00
normal-mode.indicator.unhandled-key-press.color=#0000FF

Polygon shape and appearance

Each state can have its own polygon shape, size, color, and opacity:

normal-mode.indicator.idle.size=12
normal-mode.indicator.idle.edge-count=4
normal-mode.indicator.idle.position=bottom-right
normal-mode.indicator.idle.color=#FF0000
normal-mode.indicator.idle.opacity=1.0
  • size: Size of the indicator in pixels (1-100, default 12)
  • edge-count: Number of polygon edges (3-100, default 4). 3 = triangle, 4 = square, 6 = hexagon, 30+ = circle
  • position: Position relative to the mouse cursor: center, top-left, top-right, bottom-left, bottom-right (default bottom-right). center places the indicator behind the cursor, centered on it (best used with a low opacity so the cursor remains visible).

Outlines

Two optional outlines can be drawn around the polygon: an outer outline and an inner outline.

# Outer outline
normal-mode.indicator.idle.outer-outline-thickness=3
normal-mode.indicator.idle.outer-outline-color=#FFFFFF
normal-mode.indicator.idle.outer-outline-opacity=1
normal-mode.indicator.idle.outer-outline-fill-percent=1.0

# Inner outline
normal-mode.indicator.idle.inner-outline-thickness=1
normal-mode.indicator.idle.inner-outline-color=#CC0000
normal-mode.indicator.idle.inner-outline-opacity=1
normal-mode.indicator.idle.inner-outline-fill-percent=1
  • outer-outline-fill-percent / inner-outline-fill-percent: How much of the outline is filled (0.0-1.0, default 1.0)

outline-* is equivalent to outer-outline-*.

Shadow

An optional drop shadow can be added to the indicator:

normal-mode.indicator.idle.shadow-blur-radius=10
normal-mode.indicator.idle.shadow-color=#000000
normal-mode.indicator.idle.shadow-opacity=0.5
normal-mode.indicator.idle.shadow-horizontal-offset=2
normal-mode.indicator.idle.shadow-vertical-offset=2
  • shadow-blur-radius: Blur radius in pixels (0-1000, default 0). Set to > 0 to enable.
  • shadow-color: Hex color of the shadow
  • shadow-opacity: Opacity (0.0-1.0)
  • shadow-horizontal-offset / shadow-vertical-offset: Shadow offset in pixels (-100 to 100)

Label

An optional text label can be displayed inside the indicator:

normal-mode.indicator.idle.label-enabled=false
normal-mode.indicator.idle.label-text=N
normal-mode.indicator.idle.label-font-name=Arial
normal-mode.indicator.idle.label-font-size=8
normal-mode.indicator.idle.label-font-weight=normal
normal-mode.indicator.idle.label-font-color=#FFFFFF
normal-mode.indicator.idle.label-font-opacity=1.0

# Label font outline
normal-mode.indicator.idle.label-font-outline-thickness=0
normal-mode.indicator.idle.label-font-outline-color=#000000
normal-mode.indicator.idle.label-font-outline-opacity=0.0

# Label font shadow
normal-mode.indicator.idle.label-font-shadow-blur-radius=0
normal-mode.indicator.idle.label-font-shadow-color=#000000
normal-mode.indicator.idle.label-font-shadow-opacity=0.0
normal-mode.indicator.idle.label-font-shadow-horizontal-offset=0
normal-mode.indicator.idle.label-font-shadow-vertical-offset=0
  • label-enabled: Whether to show a text label (default false). Automatically set to true if any label- property is set.
  • label-text: The text to display
  • label-font-name: Font family name (default Arial)
  • label-font-size: Font size in points
  • label-font-weight: Font weight (e.g. normal, bold)
  • label-font-color: Hex color of the label text
  • label-font-opacity: Opacity of the label text (0.0-1.0)

Cursor properties

The cursor can be hidden after a certain duration of inactivity:

hint1-mode.hide-cursor.enabled=true
hint1-mode.hide-cursor.idle-duration-millis=0

Zoom properties

Automatic zooming can be defined with:

hint2-2-mode.zoom.percent=5.0
hint2-2-mode.zoom.center=last-selected-hint
  • zoom.percent must be greater than or equal to 1.0 (100%).
  • zoom.center can either be screen-center, mouse or last-selected-hint.

Mouse move commands

normal-mode.start-move.up=+up
normal-mode.start-move.down=+down
normal-mode.start-move.left=+left
normal-mode.start-move.right=+right
normal-mode.stop-move.up=-up
normal-mode.stop-move.down=-down
normal-mode.stop-move.left=-left
normal-mode.stop-move.right=-right

Mouse button click commands

# Capture leftctrl (i.e. do not exit to idle mode when leftctrl is pressed) to be able to ctrl-click.
normal-mode.press.left=_{none | leftctrl} +leftbutton | _{none | leftctrl} +clickthendisable
normal-mode.press.middle=+middlebutton
normal-mode.press.right=_{none | leftctrl} +rightbutton
normal-mode.release.left=-leftbutton
normal-mode.release.middle=-middlebutton
normal-mode.release.right=-rightbutton
normal-mode.toggle.left=_{none | leftctrl} +toggleleft
normal-mode.toggle.right=_{none | leftctrl} +toggleright

Wheel (scrolling) commands

normal-mode.start-wheel.up=+wheelup
normal-mode.start-wheel.down=+wheeldown
normal-mode.start-wheel.left=+wheelleft
normal-mode.start-wheel.right=+wheelright
normal-mode.stop-wheel.up=-wheelup
normal-mode.stop-wheel.down=-wheeldown
normal-mode.stop-wheel.left=-wheelleft
normal-mode.stop-wheel.right=-wheelright

Hint properties

The hint system in mousemaster displays labels on the screen that you can select with keystrokes to move the mouse to specific locations. This is similar to the hint systems in browser extensions like Vimium, but works system-wide.

Hint types

The type of hint system to use is configured with the following property:

hint-mode.hint.type=grid

The type property determines what hints are displayed:

  • grid: Displays a grid of hints laid out across the screen
  • position-history: Displays discrete absolutely positioned hints at previously saved positions (see Position history)
  • ui: Displays hints at interactive UI elements of the active window

UI hints

UI hints use the Windows UI Automation API to detect interactive elements (buttons, links, text fields, checkboxes, etc.) in the active window and display a hint label on each one. Unlike grid hints, UI hints are positioned based on the UI elements' locations.

ui-hint-mode.hint.type=ui
ui-hint-mode.hint.selection-keys=selectionkey
ui-hint-mode.hint.select=+selectionkey
ui-hint-mode.hint.undo=backspace
ui-hint-mode.hint.mouse-movement=mouse-follows-selected-hint
ui-hint-mode.hint.font-size=10
ui-hint-mode.hint.font-weight=bold
ui-hint-mode.hint.font-color=#FFFFFF
ui-hint-mode.hint.box-color=#204E8A
ui-hint-mode.hint.box-opacity=1
ui-hint-mode.hint.cell-horizontal-padding=8
ui-hint-mode.hint.cell-vertical-padding=0
ui-hint-mode.hint.box-border-radius=3

UI hints use the same appearance properties as other hint types (box-*, font-*, etc.). The cell-horizontal-padding and cell-vertical-padding properties are particularly useful for UI hints since the hint boxes are sized to fit the label text rather than a fixed grid cell.

Hint layout and positioning

The following properties control where hints appear and how they're arranged:

# Hint area configuration
hint-mode.hint.grid-area=active-screen
hint-mode.hint.active-screen-grid-area-center=screen-center

# Grid layout configuration
hint-mode.hint.grid-cell-width=74
hint-mode.hint.grid-cell-height=36
hint-mode.hint.layout-row-count=6
hint-mode.hint.layout-column-count=5

  • grid-area: Determines where hints are displayed:

    • active-screen: Only on the screen with the mouse cursor
    • active-window: Only in the currently active window
    • all-screens: Across all connected screens

  • active-screen-grid-area-center: Sets the center point for the hint grid:

    • screen-center: Center of the screen
    • mouse: Current mouse position
    • last-selected-hint: Position of the last selected hint

  • Grid dimensions: Control the size of each hint cell:

    • grid-cell-width: Width of each hint cell in pixels
    • grid-cell-height: Height of each hint cell in pixels

  • Grid arrangement: Control the number of rows and columns:

    • layout-row-count: Number of rows in the hint grid
    • layout-column-count: Number of columns in the hint grid

You can create different layouts by adjusting the row and column counts:

  • For column layout: layout-row-count=1 and layout-column-count=1000
  • For row layout: layout-row-count=1000 and layout-column-count=1
  • For grid layout (10x3 subgrid): layout-row-count=10 and layout-column-count=3

Screen-specific hint configurations

You can optimize hint configurations for different screen resolutions by appending the resolution to the property name:

# Default hint configuration (applies to all screens unless overridden):
hint1-mode.hint.grid-cell-width=74
hint1-mode.hint.grid-cell-height=41
hint1-mode.hint.layout-row-count=6
hint1-mode.hint.layout-column-count=5

# Override for a 4K screen (3840×2160):
hint1-mode.hint.grid-cell-width.3840x2160=96
hint1-mode.hint.grid-cell-height.3840x2160=54
hint1-mode.hint.layout-row-count.3840x2160=4
hint1-mode.hint.layout-column-count.3840x2160=10

The syntax is property-name.resolution=value, where:

  • property-name is the standard property name (e.g., hint1-mode.hint.grid-cell-width)
  • resolution is the screen resolution in the format widthxheight (e.g., 3840x2160 for 4K)
  • value is the property value specific to that resolution

mousemaster automatically uses the appropriate configuration based on the screen where the hints are displayed. Any hint property can be customized per screen resolution. If a screen-specific property is not defined, mousemaster falls back to the default property value.

Hint selection and behavior

# Selection configuration
key-alias.selectionkey=a b c d e f g h i j k l m n o p q r s t u v w x y z
hint-mode.hint.selection-keys=selectionkey
hint-mode.hint.select=+selectionkey
hint-mode.hint.undo=backspace
hint-mode.to.normal-mode=+selectionkey
hint-mode.hint.mouse-movement=mouse-follows-selected-hint
hint-mode.hint.eat-unused-selection-keys=true
  • selection-keys: Keys that can be pressed to select hints
  • select: Combo that triggers hint selection. For example, if you want to be able to hold leftshift while pressing a hint selection key, then use hint-mode.hint.select=_{none | leftshift} +selectionkey
  • undo: Key combo to undo the last hint selection keystroke
  • to.<mode-name>: Use this syntax to specify which mode to switch to after a hint is selected (e.g., hint-mode.to.normal-mode=+selectionkey)
  • mouse-movement: Controls how the mouse moves when interacting with hints
    • no-movement: Mouse stays in its current position
    • mouse-follows-selected-hint: Mouse moves to the selected hint (default behavior)
    • mouse-follows-hint-grid-center: Mouse moves to the center of the hint grid
    • Use no-movement when the next mode will be another hint grid
  • eat-unused-selection-keys: If false, selection keys not used in the current hint display can be used in combos

Hint appearance

# Box appearance
hint-mode.hint.box-color=#000000
hint-mode.hint.box-opacity=0.4
hint-mode.hint.box-border-thickness=1
hint-mode.hint.box-border-length=1000
hint-mode.hint.box-border-color=#FFFFFF
hint-mode.hint.box-border-opacity=0.4
hint-mode.hint.box-border-radius=0

# Box shadow for UI hints and position history hints only
hint-mode.hint.box-shadow-blur-radius=10
hint-mode.hint.box-shadow-color=#000000
hint-mode.hint.box-shadow-opacity=0
hint-mode.hint.box-shadow-stack-count=1
hint-mode.hint.box-shadow-horizontal-offset=2
hint-mode.hint.box-shadow-vertical-offset=2

# Box size relative to the grid cell (for the hint grid only)
hint-mode.hint.box-width-percent=1.0
hint-mode.hint.box-height-percent=1.0

# Cell padding for UI hints and position history hints only
hint-mode.hint.cell-horizontal-padding=0
hint-mode.hint.cell-vertical-padding=0

# Font appearance
hint-mode.hint.font-name=Consolas
hint-mode.hint.font-size=18
hint-mode.hint.font-spacing-percent=0.7
hint-mode.hint.font-color=#FFFFFF
hint-mode.hint.font-opacity=1.0

# Font effects
hint-mode.hint.font-outline-thickness=0
hint-mode.hint.font-outline-color=#000000
hint-mode.hint.font-outline-opacity=0.5
hint-mode.hint.font-shadow-blur-radius=0
hint-mode.hint.font-shadow-color=#000000
hint-mode.hint.font-shadow-opacity=1.0
hint-mode.hint.font-shadow-horizontal-offset=0
hint-mode.hint.font-shadow-vertical-offset=0

# Selected hint appearance
hint-mode.hint.selected-font-color=#A3A3A3
hint-mode.hint.selected-font-opacity=1.0

# Prefix box (for multi-character hints)
hint-mode.hint.prefix-box-enabled=true
hint-mode.hint.prefix-box-border-thickness=4
hint-mode.hint.prefix-box-border-color=#FFD93D
hint-mode.hint.prefix-box-border-opacity=0.8
hint-mode.hint.prefix-in-background=true

# Animation
hint-mode.hint.transition-animation-enabled=true
hint-mode.hint.transition-animation-duration-millis=100
 
# Background (for UI hints and position history hints only)
hint-mode.hint.background-color=#000000
hint-mode.hint.background-opacity=0

  • Box appearance: controls the background and border of hint boxes

    • box-border-length: Higher values create continuous lines between hint boxes, lower values create dotted separators
    • box-border-radius: Radius for rounded corners (0-1000, default 0).
    • box-shadow-blur-radius: Shadow blur radius (0-1000, default 10).
    • box-shadow-color: Shadow color (hex, default #000000).
    • box-shadow-opacity: Shadow opacity (0-1, default 0 = disabled).
    • box-shadow-stack-count: Number of times the shadow is composited on itself for stronger effect (1-100, default 1).
    • box-shadow-horizontal-offset: Horizontal shadow offset (-100 to 100, default 0).
    • box-shadow-vertical-offset: Vertical shadow offset (-100 to 100, default 0).
    • background-color: Background color behind all hint boxes, mostly useful for UI hints (hex, default #000000).
    • background-opacity: Background opacity, mostly useful for UI hints (0-1, default 0 = no background).

  • Font appearance: controls how hint labels appear

    • font-spacing-percent: Controls character spacing (0=touching, 1=evenly distributed, 0.5=minimal spacing with alignment)

Hint prefix

A hint is made of several keys (letters). For example, hint JKK is made of 3 keys: J, K and K.

  • The hint prefix is JK.

  • The prefix (JK) can be displayed "in the background" with prefix-in-background=true.

  • In a column layout, hints in the same column have the same prefix.

  • In a row layout, hints in the same column have the same prefix.

  • In a grid layout (e.g. 5x6 subgrid), hints in the same subgrid have the same prefix.

Initially:

  • None of the hint keys are selected.
  • The hint key J is focused.

Then, when typing J on the keyboard:

  • J becomes selected.
  • The first K becomes focused.
  • The last K is neither focused nor selected.

Then, when typing K:

  • J and the first K are selected.
  • The second K is focused.

Each hint key can be in one of three states: default, selected, or focused. Font styles are configured per state and per category (non-prefix and prefix).

The font-* properties define the default state. The selected-font-* and focused-font-* properties override specific values for selected and focused keys. Unset selected/focused properties inherit from the default state. The prefix- variants follow the same pattern, with unset prefix properties inheriting from the corresponding non-prefix properties.

Each state supports the following font properties:

  • font-name
  • font-weight
  • font-size
  • font-color
  • font-opacity
  • font-outline-thickness
  • font-outline-color
  • font-outline-opacity
  • font-shadow-blur-radius
  • font-shadow-color
  • font-shadow-opacity
  • font-shadow-stack-count
  • font-shadow-horizontal-offset
  • font-shadow-vertical-offset

There is only one font-spacing-percent (and one prefix-font-spacing-percent), shared across all 3 states.

The property naming pattern is:

  • Default: hint.font-*
  • Selected: hint.selected-font-*
  • Focused: hint.focused-font-*
  • Prefix default: hint.prefix-font-*
  • Prefix selected: hint.prefix-selected-font-*
  • Prefix focused: hint.prefix-focused-font-*

Multi-level hint example

This example shows how to create a two-level hint system, where the first level selects a general area, and the second level provides more precise targeting:

key-alias.selectionkey=a b c d e f g h i j k l m n o p q r s t u v w x y z
# First level hint mode
hint1-mode.hint.type=grid
hint1-mode.hint.grid-area=active-screen
hint1-mode.hint.selection-keys=selectionkey
hint1-mode.to.hint2-mode=+selectionkey
# Don't move mouse after first selection
hint1-mode.hint.mouse-movement=no-movement

# Second level hint mode
hint2-mode.hint.type=grid
hint2-mode.hint.grid-area=active-screen
# Center on last selected hint
hint2-mode.hint.active-screen-grid-area-center=last-selected-hint
# 3x8 grid
hint2-mode.hint.grid-max-row-count=3
hint2-mode.hint.grid-max-column-count=8
# Smaller cells for precision
hint2-mode.hint.grid-cell-width=30
hint2-mode.hint.grid-cell-height=20
hint2-mode.hint.font-size=7
hint2-mode.hint.selection-keys=selectionkey
hint2-mode.to.normal-mode=+selectionkey
# Move mouse after second selection
hint2-mode.hint.mouse-movement=mouse-follows-selected-hint

Grid properties

The grid system in mousemaster divides the screen or window into a configurable grid. It is different from the hint grid system which shows hints (a group of letters) to select.

Basic grid configuration

# Grid area and dimensions
grid-mode.grid.area=active-screen
grid-mode.grid.area-width-percent=1.0
grid-mode.grid.area-height-percent=1.0

# Grid divisions
grid-mode.grid.row-count=2
grid-mode.grid.column-count=2

# Grid appearance
grid-mode.grid.line-visible=true
grid-mode.grid.line-color=#FF0000
grid-mode.grid.line-thickness=1

  • grid-area: Determines where the grid is displayed:

    • active-screen: Covers the screen with the mouse cursor
    • active-window: Covers only the currently active window

  • Grid size: control the grid's coverage with:

    • area-width-percent: Width as a percentage of the area (1.0 = 100%)
    • area-height-percent: Height as a percentage of the area

  • Grid divisions: set the number of cells with:

    • row-count: Number of horizontal divisions
    • column-count: Number of vertical divisions

  • Grid appearance: control the grid's visual style with:

    • line-visible: Whether to show grid lines
    • line-color: Color of grid lines (hex format)
    • line-thickness: Thickness of grid lines in pixels

Grid positioning and insets

# Grid insets (margins)
grid-mode.area-top-inset=15
grid-mode.area-bottom-inset=0
grid-mode.area-left-inset=0
grid-mode.area-right-inset=0

# Grid synchronization with mouse
grid-mode.grid.synchronization=mouse-follows-grid-center

  • Insets: control margins from the edges of the area:

    • Useful for avoiding UI elements like window title bars
    • Example: area-top-inset=15 creates a 15-pixel margin at the top

  • Synchronization: control how the grid and mouse interact:

    • mouse-follows-grid-center: Mouse moves to the center of the grid
    • grid-center-follows-mouse: Grid centers on the mouse position
    • mouse-and-grid-center-unsynchronized: Grid and mouse move independently

Grid usage example

This example shows a complete grid mode configuration:

# Define grid mode
grid-mode.grid.area=active-screen
grid-mode.grid.row-count=2
grid-mode.grid.column-count=2
grid-mode.grid.line-visible=true
grid-mode.grid.line-color=#00FF00
grid-mode.grid.synchronization=mouse-follows-grid-center

# Grid commands
grid-mode.shrink-grid.up=+i
grid-mode.shrink-grid.down=+k
grid-mode.shrink-grid.left=+j
grid-mode.shrink-grid.right=+l
grid-mode.move-to-grid-center=+space

# Exit grid mode
grid-mode.to.normal-mode=+escape

With this configuration:

  1. The screen is divided into a 2×2 grid with green lines
  2. Pressing I/J/K/L shrinks the grid in that direction
  3. Pressing Space moves the mouse to the grid center
  4. Pressing Escape returns to normal mode

Grid commands

Grid commands allow you to interact with the grid system, manipulating both the grid itself and the mouse position relative to the grid.

Types of grid commands

# Move the entire grid
grid-mode.move-grid.up=_{leftshift} +uparrow
grid-mode.move-grid.down=_{leftshift} +downarrow
grid-mode.move-grid.left=_{leftshift} +leftarrow
grid-mode.move-grid.right=_{leftshift} +rightarrow

# Snap mouse to grid cell edges
grid-mode.snap.up=_{leftctrl} +uparrow
grid-mode.snap.down=_{leftctrl} +downarrow
grid-mode.snap.left=_{leftctrl} +leftarrow
grid-mode.snap.right=_{leftctrl} +rightarrow

# Shrink the grid (refine selection)
grid-mode.shrink-grid.up=+uparrow
grid-mode.shrink-grid.down=+downarrow
grid-mode.shrink-grid.left=+leftarrow
grid-mode.shrink-grid.right=+rightarrow

# Center the mouse
grid-mode.move-to-grid-center=+space

  • Move grid commands: shift the entire grid in a direction

    • Useful for repositioning the grid without changing its size
    • Example: move-grid.up moves the entire grid upward

  • Snap commands: move the mouse to the edge of the closest grid cell

    • Useful for precise positioning along grid lines
    • Example: snap.left moves the mouse to the left edge of its current cell

  • Shrink grid commands: divide the grid size by 2 in the specified direction

    • Allows for increasingly precise targeting
    • Example: shrink-grid.up cuts the grid height in half, keeping only the top portion

  • Center command: moves the mouse to the center of the grid

    • Useful for quick centering after grid manipulation
    • Example: move-to-grid-center places the mouse at the grid's center point

Grid navigation workflow

A typical grid navigation workflow:

  1. Enter grid mode (divides screen into a 2×2 grid)
  2. Use shrink commands to narrow down to the target area
  3. Use snap commands for edge-precise positioning or center command for center positioning
  4. Exit grid mode when the mouse is at the desired position

Example grid command configuration

# Enter grid mode from normal mode
normal-mode.to.grid-mode=+g

# Option 1: Grid navigation with WASD keys
grid-mode.shrink-grid.up=+w
grid-mode.shrink-grid.down=+s
grid-mode.shrink-grid.left=+a
grid-mode.shrink-grid.right=+d

# Snap to edges with leftctrl + direction
grid-mode.snap.up=_{leftctrl} +w
grid-mode.snap.down=_{leftctrl} +s
grid-mode.snap.left=_{leftctrl} +a
grid-mode.snap.right=_{leftctrl} +d

# Move grid with leftshift + direction
grid-mode.move-grid.up=_{leftshift} +w
grid-mode.move-grid.down=_{leftshift} +s
grid-mode.move-grid.left=_{leftshift} +a
grid-mode.move-grid.right=_{leftshift} +d

# Center and exit
grid-mode.move-to-grid-center=+space
grid-mode.to.normal-mode=+escape

Alternatively, you could use arrow keys instead of WASD:

# Option 2: Grid navigation with arrow keys
grid-mode.shrink-grid.up=+uparrow
grid-mode.shrink-grid.down=+downarrow
grid-mode.shrink-grid.left=+leftarrow
grid-mode.shrink-grid.right=+rightarrow

# Snap and move commands would be configured similarly
grid-mode.snap.up=_{leftctrl} +uparrow
# etc.

App aliases

App aliases allow you to group applications together and create mode switches based on which application is currently active. This is useful for creating app-specific behaviors or disabling mousemaster for certain applications.

Defining app aliases

app-alias.browserapp=firefox.exe chrome.exe edge.exe

App aliases work similarly to key aliases, but instead of grouping keys, they group application executable names.

Using app aliases in combos

App aliases can be used in combo preconditions to create app-specific behavior:

# Switch to browser-mode when a browser becomes active
idle-mode.to.browser-mode=_{browserapp}
normal-mode.to.browser-mode=_{browserapp}

# Switch back to idle-mode when no browser is active
browser-mode.to.idle-mode=^{browserapp}

In this example:

  • _{browserapp} is a precondition that is satisfied when any of the specified browsers is the active application
  • ^{browserapp} is a precondition that is satisfied when none of the specified browsers is the active application

Position history

Position history allows you to save mouse positions and quickly return to them later. This feature can be used for frequently accessed UI elements or for creating custom navigation patterns.

Basic configuration

# Set the maximum number of positions to remember
max-position-history-size=16

# Define a key to save the current mouse position
normal-mode.position-history.save-position=+f1

# Define a key to clear all saved positions
normal-mode.position-history.clear=+f2
  • max-position-history-size: Maximum number of positions that can be stored (older positions are removed when this limit is reached)
  • save-position: Command to save the current mouse position to history
  • clear: Command to clear all saved positions

Using position history with hints

Position history works in conjunction with a hint mode of type position-history:

# Configure a hint mode to use position history
position-hint-mode.hint.type=position-history
position-hint-mode.hint.selection-keys=a b c d e f g h i j k l m n o p q r s t u v w x y z

# Switch to position hint mode
normal-mode.to.position-hint-mode=+p

When you enter a position history hint mode:

  1. One hint box will be displayed for each saved position
  2. Selecting a hint moves the mouse to that saved position
  3. If no positions are saved, no hints will be displayed

Example workflow

# Save positions in normal mode
normal-mode.position-history.save-position=+f1

# Access saved positions through hint mode
normal-mode.to.position-hint-mode=+p

# Clear all saved positions if needed
normal-mode.position-history.clear=+f2

Typical usage:

  1. Navigate to important locations and press F1 at each one to save them
  2. Press P to enter position hint mode
  3. Select a hint to instantly move to that saved position
  4. Press F2 if you want to clear all saved positions and start over

This feature is especially useful for:

  • Frequently accessed UI elements in complex applications
  • Navigating between multiple work areas
  • Creating custom navigation patterns for repeated tasks

Macros

Macros allow you to define sequences of key presses and releases that are triggered by a combo. Macros can send keys to the operating system (for controlling other applications) or to mousemaster itself (for triggering mousemaster commands).

Basic macro syntax

A macro is defined with:

mode-name.macro.macro-name=combo -> output

macro and remapping mean the same thing and can be used interchangeably (e.g. mode-name.remapping.macro-name=...).

Where:

  • combo is the trigger combo (same syntax as other combos)
  • output is the sequence of key moves to execute

Macro output syntax

The output uses the following syntax:

Meaning Example
+key Press key (sent to OS) +leftctrl
-key Release key (sent to OS) -leftctrl
'text' Type the string character by character, independently of the active keyboard layout (sent to OS) 'hello'
#key Press key (sent to mousemaster) #rightalt
~key Release key (sent to mousemaster) ~rightalt
wait-N Wait N milliseconds before continuing wait-50
key Shorthand for #key ~key rightalt

OS-bound vs internal keys

  • OS-bound keys (+/-): These keys are sent to the operating system. Other applications will receive these key events. Use this for controlling other applications, typing text, or triggering system shortcuts.

  • Internal keys (#/~ or unprefixed): These keys are fed back into mousemaster's combo system. They can trigger other mousemaster commands (including mode switches). Use this for automating mousemaster itself.

Examples

Simple key remapping

Remap V to Ctrl+V in normal mode:

normal-mode.macro.paste=+v -> +leftctrl +v -v -leftctrl

Open an app

Open the Windows notepad when pressing Win+F1:

idle-mode.macro.notepad=_{leftwin} +f1 -> +leftwin +r -r -leftwin wait-100 'notepad' +enter -enter

Automating mousemaster

Select the second screen when pressing F12:

# In the neo-mousekeys-ijkl configuration, pressing c shows the screen selection hints,
# then pressing k will select the second screen (because the hint keys are j k l ; a s d f g).
normal-mode.macro.selectsecondscreen=+f12 -> c k
# Equivalent to:
#normal-mode.macro.selectsecondscreen=+f12 -> #c ~c #k ~k

Console window

mousemaster runs with a console (command line) window by default. You can hide this window for a cleaner experience.

# Hide the console window
hide-console=true

Important considerations

  • When the console window is hidden, you won't see any error messages or logs
  • If the console is hidden, you can stop mousemaster by:
    • Using the Task Manager to end the mousemaster.exe process
    • Using Win+R and typing: taskkill /F /IM mousemaster.exe

Logging

mousemaster provides configurable logging to help with troubleshooting and debugging.

# Logging configuration
logging.level=INFO
logging.redact-keys=true
logging.to-file=true
logging.file-path=mousemaster.log

Logging options

  • logging.level: Controls the verbosity of logging

    • Valid values: ERROR, WARN, INFO, DEBUG, TRACE
    • Higher levels (DEBUG, TRACE) provide more detailed information but may impact performance

  • logging.redact-keys: When set to true, pressed keys will be redacted from logs

    • Useful for privacy
    • Set to false for full key logging when troubleshooting keyboard issues

  • logging.to-file: When set to true, logs are written to a file in addition to the console

    • Useful when hide-console=true or for persistent logging

  • logging.file-path: Path to the log file when logging.to-file=true

    • Default is mousemaster.log in the application directory

Keyboard layout

There is currently a limitation with keyboard layouts (#37): I have not found a reliable way to get the active keyboard layout using the Windows API. The workaround is to explicitly tell mousemaster which keyboard layout to use:

forced-active-keyboard-layout=us-dvorak

The following keyboard layouts are currently exposed and can be referenced in the configuration file:

  • zh-qwerty-pinyin
  • fr-azerty
  • de-qwertz
  • it-qwerty
  • jp-kana
  • pt-qwerty-abnt2
  • ru-jcuken
  • es-qwerty
  • us-qwerty
  • uk-qwerty
  • us-dvorak
  • us-halmak
  • sv-qwerty

If the property configuration-keyboard-layout is defined, then mousemaster will consider that the keys used in the configuration file are for that layout. If the active layout is different from the configuration-keyboard-layout, then the key will be converted to the active layout. For example:

  • configuration-keyboard-layout=us-qwerty
  • A combo uses the key - (minus)
  • The active layout is fr-azerty

In that case, the combo will be triggered when the user presses the à key because - in us-qwerty and à in fr-azerty correspond to the same physical key (same scan code). If the active layout is us-qwerty then the combo will be triggered when the user presses the - key (minus).

If configuration-keyboard-layout is not defined, then its default value is the active layout at the time the configuration file is loaded.