MAN page from Mandrake Other imwheel-0.9.6-4mdk.i586.rpm

IMWheel

Section: User Commands (1)
Updated: Version 0.9.6
Index

NAME

imwheel - a mouse wheel and stick interpreter for X Windows

SYNOPSIS

imwheel [ options ]

DESCRIPTION

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.

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, reversingthe Up and Down actions. This would make 4 buttons somewhat useful!
-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...
-h, --help: Short help on options plus version/author info.
-k, --kill: Attempts to kill old imwheel (written in --wheel-fifo methodonly.) Pidfile must be created for this to work. Process istested using /proc/${pid}/status Name: field ?= imwheel. If /proc is not mounted then this fails everytime!
-p, --pid: Don't write a pidfile for gpmwheel FIFO method. This is the onlymethod that uses the pidfile. XGrab doesn't need it, so it justissues a warning about starting multiple imwheels on the samedisplay.
-q, --quit: Quit imwheel before entering event loop. Usful in killing animwheel running in gpmwheel FIFO mode after exiting XWindows.
Example: `imwheel -k -q' = kill and quit (option order doesn't matter)
-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) to7(hard push). This sets the minimum required pressure formovement. setting it to zero will cause realtime sticking, whichis usually too much action for X to keep up. (max rate i saw was100 events a second!)
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!
-W, --wheel-fifo fifo: Use the gpm wheel fifo instead of XGrabMouse. See GPM Wheel FIFO Method section. This method allows only one X display to be used. This is required for the gpm method to work.
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.
@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 Method.

X WINDOWS ZAXIS METHOD

This method is the only method that works with multiple X displays, usingmultiple imwheels. Use multiple imwheels by either setting the DISPLAYenvironment 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 the following line to the "Pointer" section:

ZAxisMapping    4 5

Make sure your Protocol is set to either "IMPS/2" for a PS/2 mouseor for serial mice set it to "IntelliMouse" or "Auto". Then while runningX-Windows run imwheel without the --wheel-fifo or -W options.

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

Also pidfiles are not used for this method. Thus the -p and --pidoptions have no effect, and are ignored.

GPM WHEEL FIFO METHOD

This method is REQUIRED for Accelerated-X or any other server without wheelmouse support built in. This method will currently support mice as supportedthrough gpm.

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 fromto "/dev/gpmdata", then restart X Windows if it is running.

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

After starting X Windows run imwheel as follows adding options as desired:

imwheel --wheel-fifo

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 and/or imwheel can be restarted at any time, imwheel can sense when gpm isnot there, and gpm doesn't give a hoot about imwheel being up or not.

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

IMWHEELRC

IMWheel uses, optionally, two configuration files. One called /etc/imwheelrc,which is used for everybody. The other is $HOME/.imwheelrc, used only for oneuser. One is supplied and should have been installed automatically in /etcif not also in the installing users $HOME as well. All whitespace is ignoredin the files except for within the window names' double quotes.

The configuration file consists of window names and event translations and/orimwheel commands that begin with an `@' (at) symbol. Each window name starts asection that is it's configuration. The window names a priortized as firstcome first served, so more generic matches should always occur later in theconfiguration 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 three things:

Window TitleWindow Class NameWindow Resource Name

All of these are probable using fvwm2's FvwmIdent module or the configurator(see the Configuration Helper section). Other window managers may have theirown method of identifying windows' attributes.
Each window name is matched as a regex string. Thus any window is matched usingthe regex pattern ".*" as a window name. This pattern should be the lastsection in your configuration file, or it will override the other windowconfigurations in the file for matched wheel/stick actions.
Each window name must be enclosed in double quotes (") on a line byitself.

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 startinganother window section or the end of the configuration file.

IMWHEELRC TRANSLATION DEFINITIONS

Mouse wheel/stick translations each take up a line after a window section hasbeen started. Each argument is seperated by commas(,) whitespace is ignored.KeySyms are used to specify the keyboard input and outputs. pipes (|) are usedto 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 themouse action is made in order for this translation to be used. Alt, Meta,Control, and Shift keys are typical modifiers, but are stated slightly differentthan just `Shift' but rather `Shift_L' or `Shift_R', differentiating betweenleft and right shift keys. See the KeySyms section for more.

`None' is a special KeySym used by imwheel, it is used to indicate nomodifiers. A blank entry is also acceptable in this case, but less descriptiveof what is going on! If `None' is used then there can be no modifiersin use during the wheel action. If the field is blank then any modifierwill 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 andonly one:

UpDownLeftRight

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 thepreceding 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 OutputRepetition.
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 ungrabthe mouse when these windows are entered and not regrab the mouse until focusis changed to a non-excluded window. This allows the ZAxis button events topass 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 areZAxis button events created by the server.

CONFIGURATION HELPER

IMWheel contains a semi-hidden configuration helper which can be brought upby 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 yourimwheelrc file. Press on the mini-screen capture to grab another window, including the root window (whole screen).

Mouse wheel and stick actions can be grabbed along withactive modifier keys on the keyboard. The mouse wheel/stick action is displayedand the X KeySyms are displayed beneath it. All this information can bedirectly 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 theother!

Common Modifier Keysym names used in X:

Shift_L     Shift_RControl_L   Control_RAlt_L       Alt_R

These are not currently assigned any keys, unless you xmodmap them in:

Super_L     Super_RHyper_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...)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 are not assigned any KeySyms, but they do have numbers.xmodmap can be used to assign them to a real KeySym.

To find keysym names for any keys available see the /usr/X11R6/include/X11/keysymdef.h file, and for any define in that file remove the "XK_" for the usable KeySym name in the configuration file.

Remember, there's always the configurator...

WHEEL OR STICK AS MIDDLE BUTTON IN X

Configure the XF86Config without "Emulate3Buttons" and add "Buttons 3" in the Ponter 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.

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 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 samegpmwheel FIFO. - This will always be your fault :|

Stick mice are still a pain in the butt to use. - This is the manufacturer's fault.

Keyboard focus isn't changed automatically to input keys into Window mouse isover. 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)

Configuration file is not validated for correctness nicely...although it doesget preparsed before the main program starts, thus stopping you before you runwith an invalid configuration file. I just have never made a bad configurationfile, so I guess I'll have to try and do that to see what happens. Just don'tmake any mistakes and you'll be fine. - This is my fault?! ;)

HOMEPAGE

http://solaris1.mysolution.com/~jcatki/imwheel

AUTHOR

Jonathan Atkins <jcatkiAATTmysolution.com>

FILES

$HOME/.imwheelrc        The users configuration file./etc/.imwheelrc        The global location for the configuration        file, it is always loaded.  Overided by        the users configuration file./dev/gpmwheel        The default wheel FIFO from gpm, if used./tmp/imwheel.pid        The public area for imwheel's pid file./var/run/imwheel.pid        The private area for imwheel's pid file.

Index

NAME
SYNOPSIS
DESCRIPTION
COMMAND LINE OPTIONS
X WINDOWS ZAXIS METHOD
GPM WHEEL FIFO METHOD
IMWHEELRC
IMWHEELRC WINDOW SECTION HEADERS
IMWHEELRC TRANSLATION DEFINITIONS
IMWHEELRC COMMANDS
CONFIGURATION HELPER
KEYSYMS
WHEEL OR STICK AS MIDDLE BUTTON IN X
BUGS
HOMEPAGE
AUTHOR
FILES
SEE ALSO

This document was created byman2html,using the manual pages.