DsImageViewer
Class: DsImageViewer
Document Solutions Image Viewer (DsImageViewer) is a fast JavaScript based client-side Image Viewer that runs in all major browsers.
Example
var viewer = new DsImageViewer("#root");
Extends
Constructors
Constructor
new DsImageViewer(element, options?): DsImageViewer;
DsImageViewer constructor.
Parameters
element
Required. HTML element or CSS selector.
string | HTMLElement
options?
Partial<ViewerOptions>
Optional. Viewer options.
Returns
DsImageViewer
Inherited from
Accessors
actualSize
Get Signature
get actualSize(): object;
Gets the actual display size of the active image, including the active zoom value.
Returns
object
height
height: number;
width
width: number;
Inherited from
adaptiveNaturalSize
Get Signature
get adaptiveNaturalSize(): object;
Gets the active image DPI adaptive natural size. This is the image size that will be used to display the image at 100%. The adaptiveNaturalSize property is used for the actual size calculations.
Returns
object
height
height: number;
width
width: number;
Inherited from
GcImageViewer.adaptiveNaturalSize
eventBus
Get Signature
get eventBus(): IEventBus;
Image viewer event bus.
Example
viewer.eventBus.on("after-open", function(args) {
console.log("Image opened.", args);
});
viewer.open('Test.png');
Returns
Inherited from
frameIndex
Get Signature
get frameIndex(): number;
Gets or sets the active frame index. This is applicable for multi-frame images such as TIFF and ICO.
When setting this value, it will also be used as the initial frame index when opening a new image.
Example
var viewer = new DsImageViewer('#root');
viewer.frameIndex = 9;
viewer.open('Test.ico');
Returns
number
Inherited from
framesCount
Get Signature
get framesCount(): number;
Gets total frames count for the active image. Applicable for TIFF, ICO images.
Example
var viewer = new DsImageViewer('#root');
viewer.onAfterOpen.register(function() {
alert("The image opened. Total number of frames: " + viewer.framesCount);
});
viewer.open('Test.png');
Returns
number
Inherited from
hasImage
Get Signature
get hasImage(): boolean;
Indicates whether the viewer has opened the image.
Example
var hasImageFlag = viewer.hasImage;
Returns
boolean
Inherited from
hasRedo
Get Signature
get hasRedo(): boolean;
Gets a value indicating whether the image viewer can redo changes.
Example
if(viewer.hasRedo) {
viewer.redo();
}
Returns
boolean
Inherited from
hasUndo
Get Signature
get hasUndo(): boolean;
Gets a value indicating whether the image viewer can undo changes.
Example
if(viewer.hasUndo) {
viewer.undo();
}
Returns
boolean
Inherited from
imageFormat
Get Signature
get imageFormat(): ImageFormatCode;
Gets a format type of the opened image.
Returns
Inherited from
isAnimationStarted
Get Signature
get isAnimationStarted(): boolean;
Gets a value indicating whether the image animation has started.
Example
// Toggle image animation:
const viewer = DsImageViewer.findControl("#root");
if(viewer.isAnimationStarted) {
viewer.stopAnimation();
} else {
viewer.startAnimation();
}
Returns
boolean
Inherited from
GcImageViewer.isAnimationStarted
language
Get Signature
get language(): string;
language - A property that retrieves the standardized language key based on the provided language option.
The language key is determined by the options.language setting.
Returns
string
Standardized language key (e.g., 'en', 'ja').
Inherited from
layers
Get Signature
get layers(): IImageLayer[];
Image layers. Used for painting.
Returns
Inherited from
naturalSize
Get Signature
get naturalSize(): object;
Gets the active image natural size. The natural size is the image's width/height if drawn with nothing constraining its width/height, this is the number of CSS pixels wide the image will be.
Returns
object
height
height: number;
width
width: number;
Inherited from
onAfterOpen
Get Signature
get onAfterOpen(): EventFan<EventArgs>;
The event raised when the user changes the viewer theme.
Example
var viewer = new DsImageViewer('#root');
viewer.onAfterOpen.register(function() {
alert("The image opened.");
});
viewer.open('Test.png');
Returns
EventFan<EventArgs>
Inherited from
onBeforeOpen
Get Signature
get onBeforeOpen(): EventFan<BeforeOpenEventArgs>;
Occurs immediately before the image opens.
Example
var viewer = new DsImageViewer('#root');
viewer.onBeforeOpen.register(function(args) {
alert("A new image will be opened,\n payload type(binary or URL): " + args.type +",\n payload(bytes or string): " + args.payload);
});
viewer.open('Test.png');
Returns
EventFan<BeforeOpenEventArgs>
Inherited from
onError
Get Signature
get onError(): EventFan<ErrorEventArgs>;
The event indicating error.
Example
function handleError(args) {
console.error(args);
}
var viewer = new DsImageViewer('#root');
viewer.onError.register(handleError);
viewer.open('Test.png');
Returns
EventFan<ErrorEventArgs>
Inherited from
onImagePaint
Get Signature
get onImagePaint(): EventFan<ImagePaintEventArgs>;
The event raised when appearance image element changed.
Returns
EventFan<ImagePaintEventArgs>
Inherited from
openParameters
Get Signature
get openParameters(): OpenParameters;
The Open parameters that were used to open an image.
Returns
Inherited from
options
Get Signature
get options(): Partial<ViewerOptions>;
Viewer options
Returns
Partial<ViewerOptions>
Inherited from
toolbarLayout
Get Signature
get toolbarLayout(): ImageToolbarLayout;
Defines the layout of the toolbar.
Description
The full list of the viewer specific toolbar items:
'open', '$navigation', 'navigation-auto', '$split', 'zoom', '$fullscreen', 'save', 'about'
Example
// Customize the toolbar layout:
viewer.toolbarLayout.viewer.default = ["open", "$zoom", "$fullscreen", "save", "print", "about"];
viewer.applyToolbarLayout();
Returns
Set Signature
set toolbarLayout(toolbarLayout): void;
Defines the layout of the toolbar.
Description
The full list of the viewer specific toolbar items:
'open', '$navigation', '$split', 'zoom', '$fullscreen', 'save', 'about'
Example
// Customize the toolbar layout:
viewer.toolbarLayout.viewer.default = ["open", "$zoom", "$fullscreen", "save", "print", "about"];
viewer.applyToolbarLayout();
Parameters
toolbarLayout
Returns
void
Defines the layout of the toolbar.
Description
The full list of the viewer specific toolbar items:
'open', '$navigation', '$split', 'zoom', '$fullscreen', 'save', 'about'
Example
// Customize the toolbar layout:
viewer.toolbarLayout.viewer.default = ["open", "$zoom", "$fullscreen", "save", "print", "about"];
viewer.applyToolbarLayout();
Inherited from
undoCount
Get Signature
get undoCount(): number;
Gets total undo levels count.
Example
alert("Undo levels count is " + viewer.undoCount);
Returns
number
Inherited from
undoIndex
Get Signature
get undoIndex(): number;
Gets current undo level index.
Example
alert("The current Undo level index is " + viewer.undoIndex);
Returns
number
Inherited from
undoStorage
Get Signature
get undoStorage(): UndoStorage;
Command based undo state storage.
Example
const isUndoInProgress = viewer.undoStorage.undoInProgress;
Returns
Inherited from
version
Get Signature
get version(): string;
Returns the current version of the DS Image viewer.
Example
alert("The DsImageViewer version is " + viewer.version);
Returns
string
Inherited from
Methods
findControl()
static findControl(selector): GcImageViewer;
Gets the viewer instance using the host element or host element selector
Parameters
selector
string | HTMLElement
Returns
Example
var viewer = DsImageViewer.findControl("#root");
Inherited from
addKeyboardListener()
addKeyboardListener(uniqueKey, handler): void;
Add window keyboard listener.
Parameters
uniqueKey
string
handler
Returns
void
Inherited from
GcImageViewer.addKeyboardListener
addPlugin()
addPlugin(plugin): boolean;
Add plug-in instance which is used to add new functionality to the DsImageViewer.
Parameters
plugin
Returns
boolean
Example
var viewer = new DsImageViewer("#root");
var rotationPlugin = new RotationPlugin();
viewer.addPlugin(rotationPlugin);
Inherited from
applyOptions()
applyOptions(): void;
Call this method in order to apply changed options.
Returns
void
Example
viewer.applyOptions();
Inherited from
applyToolbarLayout()
applyToolbarLayout(): void;
Call this method in order to apply changes in @see:toolbarLayout.
Returns
void
Examples
viewer.toolbarLayout.viewer.default = ["open", "save"];
viewer.applyToolbarLayout();
var viewer = new DsImageViewer(document.querySelector("#viewer"));
var toolbar = viewer.toolbar;
var toolbarLayout = viewer.toolbarLayout;
toolbar.addItem({
key: 'custom-action',
icon: { type: "svg", content: '<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24"><path style="fill: #205F78;" d="M20.25 12l-2.25 2.25 2.25 2.25-3.75 3.75-2.25-2.25-2.25 2.25-2.25-2.25-2.25 2.25-3.75-3.75 2.25-2.25-2.25-2.25 2.25-2.25-2.25-2.25 3.75-3.75 2.25 2.25 2.25-2.25 2.25 2.25 2.25-2.25 3.75 3.75-2.25 2.25 2.25 2.25z"></path></svg>' },
title: 'Custom action',
checked: false, enabled: false,
action: function () {
alert("Implement your action here.");
},
onUpdate: function (args) {
return {
enabled: true,
checked: false,
title: 'Custom action title'
}
}
});
toolbarLayout.viewer.default.splice(0, 0, "custom-action");
viewer.applyToolbarLayout();
Inherited from
GcImageViewer.applyToolbarLayout
clearUndo()
clearUndo(): void;
Clear undo storage.
Returns
void
Inherited from
configurePluginMainToolbar()
configurePluginMainToolbar(pos, buttonsToInsert): void;
Used preliminarily by the plugin developers to configure the main toolbar layout.
Parameters
pos
The position where the buttons should be inserted. Use false or -1 to skip insertion. Undefined means the position will be determined automatically.
number | boolean
buttonsToInsert
string[]
An array of button keys to be inserted.
Returns
void
void
Example
// Apply a custom layout to insert "zoomIn" and "zoomOut" buttons at position 2 for the "PaintTools" plugin.
viewer.configurePluginMainToolbar(2, ["zoomIn", "zoomOut"]);
Inherited from
GcImageViewer.configurePluginMainToolbar
confirm()
confirm(
confirmationText?,
level?,
title?,
buttons?): Promise<boolean | ConfirmButton>;
Display confirmation dialog.
Parameters
confirmationText?
string | Element
level?
"error" | "info" | "warning"
title?
string
buttons?
Returns
Promise<boolean | ConfirmButton>
Example
const confirmResult = await viewer.confirm("Apply changes?", "info", "Confirm action", ["Yes", "No", "Cancel"]);
if (confirmResult === "Yes") {
// put your code here
} else if (confirmResult === "No") {
// put your code here
} else {
// put your code here
}
Inherited from
dataUrlToImageData()
dataUrlToImageData(dataUrl, destinationSize?): Promise<ImageData>;
Load image data using given data url.
Parameters
dataUrl
string
destinationSize?
height
number
width
number
Returns
Promise<ImageData>
Inherited from
GcImageViewer.dataUrlToImageData
dispose()
dispose(): void;
Use this method to close and release resources occupied by the DsImageViewer.
Returns
void
Inherited from
download()
download(fileName?, original?): void;
Downloads the Image document loaded in the Viewer to the local disk.
Parameters
fileName?
string
the destination file name.
original?
boolean
Flag indicating whether to use the original image for save. Defaults to false.
Returns
void
Deprecated
Deprecated since v1.2.0-a6 in favor of the save method.
Inherited from
ensurePaintLayer()
ensurePaintLayer(): IImageLayer;
Create at least one image layer which will be used for painting.
Returns
Inherited from
GcImageViewer.ensurePaintLayer
executeCommand()
executeCommand(command): Promise<void>;
Execute a new command.
Parameters
command
Instance of a CommandBase.
Returns
Promise<void>
Inherited from
findPlugin()
findPlugin(pluginId): IViewerPlugin;
Finds a viewer plugin by its id.
Parameters
pluginId
string
Returns
Example
// find imageFilters plugin:
var imageFilters = viewer.findPlugin("imageFilters");
// find pageTools plugin:
var pageTools = viewer.findPlugin("pageTools");
Inherited from
getEvent()
getEvent(eventName): EventFan<any>;
Get event object.
Parameters
eventName
Returns
EventFan<any>
Example
viewer.getEvent("CustomEvent").register(function(args) {
console.log(args);
});
Inherited from
getEventCanvasPoint()
getEventCanvasPoint(event, includeDpi?): PointLocation;
Retrieves the point location from the pointer event provided by the 'event' parameter. The returned point is relative to the active canvas element
Parameters
event
DOM Pointer or Mouse event object.
PointerEvent | MouseEvent
includeDpi?
boolean
Returns
Inherited from
GcImageViewer.getEventCanvasPoint
getImageDataUrl()
getImageDataUrl(): string;
Get current image data url.
Returns
string
Inherited from
getOriginalImageDataUrl()
getOriginalImageDataUrl(): string;
Get unmodified current image data url.
Returns
string
Inherited from
GcImageViewer.getOriginalImageDataUrl
hideActivitySpinner()
hideActivitySpinner(): void;
Hide activity spinner.
Returns
void
Example
viewer.hideActivitySpinner();
Inherited from
GcImageViewer.hideActivitySpinner
hideSecondToolbar()
hideSecondToolbar(toolbarKey?): Promise<void>;
Hides the second toolbar. This method deactivates any active editor mode associated with the second toolbar and then hides the toolbar itself.
Parameters
toolbarKey?
Optional. The key identifying the specific second toolbar to hide. If provided, only hides the specified toolbar if it exists.
Returns
Promise<void>
A Promise that resolves once the second toolbar is successfully hidden.
Examples
// Hide the second toolbar
viewer.hideSecondToolbar();
// Hide a specific second toolbar by passing its key
viewer.hideSecondToolbar("page-tools");
Inherited from
GcImageViewer.hideSecondToolbar
newImage()
newImage(options?): Promise<any>;
Create new empty image.
Parameters
options?
object & OpenParameters
Returns
Promise<any>
Example
await viewer.newImage({ width: 300, height: 300, fileName: "myImage.png" });
Inherited from
open()
open(file?, openParameters?): Promise<any>;
Open Image document.
Parameters
file?
any
URL to Image document(string) or binary data(Typed array - Uint8Array).
openParameters?
Loading parameters object.
ImageFormatCode | OpenParameters | ImageFormatName
Returns
Promise<any>
Example
viewer.open("Images/HelloWorld.png");
Inherited from
openLocalFile()
openLocalFile(): any;
Show the file open dialog where the user can select the Image file.
Returns
any
Example
viewer.openLocalFile();
Inherited from
redo()
redo(): Promise<void>;
Redo changes.
Returns
Promise<void>
Example
if(viewer.hasRedo) {
viewer.redo();
}
Inherited from
removeKeyboardListener()
removeKeyboardListener(uniqueKey): void;
Remove window keyboard listener.
Parameters
uniqueKey
string
Returns
void
Inherited from
GcImageViewer.removeKeyboardListener
removeLayer()
removeLayer(layerOrIndex): void;
Remove and dispose image layer given by argument layerOrIndex.
Parameters
layerOrIndex
Image layer or image layer index or image layer name.
string | number | IImageLayer
Returns
void
Inherited from
removeLayers()
removeLayers(): void;
Remove and dispose all image layers.
Returns
void
Inherited from
removePlugin()
removePlugin(pluginId): void;
Remove plug-in instance from the DsImageViewer.
Parameters
pluginId
Plugin id or plugin instance.
string | IViewerPlugin
Returns
void
Example
var viewer = new DsImageViewer("#root");
var rotationPlugin = new RotationPlugin();
viewer.addPlugin(rotationPlugin);
viewer.removePlugin(rotationPlugin.id);
Inherited from
removePlugins()
removePlugins(): void;
Remove all plug-ins.
Returns
void
Example
viewer.removePlugins();
Inherited from
resetCursor()
resetCursor(): IImageViewer;
Resets the cursor to default style
Returns
Examples
// Reset cursor when operation completes
viewer.resetCursor();
// Reset cursor on mouse leave
viewerElement.addEventListener('mouseleave', () => {
viewer.resetCursor();
});
Inherited from
save()
save(options?, original?): void;
Saves the Image document loaded in the Viewer to the local disk.
Parameters
options?
The save options, including the destination file name and other settings.
string | SaveOptions
original?
boolean
Flag indicating whether to use the initial version of the image for save. Defaults to false.
Returns
void
Examples
// Example: Save the modified image without using specific options.
const viewer = DsImageViewer.findControl("#root");
viewer.save();
// Example: Save the modified image as "image.png".
const viewer = DsImageViewer.findControl("#root");
viewer.save({ fileName: "image.png" });
// Example: Download the original version of the image as "original_image.jpg".
const viewer = DsImageViewer.findControl("#root");
viewer.save({ fileName: "original_image.jpg", original: true });
// Example: Save the modified image in PNG format.
const viewer = DsImageViewer.findControl("#root");
viewer.save({ convertToFormat: "image/png" });
// Example: Save the modified image with a custom file name and in JPEG format.
const viewer = DsImageViewer.findControl("#root");
viewer.save({ fileName: "custom_name", convertToFormat: "image/jpeg" });
Inherited from
setCursor()
setCursor(cursorType): IImageViewer;
Sets the cursor style for the image viewer
Parameters
cursorType
The cursor style to apply
Returns
Examples
// Set rotate cursor during image rotation
viewer.setCursor('rotate');
// Set resize cursor when hovering over edges
viewer.setCursor('nwse-resize');
See
GlobalCursorType for all available cursor options
Inherited from
setImageDataUrl()
setImageDataUrl(dataUrl): Promise<void>;
Modify current image data url.
Parameters
dataUrl
any
Returns
Promise<void>
Inherited from
showAbout()
showAbout(): void;
Show about dialog.
Returns
void
Inherited from
showActivitySpinner()
showActivitySpinner(container?): void;
Show activity spinner.
Parameters
container?
HTMLElement
Returns
void
Example
viewer.showActivitySpinner();
Inherited from
GcImageViewer.showActivitySpinner
showMessage()
showMessage(
message,
details?,
severity?): void;
Shows the message for the user.
Parameters
message
string
details?
string
severity?
"error" | "warn" | "info" | "debug"
Returns
void
Inherited from
showSecondToolbar()
showSecondToolbar(toolbarKey): Promise<void>;
Displays a second toolbar specified by the toolbarKey argument.
Parameters
toolbarKey
The key identifying the specific second toolbar to show.
Returns
Promise<void>
Example
// Show the page tools toolbar
viewer.showSecondToolbar("page-tools");
Inherited from
GcImageViewer.showSecondToolbar
startAnimation()
startAnimation(): void;
Start GIF animation.
Returns
void
Example
DsImageViewer.findControl("#root").startAnimation();
Inherited from
stopAnimation()
stopAnimation(): void;
Stop GIF animation. *
Returns
void
Example
-
- DsImageViewer.findControl("#root").stopAnimation();
-
Inherited from
toggleAnimation()
toggleAnimation(): void;
Toggle GIF animation.
Returns
void
Example
DsImageViewer.findControl("#root").toggleAnimation();
Inherited from
toggleCursor()
toggleCursor(cursorType): IImageViewer;
Toggles between specified cursor and default style
Parameters
cursorType
Cursor style to apply, or false to reset
false | GlobalCursorType
Returns
Examples
// Toggle grab cursor during drag operations
viewer.toggleCursor(isDragging ? 'grab' : false);
// Toggle zoom cursor based on modifier key
document.addEventListener('keydown', (e) => {
if (e.ctrlKey) {
viewer.toggleCursor('zoom-in');
}
});
Inherited from
triggerEvent()
triggerEvent(eventName, args?): void;
Trigger event.
Parameters
eventName
args?
any
Returns
void
Example
// Listen CustomEvent:
viewer.getEvent("CustomEvent").register(function(args) {
console.log(args);
});
// Trigger CustomEvent:
viewer.triggerEvent("CustomEvent", { arg1: 1, arg2: 2});
Inherited from
undo()
undo(): Promise<void>;
Undo changes.
Returns
Promise<void>
Example
if(viewer.hasUndo) {
viewer.undo();
}