Class: Viewer

OpenSeadragon.Viewer

The main OpenSeadragon viewer class.
Members Methods Events

Constructor

new Viewer(options)

The main point of entry into creating a zoomable image on the page.

We have provided an idiomatic javascript constructor which takes a single object, but still support the legacy positional arguments.

The options below are given in order that they appeared in the constructor as arguments and we translate a positional call into an idiomatic call.

To create a viewer, you can use either of this methods:
  • var viewer = new OpenSeadragon.Viewer(options);
  • var viewer = OpenSeadragon(options);
Parameters:
Name Type Description
options OpenSeadragon.Options Viewer options.
Source:

Extends

Members

canvas :Element

A <div> element, the element where user-input events are handled for panning and zooming.

Child element of OpenSeadragon.Viewer#container, positioned on top of OpenSeadragon.Viewer#keyboardCommandArea.

The parent of OpenSeadragon.Drawer#canvas instances.
Type:
  • Element
Source:

container :Element

A <div> element (provided by OpenSeadragon.ControlDock), the base element of this Viewer instance.

Child element of OpenSeadragon.Viewer#element.
Type:
  • Element
Source:

drawer :OpenSeadragon.Drawer

Handles rendering of tiles in the viewer. Created for each TileSource opened.
Type:
Source:

element :Element

The parent element of this Viewer instance, passed in when the Viewer was created.
Type:
  • Element
Source:

initialPage :Number

Index for page to be shown first next time open() is called (only used in sequenceMode).
Type:
  • Number
Source:
Type:
Source:

viewport :OpenSeadragon.Viewport

Handles coordinate-related functionality - zoom, pan, rotation, etc. Created for each TileSource opened.
Type:
Source:

world :OpenSeadragon.World

Keeps track of all of the tiled images in the scene.
Type:
Source:

Methods

_cancelPendingImages()

Cancel the "in flight" images.
Source:

addButton(button)

Adds the given button to this viewer.
Parameters:
Name Type Description
button OpenSeadragon.Button
Source:

addControl()

Inherited From:
Source:

addHandler(eventName, handler, userDataopt, priorityopt)

Add an event handler for a given event.
Parameters:
Name Type Attributes Default Description
eventName String Name of event to register.
handler OpenSeadragon.EventHandler Function to call when event is triggered.
userData Object <optional>
null Arbitrary object to be passed unchanged to the handler.
priority Number <optional>
0 Handler priority. By default, all priorities are 0. Higher number = priority.
Inherited From:
Source:

addOnceHandler(eventName, handler, userDataopt, timesopt, priorityopt)

Add an event handler to be triggered only once (or a given number of times) for a given event. It is not removable with removeHandler().
Parameters:
Name Type Attributes Default Description
eventName String Name of event to register.
handler OpenSeadragon.EventHandler Function to call when event is triggered.
userData Object <optional>
null Arbitrary object to be passed unchanged to the handler.
times Number <optional>
1 The number of times to handle the event before removing it.
priority Number <optional>
0 Handler priority. By default, all priorities are 0. Higher number = priority.
Inherited From:
Source:

addOverlay(element, location, placementopt, onDrawopt) → {OpenSeadragon.Viewer}

Adds an html element as an overlay to the current viewport. Useful for highlighting words or areas of interest on an image or other zoomable interface. The overlays added via this method are removed when the viewport is closed which include when changing page.
Parameters:
Name Type Attributes Default Description
element Element | String | Object A reference to an element or an id for the element which will be overlaid. Or an Object specifying the configuration for the overlay. If using an object, see OpenSeadragon.Overlay for a list of all available options.
location OpenSeadragon.Point | OpenSeadragon.Rect The point or rectangle which will be overlaid. This is a viewport relative location.
placement OpenSeadragon.Placement <optional>
OpenSeadragon.Placement.TOP_LEFT The position of the viewport which the location coordinates will be treated as relative to.
onDraw function <optional>
If supplied the callback is called when the overlay needs to be drawn. It it the responsibility of the callback to do any drawing/positioning. It is passed position, size and element.
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

addReferenceStrip()

