Seadragon.Viewer class

Version - Back to Seadragon Ajax Library

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

Signature	Description
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.

Name	Type	Description
container	HTML Element	The HTML element that was passed into the constructor.
elmt	HTML Element	The 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.Drawer	If content is open, this points to the Seadragon.Drawer instance that renders the content. Otherwise, this is null.
profiler	Seadragon.Profiler	If content is open, this points to a Seadragon.Profiler instance that is profiling each update. Otherwise, this is null.
source	Seadragon.TileSource	If content is open, this points to the Seadragon.TileSource instance for the content. Otherwise, this is null.
tracker	Seadragon.MouseTracker	The 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.Viewport	If content is open, this points to the Seadragon.Viewport instance for the content. Otherwise, this is null.

Methods

Content

Name and Signature	Return Type	Description
isOpen()	Boolean	Returns 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 Signature	Return Type	Description
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 Element	Returns 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 Signature	Return Type	Description
isDashboardEnabled()	Boolean	Returns true if the dashboard is currently enabled. The dashboard includes all of the controls.
isFullPage()	Boolean	Returns true if the viewport is currently full page.
isMouseNavEnabled()	Boolean	Returns true if the default mouse navigation is currently enabled.
isVisible()	Boolean	Returns 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 Signature	Return Type	Description
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.

Name	Description
open	Fired 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.
error	Fired when content fails to open. Some of the viewer's properties will not be set.
ignore	Fired 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.
resize	Fired when the viewer's container is resized, e.g. due to window resizing. This is also fired on fullscreen changes.
animationstart	Fired whenever an animation begins when there was no previous animation occuring. This is fired before the drawn content is updated.
animationfinish	Fired whenever an animation ends when there was a previous animation occuring. This is fired after the drawn content is updated.
animation	Fired every frame during which an animation is occuring. This is fired after the drawn content is updated each frame.