Javascript Madness: Mouse Events

Introduction

The tests were done with the intention of learning just enough to write the code I needed to write. Many, many browsers have been tested over the years. The most recent test on each platform were done with the browser versions in the table below.

Tests were also performed on Netscape, Mozilla, Camino, Seamonkey and K-Meleon. These all use the same layout engine as Firefox, called "Gecko" and behave the same way as versions of Firefox with the same Gecko version, just as Safari, Chrome, Ephiphay all use the WebKit engine. In this article we will generally refer to Gecko and Webkit version numbers instead of any particular Gecko-based browser version numbers. See the Gecko/Webkit version table for the mapping between browser version numbers and layout engine version numbers.

Previous versions of this document included coverage of the iCab 3 browser, but more recent versions of iCab use WebKit, and so presumably behave exactly like the other WebKit browsers. Since it is unlikely that many web developers will want to go out of their way to support iCab 3, that material has been removed from this document and archived in a separate report on iCab 3.

The script used to collect the test results reported here is available at http://unixpapa.com/js/testmouse.html.

Mouse Buttons and Default Events

All browsers let you disable the default action of the left mouse button. I typically do this by ending the event handling function with the following code, which should cover all browsers:

    if (event.preventDefault)
        event.preventDefault();
    else
        event.returnValue= false;
    return false;

However, in some browsers the default actions of the right and middle mouse buttons cannot be disabled, or can only be disabled by changing browser settings. Such changes to browser settings typically effect all pages viewed through the browser, and typically cannot be done from Javascript. Since few users will want to do this, it pretty much means that the those mouse events are not usable from Javascript.

Netscape 4 pioneered this philosophy by making it impossible to disable the URL paste that occurs with a middle click, and requiring a config file edit to disable the context menus that come up with a right click. Firefox and the other Gecko browsers have released control of the right mouse button, but the default action of a middle click can only be disabled by a config file edit. (Update: in the last version of Firefox I tested, config options could be changed by going to the "about:config" URL, but no combination of settings there seemed sufficient to release control of the middle mouse button to Javascript).

The middle and right mouse buttons have never been fully usable in any version of Opera. The precise manner in which they were broken has, however, changed many times over the years:

• In Opera versions before 7.23 right click events were never sent to Javascript.

