Interface ImageViewerAPI

Defines Image Viewer API.

interface ImageViewerAPI {
    hasImage: boolean;
    adaptiveNaturalSize: Size;
    actualSize: Size;
    language: string;
    layers: ImageLayer[];
    naturalSize: Size;
    openParameters: OpenParameters | undefined;
    undoStorage: UndoStorage;
    hasUndo: boolean;
    hasRedo: boolean;
    undoIndex: number;
    undoCount: number;
    version: string;
    framesCount: number;
    eventBus: EventBus;
    onAfterOpen: EventFan;
    onBeforeOpen: EventFan;
    onError: EventFan;
    onImagePaint: EventFan;
    isAnimationStarted: boolean;
    options: Partial<ViewerOptions>;
    toolbarLayout: ImageToolbarLayout;
    frameIndex: number;
    zoom: ZoomSettings;
    ensurePaintLayer(): ImageLayer;
    removeLayer(layerOrIndex: string | number | ImageLayer): void;
    removeLayers(): void;
    applyOptions(): void;
    applyToolbarLayout(): void;
    addPlugin(plugin: ImageViewerPluginReference): boolean;
    addKeyboardListener(
        uniqueKey: string,
        handler: WindowKeyboardListener,
    ): void;
    removeKeyboardListener(uniqueKey: string): void;
    configurePluginMainToolbar(
        pos: number | boolean | undefined,
        buttonsToInsert: string[],
    ): void;
    getEventCanvasPoint(
        event: MouseEvent | PointerEvent,
        includeDpi: boolean,
    ): PointLocation;
    setCursor(cursorType: GlobalCursorType): void;
    resetCursor(): void;
    toggleCursor(cursorType: false | GlobalCursorType): void;
    dataUrlToImageData(
        dataUrl: string,
        destinationSize?: Size,
    ): Promise<ImageData>;
    confirm(
        confirmationText?: any,
        level?: "error" | "info" | "warning",
        title?: string,
        buttons?: ConfirmButton[],
    ): Promise<boolean | ConfirmButton>;
    removePlugin(pluginId: PluginType | ImageViewerPluginReference): void;
    showAbout(): void;
    findPlugin(pluginId: PluginType): ImageViewerPluginReference | null;
    removePlugins(): void;
    clearUndo(): void;
    executeCommand(command: UndoCommandSupport): Promise<void>;
    newImage(options?: Partial<Size> & OpenParameters): Promise<any>;
    open(
        file: string | URL | Uint8Array<ArrayBufferLike>,
        openParameters?: ImageFormatName | ImageFormatCode | OpenParameters,
    ): Promise<any>;
    close(): Promise<void>;
    dispose(): void;
    showActivitySpinner(container?: HTMLElement): void;
    hideActivitySpinner(): void;
    startAnimation(): void;
    stopAnimation(): void;
    toggleAnimation(): void;
    undo(): Promise<void>;
    redo(): Promise<void>;
    getEvent(eventName: string): EventFan;
    triggerEvent(eventName: string, args?: Record<string, unknown>): void;
    getOriginalImageDataUrl(): string;
    getImageDataUrl(): string;
    setImageDataUrl(dataUrl: any): Promise<void>;
    showSecondToolbar(toolbarKey: SecondToolbarType): Promise<void>;
    hideSecondToolbar(toolbarKey?: SecondToolbarType): Promise<void>;
    openLocalFile(): void;
    save(options?: string | SaveOptions, original?: boolean): void;
    showMessage(
        message: string,
        details: string,
        severity: "error" | "info" | "warn" | "debug",
    ): void;
}

Implemented by

Methods

ensurePaintLayer

ensurePaintLayer(): ImageLayer
Create at least one image layer which will be used for painting.

Returns ImageLayer

removeLayer

removeLayer(layerOrIndex: string | number | ImageLayer): void
Remove and dispose image layer given by argument layerOrIndex.
Parameters
- layerOrIndex: string | number | ImageLayer
  Image layer or image layer index or image layer name.
Returns void

removeLayers

removeLayers(): void
Remove and dispose all image layers.

