[#808] Add PointerWheel event support (#809)

Closes #808 

## Changes

- Added event "wheel"
- Added sandbox pointer wheel test
- Added docs

CHANGELOG.md

@@ -8,14 +8,14 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 
 ### Breaking Changes
-- Renamed Utils.removeItemFromArray() to Utils.removeItemFromArray() ([#798](https://github.com/excaliburjs/Excalibur/issues/798/)]
+- Renamed Utils.removeItemFromArray() to Utils.removeItemFromArray() ([#798](https://github.com/excaliburjs/Excalibur/issues/798/))
 
 ### Added
-- Added optional volume argument to `Sound.play(volume?: number)`, which will play the Audio file
-at anywhere from mute (`volume` is 0.0) to full volume (`volume` is 1.0). ([#801](https://github.com/excaliburjs/Excalibur/issues/801))
+- Added optional volume argument to `Sound.play(volume?: number)`, which will play the Audio file at anywhere from mute (`volume` is 0.0) to full volume (`volume` is 1.0). ([#801](https://github.com/excaliburjs/Excalibur/issues/801))
 - Added another DisplayMode option: `DisplayMode.Position`. When this is selected as the displayMode type, the user must specify a new `position` option
 - Added a new Interface `AbsolutePosition` which can described the `position` option. A `string` can also describe `position`
-- Added a static method distanceBetweenVectors to the Vector class (#517)[https://github.com/excaliburjs/Excalibur/issues/517]
+- Added a static method distanceBetweenVectors to the Vector class ([#517](https://github.com/excaliburjs/Excalibur/issues/517))
+- Added `PointerWheel` event type for the `wheel` browser event, Excalibur now supports scroll wheel ([#808](https://github.com/excaliburjs/Excalibur/issues/808/))
 
 ### Changed
 - Edge builds have more descriptive versions now containing build number and Git commit hash (e.g. `0.10.0-alpha.105#commit`) ([#777](https://github.com/excaliburjs/Excalibur/issues/777))

sandbox/tests/input/pointer.html

@@ -27,6 +27,8 @@
         <dd id="pointer-screen-pos"></dd>
         <dt>Last Pointer World Pos (x,y)</dt>
         <dd id="pointer-world-pos"></dd>
+        <dt>Last Wheel Deltas (x,y,z,mode)</dt>
+        <dd id="pointer-wheel-deltas"></dd>
     </dl>
 
     <script src="../../excalibur.js"></script>

sandbox/tests/input/pointer.ts

@@ -47,6 +47,10 @@ box.on("pointerdown", (pe: ex.Input.PointerEvent) => {
    boxPointerDown = true;
 });
 
+box.on("pointerwheel", (pe: ex.Input.WheelEvent) => {
+   box.rotation = box.rotation + (pe.deltaY > 0 ? 0.1 : -0.1);
+});
+
 // Follow cursor
 game.input.pointers.primary.on("move", (pe: ex.Input.PointerEvent) => {
    cursor.pos.x = pe.x;
@@ -61,6 +65,17 @@ game.input.pointers.primary.on("up", (pe: ex.Input.PointerEvent) => {
    document.getElementById("pointer-btn").innerHTML = "";
 });
 
+// Wheel
+game.input.pointers.primary.on("wheel", (pe: ex.Input.WheelEvent) => {
+   var type: string;
+   switch (pe.deltaMode) {
+      case ex.Input.WheelDeltaMode.Pixel: type = "pixel"; break;
+      case ex.Input.WheelDeltaMode.Line: type = "line"; break;
+      case ex.Input.WheelDeltaMode.Page: type = "page"; break;
+   }
+   document.getElementById("pointer-wheel-deltas").innerHTML = pe.deltaX + ", " + pe.deltaY + ", " + pe.deltaZ + ", " + type;
+});
+
 var paintBrush = {
    paint: (x: number, y: number, color: ex.Color) => {
       var brush = new ex.Actor(x, y, 5, 5, color);
@@ -104,4 +119,4 @@ game.currentScene.camera.y = 0;
 game.add(box);
 game.add(cursor);
 game.add(uiElement);
-game.start();
+game.start();

src/engine/Actor.ts

@@ -477,6 +477,7 @@ export class Actor extends Class implements IActionable, IEvented {
    public on(eventName: Events.pointerdown, handler: (event?: PointerEvent) => void): void;
    public on(eventName: Events.pointermove, handler: (event?: PointerEvent) => void): void;
    public on(eventName: Events.pointercancel, handler: (event?: PointerEvent) => void): void;
+   public on(eventName: Events.pointerwheel, handler: (event?: WheelEvent) => void): void;
    public on(eventName: string, handler: (event?: GameEvent<any>) => void): void;
    public on(eventName: string, handler: (event?: GameEvent<any>) => void): void {
       this._checkForPointerOptIn(eventName);
@@ -1123,4 +1124,4 @@ export enum CollisionType {
     * collision events.
     */
    Fixed
-}
+}

src/engine/Docs/Pointers.md

@@ -26,6 +26,17 @@ engine.input.pointers.primary.on("move", function (evt) { });
 engine.input.pointers.primary.on("cancel", function (evt) { });
 ```
 
+### Wheel Event
+
+You can also subscribe to the mouse wheel event through `engine.input.pointers.on`. A [[WheelEvent]]
+object is passed to your handler which offers information about the wheel event being received.
+
+- `wheel` - When a mousewheel is activated (trackpad scroll or mouse wheel)
+
+```js
+engine.input.pointers.on("wheel", function (evt) { });
+```
+
 ## Last position querying
 
 If you don't wish to subscribe to events, you can also access the [[Pointer.lastPagePos]], [[Pointer.lastScreenPos]]
@@ -129,4 +140,4 @@ player.capturePointer.captureMoveEvents = true;
 player.on("pointerup", function (ev) {
   player.logger.info("Player selected!", ev);
 });
-```
+```

src/engine/Engine.ts

@@ -47,6 +47,24 @@ export enum DisplayMode {
    Position
 }
 
+/**
+ * Enum representing the different mousewheel event bubble prevention
+ */
+export enum ScrollPreventionMode {
+   /**
+    * Do not prevent any page scrolling
+    */
+   None,
+    /**
+     * Prevent page scroll if mouse is over the game canvas
+     */
+   Canvas,
+    /**
+     * Prevent all page scrolling via mouse wheel
+     */
+   All
+}
+
 /*
 * Interface describing the absolute CSS position of the game window. For use when DisplayMode.Position
 * is specified and when the user wants to define exact pixel spacing of the window.
@@ -112,6 +130,11 @@ export interface IEngineOptions {
    */
 
    position?: string | IAbsolutePosition;
+
+   /**
+    * Scroll prevention method.
+    */
+   scrollPreventionMode?: ScrollPreventionMode;
 }
 
 /**
@@ -234,6 +257,11 @@ export class Engine extends Class {
     */
    public onFatalException = (e: any) => { Logger.getInstance().fatal(e); };
 
+   /**
+    * The mouse wheel scroll prevention mode
+    */
+   public pageScrollPreventionMode: ScrollPreventionMode;
+
    private _logger: Logger;
    private _isSmoothingEnabled: boolean = true;
 
@@ -268,12 +296,13 @@ export class Engine extends Class {
     * Default [[IEngineOptions]]
     */
    private static _DefaultEngineOptions: IEngineOptions = {
-      width: 0,
-      height: 0,
-      canvasElementId: '',
-      pointerScope: Input.PointerScope.Document,
-      suppressConsoleBootMessage: null,
-      suppressMinimumBrowserFeatureDetection: null
+      width:                                  0,
+      height:                                 0,
+      canvasElementId:                        '',
+      pointerScope:                           Input.PointerScope.Document,
+      suppressConsoleBootMessage:             null,
+      suppressMinimumBrowserFeatureDetection: null,
+      scrollPreventionMode:                   ScrollPreventionMode.Canvas
    };
 
    /**
@@ -875,6 +904,8 @@ O|===|* >________________>\n\
       this.input.pointers.init(options && options.pointerScope === Input.PointerScope.Document ? document : this.canvas);
       this.input.gamepads.init();
 
+      this.pageScrollPreventionMode = options.scrollPreventionMode;
+
       // Issue #385 make use of the visibility api
       // https://developer.mozilla.org/en-US/docs/Web/Guide/User_experience/Using_the_Page_Visibility_API
 

src/engine/Events.ts

@@ -49,11 +49,13 @@ export type pointerup = 'pointerup';
 export type pointerdown = 'pointerdown';
 export type pointermove = 'pointermove';
 export type pointercancel = 'pointercancel';
+export type pointerwheel = 'pointerwheel';
 
 export type up = 'up';
 export type down = 'down';
 export type move = 'move';
 export type cancel = 'cancel';
+export type wheel = 'wheel';
 
 export type press = 'press';
 export type release = 'release';
@@ -336,4 +338,4 @@ export class EnterViewPortEvent extends GameEvent<Actor> {
    constructor(public target: Actor) {
       super();
    }
-}
+}