Class: MouseTracker

OpenSeadragon.MouseTracker

Provides simplified handling of common pointer device (mouse, touch, pen, etc.) gestures and keyboard events on a specified element.

Constructor

new MouseTracker(options)

Parameters:
Name Type Description
options Object Allows configurable properties to be entirely specified by passing an options object to the constructor. The constructor also supports the original positional arguments 'element', 'clickTimeThreshold', and 'clickDistThreshold' in that order.
Properties
Name Type Attributes Default Description
element Element | String A reference to an element or an element id for which the pointer/key events will be monitored.
startDisabled Boolean <optional>
false If true, event tracking on the element will not start until setTracking is called.
clickTimeThreshold Number The number of milliseconds within which a pointer down-up event combination will be treated as a click gesture.
clickDistThreshold Number The maximum distance allowed between a pointer down event and a pointer up event to be treated as a click gesture.
dblClickTimeThreshold Number The number of milliseconds within which two pointer down-up event combinations will be treated as a double-click gesture.
dblClickDistThreshold Number The maximum distance allowed between two pointer click events to be treated as a click gesture.
stopDelay Number <optional>
50 The number of milliseconds without pointer move before the stop event is fired.
enterHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer enter.
exitHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer exit.
pressHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer press.
nonPrimaryPressHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer non-primary button press.
releaseHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer release.
nonPrimaryReleaseHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer non-primary button release.
moveHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer move.
scrollHandler OpenSeadragon.EventHandler <optional>
null An optional handler for mouse wheel scroll.
clickHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer click.
dblClickHandler OpenSeadragon.EventHandler <optional>
null An optional handler for pointer double-click.
dragHandler OpenSeadragon.EventHandler <optional>
null An optional handler for the drag gesture.
dragEndHandler OpenSeadragon.EventHandler <optional>
null An optional handler for after a drag gesture.
pinchHandler OpenSeadragon.EventHandler <optional>
null An optional handler for the pinch gesture.
keyDownHandler OpenSeadragon.EventHandler <optional>
null An optional handler for keydown.
keyUpHandler OpenSeadragon.EventHandler <optional>
null An optional handler for keyup.
keyHandler OpenSeadragon.EventHandler <optional>
null An optional handler for keypress.
focusHandler OpenSeadragon.EventHandler <optional>
null An optional handler for focus.
blurHandler OpenSeadragon.EventHandler <optional>
null An optional handler for blur.
userData Object <optional>
null Arbitrary object to be passed unchanged to any attached handler methods.
Source:

Members

clickDistThreshold :Number

The maximum distance allowed between two pointer click events to be treated as a click gesture.
Type:
  • Number
Source:

clickDistThreshold :Number

The maximum distance allowed between a pointer down event and a pointer up event to be treated as a click gesture.
Type:
  • Number
Source:

clickTimeThreshold :Number

The number of milliseconds within which a pointer down-up event combination will be treated as a click gesture.
Type:
  • Number
Source:

dblClickTimeThreshold :Number

The number of milliseconds within which two pointer down-up event combinations will be treated as a double-click gesture.
Type:
  • Number
Source:

element :Element

The element for which pointer events are being monitored.
Type:
  • Element
Source:

Methods

blurHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

clickHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
quick Boolean True only if the clickDistThreshold and clickTimeThreshold are both passed. Useful for ignoring drag events.
shift Boolean True if the shift key was pressed during this event.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

dblClickHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
shift Boolean True if the shift key was pressed during this event.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

destroy()

Clean up any events or objects created by the tracker.
Source:

dragEndHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
speed Number Speed at the end of a drag gesture, in pixels per second.
direction Number Direction at the end of a drag gesture, expressed as an angle counterclockwise relative to the positive X axis (-pi to pi, in radians). Only valid if speed > 0.
shift Boolean True if the shift key was pressed during this event.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

dragHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
delta OpenSeadragon.Point The x,y components of the difference between the current position and the last drag event position. Useful for ignoring or weighting the events.
speed Number Current computed speed, in pixels per second.
direction Number Current computed direction, expressed as an angle counterclockwise relative to the positive X axis (-pi to pi, in radians). Only valid if speed > 0.
shift Boolean True if the shift key was pressed during this event.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

enterHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
pointers Number Number of pointers (all types) active in the tracked element.
insideElementPressed Boolean True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
buttonDownAny Boolean Was the button down anywhere in the screen during the event. Deprecated. Use buttons instead.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

exitHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
pointers Number Number of pointers (all types) active in the tracked element.
insideElementPressed Boolean True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
buttonDownAny Boolean Was the button down anywhere in the screen during the event. Deprecated. Use buttons instead.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

focusHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

getActivePointerCount() → {Number}

Returns the total number of pointers currently active on the tracked element.
Source:
Returns:
Type
Number

getActivePointersListByType(type) → {OpenSeadragon.MouseTracker.GesturePointList}

Returns the GesturePointList for the given pointer device type, creating and caching a new GesturePointList if one doesn't already exist for the type.
Parameters:
Name Type Description
type String The pointer device type: "mouse", "touch", "pen", etc.
Source:
Returns:
Type
OpenSeadragon.MouseTracker.GesturePointList

