Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
IMWheel(1)              FreeBSD General Commands Manual             IMWheel(1)

       imwheel - a mouse wheel and stick interpreter for X Windows

       imwheel [ options ]

       IMWheel is a universal mouse wheel and mouse stick translator for the X
       Windows System.  Using either a special version of gpm and it's
       /dev/gpmwheel FIFO, or the support for a ZAxis on the mouse built into
       some servers, such as XFree86.  Utilizing the input from gpm or X
       Windows, imwheel translates mouse wheel and mouse stick 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 54678", see the -b option.  See
              also xmodmap(1).

       -b, --buttons button-spec
              Remap buttons in button-spec to interpreted wheel/thumb input.
              Also limits the button grab to the specified buttons when using
              the ZAxis method.  (see "X WINDOWS ZAXIS METHOD" below) the
              button-spec may specify any of up to five buttons.  the button-
              spec is decoded in the following order for wheel input:

                     Index   Interpreted As    Button Number
                     1       Wheel Up          4
                     2       Wheel Down        5
                     3       Wheel Left        6
                     4       Wheel Right       7
                     5       Thumb Button 1    8
                     6       Thumb Button 2    9

              A button-spec of "45" will limit the grabbed buttons for only
              wheel up and down.
              A button-spec of "67" may be useful to use actual buttons 6 and
              7 as wheel up and down, and limit the grab to only those two
              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 "45006" may be for normal wheel up/down and a
              thumb button 1, but no horizontal wheel axis.
              The default button-spec is "456789".
              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 it's 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 (useful only for --wheel-fifo
              method.)  Pidfile must be created for this to work (no -p or
              --pid option on the previous imwheel invocation).  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.

       -p, --pid
              Don't write a pid file for gpmwheel FIFO method.  This is the
              only method that uses the pid file.  XGrab doesn't need it, so
              it just issues a warning about starting multiple imwheels on the
              same display.  Some people really prefer this, especially when
              they are not using a SUID root imwheel executable.

       -q, --quit
              Quit imwheel before entering event loop.  Usful in killing an
              imwheel running in gpmwheel FIFO mode after exiting XWindows, if
              you're using pid files that is.
              Example: `imwheel -k -q' = kill and quit (option order doesn't

       -s, --sensitivity sum-min
              (Stick mice, Wheel FIFO method only)
              like -t only this sets a minimum total amount of movment of the
              stick or marble, before any action is taken.  This works good
              with the Marble type devices.  This should be a multiple of the
              threshhold as given by the -t option.  The default is 0, meaning
              that there is no sensitivity testing, all input spawns an event.
              See the -t option also.  (see "STICK SENSITIVITY SETTINGS"

       -t, --threshhold minimum-pressure
              Used with gpm only and then only with recognized stick mice.
              stick mice send a pressure value ranging from 0(no pressure) to
              7(hard push).  This sets the minimum required pressure for input
              to be registered.  Setting it to zero will cause realtime
              sticking, which is usually too much action for X to keep up.
              (max rate i saw was 100 events a second!).  Once input is
              registered, it is summed up per axis, and then it must equal or
              exceed the sensitivity setting to pass as an input.  See the -s
              option also, for sensitivity.
              The default is 2, to avoid slight presses on the 90-degree
              direction of the intended while still getting to the intended
              direction.  Setting this to 7 is insane, because it requires the
              user to push as hard as possible everytime they want something
              to happen!  However it may not be so insane for people using
              trackballs for input, as they may spin much faster per sample...
              (see "STICK SENSITIVITY SETTINGS" below)

       -W, --wheel-fifo fifo
              Use the gpm/jamd wheel fifo instead of XGrabMouse.  See GPM/JAMD
              WHEEL FIFO METHOD section.  This method allows only one X
              display to be used.  This is required for the gpm method to
              work.  This method only works with the imwheel version of gpm
              and with jamd.  To find out if you are running the imwheel
              version of gpm use the following command and look for
              "(imwheel)" in the title:

                     gpm -v

              fifo names the named pipe (FIFO) created by gpm.  It defaults to
              "/dev/gpmwheel" (for --wheel-fifo only).  The FIFO must exist
              before running imwheel in this mode.  using jamd requires you to
              name the correct fifo because it doesn't use /dev/gpmwheel, but
              rather one of the /dev/jam_imwheel:0.0 named fifos created by
              jamd's imwheel module.
              @Exclude commands in the rc file are unused in this mode.

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

       -x, --transpose

              This swaps the X and Y axis of movement for stick input from a

       This method is the only method that works with multiple X displays,
       using multiple imwheels.  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
       stick or wheel.

       Edit the XF86Config and add/edit the following lines in the
       "Pointer"(XFree86 3.3) or "InputDevice"(XFree86 4.x) section:

       1 axis (vertical wheel):
              (XFree86 3.3)
                     Buttons 5
                     ZAxisMapping 4 5
              (XFree86 4.x)
                     Option "Buttons" "5"
                     Option "ZAxisMapping" "4 5"

       2 axis (1 stick or 2 perpendicular wheels):
              (XFree86 3.3)
                     Buttons 7
                     ZAxisMapping 4 5 6 7
              (XFree86 4.x)
                     Option "Buttons" "7"
                     Option "ZAxisMapping" "4 5 6 7"

       The Buttons option may be greater than stated above if you have thumb
       buttons, or other extras that qualify as buttons.

       Make sure your Protocol is set to either "IMPS/2" for a PS/2 mouse or
       for serial mice set it to "IntelliMouse" or "Auto".  This is for
       IntelliMouse compatible mice, other protocols may be required for other
       mice.  Then while running X Windows run imwheel without the --wheel-
       fifo or -W options.

       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 included and exclusion for XV already.  See the
       IMWheelRC section for more information.

       Also pid files are not used for this method.  Thus the -p and --pid
       options have no effect, and are ignored.

       This method is REQUIRED for any X Windows server without wheel mouse
       support built in.  This method will currently support mice as supported
       through gpm or jamd.

       In the Pointer section of your XF86Config (or the equivalent
       configuration file for your X server) change your mouse Protocol to be
       "MouseSystems" (or the equivelant...), also change the Device file that
       the mouse is read from to "/dev/gpmdata", then restart X Windows if it
       is running.  jamd will replicate to /dev/jam_ps2:0.0 or some other
       devices as well, make sure to use the right X Mouse protocol in this
       case, like the jamd_ps2 device is X mouse protocol PS/2, and the
       jamd_imps2 device is X mouse protocol IMPS/2.

       Before starting X Windows (re)start gpm with the -W option.  Make sure
       you are using a supported wheel or stick mouse as stated in the gpm man

       After starting X Windows run imwheel as follows adding options as

       for gpm you can use the following option to imwheel


       jamd requires you specify the fifo name as one of the
       /dev/jamd_imwheel:0.0 named fifos.  Run

       ls -al /dev/jam_imwheel*

       to see what is available.  In this example I would use

       -W /dev/jam_imwheel:0.0

       as the option to imwheel.

       I usually add the -k option to kill off any old imwheel processes left
       over, as imwheel doesn't exit with the server, but rather it will only
       die if a wheel or stick action occurs when an X server is not
       connected, such as when X is dead or the DISPLAY environment variable
       is setup wrong, or the -X or --display variables connected imwheel to a
       now defunct X server.

       gpm or jamd, and/or imwheel can be restarted at any time, imwheel can
       sense when gpm of jamd is not there, and gpm nor jamd doesn't give a
       hoot about imwheel being up or not.

       The @Exclude command has no bearing in this method, it is ignored.  No
       Focus change events are received in this method.  Thus KDE and other
       clients that support X based wheel events through the ZAxis are not
       going to work except through normal imwheel keypress translation of
       wheel and stick actions.
       XV will function fine, as will any client that grabs the mouse and/or
       mouse buttons.  This mode doesn't use any grabs to function.

       The -s and -t options specify a sensitivity and threshhold.  each
       movement of a stick, or trackball, must equal or exceed the threshhold
       to be added to the respective axis sum.  In other words if you puch the
       stick up hard enough to exceed the threshhold then the Y axis sum would
       be increased by however much you pressed up.

       Next the summed X and Y axis movement is each compared to the
       sensitivity setting.  If the sensitivity setting is equalled or
       exceeded, then one imwheel event is spawned, thus after pressing up for
       a bit, the Y sum exceeds the sensitivity and a wheel up event is
       interpreted by imwheel into an action such as a PageUp key.

       The sensitivity therefore must be greater than the threshhold for it to
       have any bearing on the input.  Pseudo code such as the following may
              if(input >= threshhold)
                     sum = sum + input
              if(sum >= sensitivity) {
                     do an imwheel action
                     sum = 0

       IMWheel uses, optionally, two configuration files.  One called
       /usr/X11R6/etc/imwheelrc, which is used for everybody.  The other is
       $HOME/.imwheelrc, used only for one user.  One is supplied and should
       have been installed automatically in /etc/X11/imwheel/ if not also in
       the installing users $HOME as well.  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 it's configuration.  The window
       names a 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 probe-able 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/stick 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 it's
       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/stick 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 stick.  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.
              XV and KDE clients need this for the X Windows Method.
              This command has no effect in the GPM Method.  The mouse isn't
              grabbed, nor are ZAxis button events created by the server.

              Repeat the mouse button to the window. This cause a mouse button
              to be generated in the current window.  It does not use
              XSendEvent so the mouse button presses are indistiguishable from
              the real thing.  This mode is not compatible with the
              XGrabButtons method of imwheel, otherwise listed as the ZAxis
              Method in this manpage.
              Motions are mapped as follows:

                     Up     is button 4
                     Down   is button 5
                     Left   is button 6
                     Right  is button 7
                     Thumb1 is button 8
                     Thumb2 is button 9

              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/sticking 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

       Mouse wheel and stick actions can be grabbed along with active modifier
       keys on the keyboard.  The mouse wheel/stick 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.

       For FIFO users, it is possible to send a real mouse button event, using
       the special Button# syntax.  An imwheelrc keysym of Button1 would send
       a real Mouse button 1 (left mouse button) event.  Mouse4 is what you'd
       want for a MouseWheelUp type event.  Mouse5 is what you want to
       MouseWheelDown event.  Many applications will understand the meaning of
       mouse button 4 and 5, but most don't go beyond that.  So Mouse6 and
       greater have no "standardized" meaning.  The Button# syntax can be
       combined with regular keysyms, to send keys and mouse buttons at the
       same time.

                  - meaning left shift and wheel up.
                  - meaning wheel down.

       Other button to imwheel meaniful references:
              KeySym   IMWheel Input  Real Mouse
              ------   -------------  ----------
              Button1  (none)         Left Mouse Button
              Button2  (none)         Middle Mouse Button
              Button3  (none)         Right Mouse Button
              Button4  Up             Mouse Wheel Up
              Button5  Down           Mouse Wheel Down
              Button6  Left           Mouse Wheel Left
              Button7  Right          Mouse Wheel Right
              Button8  Thumb1         Side Mouse Button 1 (left/up)
              Button9  Thumb2         Side Mouse Button 2 (right/down)

       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
       or stick  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 donn't forget to reduce the
       Buttons argument to 2!

       For those of you lefties out there using method #1, the non-gpm method
       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 on reducing 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 or using
       the same gpmwheel FIFO. - 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.
       - This is my fault?! ;)


       Jonathan Atkins <>

            The users configuration file.

            The global location for the configuration
            file, it is always loaded.  Overided by
            the users configuration file.

            The default wheel FIFO from gpm, if used.

       /dev/jam_imwheel:0.0 (or other numbers...)
            A wheel FIFO from jamd, if used, must be specified.
            jamd allows more than on FIFO, and thus allows more than
            one instance of imwheel to be running on the same computer
            when running imwheel on multiple displays
            using the Wheel FIFO method.

            The public area for imwheel's pid file.

            The private area for imwheel's pid file.

           Jon Atkins Mouse - a replacement/augmentation for/to gpm.
           The new replacement for imwheel.  Uses jamd instead of gpm or ZAxis.
            (may not be available yet)
           X Display information, including extensions.
           General Purpose Mouse, imwheel edition required.
           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.

3rd Berkeley Distribution      September 8 2002                     IMWheel(1)


Want to link to this manual page? Use this URL:

home | help