[]

ChangeLog.md

@@ -1,5 +1,16 @@
 # Mouse Wheel ChangeLog
 
+## 4.0.0-pre
+
+* BREAKING: Now requires jQuery 1.7+
+* BREAKING: Match delta signs (+-) to that of the newer wheel event standard.
+* BREAKING: Removed delta, deltaX, and deltaY from the event handler args. Use deltaX and deltaY properties from the event object instead.
+* BREAKING: Remove mousewheel/unmousehweel helper functions in preference of just using $().on and $().trigger
+* Added support for throttling/debouncing via data argument, example: $(...).on('mousewheel', { mousewheel: { behavior: 'throttle', delay: 100 } }, function(event) {...})
+* Added trigger hook so that triggering a mousewheel event works properly, example: $().trigger( $.Event('mousewheel', { deltaX: 0, deltaY: 120 }) );
+* Add examples directory
+* Add proper unit tests in addition to tried and true physical test
+
 ## 3.1.12
 
 * Fix possible 0 value for line height when in delta mode 1

Gruntfile.js

@@ -33,13 +33,22 @@ module.exports = function(grunt) {
                     }
                 }
             }
+        },
+        bump: {
+            options: {
+                files: ['package.json', 'mousewheel.jquery.json', 'bower.json', 'jquery.mousewheel.js'],
+                commit: false,
+                createTag: false,
+                push: false
+            }
         }
     });
 
     // Load the plugin that provides the 'uglify' task.
     grunt.loadNpmTasks('grunt-contrib-jshint');
     grunt.loadNpmTasks('grunt-contrib-uglify');
     grunt.loadNpmTasks('grunt-contrib-connect');
+    grunt.loadNpmTasks('grunt-bump');
 
     // Default task(s).
     grunt.registerTask('default', ['jshint', 'uglify']);

README.md

@@ -29,15 +29,39 @@ $('#my_elem').mousewheel(function(event) {
 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.
+The combination of browsers, operating systems, devices, and user settings 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.
 Check out some of the data collected from users [here](http://mousewheeldatacollector.herokuapp.com/).
 
+### Which direction
+
+One way of understanding the direction is to understand which direction the user it trying to move the content.
+This happens to also align with the natural scroll setting in the latest version of OS X.
+A positive `deltaX` or `deltaY` means the user wants to move the content to west (to the left) or north (upwards) respectively.
+A negative `deltaX` or `deltaY` means the user wants to move the content to east (to the right) or south (downwards) respectively.
+
+```js
+var directions = {
+    isNorth: function(deltaY) { return deltaY > 0; },
+    isEast:  function(deltaX) { return deltaX < 0; },
+    isSouth: function(deltaY) { return deltaY < 0; },
+    isWest:  function(deltaX) { return deltaX > 0; },
+    isNorthEast: function(deltaX, deltaY) { return deltaX < 0 && deltaY > 0; },
+    isNorthWest: function(deltaX, deltaY) { return deltaX > 0 && deltaY > 0; },
+    isSouthEast: function(deltaX, deltaY) { return deltaX < 0 && deltaY < 0; },
+    isSouthWest: function(deltaX, deltaY) { return deltaX > 0 && deltaY < 0; }
+};
+```
+
+#### Older Versions
+
+In older versions of this plugin the delta value signs are the opposite. The deltaY value in this version align with
+the newer wheel event standard which flipped the delta signs from the old wheelDelta properties.
+
 ### 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
@@ -47,6 +71,21 @@ 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.
 
+Here is an example of updating the scroll amount of an element based on the mouse wheel event.
+
+```js
+var $elem = $('#my_elem');
+$elem.on('mousewheel', function(event) {
+    event.preventDefault();
+
+    var top = $elem.scrollTop(),
+        left = $elem.scrollLeft(),
+
+    $elem
+      .scrollTop( event.deltaY * event.deltaFactor )
+      .scrollLeft( event.deltaX * event.deltaFactor );
+});
+```
 
 ## See it in action
 [See the tests on Github](http://brandonaaron.github.io/jquery-mousewheel/test).

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "jquery-mousewheel",
-  "version": "3.1.12",
+  "version": "4.0.0-pre",
   "main": "./jquery.mousewheel.js",
   "ignore": [
     "*.json",
@@ -12,6 +12,6 @@
     "test"
   ],
   "dependencies": {
-    "jquery": ">=1.2.2"
+    "jquery": ">=1.7"
   }
 }