| 1 | // Type definitions for normalize-wheel 1.0
|
| 2 | // Project: https://github.com/basilfx/normalize-wheel
|
| 3 | // Definitions by: DefinitelyTyped <https://github.com/DefinitelyTyped>
|
| 4 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
| 5 |
|
| 6 | /**
|
| 7 | * Mouse wheel (and 2-finger trackpad) support on the web sucks. It is
|
| 8 | * complicated, thus this doc is long and (hopefully) detailed enough to answer
|
| 9 | * your questions.
|
| 10 | *
|
| 11 | * If you need to react to the mouse wheel in a predictable way, this code is
|
| 12 | * like your bestest friend. * hugs *
|
| 13 | *
|
| 14 | * As of today, there are 4 DOM event types you can listen to:
|
| 15 | *
|
| 16 | * 'wheel' -- Chrome(31+), FF(17+), IE(9+)
|
| 17 | * 'mousewheel' -- Chrome, IE(6+), Opera, Safari
|
| 18 | * 'MozMousePixelScroll' -- FF(3.5 only!) (2010-2013) -- don't bother!
|
| 19 | * 'DOMMouseScroll' -- FF(0.9.7+) since 2003
|
| 20 | *
|
| 21 | * So what to do? The is the best:
|
| 22 | *
|
| 23 | * normalizeWheel.getEventType();
|
| 24 | *
|
| 25 | * In your event callback, use this code to get sane interpretation of the
|
| 26 | * deltas. This code will return an object with properties:
|
| 27 | *
|
| 28 | * spinX -- normalized spin speed (use for zoom) - x plane
|
| 29 | * spinY -- " - y plane
|
| 30 | * pixelX -- normalized distance (to pixels) - x plane
|
| 31 | * pixelY -- " - y plane
|
| 32 | *
|
| 33 | * Wheel values are provided by the browser assuming you are using the wheel to
|
| 34 | * scroll a web page by a number of lines or pixels (or pages). Values can vary
|
| 35 | * significantly on different platforms and browsers, forgetting that you can
|
| 36 | * scroll at different speeds. Some devices (like trackpads) emit more events
|
| 37 | * at smaller increments with fine granularity, and some emit massive jumps with
|
| 38 | * linear speed or acceleration.
|
| 39 | *
|
| 40 | * This code does its best to normalize the deltas for you:
|
| 41 | *
|
| 42 | * - spin is trying to normalize how far the wheel was spun (or trackpad
|
| 43 | * dragged). This is super useful for zoom support where you want to
|
| 44 | * throw away the chunky scroll steps on the PC and make those equal to
|
| 45 | * the slow and smooth tiny steps on the Mac. Key data: This code tries to
|
| 46 | * resolve a single slow step on a wheel to 1.
|
| 47 | *
|
| 48 | * - pixel is normalizing the desired scroll delta in pixel units. You'll
|
| 49 | * get the crazy differences between browsers, but at least it'll be in
|
| 50 | * pixels!
|
| 51 | *
|
| 52 | * - positive value indicates scrolling DOWN/RIGHT, negative UP/LEFT. This
|
| 53 | * should translate to positive value zooming IN, negative zooming OUT.
|
| 54 | * This matches the newer 'wheel' event.
|
| 55 | *
|
| 56 | * Why are there spinX, spinY (or pixels)?
|
| 57 | *
|
| 58 | * - spinX is a 2-finger side drag on the trackpad, and a shift + wheel turn
|
| 59 | * with a mouse. It results in side-scrolling in the browser by default.
|
| 60 | *
|
| 61 | * - spinY is what you expect -- it's the classic axis of a mouse wheel.
|
| 62 | *
|
| 63 | * - I dropped spinZ/pixelZ. It is supported by the DOM 3 'wheel' event and
|
| 64 | * probably is by browsers in conjunction with fancy 3D controllers .. but
|
| 65 | * you know.
|
| 66 | *
|
| 67 | * Implementation info:
|
| 68 | *
|
| 69 | * Examples of 'wheel' event if you scroll slowly (down) by one step with an
|
| 70 | * average mouse:
|
| 71 | *
|
| 72 | * OS X + Chrome (mouse) - 4 pixel delta (wheelDelta -120)
|
| 73 | * OS X + Safari (mouse) - N/A pixel delta (wheelDelta -12)
|
| 74 | * OS X + Firefox (mouse) - 0.1 line delta (wheelDelta N/A)
|
| 75 | * Win8 + Chrome (mouse) - 100 pixel delta (wheelDelta -120)
|
| 76 | * Win8 + Firefox (mouse) - 3 line delta (wheelDelta -120)
|
| 77 | *
|
| 78 | * On the trackpad:
|
| 79 | *
|
| 80 | * OS X + Chrome (trackpad) - 2 pixel delta (wheelDelta -6)
|
| 81 | * OS X + Firefox (trackpad) - 1 pixel delta (wheelDelta N/A)
|
| 82 | *
|
| 83 | * On other/older browsers.. it's more complicated as there can be multiple and
|
| 84 | * also missing delta values.
|
| 85 | *
|
| 86 | * The 'wheel' event is more standard:
|
| 87 | *
|
| 88 | * http://www.w3.org/TR/DOM-Level-3-Events/#events-wheelevents
|
| 89 | *
|
| 90 | * The basics is that it includes a unit, deltaMode (pixels, lines, pages), and
|
| 91 | * deltaX, deltaY and deltaZ. Some browsers provide other values to maintain
|
| 92 | * backward compatibility with older events. Those other values help us
|
| 93 | * better normalize spin speed. Example of what the browsers provide:
|
| 94 | *
|
| 95 | * | event.wheelDelta | event.detail
|
| 96 | * ------------------+------------------+--------------
|
| 97 | * Safari v5/OS X | -120 | 0
|
| 98 | * Safari v5/Win7 | -120 | 0
|
| 99 | * Chrome v17/OS X | -120 | 0
|
| 100 | * Chrome v17/Win7 | -120 | 0
|
| 101 | * IE9/Win7 | -120 | undefined
|
| 102 | * Firefox v4/OS X | undefined | 1
|
| 103 | * Firefox v4/Win7 | undefined | 3
|
| 104 | *
|
| 105 | */
|
| 106 | declare function normalizeWheel(event: any): { spinX: number; spinY: number; pixelX: number; pixelY: number };
|
| 107 |
|
| 108 | declare namespace normalizeWheel {
|
| 109 | function getEventType(): 'wheel' | 'mousewheel' | 'DOMMouseScroll';
|
| 110 | }
|
| 111 |
|
| 112 | export = normalizeWheel;
|