Mousewheel

From WEBAPPS
Revision as of 07:16, 19 June 2008 by Mcaceres (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

WebAppsDOM3Events ⇨ Mousewheel

The mousewheel event allows authors to capture and act on user-generated wheel activity.

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 both mouseomniwheel and mousewheel,
MouseEvent.relatedNode must indicate the element over which the
pointer is located, or null if 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 scroll event?



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.