• In Opera 7.23, possibly as a result of complaints by yours truly, they added a preference option that can be checked to "Allow Javascript to receive right clicks". This option moved to at least three different places in subsequent releases, but eventually settled down as "Tools > Preferences > Advanced > Content > Javascript Options". It was renamed to "Allow scripts to detect context menu events" in Opera 10.

  However, initially this option was over generous. If you set up a event handler on any part of the page (like on the link on my mouse event test page then the context menu would be disabled not only over that link, but over the entire page. Furthermore, only mousedown events were sent, never mouseup.

• Sometime between the 7.54 and 8.5 release this was fixed, but only sort of. If you enable the right click option, Javascript receives the right click events, but the default action can not be disabled. The context menu always comes up. Without being able to disable the default action, being able to capture the event is almost completely useless.

The middle mouse button in Opera is broken too. It triggers an events, but the default action cannot be disabled. No fiddling with the manner of its brokeness has occured so far.

None of the WebKit browsers seem to have any problem with this. All mouse buttons can be used on all platforms.

So here's the final score card:

Event Triggering - Single Clicks

• mousedown - A mouse button has been pressed down.
• mouseup - A mouse button has been released.
• click - A mouse button has been clicked.
• dblclick - A mouse button has been double-clicked.
• contextmenu - Some action to trigger a context menu as occured.

The mousedown and mouseup events are meant mostly for situations where you depress the mouse button, move the mouse and then release it, say when a section of text is selected or when an object is dragged.

The click and dblclick events are meant mostly for situations where you are simply clicking on a link or a button. A click event normally occurs if there is a mousedown and a mouseup event on the same object. If you move the mouse to point to something else between mousedown and mouseup, then there will be no click event.

The contextmenu event is triggered on some browsers when you right click on something and it's default action is to bring up the browser's standard context menu. I think that in theory this event isn't really a mouse event. It might also be triggered by a keyboard shortcut. However it is usually associated with mouse clicks in practice.

If you do a single mouse click of the left mouse botton, every modern browser I've checked does exactly the same thing. When the mouse goes down, a mousedown event is triggered. When the mouse goes back up, first a mouseup event and then a click event is triggered. Very nice.

So, here's what happens when you do click on the right mouse button:

There are no click events for right button clicks in any browser.

Opera normally generates no events for the right mouse button. For some past versions there was an option that could be turned on to make them generate events, but that no longer exists.

Notice that the contextmenu event does not exist in all browsers, and occurs at different times in different browsers. I think this relates to the different behavior of the context menus in different browsers. For example, in Firefox, the context menu comes up when the mouse key is depressed, while, in IE and Chrome, it don't come up until the mouse is released.

There is not a lot of consistency in the behavior of the WebKit browsers on this, though the only one that is distinctly bad is Epiphany, which fails to send a mousedown. The others vary only on the timing of the contextmenu event.

The Opera versions that give you no mouseup are not that much a concern because they are old and the default actions of right clicks can't be disabled from Javascript anyway.

The question of what happens on middle clicks is less academic than it used to be. In the olden days, only Unix machines commonly had three button mice. But now most Windows mice have a scroll wheel between the two buttons that can be clicked and acts as a middle button. However, Firefox and Opera still have default actions associated with middle mouse buttons that cannot be disabled from Javascript, So only in Internet Explorer, Konqueror, and the WebKit browsers does the middle mouse button really work.

Note that there is some disagreement about whether or not there should be a click event for middle buttons and older versions of Opera were broken, but otherwise things are pretty sensible.

Event Triggering - Double Clicks

Internet Explorer has the annoying property of not giving a mousedown on the second click of a double click. In fact there is no event fired then at all.

Ancient versions of the Mozilla browsers made up for IE's lack of a mousedown event on the second click by sending two, so that overall, a double click sent three mousedown events. Macintosh versions of Gecko never had this problem and always behaved the same way that Gecko 1.7 does.

To my astonishment and disgust, new Linux versions of the WebKit browsers Chrome and Epiphany have the same double mousedown bug on double clicks. This bug has been reported to Google.

What older versions of Opera were up to is hard to imagine. That the first click event was on a mouseup, but the second was on mousedown was just the beginning of the madness.

Luckily, recent versions of the Mozilla browser and Opera have adopted sane behaviors, and the older versions are mostly out of circulation by now (Gecko 1.6 was last used in Firefox 0.8). The Safari developers wisely chose this as one of their rare instances of incompatibility with IE and chose to emulate Gecko instead.

Right button double click events are listed in the next table. Newer versions of Opera are not listed here, because it is no longer possible to execute a right button double click in Opera. The first click cannot be stopped from activating the context menu, so the second click is caught by the context window, not the browser window.

Happily, IE doesn't omit the second mousedown event in this case, but old versions of Gecko and new Linux WebKit browsers stutter on it just as they do on all the other buttons. Epiphany combines the stutter with missing mousedown events to achieve glorious new levels of brokeness.

If we ignore the stutters, then all browsers treat this simply as two clicks in a row, not a doubleclick.

Opera is omitted from this table because it normally doesn't generate right click events. In the old versions which had an option to enable right clicks, double clicks were just treated as two single clicks.

Finally, here are the events for double-clicks on the middle button, a button that isn't actually usable Gecko and Opera. Like the right click case, this is mostly just treated as two single clicks.

This is pretty much what you'd expect except that here, for once, the WebKit browsers do not perfectly emulate IE. Of course, it makes perfect sense that dblclick should be fired if click is, and firing an extra event is unlikely to cause compatibility problems, so this is probably a good choice.

Identifying Mouse Buttons

It used to be that every browser used a different combination of values to indicate the buttons, but there has been a gradual convergence on a standard now, so all browsers except IE work alike:

The event.which value was originally used in Netscape, and the event.button value was originally used in Internet Explorer. Later browers used both, and messed them both up. Event.button was an especially hopeless mess, with different browsers returning 1, 2, 3 or 4 for a middle mouse click. Event.which is better, except that old versions of Opera got the middle and right mouse buttons mixed up, and IE doesn't return it at all.

Note that IE returns useful values in event.button only on mousedown and mouseup events. It is not possible to identify the mouse button for a click, dblclick or contextmenu event because event.button will be zero regardless of which button was pressed.

A further IE oddity becomes apparent if you hold down more than one mouse button at a time. On mousedown events, IE returns the boolean-or of the values for all mouse buttons currently depressed. So if you hold down both the left and right mouse buttons, the second mousedown event will have event.button=3. IE does not do this on mouseup events, and no other browsers do this on any events.

Newer versions of most browsers except IE have converged on column three of this table, which is the W3C standard. It's encouraging to increasingly see standards taking hold where they exist.

Some mice now have more buttons than three buttons. I've done a few tests of this on a Linux system with a five button mouse. In Gecko and Opera, the extra buttons have the same values as the left mouse button, event.which=1, and event.button=0. In Konqueror 3.5 both extra buttons give event.which=65536, and event.button=0, which are at least different from any of the other three buttons, but may well be intended as error codes.

The end result? While there is no browser-independent way to recognize which mouse button is which for all the browsers surveyed, you can come extremely close. The following test works for all browsers except Opera 7. (It mixes up the right and middle mouse buttons in Opera 7, but Opera 7 is pretty old, there were only a few versions where the right and middle buttons even worked, and then only if the user set an obscure option, so you really don't care.) It also doesn't correctly handle simultaneous clicks of multiple mouse buttons in IE. To do that your application needs to track which buttons were reported to be down in previous mousedown events so it can figure out which one was added.

    if (event.which == null)
       /* IE case */
       button= (event.button < 2) ? "LEFT" :
                 ((event.button == 4) ? "MIDDLE" : "RIGHT");
    else
       /* All others */
       button= (event.which < 2) ? "LEFT" :
                 ((event.which == 2) ? "MIDDLE" : "RIGHT");

If you don't have any other compelling reason to prefer one event over another, it's probably generally best to attach your event handlers to mouseup. IE has annoying little problems with the others (click doesn't identify the mouse button, and mousedown ORs together mouse button values and isn't fired on the second click of a double click) and WebKit versions of Epiphany fail to send mousedown. Triggering on mouseup also means that users get a last chance to change their mind about clicking on something - they can move their mouse off the control before releasing the button.

Finding Mouse Positions

• Screen Coordinates: These are coordinates measured from the top left corner of the user's computer screen. You'd rarely get coordinates (0,0) because that is usually outside the browser window. About the only time you'd want these coordinates is if you want to position a newly created browser window at the point where the user clicked.

  In all browsers these are in event.screenX and event.screenY.

• Window Coordinates: These are coordinates measured from the top left corner of the browser's content area. If the window is scrolled, vertically or horizontally, this will be different from the top left corner of the document. This is rarely what you want.

  In all browsers these are in event.clientX and event.clientY.

• Document Coordinates: These are coordinates measured from the top left corner of the HTML Document. These are the coordinates that you most frequently want, since that is the coordinate system in which the document is defined.

  In most browsers these coordinates are returned in event.pageX and event.pageY. But IE does not implement these. For IE, you need to compute them by adding the current scrolling offset to the the window coordinates. Unfortunately, the scrolling offset is stored in different places in different versions of IE, so this gets a bit complex:

     if (event.pageX == null)
     {
        // IE case
        var d= (document.documentElement && 
                document.documentElement.scrollLeft != null) ?
               document.documentElement : document.body;
        docX= event.clientX + d.scrollLeft;
        docY= event.clientY + d.scrollTop;
     }
     else
     {
        // all other browsers
        docX= event.pageX;
        docY= event.pageY;
     }
  

  A demo of this code is available.

• Target Coordinates: These are coordinates measured within the HTML element that is the target of the event. If you wanted to know where on a element the user clicked, then this is what you'd want.

  Theoretically, the event.offsetX and event.offsetY values are supposed to contain this, but forget it. There are so many bugs and incompatibilities in these values that they are essentially completely useless.

  Instead you'll need to subtract the document coordinates of the target element from the document coordinates of the mouse click. (If you are computing the coordinates of the target element, remember that offsetLeft and offsetTop are relative to offsetParent which is not necessarily the document. You may need to climb the chain of offsetParents adding up offsets as you go.)

Mouseover and Mouseout

There are some other mouse events. The mouseover and mouseout events are triggered whenever the mouse moves on to or off of an object. The mousemove event is triggered whenever the mouse is moved. These events are handled pretty consistently in different browsers so far as I have been able to tell, but there are some oddities.

A test script for the mouseover and mouseout events is available at http://unixpapa.com/js/testover.html. The test script shows two nested <DIV> blocks, with some text inside the inner one. It's important to note that in all browsers, when the mouse moves from the outer block into the inner block, there is a mouseout event fired for the outer block. The concept is that the mouse is never "in" more than one object at a time, and the one it is "in" is the frontmost of those in whose enclosing box it falls.

Internet Explorer has some additional events, mouseenter and mouseleave which fire only when you cross the outer boundaries of objects. These are more convenient for many applications, however no other browser supports these events.

Safari 3 and other modern Webkit browsers seem to handle mouseover and mouseout correctly, but older versions of Safari had real problems. They also generated mouseover and mouseout events for text nodes. So, on the test page, when you moved the mouse over the text inside the inner <DIV> you would get a mouseout event on the <DIV> and then a mouseover event on the text. I don't think other browsers can even fire events on text nodes.

In Safari 1.3, the mouseover event fires when the mouse pointer enters the rectangular box surrounding the text. This was strange but understandable. In Safari 2.0, when you swept the mouse pointer over some text in a <DIV> you would get dozens and dozens of mouseover and mouseout events. At first I thought they were triggering events on the actual boundaries of the letters, but that didn't seem to be the case. Then I noticed that on the text you get only mouseout events, and on the <DIV> you only get mouseover events, so basically the firing of these events as you go over text was just completely wacky.

In applications it's usually the spurious mouseout events on the <DIV> that cause problems. In Safari 2.0, you only get spurious mouseover events, which are usually less of a problem. The best general solution I've found for Safari 1.3 is to have the event handler on the <DIV> check if the mouse is still actually within the bounds of the <DIV> and ignore the event if it is. Since finding mouse coordinates and block borders is pretty browser dependent too, and takes a bit of computation, I tend to perform that test only on Safari.

Drag and Text Selection Events

However, even if you don't want to drop and drag anything, it is worth knowing a bit about these things, because they can interfere with ordinary mousing around. Sometimes the browser will decide that the user is trying to do a drag, and everything will go wrong. Events like mousemove and mouseover stop firing when the browser thinks a drag is in progress.

In most browsers, just disabling the browser default action on the mousedown event (see above for how to do this). seems to disable this. I'm pretty sure that in older versions of gecko it was necessary to disable the default action on the dragstart event, but this no longer seems necessary.

There are also events fired in some browsers when text is selected with the mouse. These also may be undesirable if you are trying to have something else happen with mouse clicks. I've never had any luck disabling these, though I've heard that canceling the browser default on the selectstart event can help with this on some browsers.