MouseWheel System

System which dispatches mouse wheel events received by Crafty.

Events

MouseWheelScroll [Data = {MouseWheelEvent}]: when mouse is scrolled

The event callback is triggered with a native wheel event (all newer browsers), a native mousewheel event (old IE and WebKit browsers) or a native DOMMouseScroll event (old Firefox browsers) received by Crafty's stage (Crafty.stage.elem), which is wrapped in a standard Crafty event object (see below).

These MouseWheel events are triggered on the global Crafty object and thus on every entity and system.

The standard MouseWheelEvent object:

// event name of mouse wheel event - "MouseWheelScroll"
e.eventName

// the direction the wheel was scrolled, +1 if wheel was scrolled up, -1 if wheel was scrolled down
e.direction

// the closest (visible & Mouse-enhanced) entity to the source of the event (if available), otherwise null
e.target

// (x,y) coordinates of mouse event in world (default viewport) space
e.realX
e.realY

// Original mouse wheel event, containing additional native properties
e.originalEvent

Example

Zoom the viewport (camera) in response to mouse scroll events.

Crafty.bind("MouseWheelScroll", function(evt) {
    Crafty.viewport.scale(Crafty.viewport._scale * (1 + evt.direction * 0.1));
});

For more details see mdn article on wheel events.

Note: The wheel delta properties of the event vary in magnitude across browsers, thus it is recommended to check for .direction instead. The .direction equals +1 if wheel was scrolled up, -1 if wheel was scrolled down (see details).

Example

Interactive, map-like zooming of the viewport (camera) in response to mouse scroll events.

// sign public void zoomTowards(Number amt, Number posX, Number posY, Number time[, String|function easingFn])
// param Number amt - amount to zoom in on the target by (eg. `2`, `4`, `0.5`)
// param Number posX - the x coordinate to zoom towards
// param Number posY - the y coordinate to zoom towards
// param Number time - the duration in ms of the entire zoom operation
// param easingFn - A string or custom function specifying an easing.
//                   (Defaults to linear behavior.)
//                   See `Crafty.easing` for more information.
//
// Zooms the camera towards a given point, preserving the current center.
// `amt > 1` will bring the camera closer to the subject,
// `amt < 1` will bring it farther away,
// `amt = 0` will reset to the default zoom level.
// Zooming is multiplicative. To reset the zoom amount, pass `0`.
//
// <example>
// // Make the entities appear twice as large by zooming in towards (100,100) over the duration of 3 seconds using linear easing behavior
// zoomTowards(2, 100, 100, 3000);
// </example>
//
function zoomTowards (amt, posX, posY, time, easingFn) {
    var scale = Crafty.viewport._scale,
        // current viewport center
        centX = -Crafty.viewport._x + Crafty.viewport._width / 2 / scale,
        centY = -Crafty.viewport._y + Crafty.viewport._height / 2 / scale,
        // direction vector from viewport center to position
        deltaX = posX - centX,
        deltaY = posY - centY;
    var f = amt - 1;

    Crafty.viewport.zoom(amt, centX + deltaX * f, centY + deltaY * f, time, easingFn);
}

// don't restrict panning of viewport in any way
Crafty.viewport.clampToEntities = false;

// enable panning of viewport by dragging the mouse
Crafty.viewport.mouselook(true);

// enable interactive map-like zooming by scrolling the mouse
Crafty.bind("MouseWheelScroll", function (evt) {
    zoomTowards(1 + evt.direction/10, evt.realX, evt.realY, 5);
});