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. 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 per-
	      haps 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 proto-
       cols 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  sup-
       plied 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 man-
       agers 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  possi-
       ble  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  `Con-
	      trol_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 priori-
	      ties 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 with-
       out 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  uni-
       versal.	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 manag-
       ment 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)