| IMWheel(1) | General Commands Manual | IMWheel(1) |
imwheel - a mouse wheel and button interpreter for X Windows
imwheel [ options ]
IMWheel is a universal mouse wheel and button translator for the X Windows System. Utilizing the input from X Windows, imwheel translates mouse wheel and mouse button actions into keyboard events using the XTest extension to X. Use xdpyinfo for information on the supported extensions in your X server.
Available command line options are as follows:
Index Interpreted As Button Number Name in imwheelrc
1 Wheel Up 4 Up
2 Wheel Down 5 Down
3 Wheel Left 6 Left
4 Wheel Right 7 Right
5 Thumb Button 1 8 Thumb1
6 Thumb Button 2 9 Thumb2
7 Extra Button 1 10 ExtBt7
8 Extra Button 2 11 ExtBt8
etc.
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. Running multiple imwheels on the same display is not recommended, but is allowed, and may cause strange things to happen while using the wheel or buttons.
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.
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.
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.
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.
`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.
Up Down Left Right Thumb
These are self explanatory. If you have trouble use the configurator!
OPTIONAL
The following options are optional, but to use one you must fill in all the
preceding arguments.
Default is 1.
Default is 0.
Default is 0.
Commands start with the `@' character. Commands are as follows:
IMWheel contains a semi-hidden configuration helper which can be brought up by rolling up and down a few times in the root window of the X server. 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 (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 this information can be directly entered into an imwheelrc as desired.
IMWheel can be restarted to read in a changed imwheelrc file or the configurator can be canceled causing imwheel to resume oprations without reading the configuration file. To restart, imwheel execs itself as called by the user in the first place but adding the -R option to indicate to itself that this is a restarted imwheel. The -R is not for use by the user, as it bypasses some configuration of imwheel.
The program expects combinations of keysyms to be used by using pipe(|) characters to combine them together.
Example:
Alt_R|Shift_RMeans right alt and right shift together, not just either one or the other! And not one after the other, they are 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 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!
Configure the XF86Config without "Emulate3Buttons" and increase "Buttons" if it is 2 in the Ponter or InputDevice section. The wheel will act as a real middle button and the outer two buttons will 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!
For those 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!
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 Window 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.
http://imwheel.sourceforge.net
Jonathan Atkins <jcatki@jcatki.no-ip.org>
$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.
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.
| January 28 2008 | 3rd Berkeley Distribution |