# Input Sources

Cornerstone Tools provides support for a number of input sources which can be used to create interactive tools.

Currently, we provide four input sources: mouse, mouseWheel, touch, and keyboard. Each of these input sources triggers a number of events which can be used by tools. This section will explain the events triggered by each of these input sources.

# Common Event Data

Each of the input types triggers separate events for use by tools. The following properties are common to all events:

Property	Type	Meaning
event	Event (opens new window)	The original browser event which caused the Cornerstone Tools event to be fired.
element	Element (opens new window)	The DOM Element for the Cornerstone Enabled Element which is the target of this event.
viewport	Viewport	The Cornerstone Viewport object for the specific Enabled Element at the time the event was fired.
image	Image	The Cornerstone Image object for the specific Enabled Element at the time the event was fired.
type	String	Event.type (opens new window)

# Coordinates

Coordinates are currently represented as:

Object {
  page:   { x: Number, y: Number },
  image:  { x: Number, y: Number },
  client: { x: Number, y: Number },
  canvas: { x: Number, y: Number }
}

# Mouse Input Source

The mouse input source triggers the following events:

Event Name	Meaning
cornerstonetoolsmousedown	Mouse Down This is fired from the browser's mousedown (opens new window) event.
cornerstonetoolsmouseup	Mouse Up This is fired from the browser's mouseup (opens new window) event.
cornerstonetoolsmousedownactivate	Mouse Down, and no tool is present at the current location to respond to the event.
cornerstonetoolsmousedrag	Mouse move while mouse button held down
cornerstonetoolsmousemove	Mouse move without mouse button held down
cornerstonetoolsmouseclick	Mouse Click
cornerstonetoolsmousedoubleclick	Two mouse clicks in quick succession. This is fired from the browser's dblclick (opens new window) event.

# Event Data

The mouse input events include the following event data:

Property	Type	Meaning
which	Number	The jQuery 'which' value for the mouse buttons which were held down when the event occurred. These are computed from the event.buttons (opens new window) values here (opens new window). In future iterations (possibly 3.0) of Cornerstone Tools, we plan to deprecate the 'which' value in favour of the 'buttons' value.
startPoints	Cornerstone Coordinates	The starting coordinates for the mouse event (e.g., for a cornerstonetoolsmousemove event, this is the location where the initial mouseDown event started).
currentPoints	Cornerstone Coordinates	The current coordinates
lastPoints	Cornerstone Coordinates	The final coordinates
deltaPoints	Cornerstone Coordinates	The change in coordinates
ctrlKey	Boolean	MouseEvent.ctrlKey (opens new window)
metaKey	Boolean	MouseEvent.metaKey (opens new window)
shiftKey	Boolean	MouseEvent.shiftKey (opens new window)

Note: ctrlKey, metaKey, and shiftKey are only currently included in eventData for cornerstonetoolsmousemove events.

# Usage

const element = document.querySelector('.my-cornerstone-element');
// Enable mouse input
cornerstoneTools.mouseInput.enable(element);

// Disable mouse input
cornerstoneTools.mouseInput.disable(element);

# MouseWheel Input Source

The mouse input source triggers the following events:

Event Name	Meaning
cornerstonetoolsmousewheel	Mouse Wheel This is fired from the browser's mousewheel (opens new window) event.

# Event Data

The cornerstonetoolsmousewheel event includes the following event data:

Property	Type	Meaning
pageX	Number	pageX (opens new window)
pageY	Number	pageX (opens new window)
imageX	Number	The X (horizontal) coordinate (in image pixels) at which the mouse was clicked, relative to the left edge of the image.
imageY	Number	The Y (vertical) coordinate (in image pixels) at which the mouse was clicked, relative to the top of the image.
direction	Number	-1 to represent negative 'wheelDelta', +1 to represent positive 'wheelDelta'

# Usage

const element = document.querySelector('.my-cornerstone-element');