Returns void

applyOptions

applyOptions(): void
Call this method in order to apply changed options.

Returns void
Example
```
viewer.applyOptions();
```

applyToolbarLayout

applyToolbarLayout(): void

Call this method in order to apply changes in @see:toolbarLayout.

Returns void

Example

viewer.toolbarLayout.viewer.default = ["open", "save"];
viewer.applyToolbarLayout();

Example

   const viewer = new DsImageViewer(document.querySelector("#viewer"));
   const toolbar = viewer.toolbar;
   const 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();

addPlugin

addPlugin(plugin: ImageViewerPluginReference): boolean
Adds a plugin instance to the DsImageViewer. This method is now intended for internal and officially supported plugins only. Custom or third-party plugins are no longer supported starting from version 9.0. The plugin system remains available for internal use to provide optional viewer features, such as ImageFiltersPlugin, PageToolsPlugin, and PaintToolsPlugin. Attempting to register non-official plugins may lead to undefined behavior and is not supported by the product team.
Parameters
- plugin: ImageViewerPluginReference
  The plugin instance
Returns boolean
true if added successfully; otherwise false.
Example
```
// ✅ Supported (built-in plugin)
const viewer = new DsImageViewer("#root");
viewer.addPlugin(new ImageFiltersPlugin());

// ❌ Not supported (custom plugin)
viewer.addPlugin(new CustomPlugin()); // Custom plugins are no longer supported
```

addKeyboardListener

addKeyboardListener(uniqueKey: string, handler: WindowKeyboardListener): void
Add window keyboard listener.
Parameters
- uniqueKey: string
  Listener key.
- handler: WindowKeyboardListener
  Keyboard event handler.
Returns void

removeKeyboardListener

removeKeyboardListener(uniqueKey: string): void
Remove window keyboard listener.
Parameters
- uniqueKey: string
  Listener key.
Returns void

configurePluginMainToolbar

configurePluginMainToolbar(
pos: number | boolean | undefined,
buttonsToInsert: string[],
): void
Allows to configure the main toolbar layout.
Parameters
- pos: number | boolean | undefined
  The position where the buttons should be inserted. Use false or -1 to skip insertion. Undefined means the position will be determined automatically.
- buttonsToInsert: string[]
  An array of button keys to be inserted.
Returns void
Example
```
// Apply a custom layout to insert "zoomIn" and "zoomOut" buttons at position 2 for the "PaintTools" plugin.
viewer.configurePluginMainToolbar(2, ["zoomIn", "zoomOut"]);
```

getEventCanvasPoint

getEventCanvasPoint(
event: MouseEvent | PointerEvent,
includeDpi: boolean,
): 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: MouseEvent | PointerEvent
  DOM Pointer or Mouse event object.
- includeDpi: boolean
Returns PointLocation

setCursor

setCursor(cursorType: GlobalCursorType): void
Sets the cursor style for the image viewer
Parameters
- cursorType: GlobalCursorType
  The cursor style to apply
Returns void
Example
```
// Set rotate cursor during image rotation
viewer.setCursor('rotate');
```
Example
```
// Set resize cursor when hovering over edges
viewer.setCursor('nwse-resize');
```
See
GlobalCursorType for all available cursor options

resetCursor

resetCursor(): void

Resets the cursor to default style

Returns void

Example

// Reset cursor when operation completes
viewer.resetCursor();

Example

// Reset cursor on mouse leave
viewerElement.addEventListener('mouseleave', () => {
  viewer.resetCursor();
});

toggleCursor

toggleCursor(cursorType: false | GlobalCursorType): void

Toggles between specified cursor and default style

Parameters

cursorType: false | GlobalCursorType
Cursor style to apply, or false to reset

Returns void

Example

// Toggle grab cursor during drag operations
viewer.toggleCursor(isDragging ? 'grab' : false);

Example

// Toggle zoom cursor based on modifier key
document.addEventListener('keydown', (e) => {
  if (e.ctrlKey) {
    viewer.toggleCursor('zoom-in');
  }
});

