[]
DEMOS DOCS API PRICING
FREE TRIAL
(Showing Draft Content)

GcImageViewer

Document Solutions Image Viewer - v7.2.0 / GcImageViewer

Class: GcImageViewer

Document Solutions Image Viewer is a fast JavaScript based client-side Image Viewer that runs in all major browsers.

Note that DsImageViewer is the new name for GcImageViewer, with the same API.

During this transition period we are publishing both versions, but it is recommended that you switch to using DsImageViewer when possible.

Example

var viewer = new DsImageViewer("#root");

Hierarchy

Implements

Table of contents

Methods

Accessors

Properties

Constructors

Methods

findControl

▸ Static findControl(selector): undefined | GcImageViewer

Gets the viewer instance using the host element or host element selector

Example

var viewer = DsImageViewer.findControl("#root");

Parameters

Name Type
selector string | HTMLElement

Returns

undefined | GcImageViewer

executeTask

▸ executeTask(task, settings?): Promise<void>

Starts long-running operation and displays progress window while operation is running.

Parameters

Name Type
task (callbacks: TaskCallbacks) => Promise<void>
settings? TaskSettings

Returns

Promise<void>

Inherited from

ReportViewer.executeTask

showPanel

▸ showPanel(panelKey, visible?): void

Updates the panel visibility.

Parameters

Name Type
panelKey PanelHandle
visible? boolean

Returns

void

Implementation of

IImageViewer.showPanel

Inherited from

ReportViewer.showPanel

updatePanel

▸ updatePanel(panelKey, settings): void

Updates panel settings such as visibility, label or "enabled" status.

Parameters

Name Type
panelKey PanelHandle
settings Partial<PanelSettings>

Returns

void

Implementation of

IImageViewer.updatePanel

Inherited from

ReportViewer.updatePanel

getPanelState

▸ getPanelState(panelKey): null | PanelSettings

Gets the current panel state.

Parameters

Name Type
panelKey PanelHandle

Returns

null | PanelSettings

Implementation of

IImageViewer.getPanelState

Inherited from

ReportViewer.getPanelState

layoutPanels

▸ layoutPanels(layout): void

Orders and filters panel items. '*' indicates "the rest of panels". 'sep'/'separator' indicated menu separator.

Parameters

Name Type
layout string[]

Returns

void

Implementation of

IImageViewer.layoutPanels

Inherited from

ReportViewer.layoutPanels

bringPanelToFront

▸ bringPanelToFront(panelKey): void

Deprecated

use expandPanel() instead

Parameters

Name Type
panelKey PanelHandle

Returns

void

Inherited from

ReportViewer.bringPanelToFront

setActiveTopPanel

▸ setActiveTopPanel(id): void

Updates activeTopPanelId for to show/hide panel with setting.location = 'top' (id = null to hide panel)

Parameters

Name Type
id null | string

Returns

void

Inherited from

ReportViewer.setActiveTopPanel

setActiveBottomPanel

▸ setActiveBottomPanel(id): void

Updates activeBottomPanelId for to show/hide panel with setting.location = 'bottom' (id = null to hide panel)

Parameters

Name Type
id null | string

Returns

void

Inherited from

ReportViewer.setActiveBottomPanel

resetDocument

▸ resetDocument(): Promise<void>

Resets report and cancel current session if any.

Returns

Promise<void>

Inherited from

ReportViewer.resetDocument

load

▸ load(moniker, token?): Promise<LoadResult>

Loads the report (no UI), so caller has to process load result and report error if any.

Parameters

Name Type
moniker DocumentMoniker
token? CancellationToken

Returns

Promise<LoadResult>

Inherited from

ReportViewer.load

toggleFullscreen

▸ toggleFullscreen(fullscreen?): void

Toggle full screen mode.

Parameters

Name Type
fullscreen? boolean

Returns

void

Implementation of

IImageViewer.toggleFullscreen

Inherited from

ReportViewer.toggleFullscreen

toggleToolbar

▸ toggleToolbar(show?): void

Toggle toolbar visibility.

Parameters

Name Type
show? boolean

Returns

void

Implementation of

IImageViewer.toggleToolbar

Inherited from

ReportViewer.toggleToolbar

ensurePaintLayer

▸ ensurePaintLayer(): IImageLayer

Create at least one image layer which will be used for painting.

Returns

IImageLayer

Implementation of

IImageViewer.ensurePaintLayer

removeLayer

▸ removeLayer(layerOrIndex): void

Remove and dispose image layer given by argument layerOrIndex.

Parameters

Name Type Description
layerOrIndex string | number | IImageLayer Image layer or image layer index or image layer name.

Returns

void

Implementation of

IImageViewer.removeLayer