Enables and displays the reference strip based on the currently set tileSources. Works only when the Viewer has sequenceMode set to true.
Source:

addSimpleImage(options)

Add a simple image to the viewer. The options are the same as the ones in OpenSeadragon.Viewer#addTiledImage except for options.tileSource which is replaced by options.url.
Parameters:
Name Type Description
options Object See OpenSeadragon.Viewer#addTiledImage for all the options
Properties
Name Type Description
url String The URL of the image to add.
Source:
Fires:

addTiledImage(options)

Add a tiled image to the viewer. options.tileSource can be anything that OpenSeadragon.Viewer#open supports except arrays of images. Note that you can specify options.width or options.height, but not both. The other dimension will be calculated according to the item's aspect ratio. If collectionMode is on (see OpenSeadragon.Options), the new image is automatically arranged with the others.
Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default Description
tileSource String | Object | function The TileSource specifier. A String implies a url used to determine the tileSource implementation based on the file extension of url. JSONP is implied by *.js, otherwise the url is retrieved as text and the resulting text is introspected to determine if its json, xml, or text and parsed. An Object implies an inline configuration which has a single property sufficient for being able to determine tileSource implementation. If the object has a property which is a function named 'getTileUrl', it is treated as a custom TileSource.
index Number <optional>
The index of the item. Added on top of all other items if not specified.
replace Boolean <optional>
false If true, the item at options.index will be removed and the new item is added in its place. options.tileSource will be interpreted and fetched if necessary before the old item is removed to avoid leaving a gap in the world.
x Number <optional>
0 The X position for the image in viewport coordinates.
y Number <optional>
0 The Y position for the image in viewport coordinates.
width Number <optional>
1 The width for the image in viewport coordinates.
height Number <optional>
The height for the image in viewport coordinates.
fitBounds OpenSeadragon.Rect <optional>
The bounds in viewport coordinates to fit the image into. If specified, x, y, width and height get ignored.
fitBoundsPlacement OpenSeadragon.Placement <optional>
OpenSeadragon.Placement.CENTER How to anchor the image in the bounds if options.fitBounds is set.
clip OpenSeadragon.Rect <optional>
An area, in image pixels, to clip to (portions of the image outside of this area will not be visible). Only works on browsers that support the HTML5 canvas.
opacity Number <optional>
1 Proportional opacity of the tiled images (1=opaque, 0=hidden)
preload Boolean <optional>
false Default switch for loading hidden images (true loads, false blocks)
degrees Number <optional>
0 Initial rotation of the tiled image around its top left corner in degrees.
flipped Boolean <optional>
false Whether to horizontally flip the image.
compositeOperation String <optional>
How the image is composited onto other images.
crossOriginPolicy String <optional>
The crossOriginPolicy for this specific image, overriding viewer.crossOriginPolicy.
ajaxWithCredentials Boolean <optional>
Whether to set withCredentials on tile AJAX
loadTilesWithAjax Boolean <optional>
Whether to load tile data using AJAX requests. Defaults to the setting in OpenSeadragon.Options.
ajaxHeaders Object <optional>
A set of headers to include when making tile AJAX requests. Note that these headers will be merged over any headers specified in OpenSeadragon.Options. Specifying a falsy value for a header will clear its existing value set at the Viewer level (if any).
success function <optional>
A function that gets called when the image is successfully added. It's passed the event object which contains a single property: "item", which is the resulting instance of TiledImage.
error function <optional>
A function that gets called if the image is unable to be added. It's passed the error event object, which contains "message" and "source" properties.
collectionImmediately Boolean <optional>
false If collectionMode is on, specifies whether to snap to the new arrangement immediately or to animate to it.
placeholderFillStyle String | CanvasGradient | CanvasPattern | function <optional>
See OpenSeadragon.Options.
Source:
Fires:

areControlsEnabled() → {Boolean}

Overrides:
Source:
Returns:
Type
Boolean

bindSequenceControls() → {OpenSeadragon.Viewer}

Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

bindStandardControls() → {OpenSeadragon.Viewer}

Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

clearControls() → {OpenSeadragon.ControlDock}

