Skip to main content

Seadragon.Viewer class

Version 0.8.8 - Back to Seadragon Ajax API Reference

Overview

This class represents a single Seadragon viewer. It is the bridge between the HTML page and the Seadragon content. It provides the user interface, including mouse interaction, navigation and custom controls, and full page capability.

Constructors

SignatureDescription
Seadragon.Viewer(container)Creates a Seadragon.Viewer inside the given HTML element.

Properties

All properties are aliased; re-assigning them has no effect, but modifying them does.

NameTypeDescription
containerHTML ElementThe HTML element that was passed into the constructor.
elmtHTML ElementThe HTML element containing this viewer and its controls. Note that this is not the same HTML element that is passed into the constructor; the distinction is important for full page mode. The specifics of this element and its children are unspecified and implementation-dependent.
drawer Seadragon.DrawerIf content is open, this points to the Seadragon.Drawer instance that renders the content. Otherwise, this is null.
profiler Seadragon.ProfilerIf content is open, this points to a Seadragon.Profiler instance that is profiling each update. Otherwise, this is null.
source Seadragon.TileSourceIf content is open, this points to the Seadragon.TileSource instance for the content. Otherwise, this is null.
tracker Seadragon.MouseTrackerThe Seadragon.MouseTracker instance powering this viewer's default zoom/pan interactions. Modifying this tracker's handlers allows for easy tweaking of the default interactions.
viewport Seadragon.ViewportIf content is open, this points to the Seadragon.Viewport instance for the content. Otherwise, this is null.

Methods

Content

Name and SignatureReturn TypeDescription
isOpen()BooleanReturns true if content is currently open.
openDzi(jsonObj)-Asynchronously opens the DZI described by the given JSON object. The JSON format is documented in the Seadragon.DziTileSource class and is the same format returned by the Zoom.it API. Exactly one "open", "error" or "ignore" event is guaranteed to fire upon completion.
openDzi(xmlUrl, xmlString?)-Asynchronously opens the DZI from the XML file at the given URL. If the contents of the XML are also given as a string, the XML is not actually downloaded; otherwise, it is. (The location of the XML is needed in either case to determine the location of the tiles.) Exactly one "open", "error" or "ignore" event is guaranteed to fire upon completion.
openTileSource(tileSource)-Asynchronously opens the given Seadragon.TileSource instance. Exactly one "open", "error", or "ignore" event is guaranteed to fire upon completion.
close()-Closes any open content.

Controls

Name and SignatureReturn TypeDescription
addControl(elmt, anchor?)-Adds the given HTML element as a control to the viewer. The element is optionally anchored to a corner of the container based on the given Seadragon.ControlAnchor value. If no anchor is supplied, or if the anchor is ControlAnchor.NONE, the element is absolutely positioned inside the container.
removeControl(elmt)-Removes the given control element.
clearControls()-Removes all control elements.
getNavControl()HTML ElementReturns the <div> element for the default navigation control. The specific buttons in this control are children of this element, e.g. the first child is the zoom in button.

User Interface

Name and SignatureReturn TypeDescription
isDashboardEnabled()BooleanReturns true if the dashboard is currently enabled. The dashboard includes all of the controls.
isFullPage()BooleanReturns true if the viewport is currently full page.
isMouseNavEnabled()BooleanReturns true if the default mouse navigation is currently enabled.
isVisible()BooleanReturns true if the viewer is currently visible.
setDashboardEnabled(enabled)-Sets whether the dashboard should be enabled. The dashboard includes all of the controls.
setFullPage(fullPage)-Sets whether the viewport should be full page.
setMouseNavEnabled(enabled)-Sets whether the default mouse navigation should be enabled.
setVisible(visible)-Sets whether the viewer should be visible.
showMessage(message, delay?)-If no delay is given, closes any open content and shows the given message text, centered both horizontally and vertically in the viewer.

If a delay is given, delays showing the message until the given number of milliseconds have passed, and shows the message then only if no content is open. This is useful for delaying the showing of a "Loading..." message, for example, while making sure that the message isn't shown once the content has loaded.

Event Handling

Name and SignatureReturn TypeDescription
addEventListener(eventName, handler)-Adds the given handler function as a listener for the event with the given name. This function will receive this Viewer instance as a parameter.
removeEventListener(eventName, handler)-Removes the given handler function as a listener for the event with the given name.

Events

Note that all events except "error" are only fired when content is open; that is, all of the viewer's properties will be set.

NameDescription
openFired when content finishes opening and all of the viewer's properties have been set. Note that tiles will not yet be loaded, so content will not yet be drawn.
errorFired when content fails to open. Some of the viewer's properties will not be set.
ignoreFired when content becomes ready to open but is ignored by the viewer because a more recent open request was initiated after this content's corresponding open request. Content may or may not be open; some of the viewer's properties may not be set.
resizeFired when the viewer's container is resized, e.g. due to window resizing. This is also fired on fullscreen changes.
animationstartFired whenever an animation begins when there was no previous animation occuring. This is fired before the drawn content is updated.
animationfinishFired whenever an animation ends when there was a previous animation occuring. This is fired after the drawn content is updated.
animationFired every frame during which an animation is occuring. This is fired after the drawn content is updated each frame.