mozilla
Your Search Results

    wheel

    The wheel event is fired when a wheel button of a pointing device (usually a mouse) is rotated. This event replaces the non-standard deprecated mousewheel event.

    General info

    Interface
    WheelEvent
    Synchronicity
    asynchronous
    Bubbles
    Yes
    Cancelable
    Yes
    Target
    defaultView, Document, Element
    Default Action
    Scroll, moving history, or zooming in/out.

    Properties

    This event implements the properties of WheelEvent, MouseEvent, UIEvent and Event.

    Properties of WheelEvent

    This interface inherits properties from its parents, MouseEvent, UIEvent and Event.

    WheelEvent.deltaX Read only
    Returns a double representing the horizontal scroll amount.
    WheelEvent.deltaY Read only
    Returns a double representing the vertical scroll amount.
    WheelEvent.deltaZ Read only
    Returns a double representing the scroll amount for the z-axis.
    WheelEvent.deltaMode Read only
    Returns an unsigned long representing the unit of the delta values scroll amount. Permitted values are:
    Constant Value Description
    DOM_DELTA_PIXEL 0x00 The delta values are specified in pixels.
    DOM_DELTA_LINE 0x01 The delta values are specified in lines.
    DOM_DELTA_PAGE 0x02 The delta values are specified in pages.

    Properties of MouseEvent

    This interface also inherits properties of its parents, UIEvent and Event.

    MouseEvent.altKey Read only
    Returns true if the alt key was down when the mouse event was fired.
    MouseEvent.button Read only
    The button number that was pressed when the mouse event was fired. 
    MouseEvent.buttons Read only

    The buttons being pressed when the mouse event was fired

    MouseEvent.clientX Read only
    The X coordinate of the mouse pointer in local (DOM content) coordinates.
    MouseEvent.clientY Read only
    The Y coordinate of the mouse pointer in local (DOM content) coordinates.
    MouseEvent.ctrlKey Read only
    Returns true if the control key was down when the mouse event was fired.
    MouseEvent.metaKey Read only
    Returns true if the meta key was down when the mouse event was fired.
    MouseEvent.movementX Read only
    The X coordinate of the mouse pointer relative to the position of the last mousemove event.
    MouseEvent.movementY Read only
    The Y coordinate of the mouse pointer relative to the position of the last mousemove event.
    MouseEvent.region Read only
    Returns the id of the hit region affected by the event. If no hit region is affected, null is returned.
    MouseEvent.relatedTarget Read only

    The secondary target for the event, if there is one.

    MouseEvent.screenX Read only
    The X coordinate of the mouse pointer in global (screen) coordinates.
    MouseEvent.screenY Read only
    The Y coordinate of the mouse pointer in global (screen) coordinates.
    MouseEvent.shiftKey Read only
    Returns true if the shift key was down when the mouse event was fired.
    MouseEvent.which Read only
    The button being pressed when the mouse event was fired.
    MouseEvent.mozPressure Read only
    The amount of pressure applied to a touch or tablet device when generating the event; this value ranges between 0.0 (minimum pressure) and 1.0 (maximum pressure).
    MouseEvent.mozInputSource Read only

    The type of device that generated the event (one of the MOZ_SOURCE_* constants listed below). This lets you, for example, determine whether a mouse event was generated by an actual mouse or by a touch event (which might affect the degree of accuracy with which you interpret the coordinates associated with the event). The possible values are:

    Constant name Value Desription
    MouseEvent.MOZ_SOURCE_UNKNOWN 0 The input device is unknown.
    MouseEvent.MOZ_SOURCE_MOUSE 1 The event was generated by a mouse (or mouse-like device).
    MouseEvent.MOZ_SOURCE_PEN 2 The event was generated by a pen on a tablet.
    MouseEvent.MOZ_SOURCE_ERASER 3 The event was generated by an eraser on a tablet.
    MouseEvent.MOZ_SOURCE_CURSOR 4 The event was generated by a cursor.
    MouseEvent.MOZ_SOURCE_TOUCH 5 The event was generated on a touch interface.
    MouseEvent.MOZ_SOURCE_KEYBOARD 6 The event was generated by a keyboard.

    Properties of UIEvent

    This interface also inherits properties of its parent, Event.

    UIEvent.cancelBubble
    Is a Boolean indicating whether the bubbling of the event has been canceled or not.
    UIEvent.detailRead only
    Returns a long that gives some detail about the event, depending on the type of event.
    UIEvent.isChar Read only
    Returns a Boolean indicating whether the event produced a key character or not.
    UIEvent.layerX Read only
    Returns the horizontal coordinate of the event relative to the current layer.
    UIEvent.layerY Read only
    Returns the vertical coordinate of the event relative to the current layer.
    UIEvent.pageX Read only
    Returns the horizontal coordinate of the event relative to the whole document.
    UIEvent.pageY Read only
    Returns the vertical coordinate of the event relative to the whole document.
    UIEvent.viewRead only
    Returns a WindowProxy that contains the view that generated the event.
    UIEvent.which Read only
    Returns the numeric keyCode of the key pressed, or the character code (charCode) for an alphanumeric key pressed.

    Properties of Event

    Event()
    Creates an Event object.

    Properties

    This interface doesn't inherit any property.

    Event.bubbles Read only
    A boolean indicating whether the event bubbles up through the DOM or not.
    Event.cancelable Read only
    A boolean indicating whether the event is cancelable.
    Event.currentTarget Read only
    A reference to the currently registered target for the event.
    Event.defaultPrevented Read only
    Indicates whether or not event.preventDefault() has been called on the event.
    Event.eventPhase Read only
    Indicates which phase of the event flow is being processed.
    Event.explicitOriginalTarget Read only
    The explicit original target of the event (Mozilla-specific).
    Event.originalTarget Read only
    The original target of the event, before any retargetings (Mozilla-specific).
    Event.target Read only
    A reference to the target to which the event was originally dispatched.
    Event.timeStamp Read only
    The time that the event was created.
    Event.type Read only
    The name of the event (case-insensitive).
    Event.isTrusted Read only
    Indicates whether or not the event was initiated by the browser (after a user click for instance) or by a script (using an event creation method, like event.initEvent)

    Methods

    This event implements the methods of WheelEvent, MouseEvent, UIEvent and Event.

    Methods of WheelEvent

    This interface doesn't define any methods, but inherits methods from its parents, MouseEvent, UIEvent and Event.

    Methods of MouseEvent

    This interface also inherits methods of its parents, UIEvent and Event.

    MouseEvent.getModifierState()
    Returns the current state of the specified modifier key. See the KeyboardEvent.getModifierState() for details.
    MouseEvent.initMouseEvent()
    Initializes the value of a MouseEvent created. If the event has already being dispatched, this method does nothing.

    Methods of UIEvent

    This interface also inherits methods of its parent, Event.

    UIEvent.initUIEvent()
    Initializes a UIEvent object. If the event has already being dispatched, this method does nothing.

    Methods of Event

    This interface doesn't inherit any method.

    Event.initEvent()
    Initializes the value of an Event created. If the event has already being dispatched, this method does nothing.
    Event.preventBubble() Obsolete since Gecko 24
    Prevents the event from bubbling. Obsolete, use event.stopPropagation instead.
    Event.preventCapture() Obsolete since Gecko 24
    Obsolete, use event.stopPropagation instead.
    Event.preventDefault()
    Cancels the event (if it is cancelable).
    Event.stopImmediatePropagation()
    For this particular event, no other listener will be called. Neither those attached on the same element, nor those attached on elements which will be traversed later (in capture phase, for instance)
    Event.stopPropagation()
    Stops the propagation of events further along in the DOM.
    Event.getPreventDefault()
    ?

    Specifications

    Specification Status Comment
    Document Object Model (DOM) Level 3 Events Specification
    The definition of 'wheel' in that specification.
    Working Draft Initial definition.

    Browser compatibility

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
    Basic support 31 17.0 (17.0) 9.0[1] Not supported 7.0.5
    Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
    Basic support ? 17.0 (17.0) ? ? ?

    [1] Internet Explorer exposes the wheel event only via addEventListener, there is no onwheel attribute on DOM objects. Bug report.
     

    Listening to this event across browser

    The following script creates a global addWheelListener method that allows to listen to the different wheel events across browsers and prevent the default behavior.

    // creates a global "addWheelListener" method
    // example: addWheelListener( elem, function( e ) { console.log( e.deltaY ); e.preventDefault(); } );
    (function(window,document) {
    
        var prefix = "", _addEventListener, onwheel, support;
    
        // detect event model
        if ( window.addEventListener ) {
            _addEventListener = "addEventListener";
        } else {
            _addEventListener = "attachEvent";
            prefix = "on";
        }
    
        // detect available wheel event
        support = "onwheel" in document.createElement("div") ? "wheel" : // Modern browsers support "wheel"
                  document.onmousewheel !== undefined ? "mousewheel" : // Webkit and IE support at least "mousewheel"
                  "DOMMouseScroll"; // let's assume that remaining browsers are older Firefox
    
        window.addWheelListener = function( elem, callback, useCapture ) {
            _addWheelListener( elem, support, callback, useCapture );
    
            // handle MozMousePixelScroll in older Firefox
            if( support == "DOMMouseScroll" ) {
                _addWheelListener( elem, "MozMousePixelScroll", callback, useCapture );
            }
        };
    
        function _addWheelListener( elem, eventName, callback, useCapture ) {
            elem[ _addEventListener ]( prefix + eventName, support == "wheel" ? callback : function( originalEvent ) {
                !originalEvent && ( originalEvent = window.event );
    
                // create a normalized event object
                var event = {
                    // keep a ref to the original event object
                    originalEvent: originalEvent,
                    target: originalEvent.target || originalEvent.srcElement,
                    type: "wheel",
                    deltaMode: originalEvent.type == "MozMousePixelScroll" ? 0 : 1,
                    deltaX: 0,
                    deltaZ: 0,
                    preventDefault: function() {
                        originalEvent.preventDefault ?
                            originalEvent.preventDefault() :
                            originalEvent.returnValue = false;
                    }
                };
                
                // calculate deltaY (and deltaX) according to the event
                if ( support == "mousewheel" ) {
                    event.deltaY = - 1/40 * originalEvent.wheelDelta;
                    // Webkit also support wheelDeltaX
                    originalEvent.wheelDeltaX && ( event.deltaX = - 1/40 * originalEvent.wheelDeltaX );
                } else {
                    event.deltaY = originalEvent.detail;
                }
    
                // it's time to fire the callback
                return callback( event );
    
            }, useCapture || false );
        }
    
    })(window,document);

    Gecko notes

    The event order with legacy mouse scroll events

    If a trusted wheel event is not consumed, a DOMMouseScroll event and a MozMousePixelScroll event are fired for backward compatibility. Their attribute values are computed from the wheel event's delta values and the nearest ancestor clipped element (i.e., overflow is not visible). If either wheel event or one of the legacy events is consumed by event.preventDefault(), nothing happens.

    The event order is:

    1. A wheel event in the default event group (both web applications and add-ons can handle the events in this group)
    2. A vertical DOMMouseScroll event in both event group if accumulated deltaY of consecutive wheel events become larger than 1.0 or less than -1.0
    3. A vertical MozMousePixelScroll event in both event group if deltaY of the latest wheel event isn't zero
    4. A horizontal DOMMouseScroll event in both event group if accumulated deltaX of consecutive wheel events become larger than 1.0 or less than -1.0
    5. A horizontal MozMousePixelScroll event in both event group if deltaX of the latest wheel event isn't zero
    6. A wheel event in the system group (only add-ons can handle in this group)
    What happens if preventDefault() of each event called?
    wheel (default event group) preventDefault() called        
    DOMMouseScroll (Vertical) Not fired preventDefault() called      
    MozMousePixelScroll (Vertical) Not fired defaultPrevented is true preventDefault() called    
    DOMMouseScroll (Horizontal) Not fired Not affected Not affected preventDefault() called  
    MozMousePixelScroll (Horizontal) Not fired Not affected Not affected defaultPrevented is true preventDefault() called
    wheel (system event group) defaultPrevented is true defaultPrevented is true defaultPrevented is true defaultPrevented is true defaultPrevented is true

    If an Add-on needs to know if one of legacy events are consumed by web contents, it can use the wheel event of #6. See the document of nsIEventListenerService for the detail of system event group.

    The delta values and default action of trusted events can be customized by user preferences (details). Therefore, any web developers shouldn't expect a particular action would occur after receiving this event.

    The delta values

    The delta values do not indicate the actual scroll amount by default. If the user was holding a modifier key when moving the scroll wheel, the wheel action may cause another action such as moving forward or backward through browser history or zooming in or out. In addition, even when scrolling, the scrolled element may be different from its event target. The wheel event target is computed only from the mouse cursor position at the time at which the event was fired. That event may not only not be the one actually being scrolled, but may not even be scrollable.

    The deltaMode value

    On Windows, following 3 native events cause DOM wheel events.

    WM_MOUSEWHEEL (Vertical mouse wheel event)
    The deltaMode can be DOM_DELTA_LINE or DOM_DELTA_PAGE. It depends on user settings of Windows (The defualt setting causes DOM_DELTA_LINE).
    WM_MOUSEHWHEEL (Horizontal mouse wheel event)
    The deltaMode can be DOM_DELTA_LINE or DOM_DELTA_PAGE. However, neither wheel scroll speed setting dialog of Windows nor similar UI of each mouse driver's utility typically has the UI to change to page scroll. So, typically, this value is DOM_DELTA_LINE.
    WM_GESTURE (Only when caused by panning)
    The deltaMode is always DOM_DELTA_PIXEL. But note that most touchpad devices of notebook emulate mouse wheel events rather than using this event. This event it typically used on tablet PC.

    On Mac, deltaMode value depends on the device. If the device supports high resolution scroll by pixels, deltaMode value is typically DOM_DELTA_PIXEL. However, the user can change it to DOM_DELTA_LINE with "mousewheel.enable_pixel_scrolling" pref.  If the device doesn't support high resolution scroll, it's always DOM_DELTA_LINE.

    On other platforms, the deltaMode value is always DOM_DELTA_LINE.

    Untrusted events

    Untrusted wheel events never cause any default action.

    See also

    Document Tags and Contributors

    Tags: 
    Contributors to this page:
    Last updated by: teoli,