Inherited From:
Source:
Returns:
Chainable.
Type
OpenSeadragon.ControlDock

clearOverlays() → {OpenSeadragon.Viewer}

Removes all currently configured Overlays from this Viewer and schedules an update.
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

close() → {OpenSeadragon.Viewer}

Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

currentPage() → {Number}

Gets the active page of a sequence
Source:
Returns:
Type
Number

destroy()

Function to destroy the viewer and clean up everything created by OpenSeadragon. Example: var viewer = OpenSeadragon({ [...] }); //when you are done with the viewer: viewer.destroy(); viewer = null; //important
Source:
Fires:

forceRedraw() → {OpenSeadragon.Viewer}

Force the viewer to redraw its contents.
Source:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

forceResize()

Force the viewer to reset its size to match its container.
Source:

gestureSettingsByDeviceType(type) → {OpenSeadragon.GestureSettings}

Gets this viewer's gesture settings for the given pointer device type.
Parameters:
Name Type Description
type String The pointer device type to get the gesture settings for ("mouse", "touch", "pen", etc.).
Source:
Returns:
Type
OpenSeadragon.GestureSettings

getHandler(eventName)

Get a function which iterates the list of all handlers registered for a given event, calling the handler for each.
Parameters:
Name Type Description
eventName String Name of event to get handlers for.
Inherited From:
Source:

getOverlayById(element) → {OpenSeadragon.Overlay}

Finds an overlay identified by the reference element or element id and returns it as an object, return null if not found.
Parameters:
Name Type Description
element Element | String A reference to the element or an element id which represents the overlay content.
Source:
Returns:
the matching overlay or null if none found.
Type
OpenSeadragon.Overlay

goToNextPage()

Sets the image source to the source with index equal to currentIndex + 1. Changes current image in sequence mode. If specified, wraps around (see navPrevNextWrap in OpenSeadragon.Options)
Source:

goToPage() → {OpenSeadragon.Viewer}

Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

goToPreviousPage()

Sets the image source to the source with index equal to currentIndex - 1. Changes current image in sequence mode. If specified, wraps around (see navPrevNextWrap in OpenSeadragon.Options)
Source:

isFullPage() → {Boolean}

Source:
Returns:
Type
Boolean

isFullScreen() → {Boolean}

Source:
Returns:
returns true if the viewer is in fullscreen
Type
Boolean

isMouseNavEnabled() → {Boolean}

Source:
Returns:
Type
Boolean

isOpen() → {Boolean}

Source:
Returns:
Type
Boolean

isVisible() → {Boolean}

Source:
Returns:
Type
Boolean

numberOfHandlers(eventName) → {number}

Get the amount of handlers registered for a given event.
Parameters:
Name Type Description
eventName String Name of event to inspect.
Inherited From:
Source:
Returns:
amount of events
Type
number

open(tileSources, initialPage) → {OpenSeadragon.Viewer}

Open tiled images into the viewer, closing any others. To get the TiledImage instance created by open, add an event listener for OpenSeadragon.Viewer.html#.event:open, which when fired can be used to get access to the instance, i.e., viewer.world.getItemAt(0).
Parameters:
Name Type Description
tileSources Array | String | Object | function This can be a TiledImage specifier, a TileSource specifier, or an array of either. A TiledImage specifier is the same as the options parameter for OpenSeadragon.Viewer#addTiledImage, except for the index property; images are added in sequence. A TileSource specifier is anything you could pass as the tileSource property of the options parameter for OpenSeadragon.Viewer#addTiledImage.
initialPage Number If sequenceMode is true, display this page initially for the given tileSources. If specified, will overwrite the Viewer's existing initialPage property.
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

raiseEvent(eventName, eventArgs)

Trigger an event, optionally passing additional information.
Parameters:
Name Type Description
eventName String Name of event to register.
eventArgs Object Event-specific data.
Inherited From:
Source:

removeAllHandlers(eventName)

Remove all event handlers for a given event type. If no type is given all event handlers for every event type are removed.
Parameters:
Name Type Description
eventName String Name of event for which all handlers are to be removed.
Inherited From:
Source:

removeControl() → {OpenSeadragon.ControlDock}

Inherited From:
Source:
Returns:
Chainable.
Type
OpenSeadragon.ControlDock

removeHandler(eventName, handler)

Remove a specific event handler for a given event.
Parameters:
Name Type Description
eventName String Name of event for which the handler is to be removed.
handler OpenSeadragon.EventHandler Function to be removed.
Inherited From:
Source:

removeOverlay(element) → {OpenSeadragon.Viewer}

Removes an overlay identified by the reference element or element id and schedules an update.
Parameters:
Name Type Description
element Element | String A reference to the element or an element id which represent the ovelay content to be removed.
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

removeReferenceStrip()

Removes the reference strip and disables displaying it.
Source:

setAjaxHeaders(ajaxHeaders, propagateopt)

Update headers to include when making AJAX requests. Unless `propagate` is set to false (which is likely only useful in rare circumstances), the updated headers are propagated to all tiled images, each of which will subsequently propagate the changed headers to all their tiles. If applicable, the headers of the viewer's navigator and reference strip will also be updated. Note that the rules for merging headers still apply, i.e. headers returned by OpenSeadragon.TileSource#getTileAjaxHeaders take precedence over `TiledImage.ajaxHeaders`, which take precedence over the headers here in the viewer.
Parameters:
Name Type Attributes Default Description
ajaxHeaders Object Updated AJAX headers.
propagate Boolean <optional>
true Whether to propagate updated headers to tiled images, etc.
Source:

setControlsEnabled(true) → {OpenSeadragon.Viewer}

Shows or hides the controls (e.g. the default navigation buttons).
Parameters:
Name Type Description
true Boolean to show, false to hide.
Overrides:
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

setDebugMode(debugMode)

Turns debugging mode on or off for this viewer.
Parameters:
Name Type Description
debugMode Boolean true to turn debug on, false to turn debug off.
Source:

setFullPage(fullPage) → {OpenSeadragon.Viewer}

Toggle full page mode.
Parameters:
Name Type Description
fullPage Boolean If true, enter full page mode. If false, exit full page mode.
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

setFullScreen(fullScreen) → {OpenSeadragon.Viewer}

Toggle full screen mode if supported. Toggle full page mode otherwise.
Parameters:
Name Type Description
fullScreen Boolean If true, enter full screen mode. If false, exit full screen mode.
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

setMouseNavEnabled(enabled) → {OpenSeadragon.Viewer}

Parameters:
Name Type Description
enabled Boolean true to enable, false to disable
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

setVisible(visible) → {OpenSeadragon.Viewer}

Parameters:
Name Type Description
visible Boolean
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

updateOverlay(element, location, placementopt) → {OpenSeadragon.Viewer}

Updates the overlay represented by the reference to the element or element id moving it to the new location, relative to the new placement.
Parameters:
Name Type Attributes Default Description
element Element | String A reference to an element or an id for the element which is overlaid.
location OpenSeadragon.Point | OpenSeadragon.Rect The point or rectangle which will be overlaid. This is a viewport relative location.
placement OpenSeadragon.Placement <optional>
OpenSeadragon.Placement.TOP_LEFT The position of the viewport which the location coordinates will be treated as relative to.
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

Events

add-item-failed

Raised when an error occurs while adding a item.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
message String
source String
options Object The options passed to the addTiledImage method.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

add-overlay