// Enable mouse wheel input
cornerstoneTools.mouseWheelInput.enable(element);

// Disable mouse wheel input
cornerstoneTools.mouseWheelInput.disable(element);

# Touch Input Source

The touch input source triggers the following events:

Event Name	Meaning
cornerstonetoolstouchstart	Touch Start This is fired from the browser's touchstart (opens new window) event.
cornerstonetoolstouchend	Touch End This is fired from the browser's touchend (opens new window) event.
cornerstonetoolstouchactive	Mouse Down, and no tool is present at the current location to respond to the event. Note: Needs to be renamed to cornerstonetoolstouchactivate
cornerstonetoolstouchdrag	Touch Move This is fired from the browser's touchend (opens new window) event.
cornerstonetoolstouchdragend	Dragging has stopped This is fired from the Hammer.js panend (opens new window) event.
cornerstonetoolstouchpinch	Pinch This is fired from the Hammer.js pinchmove (opens new window) event.
cornerstonetoolstouchrotate	Rotation This is fired from the Hammer.js rotatemove (opens new window) event.
cornerstonetoolstouchpress	Long press on a location without significant movement
cornerstonetoolstap	Quick tap (opens new window) on a location
cornerstonetoolsdoubletap	Two taps (opens new window) in quick succession
cornerstonetoolsmultitouchstart	Equivalent to cornerstonetoolstouchstart, but fired if there are multiple pointers on screen.
cornerstonetoolsmultitouchstartactive	Equivalent to cornerstonetoolstouchactive, but fired if there are multiple pointers on screen.
cornerstonetoolsmultitouchdrag	Equivalent to cornerstonetoolstouchdrag, but fired if there are multiple pointers on screen.

# Event Data

The touch input events include the following event data:

Property	Type	Meaning
currentPoints	Cornerstone Coordinates	The current coordinates
lastPoints	Cornerstone Coordinates	The final coordinates
deltaPoints	Cornerstone Coordinates	The change in coordinates
isTouchEvent	Boolean	Always present and always True for touch events. This property is being used in certain tools to change behaviour depending on whether or not the input event is a touch event.
direction	Number	For cornerstonetoolstouchpinch events, this is -1 for "pinchout" and +1 for 'pinchin'.
scale	Number	For cornerstonetoolstouchpinch events, the ratio of change in the scale (opens new window) ((current - previous) / previous) for a 'pinchmove' sourced event.
numPointers	Number	For multi-touch events, this is the number of pointers which were touching the screen while this event was fired.
rotation	Number	For cornerstonetoolstouchrotate events, this is the rotation (opens new window) (in degrees) that has been performed.

# Usage

const element = document.querySelector('.my-cornerstone-element');

// Enable touch input
cornerstoneTools.touchInput.enable(element);

// Disable touch input
cornerstoneTools.touchInput.disable(element);

# Keyboard Input Source

The keyboard input source triggers the following events:

Event Name	Meaning
cornerstonetoolskeydown	This is fired from the browser's [keydown (opens new window) event.
cornerstonetoolskeyup	This is fired from the browser's [keyup (opens new window) event.
cornerstonetoolskeypress	This is fired from the browser's [keypress (opens new window) event.

# Event Data

The keyboard input events include the following event data:

Property	Type	Meaning
currentPoints	Cornerstone Coordinates	The current coordinates
keyCode	Number	KeyboardEvent.keyCode (opens new window)
which	Number	The jQuery 'which' value for the mouse buttons which were held down when the event occurred. These are computed from the event.buttons (opens new window) values here (opens new window). In future iterations (possibly 3.0) of Cornerstone Tools, we plan to deprecate the 'which' value in favour of the 'buttons' value.

# Usage

const element = document.querySelector('.my-cornerstone-element');

// Enable keyboard input
cornerstoneTools.keyboardInput.enable(element);

// Disable keyboard input
cornerstoneTools.keyboardInput.disable(element);