Colas Nahaboo X mouse wheel scroll page

X-logoplus signms intellimouse photologitech pilot mouse photologitech mouseman photo
The purpose of this page ( is to collect all the hacks to use the new wheel mice to scroll X apps. It has become quite big, but I think having a single big page is better, as is it easier to search and to print...

NOTE: Please mail comments, suggestions, patches, to be added to this page:

Small icons on these page are QbulletsLink to a short, explanatory page that contains no further links.

All code on this page is public domain, do what you want with it. And if you mail me code for inclusion on this page, you implicitly will put your code in public domain too...

I will also put your name (and web site or email adress) along with your contributions so that people may contact you directly for more info, as often I only report hacks I didnt try firsthand. Tell me if you dont want your coordinates to appear on this page...


On this same WWW page (started on Dec 30 1997) you will find:


The operation principle is that you must use or install a X server (XFreeLink to a different Web site greater than 3.3.2 or others), that will understand the low-level, mouse-dependant wheel protocol (a "mouse driver"), and that will translate the wheel motions to fake button4 and button5 events on up/down motions. Then this page then tries to collect all the modification to config files and patches programs to bind scroll movements to scroll windows of existing X apps when they receive these button4 and button5 events.
===> X Server ===> Button
4 & 5
===> toolkits/apps
config files
===> scrolling

For well-designed toolkits, we would only have to set a ressource somewhere that would then make all apps on this toolkit understand the wheel, but life isnt so simple, so many legacy apps must be tweaked by hand. Hopefully, new X apps will begin to support natively the whell, as with StarOffice...

I try to have the following consistent behavior in my patches, if you can, try to adopt the same policy in your submitted patches: (feel free to submit other patches for other policies)


The first mouse I saw having a wheel was a Genius mouse (Easyscroll), with pratically no support (
CoreyFromailed me that the first scroll mouse was actually a mouse systems "3d mouse"). One year afterwards, Microsoft popularised the concept with its Intellimouse, trying as usual to use if for unfair competition (it only worked with MS apps), but other manufacturers soon followed, with products working with all windows apps, such as the logitech ones.

Please report success with mouse types not listed here, there seem to be many on the market (I heard of: Fellows mouse, Kensington Thinking Mouse, Genius NetScroll, Genius NetMouse and NetMouse Pro, ASCII MieMouse...).

Reported failures (dont buy this hardware):

I strongly advise you to get a mouse being able to run either as a standard 3-button mouse or with the new wheel protocol. It will make your life much easier under non-X apps, or non-microsoft OSes. Logitech mice have this feature, MicroSoft ones dont, and I dont know for other (please mail me if you know). In MSWindows, The MicroSoft was only working with MicroSoft apps, too! (they only recently supported all apps with their new drivers).

If possible, try to use the PS/2 versions rather than the serial ones. The PS/2 protocol samples the mouse at the faster rate, giving a better tracking response

X Server

XFree 3.3.2 (and later)

XFree 3.3.2, natively supports a lot of mouse wheel devices, see the README.mouseLink to a short, explanatory page that contains no further links doc file in the XFree 3.3.2 distribution. Its support is quite complete and customisable, it even supports the 4th button (side thumb button) on some mice, such as the logitech MouseMan+. Upgrading to at least XFree 3.3.2 is thus the recommended solution.

Normally, all that is needed is to declare a bindtag in your XF86Config, add the following line in the Pointer section:

      ZAxisMapping 4 5
We map the wheel to buttons instead of using it as an axis, as buttons is the only way to support it via just changing ressources without recompiling or patching applications and toolkits

If you have a 4-button mouse, if you want tu use the 4th button, I recommend rebinding the button4 to button6 to be able to use the ressources in this page directly, rather than using 5 and 6 for the wheel. Alas, X only supports 5 buttons officially (thus you cannot use button 6 in Xt and Motif apps) so, depending on the application you may not use anymore the side button. And as the X server seems more isntable this way I dont recommend you use the side button at all. Just use "Protocol imps/2" and "ZAxisMapping 4 5" as above. If you want to have a 6th button, you can remap the side button to button6 by this command:
xmodmap -e "pointer = 1 2 3 6 4 5"
Note that this command may prompt you interactively to press and release buttons to perform its initialisation process, so I use the following code in my X startup script:

      ## rebind mouse buttons for mouseman+
      echo '#!/bin/sh
      xmodmap -e "pointer = 1 2 3 6 4 5"' >/tmp/x$$
      chmod a+x /tmp/x$$
      xterm -bg pink2 -fg blue4 -fn 9x15 -name "Pointer Remap" -e /tmp/x$$
      rm -f /tmp/x$$

In your XF86Config file, you should then use one of these protocols:

      Section "Pointer"
      Protocol "imps/2"            # for ps/2 wheel mouse
      Protocol "intellimouse"      # for serial wheel mouse
      Protocol "MouseManPlusPS/2"
      ... see the Xfree docs
WARNING! These patches or servers do not work if Emulate3Buttons is defined in the X Config file.

XFree 3.3.1 (and derivatives: SuSE)

You should upgrade to 3.3.2 or later. The following lines are here only for reference.

The standard XFree v3.3.1 server only works with the Serial MS mouse, the solutions above works with serial and PS/2 versions of the MS and Logitech mouses (oops, mice :-).

In your XF86Config file, you should then use one of these protocols:

      Section "Pointer"
      Protocol "imps/2"            # for ps/2 wheel mouse
      Protocol "intellimouse"      # for serial wheel mouse

warning!WARNING! These patches or servers do not work if Emulate3Buttons is defined ithe X Config file (XF86Config)! Symptom: only buttons 1,2,3 are emitted by the wheel. Reason: Emulate3Buttons is coded via a complex finite state machine, which should be redesigned to handle more than 3 buttons. Solution: comment out the Emulate3Buttons line if present.

Commercial servers

AcceleratedX from X-InsideLink to a different Web site: Michael Welsh Duggan has made a patch to /usr/src/linux/drivers/char/psaux.c, to recompile the kernel with, or you can grab the local copyDownload a file to your disk drive

Metro LinkLink to a different Web site : Supports the Microsoft Intellimouse (but not yet the Logitechs?) since June 1998.


You can also make gpm 1.13 decode the events for you and make X just read the processed events on the output pseudo-device /dev/gpmdata (instead of /dev/ttyS0 or /dev/tty/psaux) created by gpm by one of the commands:
gpm -t pnp -R
gpm -t ms3 -R
(tip by Olivier SIMON <>)


Marcus Sundberg writes: There is a utility called mhub which comes with LibGII from the GGI project ( mhub can read mouse data from both serial and PS/2 MouseMan+ (and a number of other mice) and output data in serial IntelliMouse, MouseSystems or PS/2 format.

If you have a MouseMan+ on the PS/2 port you probably want to use mhub with XFree servers too, because XFree (all versions up to parses the wheel data incorrectly. You can see this when you roll the wheel fast - the directions will then be reversed causing applications to scroll backwards. IntelliMouse data is however interpreted correctly, and this is where mhub is useful.


Wheel will scroll the saved output lines. Add to your ~/.Xdefaults
      !# Scrolling on wheel mouse: half a page normally, line per line with shift
      XTerm.vt100.translations: #override\n\
      !# In the scrollbar we map buttons 5 & 4 to 1 and 2 otherwise, core dump
      !# This will move proportionnaly to cursor position but we dont know how to
      !# program the same exact behavior as in the text widget.
      XTerm.vt100.Scrollbar.translations: #override\n\
      <Btn5Down>: StartScroll(Forward)\n\
      <Btn4Down>: StartScroll(Backward)\n\


rxvtLink to a different Web site, a xterm remplacement supports wheel mice since the 2.4.6 version. No ressource file tweaking is necessary.

Athena widgets

For use in all Athena-based applications. Add to your ~/.Xdefaults
      !## Athena text widgets
      *Paned.Text.translations: #override\n\
      Shift<Btn4Down>,<Btn4Up>: scroll-one-line-down()\n\
      Shift<Btn5Down>,<Btn5Up>: scroll-one-line-up()\n\
      Ctrl<Btn4Down>,<Btn4Up>: previous-page()\n\
      Ctrl<Btn5Down>,<Btn5Up>: next-page()\n\
A very useful hack for xrn, xmh: adds scrolling to the specific "Table Of Contents" (TOC) widget
      !## Athena table of contents, for toc widgets of xrn & xmh
      *toc.Translations: #override\n\
      Shift<Btn4Down>,<Btn4Up>: scroll-one-line-down()\n\
      Shift<Btn5Down>,<Btn5Up>: scroll-one-line-up()\n\
      Ctrl<Btn4Down>,<Btn4Up>: previous-page()\n\
      Ctrl<Btn5Down>,<Btn5Up>: next-page()\n\


Should work with all netscape versions. I tested with 2.02, 3.01, 4.02, 4.04, 4.05, 4.5. Contributed by
Sergey V. KovalyovPop a mailto: email dialog box on June 11, 1998, after attempts by myself and Alexey MarinichevPop a mailto: email dialog box and Alexey Solovyov.
Add to your ~/.Xdefaults:
      !## NETSCAPE
      Netscape*drawingArea.translations:  #replace    \
      <Btn1Down>:           ArmLink()   \n\
      <Btn2Down>:           ArmLink()   \n\
      ~Shift<Btn1Up>:       ActivateLink()  \n\
      ~Shift<Btn2Up>:       ActivateLink(new-window)  \
      DisarmLink()    \n\
      Shift<Btn1Up>:        ActivateLink(save-only)  \
      DisarmLink()    \n\
      Shift<Btn2Up>:        ActivateLink(save-only)  \
      DisarmLink()    \n\
      <Btn1Motion>:             DisarmLinkIfMoved()  \n\
      <Btn2Motion>:             DisarmLinkIfMoved()  \n\
      <Btn3Motion>:             DisarmLinkIfMoved()  \n\
      <Motion>:             DescribeLink()  \n\
      <Btn3Down>:           xfeDoPopup()    \n\
      <Btn3Up>:             ActivatePopup() \n\
      Ctrl<Btn4Down>: PageUp()\n\
      Ctrl<Btn5Down>: PageDown()\n\
      Shift<Btn4Down>: LineUp()\n\
      Shift<Btn5Down>: LineDown()\n\
      None<Btn4Down>: LineUp()LineUp()LineUp()LineUp()LineUp()LineUp()\n\
      None<Btn5Down>: LineDown()LineDown()LineDown()LineDown()LineDown()LineDown()\n\
      Alt<Btn4Down>: xfeDoCommand(forward)\n\
      Alt<Btn5Down>: xfeDoCommand(back)\n
      Netscape*globalNonTextTranslations: #override\n\
      Shift<Btn4Down>: LineUp()\n\
      Shift<Btn5Down>: LineDown()\n\
      Alt<Btn4Down>: xfeDoCommand(forward)\n\
      Alt<Btn5Down>: xfeDoCommand(back)\n

The above also adds the functionality to scroll netscape windows by one full page with ALT depressed. If you dont want this, just remove the 2 last lines (Alt<BtnXDown>) of each section.

You may also want to enable scrolling with the numeric keypad if you want appending these 6 lines just underneath the above:

      <Key>KP_9: PageUp()\n\
      <Key>KP_3: PageDown()\n\
      <Key>KP_8: LineUp()\n\
      <Key>KP_2: LineDown()\n\
      <Key>KP_4: ColumnLeft()\n\
      <Key>KP_6: ColumnRight()\n

PS: Unrelated hack by Alexey MarinichevWilliam M. PerryPop a mailto: email dialog box: I find this to be really cool as well (applies not only to frames): replace Btn3 entries with the following:

      <Btn3Down>: \n\
      <Btn3Down>,<Btn3Up>: xfeDoCommand(back)\n\
      <Btn3Down>,<Btn3Motion>: xfeDoPopup()\n\
Then, click with the right button sends you back, but click and drag gives you the menu.
Note: To scroll a frame, you must first click inside it, othwerwise netscape doesn't seem to known which you you can scroll (In other words: it is too dumb to look at the pointer position :-)


Normally, you should use the
mwheel.elDownload a file to your disk drive emacs package by William M. PerryPop a mailto: email dialog box, but before the above link work, you can use this local copy of a beta-version of mwheel.elDownload a file to your disk drive (Feb 23 1998) or this crude code I made:

Add to one of your .el files (~/.emacs per default)

      ;;                    scroll on  mouse wheel
      ;; scroll on wheel of mouses
      (define-key global-map 'button4
	'(lambda (&rest args)
	  (let ((curwin (selected-window)))
	    (select-window (car (mouse-pixel-position)))
	    (scroll-down 5)
	    (select-window curwin)
      (define-key global-map [(shift button4)]
	'(lambda (&rest args)
	  (let ((curwin (selected-window)))
	    (select-window (car (mouse-pixel-position)))
	    (scroll-down 1)
	    (select-window curwin)
      (define-key global-map [(control button4)]
	'(lambda (&rest args)
	  (let ((curwin (selected-window)))
	    (select-window (car (mouse-pixel-position)))
	    (select-window curwin)
      (define-key global-map 'button5
	'(lambda (&rest args)
	  (let ((curwin (selected-window)))
	    (select-window (car (mouse-pixel-position)))
	    (scroll-up 5)
	    (select-window curwin)
      (define-key global-map [(shift button5)]
	'(lambda (&rest args)
	  (let ((curwin (selected-window)))
	    (select-window (car (mouse-pixel-position)))
	    (scroll-up 1)
	    (select-window curwin)
      (define-key global-map [(control button5)]
	'(lambda (&rest args)
	  (let ((curwin (selected-window)))
	    (select-window (car (mouse-pixel-position)))
	    (select-window curwin)
And, on a related topic, you may also want this code to navigate in XEmacs with the numeric keypad:
      ;;                    scroll on numpad
      (define-key global-map 'kp_9 'scroll-down)
      (define-key global-map 'kp_3 'scroll-up)
      (define-key global-map 'kp_6
	'(lambda (&rest args) (interactive)  (other-window 1)))
      (define-key global-map 'kp_4
	'(lambda (&rest args) (interactive)  (other-window -1)))
      (define-key global-map 'kp_2
	'(lambda (&rest args) (interactive)  (scroll-up 1)))
      (define-key global-map 'kp_8
	'(lambda (&rest args) (interactive) (scroll-down 1)))
      (define-key global-map 'kp_7 'beginning-of-buffer)
      (define-key global-map 'kp_1 'end-of-buffer)
      (define-key global-map 'kp_5
	'(lambda (&rest args) (interactive)  (recenter 0)))

Gnu Emacs

Normally, you should use the same
mwheel.el emacs package as XEmacs, see the XEmacs sectionLink to another place further up on the same page

Otherwise you can use this preliminary Elisp, courtesy of Sylvia Knight, a mailto: email dialog box Send on Feb 2 1998:

      (defun up-slightly () (interactive) (scroll-up 5))
      (defun down-slightly () (interactive) (scroll-down 5))
      (global-set-key [mouse-4] 'down-slightly)
      (global-set-key [mouse-5] 'up-slightly)
      (defun up-one () (interactive) (scroll-up 1))
      (defun down-one () (interactive) (scroll-down 1))
      (global-set-key [S-mouse-4] 'down-one)
      (global-set-key [S-mouse-5] 'up-one)
      (defun up-a-lot () (interactive) (scroll-up))
      (defun down-a-lot () (interactive) (scroll-down))
      (global-set-key [C-mouse-4] 'down-a-lot)
      (global-set-key [C-mouse-5] 'up-a-lot)
If you want to scroll by half a page instead of only 5 lines as above, John RowePop a mailto: email dialog box sent this GNU Emacs code:
      (defun scroll-up-half ()
	"Scroll up half a page."
	(scroll-up (/ (window-height) 2))
      (defun scroll-down-half ()
	"Scroll down half a page."
	(scroll-down (/ (window-height) 2))
      (global-set-key [(mouse-5)] 'scroll-up-half)
      (global-set-key [(mouse-4)] 'scroll-down-half)

TCL / TK Applications

Info by
Bruce StephensPop a mailto: email dialog box:
Put this code into a file, for instance ~/.mscroll.tcl, and then include it in your tcl applications via source ~/.mscroll.tcl:
      proc mscroll {bindtag} {
      bind $bindtag <Button-5> [list %W yview scroll 5 units]
      bind $bindtag <Button-4> [list %W yview scroll -5 units]
      bind $bindtag <Shift-Button-5> [list %W yview scroll 1 units]
      bind $bindtag <Shift-Button-4> [list %W yview scroll -1 units]
      bind $bindtag <Control-Button-5> [list %W yview scroll 1 pages]
      bind $bindtag <Control-Button-4> [list %W yview scroll -1 pages]
and declare the bindings on the widgets you want by giving them as parameters to the newly defined function mscroll. For instance:

at the end of TkMan:

      source ~/.mscroll.tcl
      mscroll Text


For exmh, in ~/.tk/exmh/user.tcl:

      source ~/.mscroll.tcl
      proc User_Init {} {
      mscroll TScroll
      proc User_Layout {} {
      mscroll .ftoc.t
Then you must enter the following command from the Tcl prompt of the Log window (menu Pref/Hack support/)
auto_mkindex .tk/exmh/
and restart exmh.


FilerunnerLink to a different Web site natively support the wheel mice since version 2.4.1. I just put here for historical info my patches to filerunner 2.4Link to unformatted plain text. They should work with filerunner 2.3 too.

(Filerunner is in my opinion the best filemanager around, better than anything I have seen on Windows, Amiga or Macintosh. Try it!)


Has (of beta 4) wheel support, thanks to jamus jegierPop a mailto: email dialog box, see the KDE credits. These patches were first mailed to me by Felix IdePop a mailto: email dialog box. You can get a local copy of the patches to KDE Beta4, but you normally wont have to as they should be part of the main distribution by now...

Warning: KDE seems to be configured by default to use xrdb, thus disabling reading ~/.Xdefaults and app-default files. Be sure to remove it by a call to xrdb -remove

Actually (February 3 1999) things are not as clear as stated above, as Joe VotourPop a mailto: email dialog box told me by mail:

KDE 1.1pre1 has wheel mouse support if you use the IMWheel program (which is listed on your page). I got this information from the KDE documentation/FAQ at their website. According to the authors, KDE will integrate native wheel mouse support when Qt supports it (which is supposed to be version 2.0).
You can use the XFree86 ZAxisMapping feature only if you run xrdb -remove (as stated on your page). However, this will disable all KDE functionality in non-KDE programs (KDE1.1 allows most of your non-KDE programs to have a KDE look and feel, for example Netscape). In addition, xrdb must be done at the beginning of every KDE session, as I have found no way to disable it on startup (using a script placed in the Autostart folder didn't seem to work).
In short - use the IMWheel program, and your problems will be solved.

But I also received this email from Jamus Jegier elaborating on the status of the patch:

I just wanted to elaborate about my patch for KDE. Even though this old news, I just wanted to make it clear.
My patch did not add wheel functionality. It was to fix a bug that rendered any mouse with greater than 3 buttons useless. The code that caused the problem was the left-handed mouse button config. The psuedo code looked something like:
struct mousestuff;
if mouse_buttons=2 do ... if mouse_buttons=3 do ...
Thus, if the mouse does not have 2 or the buttons, mousestuff is in an undefined state. Since X Windows sees wheel mice as 5-button mice, the mouse config got screwed up, and rendered the mouse useless.
I hope this clears stuff up.
Also, native mousewheel support seems to be planned for Qt2.0, and in the meantime, kvt has added hardcoded supportin the version included in KDE 1.1


By Chuck HomicPop a mailto: email dialog box, and also with Tim B. LaursenPop a mailto: email dialog box, and Tobias WinterhalterPop a mailto: email dialog box:
      !# NEdit
      NEdit*text.Translations: #override\n\
      Shift<Btn4Down>,<Btn4Up>: scroll_up(1)\n\
      Shift<Btn5Down>,<Btn5Up>: scroll_down(1)\n\
      Ctrl<Btn4Down>,<Btn4Up>: previous_page()\n\
      Ctrl<Btn5Down>,<Btn5Up>: next_page(1)\n\
      <Btn4Down>,<Btn4Up>: scroll_up(3)\n\
      <Btn5Down>,<Btn5Up>: scroll_down(3)\n
I like it to do 3 lines at a time, but you can change that by changing the 3 to something else above. You can put this in .Xdefaults, or .nedit.
Note: It is impossible to scroll in the help window
- Tim

GlQuake (and Quake2)

Glquake on linux uses the svgalib, which only supports wheel mice since the 1.3.0 version that you can download from sunsite (either the binaryDownload a file to your disk drive or sourceDownload a file to your disk drive version). Otherwise, you can hack around old svgalib versions with the qkHack Library which emulates the libsvga on X, and works quite well (for Quake 1 and II)!.

I even hacked the qkHackLib to make the wheel send keycodes ("i" on up, "j" on down, and "k" on thumb button on mouseman+ logitech 4-button mice). You can get this version locally instead: qkHackLib-v0.5-colas.tgzDownload a file to your disk drive .


IMWheel is a quick hack to support older programs not supporting the wheel mouse, but undertanding keyboard accelerators to scroll. It does the simple conversion of mouse button presses into key presses, but with the nice feature of being configurable by windows classes and names.


GTK+ 1.2.x versions has support for mousewheel!

Curses (non-X, tty) apps


by Roy StognerPop a mailto: email dialog box:

To use the mouse wheel in non-X apps, it is possible to set an xterm to launch one specific app and use resources for that app only. For example, I still prefer pine to most windowed mail readers, and so my .Xdefaults includes:

      pine*vt100.translations: #override\n\
      <Btn4Down>,<Btn4Up>: string("^[OA")\n\
      <Btn5Down>,<Btn5Up>: string("^[OB")\n\
Warning You MUST replace the ^[ by the single non-printable ascii char "escape"!

The "string()" action in an xterm types the given characters into the running app, and the non-ascii stuff inside are the codes for up and down keys. You can type these in from vi by "Ctrl-V, Down" for example. If you don't like non-7bit-clean stuff in .Xdefaults the string action also takes unquoted 0x13 type arguments.

Then, starting pine with "xterm -name pine -title Pine -e pine" will start pine in it's own xterm which will obey the pine-specific resources.

Programs natively supporting the wheel

Star Office, the impressive Office suite for linux (and other OSes), free for personal use now supports the wheel in its 5.0 version. Please be sure to get also the first patch, as the first version was scrolling backwards!

Non-Working Programs

For these ones, the source must be patched. please patch them and mail me the patch, or better ask the author to patch them or send him the patch for inclusion in further releases!
Another solution is to use
ImWhellLink to another place further up on the same page above...

Being updated:

The following software should implement wheel support in the future:

Non-X, non-unix

May be of interest:

FAQ - Frequently Asked Questions

Q - Where do I apply the patch / I don't have a ~/.Xdefaults file?

A - Quick: create a text file name .Xdefaults in your home dir
Complete: look at the
section 21 of the Xt FAQ
RedHat users: Redhat, for some mysterious reason seems to use a .Xresources file in the home directory instead of a .Xdefaults. Replace .Xdefaults by .Xresources in this page for you if nothing happens when modifying .Xdefaults

Q - I want to "pan", like in some windows apps, hold a button then moving the mouse scrolls

A - This is a more high-level behavior, that is best implemented in toolkits. There is no solution on this page, you will find this features in toolkits (TCL+TK), or programs (drawing programs like Idraw, spreadsheets...) implementing this themselves

Q - Will this mouse/trackball/pointer work?

A - The first step is to have the wheel supported by the X server (XFree or others). I cannot help if it is not supported. You could always add support to XFree to the device yourself, but it is a difficult task, the mouse driving code in XFree is quite complex due to the integrated support of many different mice via a common finite state machine...

Q - I mailed you some time ago and you didnt answer?

A - Well, I have many things to do and I tend to process my mails by "batches". I will often read and answer to all the wheel-mouse related mails at once, maybe waiting for at least one month between batches :-(
You should try to use the newsgroup instead local forum if you want a quicker response...

Q - I want to use the side "thumb" button to something other than button2, or use a mouse with 4 buttons or more

A - Well, This seems difficult, due to the fact that the X protocol only supports 5 buttons and xmodmap do not allow to remap two physical buttons to the same logical value, so I have no solution here. The best way should be (and it would allow to use horizontal wheels too) should be to have the X server modified to send fake keyboard events on wheel events, not button events. Adding this to XFree would be nice.


You can also find this page translated in:


NOTE: If you want to be mailed when this page change, I advise you to use the excellent NetMind URL-MinderLink to a different Web site free web page monitoring service.

History of modifications: