Man Linux: Main Page and Category List


       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:

       -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

              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

       -X, --display display
              Use XServer at a specified display in standard  X  form.   Using
              this option is usful for multiple displays.


       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.

       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

       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


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

       The following arguments  a  required  to  make  a  minimum  translation

       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

              ‘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:


              These  are  self  explanatory.   If  you  have  trouble  use the

       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.

       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

              Default is 0.


       Commands start with the ‘@’ character.  Commands are as follows:

              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.

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


       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


       The program expects combinations of keysyms to be used by using pipe(|)
       characters to combine them together.


              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


       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 XWindows for both left handed and imwheel use.

              xmodmap -e "pointer = 3 2 1 4 5"
              xmodmap -e "pointer = 3 2 1 4 5 6 7"
              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
       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.



       Jonathan Atkins <>


            The user’s configuration file.

            The global location for the configuration
            file. Overidden by the user’s configuration file.


           X Display information, including extensions.
           FVWM2’s Identify module, for probing windows.
           POSIX 1003.2 Regular Expressions.
           Utility for modifying keymap & button mappings in X.
           Print contents of X events.
           X11 KeySym definitions.
           INT_MIN and INT_MAX definitions.