GcDocs Image Viewer - v1.0.1 / GcImageViewer

Class: GcImageViewer

GcImageViewer component. GrapeCity Documents Image Viewer (GcImageViewer) is a fast JavaScript based client-side Image Viewer that runs in all major browsers.

Example

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

Hierarchy

• ReportViewer

  ↳ GcImageViewer

Table of contents

Methods

• findControl
• executeTask
• showPanel
• updatePanel
• getPanelState
• layoutPanels
• setActiveTopPanel
• setActiveBottomPanel
• resetDocument
• load
• toggleFullscreen
• toggleToolbar
• applyOptions
• applyToolbarLayout
• addPlugin
• removePlugin
• findPlugin
• removePlugins
• clearUndo
• executeCommand
• newImage
• open
• dispose
• startAnimation
• stopAnimation
• toggleAnimation
• undo
• redo
• getEvent
• triggerEvent
• getOriginalImageDataUrl
• getImageDataUrl
• setImageDataUrl
• showSecondToolbar
• openLocalFile
• download
• showMessage

Accessors

• hostElement
• errorHandler
• onViewerStateChange
• toolbar
• viewerState
• zoom
• isFullscreen
• isToolbarHidden
• imageFormat
• hasImage
• adaptiveNaturalSize
• actualSize
• naturalSize
• openParameters
• options
• toolbarLayout
• undoStorage
• hasUndo
• hasRedo
• undoIndex
• undoCount
• version
• frameIndex
• framesCount
• eventBus
• onAfterOpen
• onBeforeOpen
• onError
• onImagePaint
• isAnimationStarted

Properties

• toggleSidebar

Constructors

• constructor

Methods

findControl

▸ Static findControl(selector): undefined | GcImageViewer

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

Example

var viewer = GcImageViewer.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

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

Inherited from

ReportViewer.updatePanel

---

getPanelState

▸ getPanelState(panelKey): null | PanelSettings

Gets the current panel state.

Parameters

Name	Type
panelKey	PanelHandle

Returns

null | PanelSettings

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

Inherited from

ReportViewer.layoutPanels

---

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

Inherited from

ReportViewer.toggleFullscreen

---

toggleToolbar

▸ toggleToolbar(show?): void

Toggle toolbar visibility.

Parameters

Name	Type
show?	boolean

Returns

void

Inherited from

ReportViewer.toggleToolbar

---

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", "download"];
viewer.applyToolbarLayout();

Example

   var viewer = new GcImageViewer(document.querySelector("#viewer"));
   viewer.addDefaultPanels();
   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

---

addPlugin

▸ addPlugin(plugin): void

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

Example

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

Parameters

Name	Type
plugin	IViewerPlugin

Returns

void

---

removePlugin

▸ removePlugin(pluginId): void

Remove plug-in instance from the GcImageViewer.

Example

var viewer = new GcImageViewer("#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

---

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

---

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?	GcImageFormatName | GcImageFormat | OpenParameters	Loading parameters object.

Returns

Promise<any>

Overrides

ReportViewer.open

---

dispose

▸ dispose(): void

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

Returns

void

Overrides

ReportViewer.dispose

---

startAnimation

▸ startAnimation(): void

Start GIF animation.

Example

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

Returns

void

---

stopAnimation

▸ stopAnimation(): void

Stop GIF animation. *

Example

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

Returns

void

---

toggleAnimation

▸ toggleAnimation(): void

Toggle GIF animation.

Example

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

Returns

void

---

undo

▸ undo(): void

Undo changes.

Example

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

Returns

void

---

redo

▸ redo(): void

Redo changes.

Example

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

Returns

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

---

getImageDataUrl

▸ getImageDataUrl(): string

Get current image data url.

Returns

string

---

setImageDataUrl

▸ setImageDataUrl(dataUrl): Promise<void>

Modify current image data url.

Parameters

Name	Type
dataUrl	any

Returns

Promise<void>

---

showSecondToolbar

▸ showSecondToolbar(toolbarKey): Promise<void>

Show a second toolbar with a key specified by the toolbarKey argument.

Example

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

Parameters

Name	Type
toolbarKey	string

Returns

Promise<void>

---

openLocalFile

▸ openLocalFile(): any

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

Example

viewer.openLocalFile();

Returns

any

---

download

▸ download(fileName?, getInitialVersion?): void

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

Example

// Download modified image.
viewer.download("image.png");

Example

// Download initial image.
viewer.download("image.png", true);

Parameters

Name	Type	Description
fileName?	string	the destination file name.
getInitialVersion?	boolean	-

Returns

void

---

showMessage

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

Shows the message for the user.

Parameters

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

Returns

void

Accessors

hostElement

• get hostElement(): Element

Gets the main window's host element

Returns

Element

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

Inherited from

ReportViewer.toolbar

---

viewerState

• get viewerState(): Model

Gets currently viewed document state

Returns

Model

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

---

isFullscreen

• get isFullscreen(): boolean

Gets a value indicating full screen mode.

Returns

boolean

Inherited from

ReportViewer.isFullscreen

---

isToolbarHidden

• get isToolbarHidden(): boolean

Gets a value indicating whether the toolbar is hidden.

Returns

boolean

Inherited from

ReportViewer.isToolbarHidden

---

imageFormat

• get imageFormat(): GcImageFormat

Format type of the active image. Available image formats are: 1 = JPEG , 2 = PNG, 3 = TIFF, 4 = GIF, 5 = BMP, 6 = ICO, 7 = SVG, 8 = WEBP.

Returns

GcImageFormat

---

hasImage

• get hasImage(): boolean

Indicates whether the viewer has opened the image.

Example

<script>
 var hasImageFlag = viewer.hasImage;
</script>

Returns

boolean

---

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

---

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

---

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', '$split', 'zoom', '$fullscreen', 'download', 'about'

Example

// Customize the toolbar layout:
viewer.toolbarLayout.viewer.default = ["open", "$zoom", "$fullscreen", "download", "print", "about"];
viewer.applyToolbarLayout();

Returns

ImageToolbarLayout

---

undoStorage

• get undoStorage(): UndoStorage

Command based undo state storage.

Example

const isUndoInProgress = viewer.undoStorage.undoInProgress;

Returns

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 GcDocs Image viewer.

Example

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

Returns

string

---

frameIndex

• get frameIndex(): number

Gets/sets the active frame index. Applicable for TIFF, ICO images.

Example

var viewer = new GcImageViewer('#root');
viewer.onAfterOpen.register(function() {
  // Navigate frame with index 9:
  viewer.frameIndex = 9;
});
viewer.open('Test.ico', { imageFormat: 6 });

Returns

number

---

framesCount

• get framesCount(): number

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

Example

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

Returns

number

---

eventBus

• get eventBus(): EventBus

Image viewer event bus.

Example

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

Returns

EventBus

---

onAfterOpen

• get onAfterOpen(): EventFan<EventArgs>

The event raised when the user changes the viewer theme.

Example

var viewer = new GcImageViewer('#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 GcImageViewer('#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 GcImageViewer('#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 = GcImageViewer.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

Inherited from

ReportViewer.toggleSidebar

Constructors

constructor

• new GcImageViewer(element, options?)

GcImageViewer constructor.

Parameters

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

Overrides

ReportViewer.constructor