Ubuntu Manpage: imwheel - a mouse wheel and button interpreter for X Windows

Provided by: imwheel_1.0.0pre12-15build2_amd64

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 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, 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.

-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 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 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.

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 grabbing 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 don't 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 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 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.

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.