Debian Codegraph @

README

raw
1 www.FreshMeat.net appindex# 903164189
2
3 Overview
4 """"""""
5 This is a not so short little ditty that does the simple conversion of mouse
6 button presses into key presses. By grabbing only the 4th and 5th mouse buttons
7 the program is able to receive input from the Intellimouse series mice. There
8 is also a modified version of gpm included that has, already, support for the
9 Intellimouse, and I added a wheel fifo. The user library may also be used,
10 although this may need to be debugged. See the gpm section below for more.
11 The wheel button can always be used as middle button, this program does not
12 affect how the XServer, nor GPM, react towards it. A mouse with a wheel button
13 is a 3 button mouse, and should be configured as such!
14
15 Required
16 """"""""
17
18 XFree86 >= 3.3.2 (or other XServer with wheel to mouse button support)
19 not version 4.0.0 for gpm or jam use, FIFO support is broken there.
20 it is fixed in 4.0.1 so upgrade if you are on 4.0.0
21 Intellimouse or Logitech MouseMan+ (other wheel mice work too...)
22
23 to compile from source:
24
25 The X11 include files and libraries. (Not the X server development packages)
26
27 Installation
28 """"""""""""
29 configure --help
30 configure (and any options you want to set)
31 make
32 make install
33
34 **********************************************************************
35 **********************************************************************
36 **** ****
37 **** READ THE MANPAGE FOR UP TO DATE DOCS! ****
38 **** everything after this point may help, but is not up to date. ****
39 **** ****
40 **********************************************************************
41 **********************************************************************
42
43 The mouse must be setup in XF86Config to send the mouse buttons 4 and 5 for
44 wheel actions. To do this:
45
46 [ METHOD #1 : XGrabButton ]
47
48 1) edit /etc/XF86Config with your favorite editor (I suggest vim! It's crunchy)
49 a. add the following line to the "Pointer" section.
50
51 for 1 wheel:
52 ZAxisMapping 4 5
53 for two wheels or a stick:
54 ZAxisMapping 4 5 6 7
55
56 b. Make sure your Protocol is set to either "IMPS/2" for a PS/2 mouse
57 or for serial mice set it to "IntelliMouse" or "Auto".
58 It should work for the following mice, which have wheels, knobs, or
59 buttons that are mappable with ZAxisMapping (according to XFree86
60 documentation):
61
62 ASCII (serial, PS/2)
63 Genius NetScroll (PS/2)
64 Genius NetMouse and NetMouse Pro (serial, PS/2)
65 Logitech MouseMan+ and FirstMouse+ (serial, PS/2)
66
67 Half functionality may be obtained from the following mice that have
68 at least a fourth button capability:
69
70 ALPS Glide-Point (serial, PS/2) ('Tapping' is button 4)
71
72 The half functionality will only go up and left, unless you include the
73 -4 option on the command-line.
74
75 c. Here's my current setup for an example of a PS/2 Intellimouse:
76
77 Section "Pointer"
78 Protocol "IMPS/2" #change for your mouse type.
79 Device "/dev/psaux" #change for your device.
80 BaudRate 1200 #This is probably not needed!
81 Resolution 100 #And neither is this!
82 ZAxisMapping 4 5 #This is necessary!
83 Buttons 3 #Use this instead of Emulate3 stuff!
84 EndSection
85
86 d. Restart XWindows if you need to!
87
88 2) make
89
90 3) make install
91 This will currently install to /usr/local/bin, so edit the Makefile to
92 change this behavior.
93 Don't forget to choose whether you want imwheel to be setuid root. This is
94 required for any users who need to use imwheel and the pidfile stuff to track
95 running imwheels.
96
97 4) After XWindows is started run imwheel like this:
98
99 imwheel -k
100
101 imwheel will automatically background itself this way.
102 I added the -k to force any old imwheel processes to stop. This will not
103 cause imwheel to die if there are no previous imwheels.
104
105 XFree86 Settings:
106 Make sure Emulate3 phrases are either deleted or commented out to use the
107 wheel button as the middle button(2), and then the right button is button 3.
108
109 STUPID FACT:
110 Obviously this method can be used for a real 5(+) button mouse as
111 well...but why?! The 4th and 5th buttons may be used as if they were the wheel
112 rolling up and down, but this will remove the regular functionality of the 4th
113 and 5th buttons, unless you "exclude" the windows in which you need the 4th and
114 5th buttons.
115
116 [ METHOD #2 : wheel fifo ]
117
118 This method is REQUIRED for Accelerated-X or any other server without wheel
119 mouse support built in. It is also the recommended method by me! This method
120 will currently support ONLY the ps/2 Intellipoint Mice, not the serial version,
121 nor any other mice for that fact...unless you want to add support in gpm
122 yourself or send me a mouse so that I can implement it in gpm. To add a new
123 mouse to this method no change to imwheel is required.
124
125 1) Edit /etc/XF86Config with your favorite editor (I suggest vim! It's crunchy)
126 OR use XF86Setup. That's easier!
127
128 b. Make sure your Protocol is set to "MouseSystems"
129 Mouse support is dependent on gpm. Right now I KNOW imps2 works!
130 others that may work for you include mm+ps2, marblefx, pcnps2, and ms3.
131 try others if these don't work or another matches your mouse better.
132
133 c. Here's my current setup for an example of a PS/2 Intellimouse:
134
135 Section "Pointer"
136 Protocol "MouseSystems" #gpm -R is MouseSystems!
137 Device "/dev/gpmdata" #this is the gpm -R output
138 BaudRate 1200 #works for me...
139 Resolution 100 #i dunno...works again!
140 Buttons 3 #use this,it's better than Emulate3!
141 #if you set this higher...more
142 #configuration is REQUIRED
143 EndSection
144
145 d. Restart XWindows if you need to!
146
147 2) make
148
149 3) make install
150 This will currently install to /usr/local/bin, so edit the Makefile to
151 change this behavior.
152 if you want ALL the gpm stuff enter that directory and "make install" there.
153 The usual install only installs the gpm executable.
154 Don't forget to choose whether you want imwheel to be setuid root. This is
155 required for any users who need to use imwheel and the pidfile stuff to track
156 running imwheels.
157
158 4) After XWindows is started run :
159
160 imwheel -k --wheel-fifo
161
162 imwheel will automatically background itself this way.
163 I added the -k to force any old imwheel processes to stop. This will not
164 cause imwheel to die if there are no previous imwheels.
165
166
167 NOTE: the @Exclude command has no bearing in this method, and is ignored.
168 mainly because by excluding a window in this method there is nothing
169 sent to the window for the wheel, whereas in the other mode
170 exclusion turns off the button grabbing and allows the usual button 4 and
171 5 events again for those clients that either need to grab all the buttons
172 or want to receive the buttons 4 and/or 5 for their own purposes.
173
174 gpm
175 """
176 The included gpm is stable, a patch is included as well, and I will try to keep
177 up with the next stable versions. Using the included gpm is only necessary if
178 you are going to use method #2 from above. To use gpm and imwheel together you
179 must run gpm and imwheel as follows:
180
181 gpm -W -R -t mousetype(see above for known working types)
182
183 NOTE: gpm may be killed and restarted with imwheel running, imwheel and gpm
184 can both handle this interruption just fine. When gpm is dead, both
185 the XServer and imwheel will not respond to the mouse. You will need
186 to run gpm again!
187
188 Other options may be added of course!! use -w to force wheel. use gpm -h to see
189 them.
190
191 imwheel -k -W /dev/gpmwheel
192 or
193 imwheel -k --wheel-fifo
194 or
195 imwheel -k --wheel-fifo /dev/gpmwheel
196 or
197 imwheel -k --wheel-fifo /dev/jam_imwheel:0 # number zero may be higher
198
199 if you want ALL the gpm stuff enter that directory and "make install" there.
200 The usual install only installs the gpm executable.
201
202 NOTE : gpm will create the fifo if it needs to, imwheel will not.
203 /dev/gpmwheel is simple it output a 4 or 5 (byte not char!) for up and down.
204 You may use it in other programs if imwheel is not used...but why? od the fifo
205 to watch your wheel at work (od is an octal dumper!), it requires a line for
206 output so wheel a lot to see your mouse actions! The gpm currently included is
207 a hacked beta, which may sound bad, but it's been very stable for my imps2.
208
209 JAM
210 """
211 For jam to work with imwheel you will have to place the imwheel output
212 module in the mice/file that you are using for your mouse. see the mice/imps2
213 file for an example. See also the JAM documentation. JAM will then output
214 imwheel compatible streams on the /dev/jam_imwheel:* set of FIFOs, see JAM docs
215 on multiple FIFO outputs. JAM is the only way to use multiple running
216 imwheels, one for each DISPLAY you may have, for multiple displays. If you
217 only have one screen then this doesn't really matter to you.
218 XWheel is the full client to be paired with JAM and intended to replace
219 imwheel. IMWheel is now an aging product...only maintanance work is being done
220 on imwheel and it's version/hack of GPM.
221
222 .imwheelrc
223 """"""""""
224 [ OVERVIEW ]
225
226 The configuration of specific clients is taken care of in the file called
227 "$HOME/.imwheelrc" or "/etc/X11/imwheelrc".
228
229 All arguments in the file are separated by commas.
230
231 The pound(#) symbol may be used anywhere for comments.
232
233 Case is VERY important in the configuration file!
234
235 [ WINDOWS ]
236
237 In this file windows are configured by title name, resource name, or class name.
238
239 Each window is configured on multiple lines. The first line in a window
240 section is the window pattern string enclosed in double-quotes("), then one
241 line each for each action in that window.
242
243 Double-quotes must surround window identifier strings, and only these strings
244 are allowed to be quoted. Without the double-quotes that window's section will
245 be parsed as if it is in the previous window's section!
246
247 The windows are matched at run-time using regular expression syntax, so to
248 match a group of windows make up the appropriate regex pattern and use that as
249 the identifier.
250
251 [ REGULAR EXPRESSIONS ]
252
253 Regular expressions are used, for one reason, because they are built into C, and
254 the other, they are powerful!
255
256 One thing to note is that if you don't put a ^ (caret) at the beginning of each
257 string then you may end up with a string matching a substring that doesn't
258 begin with the expression. Which is why in the distributed file most entries
259 begin with a caret now.
260
261 O'Reilly & Associates has a great Regular expressions book that you can get,
262 and it covers the type of expression syntax used here.
263
264 [ COMMANDS ]
265
266 Commands are began with an at('@') character. They apply to the window whose
267 section they are in. Mixing commands and window wheel actions may achieve
268 undesired results. For now mixing is moot, being that the only command is to
269 turn off wheel actions!
270
271 Available commands:
272 @Exclude
273 This will un-grab the mouse buttons for the current window, it will attempt
274 to re-grab the mouse buttons when the keyboard focus is changed. Once the
275 focus window has changed from the excluded window, every motion of the mouse
276 will cause an attempt to re-grab the buttons. The program will catch all
277 errors during this period. Once the buttons are grabbed successfully the
278 program resumes normal wheel operation.
279 NOTE: This command is required for the "xv grab" window!
280 This command is unused with the --wheel-fifo option, see gpm.
281
282 [ KEYSYMS ]
283
284 The program expects combinations of keysyms to be used by using pipe(|)
285 characters to combine them together.
286 Example: Alt_R|Shift_R
287 Means Right Alt AND Right shift together, not just either-or!
288
289 Modifier Keysym names used in X:
290 Shift_L Shift_R
291 Control_L Control_R
292 Alt_L Alt_R
293 These are not currently assigned any keys, unless you xmodmap them in:
294 Super_L Super_R
295 Hyper_L Hyper_R
296 And here's some that you may use, and they are somewhere on your keyboard!
297 Here's where they were on my keyboard, again, this is not universal.
298 Use the "xev" program to test your own keys on your keyboard!
299 Caps_Lock =The Caps Lock key! (This still turns on and off caps lock!)
300 Num_Lock =The Num Lock key! (This is not good to use...)
301 Multi_key =The scroll lock key! (Go figure!)
302 Mode_switch =Right Alt...for me anyways. (this mean I cannot use Alt_R)
303 NOTE:
304 You can add support for the windows keys. They may be set up for you as
305 Super_L and Super_R. If not use xmodmap or better, Xkeycaps the graphical
306 frontend, to set them up as these Super keys.
307
308 To find keysym names for any keys available see the
309 /usr/X11R6/include/X11/keysymdef.h file, and for any define in that file remove
310 the "XK_" for the usable keysym name in the configuration file.
311
312 If no input keysyms are named, any input modifier keys will be ignored, and
313 that action will match if the wheel action is matched! Order matters here
314 a lot! Put a no-input-modifier keysym at the end of it's section for what you
315 most likely want to happen! The "None" keysym is preferred in this situation,
316 however.
317
318 "None" is another special keysym used to indicate no input modifier is allowed.
319 This is used to make the action not match when a modifier is pressed.
320
321 "Pass" is a special keysym used to tell imwheel to pass the button press
322 through to the client window as if imwheel was not present. (Not implemented
323 yet!)
324
325 The Modifier keysym(s) are the expected keys to be pressed along with the wheel
326 actions. If the modifier is not a match, that action is not done.
327
328 The second field is the mouse wheel action, "Up" or "Down".
329
330 The Output Keysyms (the second set of keysyms) are the keys that are pressed
331 when the following conditions are met:
332
333 1) Current Focused window (not a mouse over thing!) has a match as a title,
334 resource, or class name to the window regex pattern specified as the
335 window identifier.
336 2) Current pressed keys on keyboard match the Modifier Keysym(s),
337 or there are no modifier keysyms to match.
338 3) The wheel is moving up or down and that matches the second argument.
339
340 [ REPS ]
341
342 Reps (Repetitions) lets you say a number for how many times you want the
343 output keysyms to be pressed. See the chart on the default bindings for the
344 default number of reps for each modifier-combo (The chart is near the end of
345 this document).
346
347 [ DELAYS ]
348
349 Two delays are configurable in the "/etc/X11/imwheelrc" and/or the
350 "$HOME/.imwheelrc" files. The first delay is the delay between repetitions.
351 The second delay is the delay between key down and key up events. If you make
352 the delay too long expect the likelyness of the sticky keys bug to occur (see
353 BUGS file). The delays are specified in microseconds. see the included
354 imwheelrc file (which you should copy/merge) for the netscape configuration
355 that works best for me!
356
357 [ FILES ]
358
359 See the included imwheelrc file for a few examples of configured windows. This
360 file is a good start and may be copied into the users home directory as
361 ".imwheelrc" and/or into /etc/X11/imwheelrc for a default setup for all users.
362 Then modify your individual copy or the /etc copy to add more windows.
363
364 [ CONFIGURATION HELPER ]
365
366 There is a "hidden" configuration helper that can be called up while running
367 XWindows and imwheel. The helper is called by wiggling the wheel up and down
368 in X's root window until it appears.
369 The helper is able to do the following:
370 1) Grab windows and display relevant configuration information, that is:
371 Window title, Resource name, and Class name. The class name is usually
372 the best thing to use, but this is up to you to decide!
373 2) Grab wheel actions and display the modifiers to use in the imwheelrc file.
374 3) Reload the imwheelrc file, this actually restarts imwheel for you!
375
376 The Cancel button merely exits the helper, however the imwheelrc file is not
377 rescanned, so no changes will be reflected in continued wheel usage.
378
379 To grab a window, click on the image on the left, and then click on a window.
380 If the window can be used with imwheel it will appear in the big button. This
381 is determined soley by window focus. I use focus on mouse over so this works
382 great for me, however those who use click-focus may not see the expected
383 results. It's just trying to help...
384
385 To grab a wheel action, press the button label as such and then press and hold
386 you desired modifier keys then roll the wheel in the direction to configure.
387 The wheel direction to use in the file will be shown with a list of the
388 modifiers below it. Output keys can be grabbed somewhat similarly in this
389 manner however the shifted keys may need to be translated to the actual
390 characters desired, this was not the case for XTerm though.
391
392 [ PLEAD ]
393
394 Please send your configuration additions to me at one of the addresses stated
395 below for possible inclusion in further releases. If deemed useful and
396 sensible it will be added to the distribution. Please don't write asking for
397 help with the rc file! Ask for features and bug fixes, sure, but not any more
398 of a tutorial than this!
399
400 [ SYNTAX ]
401
402 The following syntax is available ('<' and '>' characters signify variables
403 required to be filled in, '[' and ']' are optional variables):
404
405 # blank lines are ignored, and not needed, as are comments ignored.
406 # whitespace is ignored unless contained in quotes.
407 "<window identifier>"
408 [Modifier keysym(s)/None],<Up/Down>,[Keysym(s)/Pass],[Reps],[RepDelay],[DelayUp]
409 [Modifier keysym(s)/None],<Up/Down>,[Keysym(s)/Pass],[Reps],[RepDelay],[DelayUp]
410 [Modifier keysym(s)/None],<Up/Down>,[Keysym(s)/Pass],[Reps],[RepDelay],[DelayUp]
411 ...more modifiers, etc...
412 "<next window identifier>"
413 @<Command>
414 "<next window identifier>"
415 [Modifier keysym(s)/None],<Up/Down>,[Keysym(s)/Pass],[Reps],[RepDelay],[DelayUp]
416
417 ...and so forth...
418
419 The best example is availble in the supplied imwheelrc file, in the netscape
420 section, there is a commented-out version of Up and Down that do smooth
421 repeating up or down keys respectively and it is tuned to have a working delay
422 for netscape to catchup.
423
424 Options
425 """""""
426 Use the -h or --help option for all available options, and documentation.
427 --long-args can also be written as -long-args, but this sometimes causes other
428 combinations of short-args to fail due to ambiguity, just state them separately
429 to avoid the ambiguity. (e.g.: -pdD => -p -d -D)
430 Notation: "<>" surrounds required args
431 "[]" surrounds optional args.
432
433 -4
434 --flip-buttons
435 Flips the mouse buttons so that 4 is 5 and 5 is 4, reversing
436 the Up and Down actions. This would make 4 buttons more useful!
437 See also the manpage for xmodmap.
438 -f
439 --force
440 Forces the X event subwindow to be used instead of the original
441 hack that would replace the subwindow in the X event with a
442 probed focus query (XGetInputFocus). This should fix some
443 compatability problems with some window managers, such as
444 window maker, and perhaps enlightenment. If nothing seems to be
445 working right, try toggling this on or off...
446 -W <fifo-path>
447 --wheel-fifo [fifo-path]
448 Use the gpm wheel fifo instead of XGrabMouse. See gpm section.
449 This method allows only one X display to be used.
450 This is required for method #2 to work.
451 @Exclude commands in the rc file are unused in this mode.
452 fifo names the named pipe created by gpm.
453 It defaults to "/dev/gpmwheel". (--wheel-fifo only)
454 Must exist before running imwheel in this mode.
455 -k
456 --kill Attempts to kill old imwheel (written in --wheel-fifo method
457 only.) Pidfile must be created for this to work. Process is
458 tested using /proc/${pid}/status Name: field ?= imwheel.
459 If /proc is not mounted then this fails everytime!
460 -p
461 --pid Don't write a pidfile for --wheel-fifo method. This is the only
462 method that uses the pidfile. XGrab doesn't need it, so it just
463 issues a warning about starting multiple imwheels on the same
464 display.
465
466 -X <display>
467 --display <display>
468 use XServer at a specified display in standard X form.
469 using this mode allows for multiple displays.
470 this is useful in method #1.
471 -D
472 --debug Show all possible debug info while running. This spits out alot
473 and I also suggest using the -d option to prevent imwheel from
474 detaching from the controlling terminal.
475 -d
476 --detach Actually this does the opposite, it prevents detachment from the
477 controlling terminal. (no daemon...) Control-C stops, etc...
478 -h
479 --help short help on options plus version/author info.
480 -q
481 --quit Quit imwheel before entering event loop. Usful in killing an
482 imwheel running in --wheel-fifo mode after exiting XWindows.
483 (e.g.: imwheel -k -q = kill and quit)
484 -s <sum-minimum>
485 --sensitivity <sum-minimum>
486 Used with gpm only and then only with recognized stick mice.
487 like -t only this sets a minimum total amount of movment of the
488 stick or marble, before any action is taken. This works good
489 with the Marble type devices. See also --threshhold.
490 -t <minimum-pressure>
491 --threshhold <minimum-pressure>
492 Used with gpm only and then only with recognized stick mice.
493 stick mice send a pressure value ranging from 0(no pressure) to
494 7(hard push). This sets the minimum required pressure for
495 movement. setting it to zero will cause realtime sticking, which
496 is usually too much action for X to keep up. (max rate i saw was
497 100 events a second!) The default is 2, to avoid slight presses
498 on the 90degree direction of the intended while still getting to
499 the intended direction. Setting this to 7 is insane, because it
500 requires the user to press the hardest everytime they want
501 something to happen! See also --sensitivity.
502
503
504 Usage
505 """""
506 The default modifier/wheel actions that are hard-coded will always be present
507 when an imwheelrc file doesn't provide a match or doesn't exist.
508 Default modifier effects chart:
509
510 Modifier Effect (Up, Down) Repetitions
511 -------- ----------------- -----------
512 None Page_Up, Page_Down 1
513 Shift Up, Down 1
514 Control Page_Up, Page_Down 2
515 Shift+Control Page_Up, Page_Down 5
516 Meta(that's Alt!) Left, Right 10
517 Shift+Meta Left, Right 1
518 Control+Meta Left, Right 20
519 Shift+Control+Meta Left, Right 50
520
521 For left and Right on wheels and sticks the repetitions are all that matter,
522 because they only go left and right by default. This can be changed in the
523 imwheelrc. Us the Left or Right keyword for the input action keyword to alter
524 left and right motions of a wheel or stick.
525
526 Lefty X Usage
527 """"" " """""
528 For left handed users this command may help at the start of X:
529 xmodmap -e "pointer = 3 2 1 4 5"
530
531 Contact Info
532 """"""" """"
533 Jonathan Atkins
534 2012 River Run Trail
535 Fort Wayne, IN 46825-6041
536
537 [email protected]