[]
        
(Showing Draft Content)

GcImageViewer

Document Solutions Image Viewer - v8.0.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