IMWheel(1)                           General Commands Manual                           IMWheel(1)

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. Utiliz‐
       ing 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 sup‐
       ported 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  termi‐
              nal.

       -d, --detach
              Actually  this  does the opposite of its name, it prevents detachment from the con‐
              trolling 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 win‐
              dow  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!  Other‐
              wise, 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  sup‐
       plied 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 com‐
       mands  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 identi‐
       fying 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 configura‐
       tion  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 Rep‐
              etition.

              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 val‐
              ues 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 sys‐
              tem.)

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 key‐
       board.  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 com‐
       bine 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 configura‐
       tion 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.

3rd Berkeley Distribution                January 28 2008                               IMWheel(1)

imwheel 1.0.0pre12 by -=<Long Island Man>=- <jcatki@jcatki.no-ip.org>
imwheel [--auto-repeat|-a delay-rate] [--buttons|-b grab-buttons] [--config|-c] [--debug|-D] [--detach|-d] [--display|-X display-name] [--flip-buttons|-4] [--focus|-f] [--focus-events|-g] [--help|-h] [--key-defaults|-K] [--kill|-k] [--pid|-p] [--root-window|-r] [--quit|-q] [--version|-v]
--auto-repeat|-a  delay-rate   auto repeat until button release (default=250)
--buttons|-b      grab-buttons
                       Specify button remappings (default="4 5 6 7 8 9", 0=skip)
--config|-c                    Open configuration helper window imediately
--debug|-D                     Spit out all debugging info (it's a lot!)
--detach|-d                    IMWHeel process doesn't detach from terminal
--display|-X      display-name Sets X display to use
--flip-buttons|-4              Swaps buttons 4 and 5 events (same as -b "5 4")
--focus|-f                     Use event subwindow instead of XGetInputFocus
--focus-events|-g              Disable the use of Focus Events for button grabs
--help|-h                      For this help!  Now you know
--key-defaults|-K              Use the old key style default actions
--kill|-k                      Kills the running imwheel process
--pid|-p                       IMWheel doesn't use or check any pid files
--root-window|-r               Allow wheeling in the root window (no cfg dialog)
--quit|-q                      Don't start imwheel process, after args
--version|-v                   Show version info and exit