dataUrlToImageData

dataUrlToImageData(dataUrl: string, destinationSize?: Size): Promise<ImageData>
Load image data using given data url.
Parameters
- dataUrl: string
- OptionaldestinationSize: Size
  Defines needed image size
Returns Promise<ImageData>

confirm

confirm(
    confirmationText?: any,
    level?: "error" | "info" | "warning",
    title?: string,
    buttons?: ConfirmButton[],
): Promise<boolean | ConfirmButton>
Display confirmation dialog.
Parameters
- OptionalconfirmationText: any
  Confirmation text can be plain string or JSX.Element if you're using React.
- Optionallevel: "error" | "info" | "warning"
- Optionaltitle: string
- Optionalbuttons: ConfirmButton[]
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
}
```

removePlugin

removePlugin(pluginId: PluginType | ImageViewerPluginReference): void
Removes a plugin instance from the DsImageViewer. This method remains available for internal and officially supported plugins only. Custom or third-party plugins are no longer supported starting from version 9.0.
Parameters
- pluginId: PluginType | ImageViewerPluginReference
  Plugin id or plugin instance.
Returns void
Example
```
// ✅ Supported
viewer.removePlugin("ImageFiltersPlugin");

// ❌ Not supported
viewer.removePlugin("CustomPluginId");
```

showAbout

showAbout(): void
Show about dialog.

Returns void

findPlugin

findPlugin(pluginId: PluginType): ImageViewerPluginReference | null
Finds a viewer plugin by its id.
Parameters
- pluginId: PluginType
  Plugin id
Returns ImageViewerPluginReference | null
Example
```
// find imageFilters plugin:
const imageFilters = viewer.findPlugin("imageFilters");
// find pageTools plugin:
const pageTools = viewer.findPlugin("pageTools");
```

removePlugins

removePlugins(): void
Remove all plug-ins.

Returns void
Example
```
viewer.removePlugins();
```

clearUndo

clearUndo(): void
Clear undo storage.

Returns void

executeCommand

executeCommand(command: UndoCommandSupport): Promise<void>
Execute a new command.
Parameters
- command: UndoCommandSupport
  Instance of a command.
Returns Promise<void>

newImage

newImage(options?: Partial<Size> & OpenParameters): Promise<any>
Create new empty image.
Parameters
- Optionaloptions: Partial<Size> & OpenParameters
  Optional. New image parameters.
Returns Promise<any>
Example
```
await viewer.newImage({ width: 300, height: 300, fileName: "myImage.png" });
```

open

open(
file: string | URL | Uint8Array<ArrayBufferLike>,
openParameters?: ImageFormatName | ImageFormatCode | OpenParameters,
): Promise<any>
Open Image document.
Parameters
- file: string | URL | Uint8Array<ArrayBufferLike>
  Image URL or it's binary data.
- OptionalopenParameters: ImageFormatName | ImageFormatCode | OpenParameters
  Image format or image opening parameters object.
Returns Promise<any>
Example
```
viewer.open("Images/HelloWorld.png");
```

close

close(): Promise<void>
Closes the currently open image.

Returns Promise<void>
Example
```
await viewer.close();
```

dispose

dispose(): void
Use this method to close and release resources occupied by the DsImageViewer.

Returns void

showActivitySpinner

showActivitySpinner(container?: HTMLElement): void
Show activity spinner.
Parameters
- Optionalcontainer: HTMLElement
Returns void
Example
```
viewer.showActivitySpinner();
```

hideActivitySpinner

hideActivitySpinner(): void
Hide activity spinner.

Returns void
Example
```
viewer.hideActivitySpinner();
```

startAnimation

startAnimation(): void
Start GIF animation.

Returns void
Example
```
DsImageViewer.findControl("#root").startAnimation();
```

stopAnimation

stopAnimation(): void
Stop GIF animation. *

Returns void
Example
- DsImageViewer.findControl("#root").stopAnimation();

toggleAnimation

toggleAnimation(): void
Toggle GIF animation.

Returns void
Example
```
DsImageViewer.findControl("#root").toggleAnimation();
```

undo

undo(): Promise<void>
Undo changes.

Returns Promise<void>
Example
```
if(viewer.hasUndo) {
  viewer.undo();
}
```

redo

redo(): Promise<void>
Redo changes.

Returns Promise<void>
Example
```
if(viewer.hasRedo) {
  viewer.redo();
}
```

getEvent

getEvent(eventName: string): EventFan
Get event object.
Parameters
- eventName: string
  Embedded or custom event name.
Returns EventFan
Example
```
viewer.getEvent("CustomEvent").register(function(args) {
  console.log(args);
});
```

triggerEvent

triggerEvent(eventName: string, args?: Record<string, unknown>): void
Trigger event.
Parameters
- eventName: string
  Embedded or custom event name.
- Optionalargs: Record<string, unknown>
  Arguments for event handler function.
Returns void
Example
```
// Listen CustomEvent:
viewer.getEvent("CustomEvent").register(function(args) {
  console.log(args);
});
// Trigger CustomEvent:
viewer.triggerEvent("CustomEvent", { arg1: 1, arg2: 2});
```

getOriginalImageDataUrl

getOriginalImageDataUrl(): string
Get unmodified current image data url.

Returns string

getImageDataUrl

getImageDataUrl(): string
Get current image data url.

Returns string

setImageDataUrl

setImageDataUrl(dataUrl: any): Promise<void>
Modify current image data url.
Parameters
- dataUrl: any
Returns Promise<void>

showSecondToolbar

showSecondToolbar(toolbarKey: SecondToolbarType): Promise<void>
Displays a second toolbar specified by the toolbarKey argument.
Parameters
- toolbarKey: SecondToolbarType
  The key identifying the specific second toolbar to show.
Returns Promise<void>
A Promise that resolves once the second toolbar is successfully displayed.
Example
```
// Show the page tools toolbar
viewer.showSecondToolbar("page-tools");
```

hideSecondToolbar

hideSecondToolbar(toolbarKey?: SecondToolbarType): 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
- OptionaltoolbarKey: SecondToolbarType
  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.
Example
```
// Hide the second toolbar
viewer.hideSecondToolbar();
```
Example
```
// Hide a specific second toolbar by passing its key
viewer.hideSecondToolbar("page-tools");
```

openLocalFile

openLocalFile(): void
Show the file open dialog where the user can select the Image file.

Returns void
Example
```
viewer.openLocalFile();
```

save

save(options?: string | SaveOptions, original?: boolean): void

Saves the Image document loaded in the Viewer to the local disk.

Parameters

Optionaloptions: string | SaveOptions
Optional Destination file name or the save options, including the destination file name and other settings.
Optionaloriginal: boolean
Optional Flag indicating whether to use the initial version of the image for save. Defaults to false.

Returns void

Example

// Example: Save the modified image without using specific options.
const viewer = DsImageViewer.findControl("#root");
viewer.save();

Example

// Example: Save the modified image as "image.png".
const viewer = DsImageViewer.findControl("#root");
viewer.save({ fileName: "image.png" });

Example

// 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

// Example: Save the modified image in PNG format.
const viewer = DsImageViewer.findControl("#root");
viewer.save({ convertToFormat: "image/png" });

Example

// 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" });

showMessage

showMessage(
    message: string,
    details: string,
    severity: "error" | "info" | "warn" | "debug",
): void
Shows the message for the user.
Parameters
- message: string
  Message title text
- details: string
  Additional details text, empty by default.
- severity: "error" | "info" | "warn" | "debug"
  Message severity, default "info".
Returns void

Properties

`Readonly`hasImage

hasImage: boolean

Indicates whether the viewer has opened the image.

Example

 const hasImageFlag = viewer.hasImage;

`Readonly`adaptiveNaturalSize

adaptiveNaturalSize: Size

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.

`Readonly`actualSize

actualSize: Size

Gets the actual display size of the active image, including the active zoom value.

`Readonly`language

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

Standardized language key (e.g., 'en', 'ja').

`Readonly`layers

layers: ImageLayer[]

Image layers. Used for painting.

`Readonly`naturalSize

naturalSize: Size

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.

`Readonly`openParameters

openParameters: OpenParameters | undefined

The Open parameters that were used to open an image.

`Readonly`undoStorage

undoStorage: UndoStorage

Command based undo state storage.

Example

const isUndoInProgress = viewer.undoStorage.undoInProgress;

`Readonly`hasUndo

hasUndo: boolean

Gets a value indicating whether the image viewer can undo changes.

Example

if(viewer.hasUndo) {
  viewer.undo();
}

`Readonly`hasRedo

hasRedo: boolean

Gets a value indicating whether the image viewer can redo changes.

Example

if(viewer.hasRedo) {
  viewer.redo();
}

`Readonly`undoIndex

undoIndex: number

Gets current undo level index.

Example

alert("The current Undo level index is " + viewer.undoIndex);

`Readonly`undoCount

undoCount: number

Gets total undo levels count.

Example

alert("Undo levels count is " + viewer.undoCount);

`Readonly`version

version: string

Returns the current version of the DS Image viewer.

Example

alert("The DsImageViewer version is " + viewer.version);

`Readonly`framesCount

framesCount: number

Gets total frames count for the active image. Applicable for TIFF, ICO images.

Example

const viewer = new DsImageViewer('#root');
viewer.onAfterOpen.register(function() {
  alert("The image opened. Total number of frames: " + viewer.framesCount);
});
viewer.open('Test.png');

`Readonly`eventBus

eventBus: EventBus

Image viewer event bus.

Example

viewer.eventBus.on("after-open", function(args) {
  console.log("Image opened.", args);
});
viewer.open('Test.png');

`Readonly`onAfterOpen

onAfterOpen: EventFan

The event raised when the user changes the viewer theme.

Example

const viewer = new DsImageViewer('#root');
viewer.onAfterOpen.register(function() {
  alert("The image opened.");
});
viewer.open('Test.png');

`Readonly`onBeforeOpen

onBeforeOpen: EventFan

Occurs immediately before the image opens.

Example

const 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');

`Readonly`onError

onError: EventFan

The event indicating error.

Example

function handleError(args) {
    console.error(args);
}
const viewer = new DsImageViewer('#root');
viewer.onError.register(handleError);
viewer.open('Test.png');

`Readonly`onImagePaint

onImagePaint: EventFan

The event raised when appearance image element changed.

`Readonly`isAnimationStarted

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();
}

options

options: Partial<ViewerOptions>

Viewer options

toolbarLayout

toolbarLayout: ImageToolbarLayout

Defines the layout of the toolbar. 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();

frameIndex

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

const viewer = new DsImageViewer('#root');
viewer.frameIndex = 9;
viewer.open('Test.ico');

zoom

zoom: ZoomSettings

Gets or sets the current zoom settings

Interface ImageViewerAPI

Implemented by

Methods

ensurePaintLayer

Returns ImageLayer

removeLayer

Parameters

Returns void

removeLayers

Returns void

applyOptions

Returns void

Example

applyToolbarLayout

Returns void

Example

Example

addPlugin

Parameters

Returns boolean

Example

addKeyboardListener

Parameters

Returns void

removeKeyboardListener

Parameters

Returns void

configurePluginMainToolbar

Parameters

Returns void

Example

getEventCanvasPoint

Parameters

Returns PointLocation

setCursor

Parameters

Returns void

Example

Example

See

resetCursor

Returns void

Example

Example

toggleCursor

Parameters

Returns void

Example

Example

dataUrlToImageData

Parameters

Returns Promise<ImageData>

confirm

Parameters

Returns Promise<boolean | ConfirmButton>

Example

removePlugin

Parameters

Returns void

Example

showAbout

Returns void

findPlugin

Parameters

Returns ImageViewerPluginReference | null

Example

removePlugins

Returns void

Example

clearUndo

Returns void

executeCommand

Parameters

Returns Promise<void>

newImage

Parameters

Returns Promise<any>

Example

open

Parameters

`Readonly`hasImage