A utility class that abstracts away the complexity of a proper mouse-tracking state machine. Registers mouse event listeners on an element, and invokes user-set handlers for useful mouse events. Also uses custom thresholds for clicks to differentiate them from drags and holds more precisely.
| Signature | Description |
|---|---|
| Seadragon.MouseTracker(elmt) | Creates a MouseTracker for the given HTML element. This MouseTracker is not initially tracking. |
All handler properties except target are user-defined functions that are invoked by this class. Setting a handler means that it will get invoked on the next corresponding event. All handlers are passed at least two arguments: the MouseTracker instance that invoked the handler, and the position of the mouse, relative to the target element, as a Seadragon.Point. All handlers are initially null.
| Name | Type | Description |
|---|---|---|
| target | HTML Element | The element that is getting tracked. This property is aliased; re-assigning it has no effect, but modifying it does. |
| enterHandler | Function ( tracker, position, buttonDownElmt, buttonDownAny ) |
Handler function for the mouse entering the target element. Both buttonDownElmt and buttonDownAny are false if the mouse button is up. Otherwise, buttonDownAny is always true, and buttonDownElmt is true if the mouse was initially pressed inside the target element. (Note that buttonDownElmt implies buttonDownAny, but not necessarily the reverse.) |
| exitHandler | Function ( tracker, position, buttonDownElmt, buttonDownAny ) |
Handler function for the mouse exiting the target element. Both buttonDownElmt and buttonDownAny are false if the mouse button is up. Otherwise, buttonDownAny is always true, and buttonDownElmt is true if the mouse was initially pressed inside the target element. (Note that buttonDownElmt implies buttonDownAny, but not necessarily the reverse.) |
| pressHandler | Function ( tracker, position ) | Handler function for the mouse button being pressed inside the target element. |
| releaseHandler | Function ( tracker, position, insideElmtPress, insideElmtRelease ) |
Handler function for the mouse button being released. Note that
like regular "mouseup" events, this is always triggered when the
mouse is released over the target element. However, unlike
regular "mouseup" events, this is also always triggered when the
corresponding "mousedown" event was fired inside the target
element, even if the mouse is no longer over the element. insideElmtPress is true if the mouse was initially pressed inside the target element, and insideElmtRelease is true if this release occured inside the target element. (Note that at least one of insideElmtPress and insideElmtRelease will be true.) |
| clickHandler | Function ( tracker, position, quick, shift ) |
Handler function for the mouse button being clicked inside the
target element. quick is true if, during the click, the mouse was neither moved a significant distance nor held down for a significant amount of time. shift is true if the shift key was pressed during the click. (The thresholds used to determine if the click was quick are defined in Seadragon.Config.) |
| dragHandler | Function ( tracker, position, delta, shift ) |
Handler function for the mouse being dragged. This is triggered only when the drag
was initially begun inside the target element, but is triggered wherever the mouse
may be at the moment. delta is a Seadragon.Point for the distance the mouse was dragged. shift is true if the shift key was pressed during the drag. |
| scrollHandler | Function ( tracker, position, scroll, shift ) |
Handler function for the mouse wheel being scrolled inside the
target element. scroll is the amount the mouse wheel was scrolled, normalized between -1 and 1. shift is true if the shift key was pressed during the scroll. |
| Name and Signature | Return Type | Description |
|---|---|---|
| isTracking() | Boolean | Returns true if the target element is currently being tracked. |
| setTracking(tracking) | - | Sets whether the target element should be tracked. |
The following code allows a chess piece to be dragged and dropped on a chess board.
var tracker = new Seadragon.MouseTracker(piece); var location = null; tracker.pressHandler = function(tracker, position) { piece.pickUp(); // draw piece bigger, add shadow, etc. location = new Seadragon.Point( parseInt(piece.style.left), parseInt(piece.style.top) ); // remember where piece was originally drawn }; tracker.dragHandler = function(tracker, position, delta, shift) { location = location.plus(delta); piece.style.left = location.x + "px"; piece.style.top = location.y + "px"; }; tracker.releaseHandler = function(tracker, position, insideElmtPress, insideElmtRelease) { if (!insideElmtPress) { return; // ignore releases from outside } piece.putDown(); // draw piece smaller, remove shadow, etc. location = null; }; tracker.setTracking(true); // begin tracking
The following code toggles a button between a regular state, a hover state, and a pressed state. It only goes to hover when the mouse is over the button and the mouse button is up.
var tracker = new Seadragon.MouseTracker(button); tracker.enterHandler = function(tracker, position, buttonDownElmt, buttonDownAny) { if (buttonDownElmt) { // the mouse is down and was pressed inside the button button.goToPressedState(); } else if (buttonDownAny) { // the mouse is down from elsewhere, stay in normal state return; } else { // the mouse is up button.goToHoverState(); } }; tracker.exitHandler = function(tracker, position, buttonDownElmt, buttonDownAny) { // always go to normal state button.goToNormalState(); }; tracker.pressHandler = function(tracker, position) { // always go to pressed state button.goToPressedState(); }; tracker.releaseHandler = function(tracker, position, insideElmtPress, insideElmtRelease) { if (insideElmtPress) { // mouse was pressed inside the button and released inside the button button.goToHoverState(); button.doAction(); } else { // precondition: insideElmtRelease must be true if insideElmtPress is false. // the mouse was pressed elsewhere and released inside the button. // we didn't go to hover when the mouse entered since the mouse was down, // so we'll go to hover now that the mouse is up again. button.goToHoverState(); } }; tracker.setTracking(true);