IMWheel - ArchWiki

Jump to content

# IMWheel

From ArchWiki

Related articles

- Xorg
- Mouse acceleration

IMWheel is a tool for tweaking mouse wheel behavior, on a per-program basis. It can map mouse wheel input to keyboard input, increase mouse wheel speed, and has support for modifier keys.

## Installation

Install the imwheel package.

## Configuration

See imwheel(1).

IMWheel matches window class strings with regular expressions for deciding which windows to apply tweaks to. To find the specific class strings that are being matched, kill all other IMWheel processes, then run this command:

    $ imwheel -d --debug --kill

This will run IMWheel in the foreground in debug mode. As you use your mouse and keyboard, you will be able to see the window property values that IMWheel is attempting to match.

### Edit your configuration file

Create or edit `~/.imwheelrc`. In this configuration file lines can be added for each program you want to tweak mouse wheel behavior for. The following example will increase the mouse wheel speed for the document viewer zathura:

    # Speed up scrolling for the document viewer
    "^org\.pwmt\.zathura$"
        None, Up, Button4, 4
        None, Down, Button5, 4

Keep in mind that certain values, like the Window title, are Unicode. This can lead to difficulties when trying to write regular expressions that will match them. For example, an em dash (—) looks very much like a standard dash (-), but in regex is considered three "characters", not one.

`Up` and `Down` may be used in the place of `Button4` and `Button5` respectively for the mouse wheel.

Matching all programs (using ".*") can cause unwanted behaviour in some programs; since IMWheel emulates multiple scroll actions for each one the user makes, programs that have actions bound to the mouse wheel will perform those actions more times than expected.

For example, terminal emulators in which scrolling selects commands from the history will jump multiple items per scroll.

IMWheel catches modifier keys for monitored mouse buttons, for passing them further you need to explicitly configure it to do so. In the example below, the left `Ctrl` and mouse wheel combinations are passed to Chromium for zooming in/out without multiplying:

    # Speed up scrolling for chromium and pass unchanged for zoom
    "^chromium$"
        None, Up, Button4, 4
        None, Down, Button5, 4
        Shift_L,   Up,   Shift_L|Button4, 4
        Shift_L,   Down, Shift_L|Button5, 4
        Control_L, Up,   Control_L|Button4
        Control_L, Down, Control_L|Button5

To match a certain program in the terminal, use Bash to set the program name in the window title before the program is started. See Bash/Prompt customization#Customizing the terminal window title. You may need to reconfigure your terminal emulator to allow the window title to be set by programs running in the shell. Some terminals, like Konsole and GNOME Terminal, do this automatically.

### Run IMWheel

Run IMWheel simply like so:

    $ imwheel

The program will print its PID and run in the background.

### Run IMWheel on startup using a service

To avoid starting IMWheel manually, you can run it as part of your systemd startup.

Example:

    ~/.config/systemd/user/imwheel.service

    [Unit]
    Description=IMWheel
    Wants=display-manager.service
    After=display-manager.service

    [Service]
    Type=simple
    Environment=XAUTHORITY=%h/.Xauthority
    ExecStart=/usr/bin/imwheel -d
    ExecStop=/usr/bin/pkill imwheel
    RemainAfterExit=yes

    [Install]
    WantedBy=graphical-session.target

After creating the service above, reload the systemd manager configuration of the calling user and start/enable the `imwheel.service` user unit. Verify that the user service is running by checking its unit status or by checking the journal:

    $ journalctl --user --unit imwheel.service

### Run IMWheel on startup using a shell script

Alternatively, you can create a `startup.sh` script in `/etc/profile.d/`:

    #!/bin/sh

    imwheel

And then, on restart, it will automatically read and run the file. Always test your script manually before putting it in /etc/profile.d

## Troubleshooting

### Back/forward buttons not working

You may need to restrict IMWheel so only the scroll wheel is affected to prevent it from breaking other mouse input like the back/forward buttons. You can do this with the -b option.

    $ imwheel -b 45

See also a related question on Ask Ubuntu.

### Scroll speed is not affected when I hover over the target window

In order for IMWheel to affect the scroll speed of a window, it must be focused. Scroll speed of an unfocused window will remain unchanged.

Category:

- X server