Upgrade to v0.15
April 2, 2026 ยท View on GitHub
Change 1 - Interrupting multipurpose key
Multipurpose keys were previously interrupted by mouse move events by defualt. Which is quite unexcepted. That is changed, so one has to opt-in to this. Mouse scroll still interrupts multipurpose keys by default.
Change 2 - Relative mouse events
This version changes the behavior of 'relative mouse events'. These events can be remapped even though they are not really keys. The events are primarily mouse wheel (scroll):
XRightScroll, XLeftScroll, XUpScroll, XDownScroll
And mouse move:
XRightCursor, XLeftCursor, XDownCursor, XUpCursor
These events could previously appear in both modmap and keymap but they
made little sense in modmap, so that has been removed. This makes maintaining
and adding new features easier.
Examples of migrating from modmap to keymap
Turn mouse events into keys
Scroll up is replaced with KEY_A, and mouse right is replaced with KEY_B
modmap:
- remap:
XUpScroll: KEY_A
# Mouse move right
XRightCursor: KEY_B
To upgrade just replace modmap with keymap.
Launch command when scrolling
modmap:
- remap:
XDownScroll:
press: { launch: [bash, -c, "echo hello >> /home/USER_NAME/test_file"] }
skip_key_event: false
There is no replacement for this. Because keymap can't emit XDownScroll and there isn't
something like skip_key_event in keymap. Had the config used skip_key_event: true however it works in keymap.
Mapped events from modmap is used in keymap
modmap:
- remap:
XUpScroll: C
keymap:
- remap:
C: D
Can be replaced with:
keymap:
- remap:
XUpScroll: D
Multipurpose key interrupted by mouse move
modmap:
- remap:
Capslock:
alone: KEY_A
held: KEY_B
# This will also make mouse move events interrupt
interruptable: true
Multipurpose key
This use case has little purpose, because the release is fired immediately. so the alone definition is always emitted.
modmap:
- remap:
XUpScroll:
alone: KEY_A
held: KEY_B