NAME
imwheel - a mouse wheel and button interpreter for X Windows
SYNOPSIS
imwheel [ options ]
DESCRIPTION
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.
COMMAND LINE OPTIONS
Available command line options are as follows:
-4, --flip-buttons
Flips the mouse buttons so that 4 is 5 and 5 is 4, reversing the
Up and Down actions. This would make 4 buttons somewhat useful!
This is the similar to using ’-b "5 4 6 7 8"’; see the -b
option. See also xmodmap(1).
-b, --buttons button-spec
Remap buttons in button-spec to interpreted wheel/button input.
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 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.
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 configuration helper window imediately.
See also CONFIGURATION HELPER
-D, --debug
Show all possible debug info while running. This spits out alot
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, 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
compatability 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.
-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 everytime! Otherwise, this ensures that
the wrong process is not killed.
-q, --quit
Quit imwheel before entering event loop.
Example: ‘imwheel -k -q’ = kill and quit (option order doesn’t
matter)
-X, --display display
Use XServer at a specified display in standard X form. Using
this option is usful for multiple displays.
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. 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.
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 seperated 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.
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.
IMWHEELRC COMMANDS
Commands start with the ‘@’ character. Commands are as follows:
@Exclude
Exclude this window from imwheel grabing mouse events. IMWheel
will ungrab the mouse when these windows are entered and not
regrab the mouse until focus is changed to a non-excluded
window. This allows the ZAxis button events to pass through
normally and mouse grabs to succeed.
@Priority=priority
Using this is allowed in each window/class/resource section.
Higher priority values take precedence over lower ones. Equal
priorities on sections make the imwheelrc file parsed from top
to bottom to find the first match. Thus @Priority can be used
to make the file search for matches out of order, then you dont
have to keep the entries in order if you so please. The
supplied imwheelrc file contains extensive comments and examples
of the @Priority function.
The default priority for any new section is 0. The last
@Priority command in a section overrides all previous priorities
for that section. Thus each section has only one priority
setting in the end. Priorities are kept as an int, thus range
from INT_MAX to INT_MIN. (See /usr/include/limits.h for these
values on your system.)
CONFIGURATION HELPER
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.
KEYSYMS
The program expects combinations of keysyms to be used by using pipe(|)
characters to combine them together.
Example:
Alt_R|Shift_R
Means 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!
WHEEL AS MIDDLE BUTTON IN X
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!
LEFTY BUTTON MAPPING IN X WINDOWS
For those lefties out there, this command may help you get the buttons
set up correctly in XWindows 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 Window
mouse is over. This only occurs with Click-to-Focus type focus
managment 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. Overidden 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.