isTracking() → {Boolean}

Are we currently tracking events on this element.
Deprecated:
  • Just use this.tracking
Source:
Returns:
Are we currently tracking events on this element.
Type
Boolean

keyDownHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
keyCode Number The key code that was pressed.
ctrl Boolean True if the ctrl key was pressed during this event.
shift Boolean True if the shift key was pressed during this event.
alt Boolean True if the alt key was pressed during this event.
meta Boolean True if the meta key was pressed during this event.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

keyHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
keyCode Number The key code that was pressed.
ctrl Boolean True if the ctrl key was pressed during this event.
shift Boolean True if the shift key was pressed during this event.
alt Boolean True if the alt key was pressed during this event.
meta Boolean True if the meta key was pressed during this event.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

keyUpHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
keyCode Number The key code that was pressed.
ctrl Boolean True if the ctrl key was pressed during this event.
shift Boolean True if the shift key was pressed during this event.
alt Boolean True if the alt key was pressed during this event.
meta Boolean True if the meta key was pressed during this event.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

moveHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

nonPrimaryPressHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
button Number Button which caused the event. -1: none, 0: primary/left, 1: aux/middle, 2: secondary/right, 3: X1/back, 4: X2/forward, 5: pen eraser.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

nonPrimaryReleaseHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
button Number Button which caused the event. -1: none, 0: primary/left, 1: aux/middle, 2: secondary/right, 3: X1/back, 4: X2/forward, 5: pen eraser.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

pinchHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
gesturePoints Array.<OpenSeadragon.MouseTracker.GesturePoint> Gesture points associated with the gesture. Velocity data can be found here.
lastCenter OpenSeadragon.Point The previous center point of the two pinch contact points relative to the tracked element.
center OpenSeadragon.Point The center point of the two pinch contact points relative to the tracked element.
lastDistance Number The previous distance between the two pinch contact points in CSS pixels.
distance Number The distance between the two pinch contact points in CSS pixels.
shift Boolean True if the shift key was pressed during this event.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

pressHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

releaseHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
insideElementPressed Boolean True if the left mouse button is currently being pressed and was initiated inside the tracked element, otherwise false.
insideElementReleased Boolean True if the cursor inside the tracked element when the button was released.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

scrollHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
scroll Number The scroll delta for the event.
shift Boolean True if the shift key was pressed during this event.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead. Touch devices no longer generate scroll event.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

setTracking(track) → {OpenSeadragon.MouseTracker}

Enable or disable whether or not we are tracking events on this element.
Parameters:
Name Type Description
track Boolean True to start tracking, false to stop tracking.
Source:
Returns:
Chainable.
Type
OpenSeadragon.MouseTracker

stopHandler(event)

Implement or assign implementation to these handlers during or after calling the constructor.
Parameters:
Name Type Description
event Object
Properties
Name Type Description
eventSource OpenSeadragon.MouseTracker A reference to the tracker instance.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. Combination of bit flags 0: none, 1: primary (or touch contact), 2: secondary, 4: aux (often middle), 8: X1 (often back), 16: X2 (often forward), 32: pen eraser.
isTouchEvent Boolean True if the original event is a touch event, otherwise false. Deprecated. Use pointerType and/or originalEvent instead.
originalEvent Object The original event object.
preventDefaultAction Boolean Set to true to prevent the tracker subscriber from performing its default action (subscriber implementation dependent). Default: false.
userData Object Arbitrary user-defined object.
Source:

Type Definitions

GesturePoint

Represents a point of contact on the screen made by a mouse cursor, pen, touch, or other pointer device.
Type:
  • Object
Properties:
Name Type Description
id Number Identifier unique from all other active GesturePoints for a given pointer device.
type String The pointer device type: "mouse", "touch", "pen", etc.
captured Boolean True if events for the gesture point are captured to the tracked element.
isPrimary Boolean True if the gesture point is a master pointer amongst the set of active pointers for each pointer type. True for mouse and primary (first) touch/pen pointers.
insideElementPressed Boolean True if button pressed or contact point initiated inside the screen area of the tracked element.
insideElement Boolean True if pointer or contact point is currently inside the bounds of the tracked element.
speed Number Current computed speed, in pixels per second.
direction Number Current computed direction, expressed as an angle counterclockwise relative to the positive X axis (-pi to pi, in radians). Only valid if speed > 0.
contactPos OpenSeadragon.Point The initial pointer contact position, relative to the page including any scrolling. Only valid if the pointer has contact (pressed, touch contact, pen contact).
contactTime Number The initial pointer contact time, in milliseconds. Only valid if the pointer has contact (pressed, touch contact, pen contact).
lastPos OpenSeadragon.Point The last pointer position, relative to the page including any scrolling.
lastTime Number The last pointer contact time, in milliseconds.
currentPos OpenSeadragon.Point The current pointer position, relative to the page including any scrolling.
currentTime Number The current pointer contact time, in milliseconds.
Source: