INFO: WebAnnotationViewer - JavaScript API Reference (Legacy Web Controls)

Legacy Controls NOTICE

This article references our legacy Web Forms Web Viewing controls (WebImageViewer, WebAnnotationViewer, WebThumbnailViewer). It is preserved for archival purposes, but support strongly recommends using our modern HTML5 web controls: WebDocumentViewer, WebDocumentThumbnailer instead)

INFO: WebDocumentViewer Whitepaper - Getting Started With Web Viewing

Main Article Content

atalaWebAnnotationViewer

Although this function is public, it is not intended for users to create WebAnnotationViewers on the client side directly. The server side generated HTML is needed for this function to initialize.

Properties

Server Name JavaScript Syntax : Return value Description
Annotations[index] getAnnotation(index : int): atalaAnnotation
getAnnotation(layerindex : int, index : int) : atalaAnnotation		 Gets the atalaAnnotation object at the given layer and item indexes, respectively.
Annotations getAnnotations() : Array Returns an array of atalaAnnotation objects that are on every layer in this control.
N/A getAnnotationDataUrl() : string Returns the url used to store the cached data file.
AuthorMode getAuthorMode() : int Gets a value that indicates how many annotations can be created with the mouse.

Returns an int: 0:Unlimited 1:Single
AutoLinkThumbnailViewer getAutoLinkThumbnailViewer() : bool Gets a value that indicates whether this control should automatically link events with the WebThumbnailViewer that is associated with this control
CurrentLayer getCurrentLayer() : atalaLayer
setCurrentLayer(value: atalaLayer)
setCurrentLayer(value: int)		 Gets or sets the current active layer in the control. This is primarily used to indicate which layer mouse events are handled on.
CurrentUserName getCurrentUserName() : string Returns a string that represents the current user name associated with this session.

Note: This is not automatically populated, and as such, the CurrentUserName property must be set on the server side.
InteractMode getInteractMode(): int
setInteractMode(value : int)		 Expected input: int from 0-2, 0:None 1:View 2:Edit
Annotations.Layers getLayers() : Array Returns an array of atalaLayer objects contained in this control.
N/A getSelectedAnnotations() : Array Returns an array of atalaAnnotation objects that have the Selected property set to true.

Inherited Properties from atalaWebImageViewer

Server Name JavaScript Syntax : Return value Description
ClientID ID() : string Gets the server control identifier generated by ASP.NET.
N/A Form() : object Gets the form object that the Web server control is on.
AntialiasDisplay getAntialiasDisplay() : int
setAntialiasDisplay(value : int)		 Gets or sets the quality of the scaled image.

Expected input: AntialiasDisplayMode or int from 0-3, 0:None 1:ScaleToGray 2:ReductionOnly 3:Full
AutoZoom getAutoZoom() : int
setAutoZoom(value : int)		 Gets or sets a value indicating how the image should be zoomed as the control is resized or the image size changes. This will override setZoom. For a one time zoom, see setZoomMode.

Expected input: AutoZoomMode or int from 0-5, 0:None 1:BestFit 2:BestFitShrinkOnly 3:FitToWidth 4:FitToHeight 5:FitToImage
BackColor getBackColor() : string
setBackColor(value : string)		 Gets or sets the background color of the Web server control.

Expected input: string representing a hex value or exact color name: '#ACFF00'
BorderColor getBorderColor() : string
setBorderColor(value : string)		 Gets or sets the border color of the Web server control.

Expected input: string representing a hex value or exact color name: '#ACFF00'
BorderStyle getBorderStyle() : string
setBorderStyle(value : string)		 Gets or sets the border style used for this Web server control.

Expected input: string representing Style: '1px solid #FF9900'
BorderWidth getBorderWidth() : int
setBorderWidth(value : int)		 Gets or sets the border width of the Web server control in pixels.
BrowserFormat getBrowserFormat() : int Gets the format of the images created for browser output.

Returns an int: 0:Jpeg 1:Png 2:Gif 3:Auto
CachePath getCachePath() : string Gets the file path used for the file cache as specified in the Web.config file.
Caption getCaption() : string
setCaption(value : string)		 Gets or sets a string used for creating a caption under the Web server control. HTML syntax is allowed.

Note: This property is tied to a hidden input tag, so changing this value to HTML in JavaScript could cause problems if the page needs to PostBack.
Centered getCentered() : bool
setCentered(value : bool)		 Gets or sets a value indicating if the image is centered when the image is smaller than the Web server control.
N/A getDisplayImageUrl() : string Gets a url that will return the current viewable portion of the image. Often used for printing the current area of the image.
Font getFont() : string
setFont(value : string)		 Gets or sets the font name associated with the Web server control.

Expected input: string representing font name: 'Verdana'
ForeColor getForeColor() : string
setForeColor(value : string)		 Gets or sets the foreground color (typically the color of the text) of the Web server control.

Expected input: string representing a hex value or exact color name: '#ACFF00'
N/A getFrameIndex() : int Gets the index value used to open the current image.

Note: If the image has been modified with a server side ApplyCommand, or has been opened from a method other than OpenUrl or a linked WebThumbnailViewer, this will always return 0.
Height getHeight() : string
setHeight(value : string)		 Gets or sets the CSS height style property of the server control.

Expected input: string representing style height: '320px'
ImageDisplayOrder getImageDisplayOrder() : int Gets the order that tiles are loaded.

Returns an int: 0:Sequential 1:VisibleFirst 2:OnDemand
Image.Size getImageSize() : atalaSize Gets the size, in pixels, of the current image.
N/A getImageUrl() : string Gets the currently loaded image url.
MouseTool getMouseToolLeft() : int
getMouseToolRight() : int
setMouseTool(left: int, right: int)		 Gets or sets the behavior of the mouse when interacting with the viewable area.

Expected input: MouseToolType or int from 0-7, 0:None 1:Center 2:Selection 3:ZoomIn 4:ZoomOut 5:ZoomArea 6:Pan 7:PassThrough
MouseTool.Cursor getMouseToolCursor() : int
setMouseToolCursor(value : int)		 Gets or sets the cursor used with the mouse tool.

Expected input: MouseToolCursor or int from 0-8, 0:Auto 1:Arrow 2:Crosshair 3:Grab 4:Hand 5:Move 6:ZoomIn 7:ZoomOut 8:Custom
Note: Currently, Grab is a CSS Extension supported by Mozilla based browsers only.
MouseTool.CustomCursor getMouseToolCustomCursor() : string
setMouseToolCustomCursor(value : string)		 Gets or sets a value that represents the custom CSS style used for the MouseTool.

Expected input: string representing Style: 'wait' or 'url(MyCursor.cur)'
Note: Url based CSS cursor styles may not work in all browsers.
PathToResources getPathToResources() : string Gets the virtual path to where the image, script, and cursor files are located.
N/A getReturnValue() : var Gets the return value populated by the last successful RemoteInvoke.
ImagePosition getScrollPosition() : atalaPoint
setScrollPosition(value : atalaPoint)		 Gets or sets the upper left image position in relation to the upper left corner of the Web server control. Negative values are expected.

Expected input: atalaPoint
ScrollBarVisibility getScrollBarVisibility() : int Gets the visibility of the scrollbars.

Returns an int: 0:Dynamic 1:None 2:Always
Selection getSelection() : Selection Gets the Selection object of this Web server control.
TileSize getTileSize() : atalaSize Gets the height and width of the tiles in pixels.
TitleBar getTitleBar() : string
setTitleBar(value : string)		 Gets or sets a string used for a creating a title bar above the Web server control. HTML syntax is allowed.

Note: This property is tied to a hidden input tag, so changing this value to HTML in JavaScript could cause problems if the page needs to PostBack.
ViewPortSize getViewPortSize() : atalaSize Gets the size of the viewable area, excluding scroll bars.
Visibility getVisibility() : string
setVisibility(value : string)		 Gets or sets a value that indicates whether the Web server control is hidden or visible on the page.

Expected input: string that is either 'hidden', 'visible', or 'inherit'.
Note: 'inherit' will return VisibilityStyle.Visible on the server side.
Width getWidth() : string
setWidth(value : string)		 Gets or sets the CSS width style property of the server control.

Expected input: string representing style width: '200px'
Zoom getZoom() : float
setZoom(value : float)		 Gets or sets the zoom level of the image in this Web server control.
ZoomInOutPercentage getZoomInOutPercentage() : int
setZoomInOutPercentage(value : int)		 Gets or sets the percentage used to increase or decrease the zoom level when the zoom MouseTools are used.

Events

Server Name JavaScript Syntax Description

Annotation Events

 Note: These events only pertain to the underlying atalaAnnotation objects.
N/A AnnotationChanged = function(e) Fires when an atalaAnnotation has changed. Passes an AnnotationEvent object.
N/A AnnotationChanging = function(e) Fires while an atalaAnnotation is changing. Passes an AnnotationEvent object.
N/A AnnotationClicked = function(e) Fires when an atalaAnnotation is clicked with the left mouse button. Passes an AnnotationEvent object.
N/A AnnotationCreated = function(e) Fires when an atalaAnnotation is created with the mouse. Passes an AnnotationEvent object.
N/A AnnotationDoubleClicked = function(e) Fires when an atalaAnnotation is double-clicked with the left mouse button. Passes an AnnotationEvent object.
N/A AnnotationMouseDown = function(e) Fires when a mouse button is pressed down on an atalaAnnotation. Passes an AnnotationEvent object.
N/A AnnotationMouseDownLeft = function(e) Fires when the left mouse button is pressed down on an atalaAnnotation. Passes an AnnotationEvent object.
N/A AnnotationMouseDownRight = function(e) Fires when the right mouse button is pressed down on an atalaAnnotation. Passes an AnnotationEvent object.
N/A AnnotationMouseMove = function(e) Fires when the mouse cursor moves over an atalaAnnotation. Passes an AnnotationEvent object.
N/A AnnotationMouseOut = function(e) Fires when the mouse cursor leaves an atalaAnnotation's area. Passes an AnnotationEvent object.
N/A AnnotationMouseOver = function(e) Fires when the mouse cursor enters an atalaAnnotation's area. Passes an AnnotationEvent object.
N/A AnnotationMouseUp = function(e) Fires when a mouse button is released on an atalaAnnotation. Passes an AnnotationEvent object.
N/A AnnotationRightClicked = function(e) Fires when an atalaAnnotation is right clicked. Passes an AnnotationEvent object.
N/A AnnotationsChanged = function(e) Fires when the z-order of atalaAnnotations has changed. Passes an AnnotationEvent object.

Layer Events

 Note: These events only pertain to the underlying atalaLayer objects.
N/A CurrentLayerChanged = function(e) Fires when the current atalaLayer object has been changed to a different atalaLayer. Passes an AnnotationEvent object.
N/A LayerChanged = function(e) Fires when an atalaLayer has changed. Passes an AnnotationEvent object.
N/A LayersChanged = function (e) Fires when the z-order of atalaLayers has changed. Passes an AnnotationEvent object.

Events inherited from atalaWebImageViewer

Server Name JavaScript Syntax Description
N/A AntialiasDisplayChanged = function() Fires when the AntialiasDisplay property has changed.
N/A AutoZoomChanged = function() Fires when the AutoZoom property has changed.
N/A BackColorChanged = function() Fires when the BackColor property has changed.
N/A BorderColorChanged = function() Fires when the BorderColor property has changed.
N/A BorderStyleChanged = function() Fires when the BorderStyle property has changed.
N/A BorderWidthChanged = function() Fires when the BorderWidth property has changed.
N/A CaptionChanged = function() Fires when the Caption property has changed.
CenteredChanged CenteredChanged = function() Fires when the Centered property has changed.
N/A FontChanged = function() Fires when the Font property has changed.
N/A ForeColorChanged = function() Fires when the ForeColor property has changed.
ImageChanged ImageChanged = function() Fires when the Image has changed.
N/A ImageSizeChanged = function() Fires when the Image changes size.
N/A MouseToolChanged = function() Fires when the MouseTool property has changed.
RemoteInvoked RemoteInvoked = function() Fires when the RemoteInvoke function is called.
ImagePositionChanged ScrollPositionChanged = function() Fires when the ScrollPosition has changed
SelectionChanged SelectionChanged = function() Fires when the Selection has changed.
N/A SizeChanged = function() Fires when the Size property has changed.
N/A TitleBarChanged = function() Fires when the TitleBar property has changed.
N/A VisibilityChanged = function() Fires when the Visibility property has changed.
N/A ZoomChanged = function() Fires when the Zoom property has changed.
N/A ZoomInOutPercentageChanged = function() Fires when the ZoomInOutPercentage property has changed.

Mouse Events

 Note: All of these events pertain to the underlying image only, and attempt to pass a ImageMouseEvent object to the function.
N/A Clicked = function(e) Fires when the image is clicked. Passes an ImageMouseEvent object.
N/A DoubleClicked = function(e) Fires when the image is double clicked. Passes an ImageMouseEvent object.
N/A MouseDown = function(e) Fires when a mouse button is pressed down on the image. Passes an ImageMouseEvent object.
N/A MouseDownLeft = function(e) Fires when the when the left mouse button is pressed down. Passes an ImageMouseEvent object.
N/A MouseDownRight = function(e) Fires when the when the right mouse button is pressed down. Passes an ImageMouseEvent object.
N/A MouseMove = function(e) Fires when the mouse cursor moves over the image. Passes an ImageMouseEvent object.
N/A MouseOut = function(e) Fires when the mouse cursor leaves the image area. Passes an ImageMouseEvent object.
N/A MouseOver = function(e) Fires when the mouse cursor enters the image area. Passes an ImageMouseEvent object.
N/A MouseUp = function(e) Fires when a mouse button is released on the image. Passes an ImageMouseEvent object.
N/A RightClicked = function(e) Fires when the image is right clicked. Passes an ImageMouseEvent object.

Key Events

 Note: The control must have focus for these events to fire. You can programmatically set focus to this control by calling Focus(). These events also attempt to pass a ImageKeyEvent object to the function.
N/A KeyDown = function(e) Fires when a key is pressed down, if the control has focus. Passes an ImageKeyEvent object.
N/A KeyUp = function(e) Fires when a key is released, if the control has focus. Passes an ImageKeyEvent object.
N/A KeyPress = function(e) Fires when a key is pressed down, and then released, if the control has focus. Passes an ImageKeyEvent object.

Methods

Server Name JavaScript Syntax : Return value Description
Annotations.Layers.Add AddLayer(layer: atalaLayer) : bool Adds the given atalaLayer to this control. Returns true on success, false otherwise.
N/A Clear() Clears all annotations, all layers, and the image contained in this control.
Annotations.Layers.Clear ClearAnnotations() Clears all annotations and all layers contained in this control.
N/A CountAnnotations() : int Returns an int of the total count of all annotations on all layers in this control.
Annotations.Layers.Count CountLayers() : int Returns an int of the count of all layers in this control.
N/A CreateAnnotation(type: string) : atalaAnnotation

CreateAnnotation(type: string, name: string) : atalaAnnotation

Creates and returns an atalaAnnotation from the object type string specified. The string must represent an object type that inherits from Atalasoft.Annotate.AnnotationData on the server side.

Expected input: string representing AnnotationData: 'EllipseData' or 'RectangleData', string representing the name of a DefaultAnnotation created on the server side.
Note: The atalaAnnotation returned must be added to an atalaLayer by using InsertAnnotation or it will be created by drawing it with the mouse (if the current AnnotationInteractMode allows)
N/A CreateLayer() : atalaLayer Creates and returns an atalaLayer object.

Note: The atalaLayer returned must be added using AddLayer or it (including child annotations) will not be visible.
N/A DeleteAnnotation(zindex: int) : bool Deletes the atalaAnnotation at the given z-index from the CurrentLayer. Returns true on success, false otherwise.
N/A DeleteAnnotations(anns: Array) : bool Deletes an Array of atalaAnnotations from their parent atalaLayers. Returns true on success, false otherwise.
N/A DeselectAll() Sets the Selected property of all atalaAnnotations on all atalaLayers to false, and hides their grips.
Annotations.CurrentLayer.Insert InsertAnnotation(ann: atalaAnnotation, zindex: int) : bool Inserts the given atalaAnnotation into the CurrentLayer, at the given z-index, and automatically removes it from it's previous parent object (if any). Returns true on success, false otherwise.
LoadAnnotationDataUrl LoadAnnotations(url: string) Loads annotation data from a URL or virtual path.
N/A SelectAll() Sets the Selected property of all atalaAnnotations on all atalaLayers to true, and shows their grips.

Methods Inherited from atalaWebImageViewer

