60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
|
# jQuery Mouse Wheel Plugin
|
||
|
|
|
||
|
|
A [jQuery](https://jquery.com/) plugin that adds cross-browser mouse wheel support with delta normalization.
|
||
|
|
|
||
|
|
In order to use the plugin, simply bind the `mousewheel` event to an element.
|
||
|
|
|
||
|
|
It also provides two deprecated helper methods called `mousewheel` and `unmousewheel`
|
||
|
|
that act just like other event helper methods in jQuery.
|
||
|
|
|
||
|
|
The event object is updated with the normalized `deltaX` and `deltaY` properties.
|
||
|
|
In addition, there is a new property on the event object called `deltaFactor`. Multiply
|
||
|
|
the `deltaFactor` by `deltaX` or `deltaY` to get the scroll distance that the browser
|
||
|
|
has reported.
|
||
|
|
|
||
|
|
Here is an example of using both the bind and helper method syntax:
|
||
|
|
|
||
|
|
```js
|
||
|
|
// using on
|
||
|
|
$( "#my_elem" ).on( "mousewheel", function( event ) {
|
||
|
|
console.log( event.deltaX, event.deltaY, event.deltaFactor );
|
||
|
|
} );
|
||
|
|
|
||
|
|
// using the event helper - not recommended!
|
||
|
|
$( "#my_elem" ).mousewheel( function( event ) {
|
||
|
|
console.log( event.deltaX, event.deltaY, event.deltaFactor );
|
||
|
|
} );
|
||
|
|
```
|
||
|
|
|
||
|
|
The old behavior of adding three arguments (`delta`, `deltaX`, and `deltaY`) to the
|
||
|
|
event handler is now deprecated and will be removed in later releases.
|
||
|
|
|
||
|
|
|
||
|
|
## The Deltas...
|
||
|
|
|
||
|
|
The combination of browsers, operating systems, and devices offer a huge range of possible delta values. In fact if the user
|
||
|
|
uses a trackpad and then a physical mouse wheel the delta values can differ wildly. This plugin normalizes those
|
||
|
|
values so you get a whole number starting at +-1 and going up in increments of +-1 according to the force or
|
||
|
|
acceleration that is used. This number has the potential to be in the thousands depending on the device.
|
||
|
|
|
||
|
|
### Getting the scroll distance
|
||
|
|
|
||
|
|
In some use-cases we prefer to have the normalized delta but in others we want to know how far the browser should
|
||
|
|
scroll based on the users input. This can be done by multiplying the `deltaFactor` by the `deltaX` or `deltaY`
|
||
|
|
event property to find the scroll distance the browser reported.
|
||
|
|
|
||
|
|
The `deltaFactor` property was added to the event object in 3.1.5 so that the actual reported delta value can be
|
||
|
|
extracted. This is a non-standard property.
|
||
|
|
|
||
|
|
## Building the code in the repo & running tests
|
||
|
|
|
||
|
|
```sh
|
||
|
|
git clone git@github.com:jquery/jquery-mousewheel.git
|
||
|
|
cd jquery-mousewheel/
|
||
|
|
npm install
|
||
|
|
npm test
|
||
|
|
```
|
||
|
|
|
||
|
|
The unit tests are _very_ basic sanity checks; improvements welcome.
|
||
|
|
To fully test the plugin, load [test/index.html](test/index.html) in each supported
|
||
|
|
browser and follow the instructions at the top of the file after the unit tests finish.
|