Class: Navigator

OpenSeadragon.Navigator

The Navigator provides a small view of the current image as fixed while representing the viewport as a moving box serving as a frame of reference in the larger viewport as to which portion of the image is currently being examined. The navigator's viewport can be interacted with using the keyboard or the mouse.
Members Methods

Constructor

Parameters:
Name Type Description
options Object Navigator options
Properties
Name Type Attributes Description
element Element <optional>
 An element to use for the navigator.
id String <optional>
 Id of the element to use for the navigator. However, this is ignored if options.element is provided.
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
Inherited From:
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
Inherited From:
Source:

drawer :OpenSeadragon.Drawer

Handles rendering of tiles in the viewer. Created for each TileSource opened.
Type:
  • OpenSeadragon.Drawer
Inherited From:
Source:

element :Element

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

initialPage :Number

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

viewport :OpenSeadragon.Viewport

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

world :OpenSeadragon.World

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

Methods

_cancelPendingImages()

Cancel the "in flight" images.
Inherited From:
Source:

addButton(button)

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

addControl()

Inherited From:
Source:

addHandler(eventName, handler, userDataopt, priorityopt) → {Boolean}

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.
Overrides:
Source:
Returns:
- True if the handler was added, false if it was rejected
Type
Boolean

addOnceHandler(eventName, handler, userDataopt, timesopt, priorityopt) → {Boolean}

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.
Overrides:
Source:
Returns:
- True if the handler was added, false if it was rejected
Type
Boolean

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 is the responsibility of the callback to do any drawing/positioning. It is passed position, size and element.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Overrides:
Source:
Fires:

areControlsEnabled() → {Boolean}

Inherited From:
Source:
Returns:
Type
Boolean

bindSequenceControls() → {OpenSeadragon.Viewer}

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

bindStandardControls() → {OpenSeadragon.Viewer}

Inherited From:
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.
Inherited From:
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

close() → {OpenSeadragon.Viewer}

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

currentPage() → {Number}

Gets the active page of a sequence
Inherited From:
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
Overrides:
Source:
Fires:

forceRedraw() → {OpenSeadragon.Viewer}

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

forceResize()

Force the viewer to reset its size to match its container.
Inherited From:
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.).
Inherited From:
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.
Overrides:
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.
Inherited From:
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)
Inherited From:
Source:

goToPage() → {OpenSeadragon.Viewer}

Inherited From:
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)
Inherited From:
Source:

isFullPage() → {Boolean}

Inherited From:
Source:
Returns:
Type
Boolean

isFullScreen() → {Boolean}

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

isMouseNavEnabled() → {Boolean}

Inherited From:
Source:
Returns:
Type
Boolean

isOpen() → {Boolean}

Inherited From:
Source:
Returns:
Type
Boolean

isVisible() → {Boolean}

Inherited From:
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.
Overrides:
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.
Inherited From:
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

raiseEvent(eventName, eventArgs) → {Boolean}

Trigger an event, optionally passing additional information.
Parameters:
Name Type Description
eventName String Name of event to register.
eventArgs Object Event-specific data.
Overrides:
Source:
Returns:
True if the event was fired, false if it was rejected because of rejectEventHandler(eventName)
Type
Boolean

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.
Overrides:
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.
Overrides:
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.
Inherited From:
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

removeReferenceStrip()

Removes the reference strip and disables displaying it.
Inherited From:
Source:

requestDrawer(drawerCandidate, options) → {Object|Boolean}

Request a drawer for this viewer, as a supported string or drawer constructor.
Parameters:
Name Type Description
drawerCandidate String | OpenSeadragon.DrawerBase The type of drawer to try to construct.
options Object
Properties
Name Type Attributes Description
mainDrawer Boolean <optional>
 Whether to use this as the viewer's main drawer. Default = true.
redrawImmediately Boolean <optional>
 Whether to immediately draw a new frame. Only used if options.mainDrawer = true. Default = true.
drawerOptions Object <optional>
 Options for this drawer. Defaults to viewer.drawerOptions. for this viewer type. See OpenSeadragon.Options.
Inherited From:
Source:
Returns:
The drawer that was created, or false if the requested drawer is not supported
Type
Object | Boolean

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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
Source:

setFlip(state)

Flip navigator element
Parameters:
Name Type Description
state Boolean Flip state to set.
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.
Inherited From:
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.
Inherited From:
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

setHeight(height)

Explicitly sets the height of the navigator, in web coordinates. Disables automatic resizing.
Parameters:
Name Type Description
height Number | String the new height, either a number of pixels or a CSS string, such as "100%"
Source:

setMouseNavEnabled(enabled) → {OpenSeadragon.Viewer}

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

setVisible(visible) → {OpenSeadragon.Viewer}

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

setWidth(width)

Explicitly sets the width of the navigator, in web coordinates. Disables automatic resizing.
Parameters:
Name Type Description
width Number | String the new width, either a number of pixels or a CSS string, such as "100%"
Source:

update(viewportopt)

Used to update the navigator minimap's viewport rectangle when a change in the viewer's viewport occurs.
Parameters:
Name Type Attributes Description
viewport OpenSeadragon.Viewport <optional>
 The viewport to display. Default: the viewport this navigator is tracking.
Source:

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.
Inherited From:
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

updateSize()

Used to notify the navigator when its size has changed. Especially useful when OpenSeadragon.Options.navigatorAutoResize is set to false and the navigator is resizable.
Source: