IMWheel(1)

📦
version 1.0.0pre12 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 imwheel — the mouse wheel & button interpreter for X Windows 💖

okay bestie, listen. this is imwheel from the General Commands Manual, section 1 (yes, the executable-commands one, we're in the big leagues). it's giving "your mouse wheel finally does what you actually want." buckle up. 🎀

✨ NAME ✨

imwheel — a mouse wheel and button interpreter for X Windows. literally what it says on the tin, no cap. 🖱️

🌸 SYNOPSIS 🌸

imwheel [ options ]

🦋 DESCRIPTION 🦋

IMWheel is a universal mouse wheel and button translator for the X Windows System. it's the main character of wheel remapping, fr fr.

it takes the input from X Windows and translates your mouse wheel + mouse button actions into keyboard events, using the XTest extension to X. that's the whole vibe. ✨

pro tip from the manpage itself: use xdpyinfo if you wanna know which extensions your X server actually supports. vibe check your server first, bestie.

💅 COMMAND LINE OPTIONS 💅

the available command line options are, in order, as follows — and yes, we're doing all of them, nobody's skipping anything here:

  • -4, --flip-buttons — flips the mouse buttons so that 4 is 5 and 5 is 4, which reverses the Up and Down actions. this would make 4 buttons somewhat useful! 👀 it's the same as using -b "5 4 6 7 8"; peep the -b option. also see xmodmap(1).
  • -b, --buttons button-spec — remaps buttons in button-spec to interpreted wheel/button input. it also limits the button grab to the specified buttons. the button-spec must be surrounded by quotes. each button number must be separated by a space. the button-spec is decoded in the following order for wheel input:
    • index 1 → interpreted as Wheel Up, button number 4, name in imwheelrc Up
    • index 2 → interpreted as Wheel Down, button number 5, name in imwheelrc Down
    • index 3 → interpreted as Wheel Left, button number 6, name in imwheelrc Left
    • index 4 → interpreted as Wheel Right, button number 7, name in imwheelrc Right
    • index 5 → interpreted as Thumb Button 1, button number 8, name in imwheelrc Thumb1
    • index 6 → interpreted as Thumb Button 2, button number 9, name in imwheelrc Thumb2
    • index 7 → interpreted as Extra Button 1, button number 10, name in imwheelrc ExtBt7
    • index 8 → interpreted as Extra Button 2, button number 11, name in imwheelrc ExtBt8
    • etc.

a button-spec of "4 5" will limit the grabbed buttons to only wheel up and down.

a button-spec of "0" turns off any defined mapping, thus allowing for skips in the button-spec for something that doesn't exist on your mouse.

a button-spec of "4 5 0 0 8" may be for normal wheel up/down and a thumb button 1, but no horizontal wheel axis.

the default button-spec is "4 5 6 7 8 9", but you may want or need to customize this yourself. if you want to ignore the mouse wheel on regular mice, make sure to start the button-spec with "0 0 0 0 ...", thereby skipping over the vertical and horizontal axes of the wheel (whether or not the horizontal axis exists or is used).

see also xmodmap(1). 🫶

  • -c, --config — popup to the configuration helper window immediately. see also CONFIGURATION HELPER.
  • -D, --debug — show all possible debug info while running. this spits out a lot 😭 and I also suggest using the -d option to prevent imwheel from detaching from the controlling terminal.
  • -d, --detach — actually this does the opposite of its name, iconic behaviour honestly 💀 it prevents detachment from the controlling terminal (no daemon). Control-C stops, etc...
  • -f, --focus — forces the X event subwindow to be used instead of the original hack that would replace the subwindow in the X event with a probed focus query (XGetInputFocus). this should fix some compatibility problems with some window managers, such as window maker, and perhaps enlightenment. if nothing seems to be working right, try toggling this on or off... 🔄
  • -g, --focus-events — disable the use of focus events for button grabs. if your @Excluded windows are not regrabbing the mouse buttons when exited, try toggling this on or off...
  • -h, --help — short help on options plus version/author info. the classic. 👑
  • -k, --kill — attempts to kill old imwheel. process IDs are tested using /proc/${pid}/status Name: field ?= imwheel. if /proc is not mounted then this fails every time! 😵 otherwise, this ensures that the wrong process is not killed.
  • -q, --quit — quit imwheel before entering the event loop. example: imwheel -k -q = kill and quit (option order doesn't matter). chef's kiss, one line, two jobs. 💅
  • -X, --display display — use XServer at a specified display in standard X form. using this option is usful for multiple displays. (that typo is theirs, I'm keeping it, no cap — it's canon now. 😌)

🌈 X WINDOWS 🌈

use multiple imwheels by either setting the DISPLAY environment variable before running each imwheel, or use the -X or --display options to specify a different display for each imwheel.

not recommended but allowed: running multiple imwheels on the same display. it's permitted, but it may cause strange things to happen while using the wheel or buttons. 😭 proceed at your own risk bestie.

edit your xorg.conf, and ensure that in the "InputDevice" section, your mouse Protocol is set to "ExplorerPS/2" for a modern PS/2 or USB mouse, or if not then "IMPS/2". for serial mice set it to "IntelliMouse" or "Auto". this is for IntelliMouse compatible mice; other protocols may be required for other mice.

⭐ NOTE ⭐

the @Exclude command must be used for clients that either use the ZAxis for themselves and have no keyboard translations to cause the same desired effect. the @Exclude command must also be added for any client requiring mouse and/or mouse button grabs and that don't specify specific buttons to grab. these clients fail when they try to grab the mouse because the buttons 4 and 5 are already grabbed by imwheel. XV is an example of a client that requires these types of grabs to succeed. KDE clients use the ZAxis for their own purposes. the supplied imwheelrc includes an exclusion for XV already. see the IMWheelRC section for more information.

🎀 IMWHEELRC 🎀

IMWheel uses, optionally, two configuration files:

  • one, /etc/X11/imwheel/imwheelrc, is usable by everybody. 🌍
  • the other is $HOME/.imwheelrc, used only by one user. 🙋

one is supplied and should have been installed automatically in /etc/X11/imwheel. all whitespace is ignored in the files except for within the window names' double quotes.

the configuration file consists of window names and event translations and/or imwheel commands that begin with an @ (at) symbol. each window name starts a section that is its configuration. the window names are priortized as first come first served, so more generic matches should always occur later in the configuration file. 🫶

comments are started with a pound (#) and extend to the end of the line.

🌸 IMWHEELRC WINDOW SECTION HEADERS 🌸

window name section headers are actually one of four things:

  • Window Title
  • Window Class Name
  • Window Resource Name
  • (null) which matches "\(null\)" in the imwheelrc

most of these are probeable using fvwm2's FvwmIdent module or the configurator (see the CONFIGURATION HELPER section). other window managers may have their own method of identifying windows' attributes.

each window name is matched as a regex string. thus any window is matched using the regex pattern ".*" as a window name. this pattern should be the last section in your configuration file, or it will override the other window configurations in the file for matched wheel/button actions. ⚠️

there is one special header noted as "(null)" which matches windows that have a null string in the three attributes. this makes it possible to assign actions to even Quake3, which has no info for its window. just make sure that you realize that the keys used should not be keys that may conflict with other key actions in the game or application you are aiming to make work! the included imwheelrc file has a "(null)" section included to demonstrate, and it should work with Quake3. 🎮

each window/class/resource name must be enclosed in double quotes (") on a line by itself.

inside each window section is any number of translation definitions or commands. each translation definition or command must be on a line by itself. the window section doesn't have to be terminated, as it is terminated by either starting another window section or the end of the configuration file.

💜 IMWHEELRC TRANSLATION DEFINITIONS 💜

mouse wheel/button translations each take up a line after a window section has been started. each argument is separated by commas (,); whitespace is ignored. KeySyms are used to specify the keyboard input and outputs. pipes (|) are used to join multiple keys into one input/output. the format is as follows...

👑 REQUIRED 👑

the following arguments a required to make a minimum translation definition.

  • Key Modifiers Input — X KeySyms joined by pipes that indicate the required keys pressed when the mouse action is made in order for this translation to be used. Alt, Meta, Control, and Shift keys are typical modifiers, but are stated slightly different than just Shift but rather Shift_L or Shift_R, differentiating between left and right shift keys. see the KeySyms section for more.

None is a special KeySym used by imwheel, it is used to indicate no modifiers. a blank entry is also acceptable in this case, but less descriptive of what is going on! if None is used then there can be no modifiers in use during the wheel action. if the field is blank then any modifier will match, so put these last in their window section.

  • Mouse Action Input — this is the input from the mouse wheel or button. it is one of the following and only one:
    • Up
    • Down
    • Left
    • Right
    • Thumb

these are self explanatory. if you have trouble use the configurator! 🧚

  • Key Action Output — out KeySyms are placed here. see KeySyms section for more on all available KeySyms. join KeySyms using pipes. output keys are pressed in order and released, in reverse order, only after all have been pressed, likely making them all combined as in Control_L|C which would be a ^C (control-c) keypress.

✨ OPTIONAL ✨

the following options are optional, but to use one you must fill in all the preceding arguments. no skipping ahead bestie, it's a line, not a buffet. 🍓

  • Output Repetitions — how many times should the Output KeySyms be pressed in a row.

Default is 1.

  • Delay Before KeyUp Event — how long in microseconds until we release all the Output KeySyms in one Output Repetition.

Default is 0.

  • Delay Before Next KeyPress Event — how long in microseconds until we press the next the Output KeySyms. Ths delay occurs after the Output KeySyms are released.

Default is 0.

...and that's only part one bestie, there's more coming, don't go anywhere 💖

👑 IMWHEELRC COMMANDS 👑

Okay so commands? They all start with the @ character. That's the whole vibe. Here's every single one, no skips:

  • @Exclude — bestie, this yeets the window out of imwheel's mouse-grabbing zone. When you enter these windows, IMWheel ungrabs the mouse, and it will not regrab until focus moves to a window that isn't excluded. What does that get you? The ZAxis button events pass through like normal people, and mouse grabs actually succeed. 🦋
  • @Priority=priority — you can use this in every window/class/resource section. Higher priority values win over lower ones. If two sections have equal priorities, the imwheelrc file gets read top to bottom and the first match wins. So basically @Priority lets you make the file search for matches out of order, which means you don't have to keep your entries in order if you don't wanna. The imwheelrc file that ships with it has extensive comments and examples of the @Priority function. Default priority for any new section is 0. The last @Priority command in a section overrides all the previous priorities for that section, so each section ends up with only one priority setting. Priorities are kept as an int, so the range goes from INT_MAX to INT_MIN. (Peep /usr/include/limits.h for those values on your system. 💜)

🧚 CONFIGURATION HELPER 🧚

So there's a semi-hidden configuration helper in IMWheel, and you summon it by rolling up and down a few times in the root window of the X server. Iconic, honestly. Inside this window you can find out possible window names to use in your imwheelrc file. Press on the mini-screen capture to grab another window — including the root window, which is the whole screen. 🌈

Mouse wheel and button actions can be grabbed along with active modifier keys on the keyboard. The mouse wheel/button action is displayed, and the X KeySyms are displayed beneath it. All of that info can be entered straight into an imwheelrc however you want. ✨

You can restart IMWheel to read in a changed imwheelrc file, or you can cancel the configurator, which makes imwheel resume oprations without reading the configuration file. To restart, imwheel execs itself exactly as it was called by the user in the first place, but it adds the -R option to tell itself that this is a restarted imwheel. The -R is not for use by the user, because it bypasses some configuration of imwheel. 🙈

💅 KEYSYMS 💅

The program expects combinations of keysyms, and you combine them by using pipe (|) characters.

Example:

Alt_R|Shift_R

That means right alt and right shift together. Not either one or the other! And not one after the other — they're both pressed at the same time, essentially. 💖

Common Modifier Keysym names used in X:

Shift_L     Shift_R
Control_L   Control_R
Alt_L       Alt_R

These are probably not currently assigned any keys, unless you xmodmap them in:

Meta_L      Meta_R      (Actually, Sun keyboards have this...)
Super_L     Super_R
Hyper_L     Hyper_R

And here's some that you may use, and they are somewhere on your keyboard. Here's where they were on my keyboard — again, this is not universal. Use the xev program to test your own keys on your own keyboard!

Caps_Lock   = The Caps Lock key!
              (This still turns on and off caps lock!)
Num_Lock    = The Num Lock key!
              (This is not good to use...
               for the same reasons as Caps_Lock)
Multi_key   = The Scroll Lock key!
              (Go figure!)
Mode_switch = Right Alt...for me anyways.
              (This mean I cannot use Alt_R)

The windows keys may not be assigned any KeySyms, but they will have numbers. xmodmap can be used to assign them to a real KeySym. 🔥

To find keysym names for any keys available, see the /usr/include/X11/keysymdef.h file, and for any define in that file, remove the XK_ for the usable KeySym name in the configuration file. The path to this file may differ for you.

Remember, there's always the configurator. And xev will also help here too! ⭐

🖱️ WHEEL AS MIDDLE BUTTON IN X 🖱️

Configure the XF86Config without "Emulate3Buttons" and increase "Buttons" if it's 2 in the Ponter or InputDevice section. Then the wheel acts as a real middle button, and the outer two buttons act as separate buttons (1 and 3) — even when pressed together. 💅

Of course, if your wheel keeps clicking middle button while you're trying to use the wheel, you may want to activate the Emulate3Buttons option to disable the wheel button! And don't forget to reduce the Buttons argument to 2! 😭

🌸 LEFTY BUTTON MAPPING IN X WINDOWS 🌸

For all you lefties out there, this command may help you get the buttons set up correctly in X for both left-handed and imwheel use.

xmodmap -e "pointer = 3 2 1 4 5"
  or
xmodmap -e "pointer = 3 2 1 4 5 6 7"
  etc...
xmodmap -e "pointer = 3 2 1 4 5 6 7 8 9"

NOTE: most of these are NOT going to work, because of all the limits in X.

Add more numbers to the end of this line if you have more buttons! 🎀

💀 BUGS 💀

Of course... but most of the time it's just that you haven't read everything I've written here and in the files of the distribution itself. Even then, you may be giving up too easily. Keep trying, it's not that hard. I am always working to reduce strange behavior. This is still a beta, as indicated by the leading 0 in the version number. 🫶

Real Bugs

  • imwheel doesn't get along with itself on the same X display. This will always be your fault :-/
  • Stick mice are still a pain in the butt to use. — This is the manufacturer's fault. Or X Windows' fault, for not having a method to easily use such devices in all applications.
  • Keyboard focus isn't changed automatically to input keys into the Window the mouse is over. This only occurs with Click-to-Focus type focus management in window managers. I use sloppy focus in fvwm2, which always works for me. — Whose fault is this? (Switch focus modes and/or window managers, or try the -f option on imwheel)
  • Configuration file is not validated for correctness nicely... although it does get preparsed before the main program starts, thus stopping you before you run with an invalid configuration file. I just have never made a bad configuration file, so I guess I'll have to try and do that to see what happens. Just don't make any mistakes and you'll be fine. 😌

🌈 HOMEPAGE 🌈

http://imwheel.sourceforge.net

✨ AUTHOR ✨

Jonathan Atkins <jcatki@jcatki.no-ip.org>

🍓 FILES 🍓

  • $HOME/.imwheelrc The user's configuration file.
  • /etc/X11/imwheel/imwheelrc The global location for the configuration file. Overridden by the user's configuration file.

🦋 SEE ALSO 🦋

  • xdpyinfo(1x) X Display information, including extensions.
  • FvwmIdent(1x) FVWM2's Identify module, for probing windows.
  • regex(7) POSIX 1003.2 Regular Expressions.
  • xmodmap(1x) Utility for modifying keymap & button mappings in X.
  • xev(1x) Print contents of X events.
  • /usr/include/X11/keysymdef.h X11 KeySym definitions.
  • /usr/include/limits.h INT_MIN and INT_MAX definitions.

And that's the whole page, bestie — this one came from the 3rd Berkeley Distribution, dated January 28 2008, and it's IMWheel(1) through and through. Go forth and scroll responsibly, you absolute icon. 👑💖

📦 where this page comes from