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.

Constructor

Parameters:
Name Type Description
options Object
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:
Inherited From:
Source:

element :Element

The parent element of this Viewer instance, passed in when the Viewer was created.
Type:
  • Element
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:

Methods

_cancelPendingImages()

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

addControl()

Inherited From:
Source:

addHandler(eventName, handler, userDataopt)

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.
Overrides:
Source:

addOnceHandler(eventName, handler, userDataopt, timesopt)

Add an event handler to be triggered only once (or a given number of times) 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.
times Number <optional>
1 The number of times to handle the event before removing it.
Overrides:
Source:

addOverlay(element, location, placement, onDraw) → {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 Description
element Element | String | Object A reference to an element or an id for the element which will be overlayed. 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 overlayed. This is a viewport relative location.
placement OpenSeadragon.Placement The position of the viewport which the location coordinates will be treated as relative to.
onDraw function 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.
Inherited From:
Source:
Fires:
Returns:
Chainable.
Type
OpenSeadragon.Viewer

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>
Opacity the tiled image should be drawn at by default.
compositeOperation String <optional>
How the image is composited onto other images.
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", the resulting 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
Inherited From:
Source:

forceRedraw() → {OpenSeadragon.Viewer}

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

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

goToPage() → {OpenSeadragon.Viewer}

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

isFullPage() → {Boolean}

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

open(tileSources) → {OpenSeadragon.Viewer}

Open tiled images into the viewer, closing any others.
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.
Inherited From:
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.
Overrides:
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.
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

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

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

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

update(The)

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

updateOverlay(element, location, placement) → {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 Description
element Element | String A reference to an element or an id for the element which is overlayed.
location OpenSeadragon.Point | OpenSeadragon.Rect The point or rectangle which will be overlayed. This is a viewport relative location.
placement OpenSeadragon.Placement 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: