Warning:
This wiki has been archived and is now read-only.
Mousewheel
WebApps ⇨ DOM3Events ⇨ Mousewheel
The mousewheel event allows authors to capture and act on user-generated wheel activity.
Contents
Use Cases and Requirements
The mousewheel event must be available from a variety of devices:
- mouses and other pointer devices with a wheel button
- static jogwheels not attached to pointers (such as on mobile devices)
- trackpads or tablets which simulate a scrolling event
- scrollballs which allow free range of movement along the x and y axes
It must include vertical and horizontal movement, and a combination of both (so you don't get a "stairstep" effect for diagonal movement).
It should include a z-axis for future extensibility.
It should allow authors to override the default action for either x, y, or z activity independently.
Proposals
Proposal 1: Single Event With Multiple WheelDeltas
Note that this proposal builds on, but simplifies, previous proposals, and on the text of the MultiMouseWheel section of the current DOM3 Events draft. This is not complete specification prose, and the final spec should use the format and content of the current draft, modulo the name and attribute changes, and with the descriptions of wheelDelta presented here.
This module defines the feature MouseWheelEvents 3.0 and depends on the feature MouseEvents 3.0.
Mousewheels are devices that can be rotated in one or more spatial dimensions. The coordinate system depends on the environment configuration. As an example, the environment may be configured to associate vertical scrolling with rotation along the y-axis, horizontal scrolling with rotation along the x-axis, and zooming with rotation along the z-axis. The delta attributes of MouseMultiWheelEvent objects indicate the distance of the rotation. The measurement unit depends on the environment configuration. The sign of the delta value should indicate the direction of the rotation.
Interface MouseWheelEvent (introduced in DOM Level 3)
The MouseWheelEvent interface provides specific contextual information associated with mousewheel events.
To create an instance of the MouseWheelEvent interface, use the DocumentEvent.createEvent("MouseWheelEvent") method call.
IDL Definition
// Introduced in DOM Level 3:
interface MouseWheelEvent : MouseEvent {
readonly attribute long wheelDelta;
readonly attribute long wheelDeltaX;
readonly attribute long wheelDeltaY;
readonly attribute long wheelDeltaZ;
void initMouseWheelEventNS(in DOMString namespaceURI,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersList,
in long wheelDeltaArg,
in long wheelDeltaXArg,
in long wheelDeltaYArg,
in long wheelDeltaZArg);
};
If the mousewheel event is canceled, the default action for wheeling along all axes is canceled.
wheelDelta
A number indicating the distance, measured as the number of "rolls" the
wheel has been rotated. A positive value must indicate that the wheel has been
rotated away from the user on vertically-aligned devices or in a left-hand manner
on horizontally aligned devices, and a negative value must indicate that the wheel
has been rotated towards the user on vertically-aligned devices or in a right-hand
manner on horizontally aligned devices. The value of the wheelDelta must be the
largest of the wheelDeltaX, wheelDeltaY, and wheelDeltaZ values. The default
value of the wheelDelta attribute must be 0.
A "roll" is defined to be a unit of rotation. On some devices this is a
finite physical step. On devices with smooth rotation, a "roll" becomes the
smallest reported amount of rotation.
"Rotation" is defined to be an indication of incremental change. On some
devices this is a literal rotation of a wheel, while on others, it may be
movement along a flat surface, or pressure on a particular button.
NOTE: add text to indicate that there is no upper bound on the rolls, unlike IE (which defines the roll as a fraction of 160)
NOTE: changed term from "clicks" to "rolls", so as not to be confused with mouse clicks; "degrees" and "radians" were too specific, and "smidgens" is maybe a little too informal.
wheelDeltaX is a number indicating the horizontal distance (in the same manner as described in wheelDelta).
wheelDeltaY is a number indicating the vertical distance (in the same manner as described in wheelDelta).
wheelDeltaZ, included for future extensibility, is a number indicating the distance along a depth axis (positive means rotated upwards, means rotated downwards). At the present time, implementors may use whatever modality is best suited to the task, such as the the use of the wheel in conjunction with a control key.
The default value of wheelDeltaX, wheelDeltaY and wheelDeltaZ is 0. UIEvent.detail must always be 0.
This event includes both wheel deltas. The default action of this event is to dispatch a mousewheel event if the y delta is non-zero. Besides that, its default action is to do whatever platform conventions suggest for the wheeling behavior.
Problems
This proposal does not allow individual wheel axes to be canceled independently. However, authors could make a workaround by canceling the original event and generating a new one with the values they wish. It's not clear if this workaround addresses the concerns of Ian Hickson (see also ISSUE-84, a proposal by Maciej Stachowiak, and a recent comment by Anne van Kesteren).
Proposal 2: Multiple WheelDelta Events With Hierarchy
Note that The name of the top-level event was a matter of some contention. The WG decided upon "mousemultiwheel", but since this implies multiple mice or multiple wheels (such as in a multi-touch interface, this proposal users the name "mouseomniwheel", implying omnidirectional movement.
Note also that this proposal is the original proposal submitted to the WG, and that it assumes a different directionality for horizontal values (positive means rotated to the right, negative means rotated to the left), which is an orthogonal issue to the matter of hierarchy.
When "mouse wheeling" occurs, the implementation must dispatch a
mouseomniwheel event implementing the following interface:
interface MouseOmniWheelEvent : MouseEvent {
readonly attribute long wheelDeltaX;
readonly attribute long wheelDeltaY;
readonly attribute long wheelDeltaZ;
void initMouseOmniWheelEventNS(in DOMString namespaceURI,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersList,
in long wheelDeltaX,
in long wheelDeltaY,
in long wheelDeltaZ);
};
wheelDeltaX is a number indicating the horizontal distance (positive means rotated to the right, negative means rotated to the left).
wheelDeltaY is a number indicating the vertical distance (positive means rotated away from user or to the right, negative means rotated towards user or to the left).
wheelDeltaZ, included for future extensibility, is a number indicating the distance along a third unspecified axis (positive means rotated away from the user, means rotated towards user). At the present time, implementors may use whatever modality is best suited to the task, such as the the use of the wheel in conjunction with a control key.
The default value of wheelDeltaX, wheelDeltaY and wheelDeltaZ is 0. UIEvent.detail must always be 0.
This event includes both scroll deltas. The default action of this event is to
dispatch a mousewheel event if the y delta is non-zero. Besides
that, its default action is to do whatever platform conventions suggest for the
wheeling behavior.
The mousewheel event implements the following interface:
interface MouseWheelEvent : MouseEvent {
readonly attribute long wheelDelta;
void initMouseWheelEventNS(in DOMString namespaceURI,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersList,
in long wheelDelta);
};
If the mousewheel event is cancelled, only the default action for
vertical wheeling is cancelled.
wheelDelta
A number indicating the distance, measured as the number of "clicks" the
wheel has been rotated. A positive value indicates that the wheel has been rotated
away from the user (or in a right-hand manner on horizontally aligned devices) and
a negative value indicates that the wheel has been rotated towards the user (or in
a left-hand manner on horizontally aligned devices). The default value of the
wheelDelta attribute is 0.
A "click" is defined to be a unit of rotation. On some devices this is a
finite physical step. On devices with smooth rotation, a "click" becomes the
smallest reported amount of rotation.
Open Questions
- What about UIEvent.detail?
- MouseEvent.relatedNode
For bothmouseomniwheelandmousewheel,MouseEvent.relatedNodemust indicate the element over which the pointer is located, ornullif there is no such element (in the case where the device does not have a pointer, but does have a wheel).
- What is the relationship to the
scrollevent?
Proposal 3: Separate Events for Legacy MouseWheel Events and New Wheel Events
This proposal uses the MouseWheelEvent<code> interface for the legacy event, and introduces a new <code>WheelEvent<code> interface as defined below.
This module defines the feature WheelEvents 3.0 and depends on the feature MouseEvents 3.0.
Wheels are devices that can be rotated in one or more spatial dimensions, and which may or may not be associated with a pointer device. The coordinate system depends on the environment configuration. As an example, the environment may be configured to associate vertical scrolling with rotation along the y-axis, horizontal scrolling with rotation along the x-axis, and zooming with rotation along the z-axis. The deltax, deltaY, and deltaX attributes of WheelEvent objects indicate the distance of the rotation, as specified in the delta definition.
delta The distance the wheel has rotated around the its axis. The value of a delta is a floating-point number indicating a distance, measured as the number of rolls the wheel has been rotated. A positive value shall indicate that the wheel has been rotated away from the user on vertically-aligned devices or in a left-hand manner on horizontally aligned devices, and a negative value shall indicate that the wheel has been rotated towards the user on vertically-aligned devices or in a right-hand manner on horizontally-aligned devices. The default value of a delta attribute shall be 0.
roll A unit of rotation for a device using the WheelEvent interface. On some devices this is a finite physical step. On devices with smooth rotation, a roll becomes the smallest reported amount of rotation.
rotation An indication of incremental change. On some devices this is a literal rotation of a wheel, while on others, it may be movement along a flat surface, or pressure on a particular button.
Interface WheelEvent (introduced in DOM Level 3)
The WheelEvent interface provides specific contextual information associated with mouse multi wheel events.
To create an instance of the WheelEvent interface, use the DocumentEvent.createEvent("WheelEvent") method call.
IDL Definition
// Introduced in DOM Level 3:
interface WheelEvent : MouseEvent {
readonly attribute long deltaX;
readonly attribute long deltaY;
readonly attribute long deltaZ;
void initWheelEventNS(in DOMString namespaceURIArg,
in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg,
in DOMString modifiersListArg,
in long deltaXArg,
in long deltaYArg,
in long deltaZArg);
};
Attributes
deltaX of type long, readonly
The distance the wheel has rotated around the x-axis.
deltaY of type long, readonly
The distance the wheel has rotated around the y-axis.
deltaZ of type long, readonly
The distance the wheel has rotated around the z-axis.
Methods
initWheelEventNS
Initializes attributes of a WheelEvent object. This method has the same behavior as MouseEvent.initMouseEventNS().
Parameters
namespaceURIArg of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
typeArg of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
cancelableArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
detailArg of type long
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
screenXArg of type long
Refer to the MouseEvent.initMouseEventNS() method for a description of this parameter.
screenYArg of type long
Refer to the MouseEvent.initMouseEventNS() method for a description of this parameter.
clientXArg of type long
Refer to the MouseEvent.initMouseEventNS() method for a description of this parameter.
clientYArg of type long
Refer to the MouseEvent.initMouseEventNS() method for a description of this parameter.
buttonArg of type unsigned short
Refer to the MouseEvent.initMouseEventNS() method for a description of this parameter.
relatedTargetArg of type EventTarget
Refer to the MouseEvent.initMouseEventNS() method for a description of this parameter.
modifiersListArg of type DOMString
Refer to the MouseEvent.initMouseEventNS() method for a description of this parameter.
deltaXArg of type long
Specifies WheelEvent.deltaX.
deltaYArg of type long
Specifies WheelEvent.deltaY.
deltaZArg of type long
Specifies WheelEvent.deltaZ.
No Return Value
No Exceptions
wheel Type wheel Namespace None Interface WheelEvent Cancelable Yes Bubbles Yes Target Document, Element Context info WheelEvent.deltaX, WheelEvent.deltaY, WheelEvent.deltaZ, MouseEvent.altKey, MouseEvent.ctrlKey, MouseEvent.shiftKey, MouseEvent.metaKey, and UIEvent.view are in use. MouseEvent.screenX, MouseEvent.screenY, MouseEvent.clientX, MouseEvent.clientY, and MouseEvent.button are in use if the wheel is associated to a pointing device. MouseEvent.relatedTarget indicates the event target the pointing device is pointing at, if any. UIEvent.detail is not in use.
A mouse wheel has been rotated. A default action of user agent generated event objects of this type causes implementations to dispatch a mousewheel event iff it supports that event type and WheelEvent.deltaY is non-zero.