removeLayers

▸ removeLayers(): void

Remove and dispose all image layers.

Returns

void

Implementation of

IImageViewer.removeLayers

applyOptions

▸ applyOptions(): void

Call this method in order to apply changed options.

Example

viewer.applyOptions();

Returns

void

applyToolbarLayout

▸ applyToolbarLayout(): void

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

Example

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

Example

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

Returns

void

Implementation of

IImageViewer.applyToolbarLayout

addPlugin

▸ addPlugin(plugin): boolean

Add plug-in instance which is used to add new functionality to the DsImageViewer.

Example

var viewer = new DsImageViewer("#root");
var rotationPlugin = new RotationPlugin();
viewer.addPlugin(rotationPlugin);

Parameters

Name Type
plugin IViewerPlugin

Returns

boolean

addKeyboardListener

▸ addKeyboardListener(uniqueKey, handler): void

Add window keyboard listener.

Parameters

Name Type
uniqueKey string
handler WindowKeyboardListener

Returns

void

Implementation of

IImageViewer.addKeyboardListener

removeKeyboardListener

▸ removeKeyboardListener(uniqueKey): void

Remove window keyboard listener.

Parameters

Name Type
uniqueKey string

Returns

void

Implementation of

IImageViewer.removeKeyboardListener

configurePluginMainToolbar

▸ configurePluginMainToolbar(pos, buttonsToInsert): void

Used preliminarily by the plugin developers to configure the main toolbar layout.

Example

// Apply a custom layout to insert "zoomIn" and "zoomOut" buttons at position 2 for the "PaintTools" plugin.
viewer.configurePluginMainToolbar(2, ["zoomIn", "zoomOut"]);

Parameters

Name Type Description
pos undefined | number | boolean 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

void

Implementation of

IImageViewer.configurePluginMainToolbar

getEventCanvasPoint

▸ getEventCanvasPoint(event): 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

Name Type Description
event PointerEvent | MouseEvent DOM Pointer or Mouse event object.

Returns

PointLocation

Implementation of

IImageViewer.getEventCanvasPoint

dataUrlToImageData

▸ dataUrlToImageData(dataUrl, destinationSize?): Promise<ImageData>

Load image data using given data url.

Parameters

Name Type
dataUrl string
destinationSize? Object
destinationSize.width number
destinationSize.height number

Returns

Promise<ImageData>

Implementation of

IImageViewer.dataUrlToImageData

confirm

▸ confirm(confirmationText?, level?, title?, buttons?): Promise<boolean | ConfirmButton>

Display confirmation dialog.

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
}

Parameters

Name Type
confirmationText? string | Element
level? "error" | "info" | "warning"
title? string
buttons? ConfirmButton[]

Returns

Promise<boolean | ConfirmButton>

Implementation of

IImageViewer.confirm

removePlugin

▸ removePlugin(pluginId): void

Remove plug-in instance from the DsImageViewer.

Example

var viewer = new DsImageViewer("#root");
var rotationPlugin = new RotationPlugin();
viewer.addPlugin(rotationPlugin);

viewer.removePlugin(rotationPlugin.id);

Parameters

Name Type Description
pluginId string | IViewerPlugin Plugin id or plugin instance.

Returns

void

showAbout

▸ showAbout(): void

Show about dialog.

Returns

void

findPlugin

▸ findPlugin(pluginId): null | IViewerPlugin

Finds a viewer plugin by its id.

Example

// find imageFilters plugin:
var imageFilters = viewer.findPlugin("imageFilters");
// find pageTools plugin:
var pageTools = viewer.findPlugin("pageTools");

Parameters

Name Type
pluginId string

Returns

null | IViewerPlugin

Implementation of

IImageViewer.findPlugin

removePlugins

▸ removePlugins(): void

Remove all plug-ins.

Example

viewer.removePlugins();

Returns

void

clearUndo

▸ clearUndo(): void

Clear undo storage.

Returns

void

executeCommand

▸ executeCommand(command): Promise<void>

Execute a new command.

Parameters

Name Type Description
command UndoCommandSupport Instance of a CommandBase.

Returns

Promise<void>

newImage

▸ newImage(options?): Promise<any>

Create new empty image.

Example

await viewer.newImage({ width: 300, height: 300, fileName: "myImage.png" });

Parameters

Name Type
options? { width?: number ; height?: number } & OpenParameters

Returns

Promise<any>

open

▸ open(file?, openParameters?): Promise<any>

Open Image document.

Example

viewer.open("Images/HelloWorld.png");

Parameters

Name Type Description
file? any URL to Image document(string) or binary data(Typed array - Uint8Array).
openParameters? ImageFormatCode | ImageFormatName | OpenParameters Loading parameters object.