Raised when an overlay is added to the viewer (see OpenSeadragon.Viewer#addOverlay).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
element Element The overlay element.
location OpenSeadragon.Point | OpenSeadragon.Rect
placement OpenSeadragon.Placement
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

after-resize

Raised after the viewer is resized (see OpenSeadragon.Viewport#resize). See also OpenSeadragon.Viewer#resize event which happens before the new bounds have been calculated and applied.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
newContainerSize OpenSeadragon.Point
maintain Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

animation

Raised when any spring animation update occurs (zoom, pan, etc.), after the viewer has drawn the new location.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

animation-finish

Raised when any spring animation ends (zoom, pan, etc.).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

animation-start

Raised when any spring animation starts (zoom, pan, etc.).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

before-destroy

Raised when the viewer is about to be destroyed (see OpenSeadragon.Viewer#before-destroy).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-blur

Raised when the OpenSeadragon.Viewer#canvas element loses keyboard focus.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-click

Raised when a mouse press/release or touch/remove occurs on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
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 differentiating between clicks and drags.
shift Boolean True if the shift key was pressed during this event.
originalEvent Object The original DOM event.
originalTarget Element The DOM element clicked on.
preventDefaultAction Boolean Set to true to prevent default click to zoom behaviour. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-contextmenu

Raised when a contextmenu event occurs in the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
position OpenSeadragon.Point The position of the event relative to the tracked element.
originalEvent Object The original DOM event.
preventDefault Boolean Set to true to prevent the default user-agent's handling of the contextmenu event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-double-click

Raised when a double mouse press/release or touch/remove occurs on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
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.
originalEvent Object The original DOM event.
preventDefaultAction Boolean Set to true to prevent default double tap to zoom behaviour. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-drag

Raised when a mouse or touch drag operation occurs on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
delta OpenSeadragon.Point The x,y components of the difference between start drag and end drag.
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.
originalEvent Object The original DOM event.
preventDefaultAction Boolean Set to true to prevent default drag to pan behaviour. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-drag-end

Raised when a mouse or touch drag operation ends on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
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.
originalEvent Object The original DOM event.
preventDefaultAction Boolean Set to true to prevent default drag-end flick behaviour. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-enter

Raised when a pointer enters the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. A 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.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-exit

Raised when a pointer leaves the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. A 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.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-focus

Raised when the OpenSeadragon.Viewer#canvas element gets keyboard focus.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-key

Raised when a keyboard key is pressed and the focus is on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
originalEvent Object The original DOM event.
preventDefaultAction Boolean Set to true to prevent default keyboard behaviour. Default: false.
preventVerticalPan Boolean Set to true to prevent keyboard vertical panning. Default: false.
preventHorizontalPan Boolean Set to true to prevent keyboard horizontal panning. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-key-press

Raised when a keyboard key is pressed and the focus is on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-nonprimary-press

Raised when any non-primary pointer button is pressed on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
position OpenSeadragon.Point The position of the event relative to the tracked element.
pointerType String "mouse", "touch", "pen", etc.
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.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-nonprimary-release

Raised when any non-primary pointer button is released on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
position OpenSeadragon.Point The position of the event relative to the tracked element.
pointerType String "mouse", "touch", "pen", etc.
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.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-pinch

Raised when a pinch event occurs on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
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 DOM event.
preventDefaultPanAction Boolean Set to true to prevent default pinch to pan behaviour. Default: false.
preventDefaultZoomAction Boolean Set to true to prevent default pinch to zoom behaviour. Default: false.
preventDefaultRotateAction Boolean Set to true to prevent default pinch to rotate behaviour. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-press

Raised when the primary mouse button is pressed or touch starts on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
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 still inside the tracked element when the button was released.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-release

Raised when the primary mouse button is released or touch ends on the OpenSeadragon.Viewer#canvas element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
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 still inside the tracked element when the button was released.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

canvas-scroll

Raised when a scroll event occurs on the OpenSeadragon.Viewer#canvas element (mouse wheel).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
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.
originalEvent Object The original DOM event.
preventDefaultAction Boolean Set to true to prevent default scroll to zoom behaviour. Default: false.
preventDefault Boolean Set to true to prevent the default user-agent's handling of the wheel event. Default: true.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

clear-overlay

Raised when all overlays are removed from the viewer (see OpenSeadragon.Drawer#clearOverlays).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

close

Raised when the viewer is closed (see OpenSeadragon.Viewer#close).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

constrain

Raised when the viewport constraints are applied (see OpenSeadragon.Viewport#applyConstraints).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
immediately Boolean whether the function that triggered this event was called with the "immediately" flag
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

container-enter

Raised when the cursor enters the OpenSeadragon.Viewer#container element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. A 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.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

container-exit

Raised when the cursor leaves the OpenSeadragon.Viewer#container element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
pointerType String "mouse", "touch", "pen", etc.
position OpenSeadragon.Point The position of the event relative to the tracked element.
buttons Number Current buttons pressed. A 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.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

controls-enabled

Raised when the navigation controls are shown or hidden (see OpenSeadragon.Viewer#setControlsEnabled).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
enabled Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

destroy

Raised when the viewer is destroyed (see OpenSeadragon.Viewer#destroy).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

flip

Raised when flip state has been changed.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
flipped Number The flip state after this change.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

full-page

Raised when the viewer has changed to/from full-page mode (see OpenSeadragon.Viewer#setFullPage).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
fullPage Boolean True if changed to full-page mode, false if exited full-page mode.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

full-screen

Raised when the viewer has changed to/from full-screen mode (see OpenSeadragon.Viewer#setFullScreen).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
fullScreen Boolean True if changed to full-screen mode, false if exited full-screen mode.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

home

Raised when the "home" operation occurs (see OpenSeadragon.Viewport#goHome).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
immediately Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

mouse-enabled

Raised when mouse/touch navigation is enabled or disabled (see OpenSeadragon.Viewer#setMouseNavEnabled).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
enabled Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

navigator-click

Raised when a click event occurs on the OpenSeadragon.Viewer#navigator element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
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 differentiating between clicks and drags.
shift Boolean True if the shift key was pressed during this event.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
preventDefaultAction Boolean Set to true to prevent default click to zoom behaviour. Default: false.
Source:

navigator-drag

Raised when a drag event occurs on the OpenSeadragon.Viewer#navigator element.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
position OpenSeadragon.Point The position of the event relative to the tracked element.
delta OpenSeadragon.Point The x,y components of the difference between start drag and end drag.
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.
originalEvent Object The original DOM event.
userData Object <nullable>
Arbitrary subscriber-defined object.
preventDefaultAction Boolean Set to true to prevent default drag to pan behaviour. Default: false.
Source:

navigator-scroll

Raised when a scroll event occurs on the OpenSeadragon.Viewer#navigator element (mouse wheel, touch pinch, etc.).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
tracker OpenSeadragon.MouseTracker A reference to the MouseTracker which originated this event.
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.
originalEvent Object The original DOM event.
preventDefault Boolean Set to true to prevent the default user-agent's handling of the wheel event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

open

Raised when the viewer has opened and loaded one or more TileSources.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
source OpenSeadragon.TileSource The tile source that was opened.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

open-failed

Raised when an error occurs loading a TileSource.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
message String Information about what failed.
source String The tile source that failed.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

page

Raised when the page is changed on a viewer configured with multiple image sources (see OpenSeadragon.Viewer#goToPage).
Type:
  • Object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
page Number The page index.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

pan

Raised when the viewport is panned (see OpenSeadragon.Viewport#panBy and OpenSeadragon.Viewport#panTo).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
center OpenSeadragon.Point
immediately Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

pre-full-page

Raised when the viewer is about to change to/from full-page mode (see OpenSeadragon.Viewer#setFullPage).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
fullPage Boolean True if entering full-page mode, false if exiting full-page mode.
preventDefaultAction Boolean Set to true to prevent full-page mode change. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

pre-full-screen

Raised when the viewer is about to change to/from full-screen mode (see OpenSeadragon.Viewer#setFullScreen). Note: the pre-full-screen event is not raised when the user is exiting full-screen mode by pressing the Esc key. In that case, consider using the full-screen, pre-full-page or full-page events.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
fullScreen Boolean True if entering full-screen mode, false if exiting full-screen mode.
preventDefaultAction Boolean Set to true to prevent full-screen mode change. Default: false.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

remove-overlay

Raised when an overlay is removed from the viewer (see OpenSeadragon.Viewer#removeOverlay).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
element Element The overlay element.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

reset-size

Raised when the viewer's content size or home bounds are reset (see OpenSeadragon.Viewport#resetContentSize).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
contentSize OpenSeadragon.Point
contentBounds OpenSeadragon.Rect Content bounds.
homeBounds OpenSeadragon.Rect Content bounds. Deprecated use contentBounds instead.
contentFactor Number
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

resize

Raised when a viewer resize operation is initiated (see OpenSeadragon.Viewport#resize). This event happens before the viewport bounds have been updated. See also OpenSeadragon.Viewer#after-resize which reflects the new viewport bounds following the resize action.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
newContainerSize OpenSeadragon.Point
maintain Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

rotate

Raised when rotation has been changed.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
degrees Number The number of degrees the rotation was set to.
immediately Boolean Whether the rotation happened immediately or was animated
pivot OpenSeadragon.Point The point in viewport coordinates around which the rotation (if any) happened
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

tile-drawing

This event is fired just before the tile is drawn giving the application a chance to alter the image. NOTE: This event is only fired when the drawer is using a <canvas>.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
tile OpenSeadragon.Tile The Tile being drawn.
tiledImage OpenSeadragon.TiledImage Which TiledImage is being drawn.
context OpenSeadragon.Tile The HTML canvas context being drawn into.
rendered OpenSeadragon.Tile The HTML canvas context containing the tile imagery.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

tile-drawn

- Needs documentation -
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
tiledImage OpenSeadragon.TiledImage Which TiledImage is being drawn.
tile OpenSeadragon.Tile
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

tile-load-failed

Triggered when a tile fails to load.
Type:
  • object
Properties:
Name Type Description
tile OpenSeadragon.Tile The tile that failed to load.
tiledImage OpenSeadragon.TiledImage The tiled image the tile belongs to.
time number The time in milliseconds when the tile load began.
message string The error message.
tileRequest XMLHttpRequest The XMLHttpRequest used to load the tile if available.
Source:

tile-loaded

Triggered when a tile has just been loaded in memory. That means that the image has been downloaded and can be modified before being drawn to the canvas.
Type:
  • object
Properties:
Name Type Description
image Image | * The image (data) of the tile. Deprecated.
data * image data, the data sent to ImageJob.prototype.finish(), by default an Image object
tiledImage OpenSeadragon.TiledImage The tiled image of the loaded tile.
tile OpenSeadragon.Tile The tile which has been loaded.
tileRequest XMLHttpRequest The AJAX request that loaded this tile (if applicable).
getCompletionCallback function A function giving a callback to call when the asynchronous processing of the image is done. The image will be marked as entirely loaded when the callback has been called once for each call to getCompletionCallback.
Source:

tile-unloaded

Triggered when a tile has just been unloaded from memory.
Type:
  • object
Properties:
Name Type Description
tiledImage OpenSeadragon.TiledImage The tiled image of the unloaded tile.
tile OpenSeadragon.Tile The tile which has been unloaded.
Source:

update-level

- Needs documentation -
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
tiledImage OpenSeadragon.TiledImage Which TiledImage is being drawn.
havedrawn Object
level Object
opacity Object
visibility Object
drawArea OpenSeadragon.Rect
topleft Object deprecated, use drawArea instead
bottomright Object deprecated, use drawArea instead
currenttime Object
best Object
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

update-overlay

Raised when an overlay's location or placement changes (see OpenSeadragon.Viewer#updateOverlay).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
element Element
location OpenSeadragon.Point | OpenSeadragon.Rect
placement OpenSeadragon.Placement
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

update-tile

- Needs documentation -
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
tiledImage OpenSeadragon.TiledImage Which TiledImage is being drawn.
tile OpenSeadragon.Tile
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

update-viewport

- Needs documentation -
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

viewport-change

Raised when any spring animation update occurs (zoom, pan, etc.), before the viewer has drawn the new location.
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

visible

Raised when the viewer is shown or hidden (see OpenSeadragon.Viewer#setVisible).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised the event.
visible Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source:

zoom

Raised when the viewport zoom level changes (see OpenSeadragon.Viewport#zoomBy and OpenSeadragon.Viewport#zoomTo).
Type:
  • object
Properties:
Name Type Attributes Description
eventSource OpenSeadragon.Viewer A reference to the Viewer which raised this event.
zoom Number
refPoint OpenSeadragon.Point
immediately Boolean
userData Object <nullable>
Arbitrary subscriber-defined object.
Source: