README.md
77 lines
| 1 | # jQuery Mouse Wheel Plugin |
| 2 | |
| 3 | A [](http://jquery.com/jQuery](http://jquery.com/](http://jquery.com/) plugin that adds cross-browser mouse wheel support with delta normalization. |
| 4 | |
| 5 | In order to use the plugin, simply bind the `mousewheel` event to an element. |
| 6 | |
| 7 | It also provides two helper methods called `mousewheel` and `unmousewheel` |
| 8 | that act just like other event helper methods in jQuery. |
| 9 | |
| 10 | The event object is updated with the normalized `deltaX` and `deltaY` properties. |
| 11 | In addition there is a new property on the event object called `deltaFactor`. Multiply |
| 12 | the `deltaFactor` by `deltaX` or `deltaY` to get the scroll distance that the browser |
| 13 | has reported. |
| 14 | |
| 15 | Here is an example of using both the bind and helper method syntax: |
| 16 | |
| 17 | ```js |
| 18 | // using on |
| 19 | $('#my_elem').on('mousewheel', function(event) { |
| 20 | console.log(event.deltaX, event.deltaY, event.deltaFactor); |
| 21 | }); |
| 22 | |
| 23 | // using the event helper |
| 24 | $('#my_elem').mousewheel(function(event) { |
| 25 | console.log(event.deltaX, event.deltaY, event.deltaFactor); |
| 26 | }); |
| 27 | ``` |
| 28 | |
| 29 | The old behavior of adding three arguments (`delta`, `deltaX`, and `deltaY`) to the |
| 30 | event handler is now deprecated and will be removed in later releases. |
| 31 | |
| 32 | |
| 33 | ## The Deltas... |
| 34 | |
| 35 | The combination of Browsers, Operating Systems, and Devices offer a huge range of possible delta values. In fact if the user |
| 36 | uses a trackpad and then a physical mouse wheel the delta values can differ wildly. This plugin normalizes those |
| 37 | values so you get a whole number starting at +-1 and going up in increments of +-1 according to the force or |
| 38 | acceleration that is used. This number has the potential to be in the thousands depending on the device. |
| 39 | Check out some of the data collected from users [](http://mousewheeldatacollector.herokuapp.com/here](http://mousewheeldatacollector.herokuapp.com/](http://mousewheeldatacollector.herokuapp.com/). |
| 40 | |
| 41 | ### Getting the scroll distance |
| 42 | |
| 43 | In some use-cases we prefer to have the normalized delta but in others we want to know how far the browser should |
| 44 | scroll based on the users input. This can be done by multiplying the `deltaFactor` by the `deltaX` or `deltaY` |
| 45 | event property to find the scroll distance the browser reported. |
| 46 | |
| 47 | The `deltaFactor` property was added to the event object in 3.1.5 so that the actual reported delta value can be |
| 48 | extracted. This is a non-standard property. |
| 49 | |
| 50 | |
| 51 | ## Using with [](http://browserify.orgBrowserify](http://browserify.org](http://browserify.org) |
| 52 | |
| 53 | Support for browserify is baked in. |
| 54 | |
| 55 | ```bash |
| 56 | npm install jquery-mousewheel |
| 57 | npm install jquery-browserify |
| 58 | ``` |
| 59 | |
| 60 | In your server-side node.js code: |
| 61 | |
| 62 | ```js |
| 63 | var express = require('express'); |
| 64 | var app = express.createServer(); |
| 65 | |
| 66 | app.use(require('browserify')({ |
| 67 | require : [ 'jquery-browserify', 'jquery-mousewheel' ] |
| 68 | })); |
| 69 | ``` |
| 70 | |
| 71 | In your browser-side javascript: |
| 72 | |
| 73 | ```js |
| 74 | var $ = require('jquery-browserify'); |
| 75 | require('jquery-mousewheel')($); |
| 76 | ``` |
| 77 |