Gecko:Mouse Wheel Scrolling

Overview

Gecko can have many scrollable frames at one time. This documents the detail of mouse wheel scrolling processing in Gecko.

Gecko honors mouse cursor position

Basically, turning mouse wheel scrolls a scrollable view under mouse cursor. This behavior was designed in bug 97283.

Note that on Windows, most mouse drivers honors keyboard focus rather than mouse cursor position. However, Internet Explorer and other web browsers honor the cursor position too. So, it's not a problem, probably.

There can be two or more scrollable frames under mouse cursor. Gecko decides one scrollable frame for the target by following rules:

1. Finds a frame under mouse cursor.
2. Checks whether the frame is scrollable to the direction by user operation.
3. If the frame is scrollable, Gecko scrolls the frame.
4. Otherwise, repeats the steps with its ancestor frames.

There is a special case. If gecko finds a drop down frame of a select element, it stops going up the frame hierarchy.

Mouse wheel transaction

By above rules, users can scroll one scrollable frame smoothly. However, when two or more scrollable frames are nested, we need additional rules.

For example, there is a page body which is scrollable and has a scrollable sub frame (e.g., listbox of select element with multiple attribute, div element with overflow property, iframe element). When an user is scrolling down the sub frame, it will be reached to the end of its content. However, some mouse wheel events which were fired after that will scroll the body unexpectedly.

And there is another example, when the user is scrolling the page body, the sub frame may come under mouse cursor. Then, the sub frame intercepts the mouse wheel events unexpectedly.

We can fix these problems by a simple idea. That is, all users may want to scroll only one scrollable frame at one time. So, we can assume that two or more mouse wheel events which are fired between short term should scroll only one scrollable frame. The frame must be the frame under cursor at the first mouse wheel event.

Gecko manages this transaction by nsMouseWheelTransaction which is in nsEventStateManager.cpp. This was implemented in bug 312831.

The rules for end of a transaction:

• When no mouse wheel events are fired during specified term after latest mouse wheel event. The length is defined by mousewheel.transaction.timeout. The value means millisecond and the default value is 1500.
• When mouse cursor moves to outside of the targeted scrollable frame.
• When mouse cursor moves inside the targeted frame. However, we need to ignore some mouse move events which are fired unexpectedly when the user turned wheel. mousewheel.transaction.ignoremovedelay defines the time of ignoring mouse move events before and after a mouse wheel event. The value is millisecond, the default value is 100.
• When a keydown or keyup or keypress event is fired.
• When a mouse button down or mouse button up or click or double click event is fired.
• When a context menu key event or dragdrop_drop event is fired.
• When a target frame is destroyed.

Note that the transaction is updated only when a mouse wheel event scrolls the target frame actually. I.e., when an user keeps to turn mouse wheel to unscrollable direction, the transaction will be timed out. This is important for touchpad users, see bug 442774.