Server Name JavaScript Syntax Description
N/A ClearImage() Clears the image from client side only, used to return to a blank state.
N/A Focus() Puts focus on the WebImageViewer, used to enable key events.
N/A Invalidate() Forces the WebImageViewer to re-position child objects.
OpenUrl OpenUrl(url: string)
OpenUrl(url: string, index: int)		 Opens an image into the WebImageViewer control from a URL or virtual path, and frame index.

Note: This function is asynchronous. If any code needs to be executed after this call, it should be placed in the ImageChanged event handler.
N/A PauseRefresh() Pauses UI updates for this control until ResumeRefresh is called. Pauses and Refreshes are nestable. The update happens when an equal number of ResumeRefresh and PauseRefresh calls are made.
Print Print() Prints the current image using javascript client code.
Redo Redo() Re-does an undo.
Invoke RemoteInvoke(mthd : string)
RemoteInvoke(mthd : string, args : Array)		 Remotely invokes a server side method with the array of arguments.

Note: This function is asynchronous. If any code needs to be executed after this call, it should be placed in the RemoteInvoked event handler.
N/A ResumeRefresh() Resumes paused UI updates for this control. Pauses and Refreshes are nestable. The update happens when an equal number of ResumeRefresh and PauseRefresh calls are made.
N/A ScrollBy(dx : int, dy : int) Scrolls the viewer by the given values.
N/A ScrollTo(x: int, y: int) Scrolls the viewer to the given coordinates.
N/A setZoomMode(value : int) Zoom the image once, according to the given AutoZoomMode.

Expected input: AutoZoomMode or int from 0-5, 0:None 1:BestFit 2:BestFitShrinkOnly 3:FitToWidth 4:FitToHeight 5:FitToImage
Undo Undo() Reverts the image back to the previously cached image.

Note: This function is limited to Image changes only. The number of available undos relies on the server side CacheLevels property of the control.
Update Update() Forces the current image to be cached and updates the viewable area.

AnnotationEvent

This object is based on the browser's mouse event object, if it pertains to a mouse event. The following properties are in addition to the properties that are specified by each individual browser.

Usage:

JavaScript 
/* You will need a WebAnnotationViewer and a reference to ClientTools.js before this snippet.
 * This reference is automatically added to the page inline with the WebControls,
 * so placing this snippet below the WebAnnotationViewer control will be sufficient.
 */
Atalasoft.Utils.InitClientScript(BindAnnotationEvents);
function BindAnnotationEvents(){
   WebAnnotationViewer1.AnnotationDoubleClicked = AnnotationEventExample;
   WebAnnotationViewer1.AnnotationRightClicked = AnnotationEventExample;
}

// This simple example alerts the user when an annotation is double or right clicked.
function AnnotationEventExample(e){
   var pos = Atalasoft.Utils.getMousePosition(e);
   alert('Event fired on annotation at position: ' + pos.X + 'x' + pos.Y);
}

Properties

Server Name JavaScript Syntax : Return value Description
N/A annotation : atalaAnnotation The atalaAnnotation object that this event was fired from, if any.

Returns null if this event was fired from a layer.
N/A layer : atalaLayer The atalaLayer object that this event was fired from, if any.

Returns null if this event was fired from an annotation.

atalaLayer

This object represents the client side JavaScript version of an Atalasoft.Annotations.LayerAnnotation object.

Properties

Server Name JavaScript Syntax : Return value Description
LayerAnnotation.Items getAnnotations() : Array Returns an array of annotations that are contained in this layer.
N/A getLayerIndex() : int Returns an integer that corresponds with the array index of this layer.
LayerAnnotation.Visible getVisibility() : string
setVisibility(value : string)		 Gets or sets a value that indicates whether the layer and child elements are hidden or visible in the control.

Expected input: string that is either "hidden" or "visible"

Methods

Server Name JavaScript Syntax : Return value Description
LayerAnnotation.Items.Add Add() : bool Adds the given atalaAnnotation to the annotation array at the top most z-order. Returns true if the add succeeded, false otherwise.
N/A Delete() : bool Deletes the atalaAnnotation at the given index, and disposes of DOM objects. Returns true on success, false on failure.
LayerAnnotation.Items.Insert Insert() : bool Inserts the given atalaAnnotation into the annotation array at the given index. Returns true if the insert succeeded, false otherwise.