Returns

Promise<any>

Overrides

ReportViewer.open

dispose

▸ dispose(): void

Use this method to close and release resources occupied by the DsImageViewer.

Returns

void

Overrides

ReportViewer.dispose

showActivitySpinner

▸ showActivitySpinner(container?): void

Show activity spinner.

Example

viewer.showActivitySpinner();

Parameters

Name Type
container? HTMLElement

Returns

void

Implementation of

IImageViewer.showActivitySpinner

hideActivitySpinner

▸ hideActivitySpinner(): void

Hide activity spinner.

Example

viewer.hideActivitySpinner();

Returns

void

Implementation of

IImageViewer.hideActivitySpinner

startAnimation

▸ startAnimation(): void

Start GIF animation.

Example

DsImageViewer.findControl("#root").startAnimation();

Returns

void

stopAnimation

▸ stopAnimation(): void

Stop GIF animation. *

Example

  • DsImageViewer.findControl("#root").stopAnimation();

Returns

void

toggleAnimation

▸ toggleAnimation(): void

Toggle GIF animation.

Example

DsImageViewer.findControl("#root").toggleAnimation();

Returns

void

undo

▸ undo(): Promise<void>

Undo changes.

Example

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

Returns

Promise<void>

redo

▸ redo(): Promise<void>

Redo changes.

Example

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

Returns

Promise<void>

getEvent

▸ getEvent(eventName): EventFan<any>

Get event object.

Example

viewer.getEvent("CustomEvent").register(function(args) {
  console.log(args);
});

Parameters

Name Type
eventName EventName

Returns

EventFan<any>

triggerEvent

▸ triggerEvent(eventName, args?): void

Trigger event.

Example

// Listen CustomEvent:
viewer.getEvent("CustomEvent").register(function(args) {
  console.log(args);
});
// Trigger CustomEvent:
viewer.triggerEvent("CustomEvent", { arg1: 1, arg2: 2});

Parameters

Name Type
eventName EventName
args? any

Returns

void

getOriginalImageDataUrl

▸ getOriginalImageDataUrl(): string

Get unmodified current image data url.

Returns

string

Implementation of

IImageViewer.getOriginalImageDataUrl

getImageDataUrl

▸ getImageDataUrl(): string

Get current image data url.

Returns

string

Implementation of

IImageViewer.getImageDataUrl

setImageDataUrl

▸ setImageDataUrl(dataUrl): Promise<void>

Modify current image data url.

Parameters

Name Type
dataUrl any

Returns

Promise<void>

Implementation of

IImageViewer.setImageDataUrl

showSecondToolbar

▸ showSecondToolbar(toolbarKey): Promise<void>

Displays a second toolbar specified by the toolbarKey argument.

Example

// Show the page tools toolbar
viewer.showSecondToolbar("page-tools");

Parameters

Name Type Description
toolbarKey SecondToolbarType The key identifying the specific second toolbar to show.

Returns

Promise<void>

Implementation of

IImageViewer.showSecondToolbar

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.

Example

// Hide the second toolbar
viewer.hideSecondToolbar();

Example

// Hide a specific second toolbar by passing its key
viewer.hideSecondToolbar("page-tools");

Parameters

Name Type Description
toolbarKey? 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.

Implementation of

IImageViewer.hideSecondToolbar

openLocalFile

▸ openLocalFile(): any

Show the file open dialog where the user can select the Image file.

Example

viewer.openLocalFile();

Returns

any

download

▸ download(fileName?, original?): void

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

Deprecated

Deprecated since v1.2.0-a6 in favor of the save method.

Parameters

Name Type Description
fileName? string the destination file name.
original? boolean Flag indicating whether to use the original image for save. Defaults to false.

Returns

void

save

▸ save(options?, original?): void

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

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

Parameters

Name Type Description
options? string | SaveOptions The save options, including the destination file name and other settings.
original? boolean Flag indicating whether to use the initial version of the image for save. Defaults to false.

Returns

void

Implementation of

IImageViewer.save

showMessage

▸ showMessage(message, details?, severity?): void

Shows the message for the user.

Parameters

Name Type Default value
message string undefined
details string ""
severity "error" | "warn" | "info" | "debug" "info"

Returns

void

Accessors

hostElement

• get hostElement(): Element

Gets the main window's host element

Returns

Element

Implementation of

IImageViewer.hostElement

Inherited from

ReportViewer.hostElement

errorHandler

• get errorHandler(): ErrorHandler

Gets or sets callback that is invoked when an error occurs in the process of displaying the report

Returns

ErrorHandler

Inherited from

ReportViewer.errorHandler

onViewerStateChange

• get onViewerStateChange(): EventFan<ChangedEventArgs>

Indicates the viewer state was changed.

Returns

EventFan<ChangedEventArgs>

Inherited from

ReportViewer.onViewerStateChange

toolbar

• get toolbar(): Toolbar

Gets toolbar API

Returns

Toolbar

Implementation of

IImageViewer.toolbar

Inherited from

ReportViewer.toolbar

viewerState

• get viewerState(): Model

Gets currently viewed document state

Returns

Model

Implementation of

IImageViewer.viewerState

Inherited from

ReportViewer.viewerState

zoom

• get zoom(): ZoomSettings

Zoom settings.

Example

// Set zoom to 50%.
viewer.zoom = { mode: 0, factor: 0.5 };

Example

// Zoom mode - fit image width
viewer.zoom = { mode: 1 };

Example

// Zoom mode - fit whole image
viewer.zoom = { mode: 2 };

Returns

ZoomSettings

Inherited from

ReportViewer.zoom

backgroundColor

• get backgroundColor(): string

Gets or sets viewer background color, default value = 'transparent'

Returns

string

Inherited from

ReportViewer.backgroundColor

pageDecoration

• get pageDecoration(): PageDecoration

Gets or sets page view decoration mode.

Returns

PageDecoration

Inherited from

ReportViewer.pageDecoration

isFullscreen

• get isFullscreen(): boolean

Gets a value indicating full screen mode.

Returns

boolean

Implementation of

IImageViewer.isFullscreen

Inherited from

ReportViewer.isFullscreen

isToolbarHidden

• get isToolbarHidden(): boolean

Gets a value indicating whether the toolbar is hidden.

Returns

boolean

Implementation of

IImageViewer.isToolbarHidden

Inherited from

ReportViewer.isToolbarHidden

imageFormat

• get imageFormat(): ImageFormatCode

Gets a format type of the opened image.

Returns

ImageFormatCode

Implementation of

IImageViewer.imageFormat

hasImage

• get hasImage(): boolean

Indicates whether the viewer has opened the image.

Example

 var hasImageFlag = viewer.hasImage;

Returns

boolean

Implementation of

IImageViewer.hasImage

adaptiveNaturalSize

• 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

Name Type
width number
height number

actualSize

• get actualSize(): Object

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

Returns

Object

Name Type
width number
height number

language

• 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').

layers

• get layers(): IImageLayer[]

Image layers. Used for painting.

Returns

IImageLayer[]

Implementation of

IImageViewer.layers

naturalSize

• 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

Name Type
width number
height number

Implementation of

IImageViewer.naturalSize

openParameters

• get openParameters(): undefined | OpenParameters

The Open parameters that were used to open an image.

Returns

undefined | OpenParameters

options

• get options(): Partial<ViewerOptions>

Viewer options

Returns

Partial<ViewerOptions>

toolbarLayout

• 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

ImageToolbarLayout

Implementation of

IImageViewer.toolbarLayout

undoStorage

• get undoStorage(): UndoStorage

Command based undo state storage.

Example

const isUndoInProgress = viewer.undoStorage.undoInProgress;

Returns

UndoStorage

Implementation of

IImageViewer.undoStorage

hasUndo

• get hasUndo(): boolean

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

Example

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

Returns

boolean

hasRedo

• get hasRedo(): boolean

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

Example

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

Returns

boolean

undoIndex

• get undoIndex(): number

Gets current undo level index.

Example

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

Returns

number

undoCount

• get undoCount(): number

Gets total undo levels count.

Example

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

Returns

number

version

• get version(): string

Returns the current version of the DS Image viewer.

Example

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

Returns

string

frameIndex

• 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

framesCount

• 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

eventBus

• 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

IEventBus

Implementation of

IImageViewer.eventBus

onAfterOpen

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

onBeforeOpen

• get onBeforeOpen(): EventFan<BeforeOpenEventArgs>

Occurs immediately before the document 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>

onError

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

onImagePaint

• get onImagePaint(): EventFan<ImagePaintEventArgs>

The event raised when appearance image element changed.

Returns

EventFan<ImagePaintEventArgs>

isAnimationStarted

• 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

Properties

toggleSidebar

• toggleSidebar: (show?: boolean) => void

Type declaration

▸ (show?): void

Sets of toggles sidebar's panels visibility

Parameters
Name Type
show? boolean
Returns

void

Implementation of

IImageViewer.toggleSidebar

Inherited from

ReportViewer.toggleSidebar

Constructors

constructor

• new GcImageViewer(element, options?)

DsImageViewer constructor.

Parameters

Name Type Description
element string | HTMLElement Required. HTML element or CSS selector.
options Partial<ViewerOptions> Optional. Viewer options.

Overrides

ReportViewer.constructor