Events

Server Name JavaScript Syntax Description
N/A Changed = function(e) Fires when the layer has changed.
N/A ItemsChanged = function(e) Fires when child annotations have changed z-order.

atalaAnnotation

This object represents the client side JavaScript version of an Atalasoft.Annotations.AnnotationUI object.

Properties

Server Name JavaScript Syntax : Return value Description
AnnotationUI.AspectRatio getAspectRatio() : float
setAspectRatio(value : float)		 Gets or sets a value that indicates the aspect ratio of this annotation. A value of zero will not maintain any aspect ratio.
N/A setEditorHtml(value : string) Sets the innerHTML of the DOM object that is used to edit the annotation.
N/A getEditorObject() : object Gets the DOM object that is used to edit the annotation.
AnnotationUI.Height getHeight() : int
setHeight(value : int)		 Gets or sets the height of the annotation.
AnnotationUI.Movable getMovable() : bool
setMovable(value : bool)		 Gets or sets a value that indicates whether the annotation can be moved with the mouse.

getParent() : atalaLayer Gets the parent object of this annotation.
AnnotationUI.Position getPosition() : atalaPoint
setPosition(value : atalaPoint)		 Gets or sets the position of the annotation.

getRectangle() : atalaRectangle
setRectangle(value : atalaRectangle)		 Gets or sets the size and position of this annotation.
AnnotationUI.Resizable getResizable() : bool
setResizable(value : bool)		 Gets or sets a value that indicates whether the annotation can be resized with the mouse.

getSize() : atalaSize
setSize(value : atalaSize)		 Gets or sets the size of this annotation.
AnnotationUI.Selected getSelected() : bool
setSelected(value : bool)		 Gets or sets a value that indicates whether the annotation is selected.
AnnotationUI.Tooltip getToolTip() : string
setToolTip(value : string)		 Gets or sets the tooltip that is displayed when the mouse is moved over this annotation.

getType() : string Gets the AnnotationData type for this annotation.
AnnotationUI.Visible getVisibility() : string
setVisibility(value : string)		 Gets or sets a value that indicates whether the annotation is hidden or visible.

Expected input: string that is either "hidden" or "visible"
AnnotationUI.Width getWidth() : int
setWidth(value : int)		 Gets or sets the width of the annotation.
N/A getZIndex() : int Gets the z-index of this annotation.

Methods

Server Name JavaScript Syntax Description
N/A HideEditor() Hides the editor for this annotation, if there is one.
N/A ShowEditor() Shows the editor for this annotation, if there is one.
N/A Synchronize() Synchronizes the annotation bounds with underlying data. This should only be used if the data object is being changed directly.
N/A Update()

Synchronizes the client-side annotation data with the server-side annotation data, and requests a new image from the server.
N/A Repaint()

Sends a request to the server for a new annotation image.

Events

Server Name JavaScript Syntax Description
N/A Changed = function(e) Fires when the annotation has finished being modified.
N/A Changing = function(e) Fires while the annotation is being modified through mouse movement.
N/A Clicked = function(e) Fires when the annotation is clicked.
N/A DoubleClicked = function(e) Fires when the annotation is double clicked.
N/A MouseDown = function(e) Fires when a mouse button is pressed down on the annotation.
N/A MouseDownLeft = function(e) Fires when the left mouse button is pressed down on the annotation.
N/A MouseDownRight = function(e) Fires when the right mouse button is pressed down on the annotation.
N/A MouseMove = function(e) Fires when the mouse cursor moves over the annotation.
N/A MouseOut = function(e) Fires when the mouse cursor leaves the annotation area.
N/A MouseOver = function(e) Fires when the mouse cursor enters the annotation area.
N/A MouseUp = function(e) Fires when a mouse button is released on the annotation.
N/A RightClicked = function(e) Fires when the annotation is right clicked.
N/A Selected = function(e) Fires when the annotation is selected.

Original Article:
Q10357 - INFO: WebAnnotationViewer - JavaScript API Reference (Legacy Web Controls)
Posted 6 Years Ago, Updated 6 Years Ago
https://www.atalasoft.com/kb2/KB/50130/INFO-WebAnnotationViewer-JavaScript-API-Reference-Legacy-Web-Controls