Interface IImageViewer

Interface describing the ImageViewer API, primarily utilized for control/plugin development purposes.

Hierarchy

IImageViewer

Implemented by

GcImageViewer

Accessors

onBeforeOpen

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>

isFullscreen

get isFullscreen(): boolean
Gets a value indicating full screen mode.

Returns boolean

isToolbarHidden

get isToolbarHidden(): boolean
Gets a value indicating whether the toolbar is hidden.

Returns boolean

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

hasImage

get hasImage(): boolean
Indicates whether the viewer has opened the image.

Example
```
 var hasImageFlag = viewer.hasImage;
```
Returns boolean

imageFormat

get imageFormat(): ImageFormatCode
Gets a format type of the opened image.

Returns ImageFormatCode
set imageFormat(format: ImageFormatCode): void
Sets a format type of the opened image.
Parameters
- format: ImageFormatCode
Returns void

layers

get layers(): IImageLayer[]
Image layers. Used for painting.

Returns IImageLayer[]

naturalSize

get naturalSize(): { width: number; height: number }
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 { width: number; height: number }
- width: number
- height: number

undoStorage

get undoStorage(): IUndoStorage

Command based undo state storage.

Example

const isUndoInProgress = viewer.undoStorage.undoInProgress;

Returns IUndoStorage

hostElement

get hostElement(): Element
Outermost viewer's host element containing the gc-viewer-host class.

Returns Element

Methods

showPanel

showPanel(panelKey: PanelHandle, visible?: boolean): void
Updates the panel visibility.
Parameters
- panelKey: PanelHandle
- Optional visible: boolean
Returns void

updatePanel

updatePanel(panelKey: PanelHandle, settings: Partial<PanelSettings>): void
Updates panel settings such as visibility, label or "enabled" status.
Parameters
- panelKey: PanelHandle
- settings: Partial<PanelSettings>
Returns void

getPanelState

getPanelState(panelKey: PanelHandle): null | PanelSettings
Gets the current panel state.
Parameters
- panelKey: PanelHandle
Returns null | PanelSettings

layoutPanels

layoutPanels(layout: string[]): void
Orders and filters panel items. '*' indicates "the rest of panels". 'sep'/'separator' indicated menu separator.
Parameters
- layout: string[]
Returns void

save

save(options?: string | SaveOptions, original?: boolean): 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

Optional options: string | SaveOptions

The save options, including the destination file name and other settings.
Optional original: boolean

Flag indicating whether to use the initial version of the image for save. Defaults to false.

Returns void

toggleFullscreen

toggleFullscreen(fullscreen?: boolean): void
Toggle full screen mode.
Parameters
- Optional fullscreen: boolean
Returns void

toggleToolbar

toggleToolbar(show?: boolean): void
Toggle toolbar visibility.
Parameters
- Optional show: boolean
Returns void

applyToolbarLayout

applyToolbarLayout(): any

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

Example

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

Example

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

addKeyboardListener

addKeyboardListener(uniqueKey: string, handler: WindowKeyboardListener): any
Add window keyboard listener.
Parameters
- uniqueKey: string
- handler: WindowKeyboardListener
Returns any

removeKeyboardListener

removeKeyboardListener(uniqueKey: string): any
Remove window keyboard listener.
Parameters
- uniqueKey: string
Returns any

configurePluginMainToolbar

configurePluginMainToolbar(pos: undefined | number | boolean, buttonsToInsert: string[]): any
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"]);
```
Returns
void
Parameters
- 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 any

dataUrlToImageData

dataUrlToImageData(dataUrl: string, destinationSize?: { width: number; height: number }): Promise<ImageData>
Load image data using given data url.
Parameters
- dataUrl: string
- Optional destinationSize: { width: number; height: number }
  - width: number
  - height: number
Returns Promise<ImageData>

ensurePaintLayer

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

Returns IImageLayer

findPlugin

findPlugin(pluginId: string): 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

pluginId: string

Returns null | IViewerPlugin

getEventCanvasPoint

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

getImageDataUrl

getImageDataUrl(): string
Get current image data url.

Returns string

setCursor

setCursor(cursorType: GlobalCursorType): IImageViewer
Sets the cursor style for the image viewer

Returns

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
Parameters
- cursorType: GlobalCursorType
  
  The cursor style to apply
Returns IImageViewer

resetCursor

resetCursor(): IImageViewer

Resets the cursor to default style

Returns

Example

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

Example

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

Returns IImageViewer

toggleCursor

toggleCursor(cursorType: false | GlobalCursorType): IImageViewer

Toggles between specified cursor and default style

Returns

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

Parameters

cursorType: false | GlobalCursorType

Cursor style to apply, or false to reset

Returns IImageViewer

setImageDataUrl

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

showActivitySpinner

showActivitySpinner(container?: HTMLElement): any
Show activity spinner.

Example
```
viewer.showActivitySpinner();
```
Parameters
- Optional container: HTMLElement
Returns any

hideActivitySpinner

hideActivitySpinner(): any
Hide activity spinner.

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

confirm

confirm(confirmationText?: string | Element, level?: "error" | "info" | "warning", title?: string, buttons?: ConfirmButton[]): Promise<boolean | ConfirmButton>
Display confirmation dialog.
Parameters
- Optional confirmationText: string | Element
- Optional level: "error" | "info" | "warning"
- Optional title: string
- Optional buttons: ConfirmButton[]
Returns Promise<boolean | ConfirmButton>

getOriginalImageDataUrl

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

Returns string

removeLayer

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

removeLayers

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

Returns any

showSecondToolbar

showSecondToolbar(toolbarKey: SecondToolbarType): Promise<void>
Show a second toolbar specified by the toolbarKey argument.

Example
```
// Show page tools bar.
viewer.showSecondToolbar("page-tools");
```
Parameters
- toolbarKey: SecondToolbarType
Returns Promise<void>

Properties

toggleSidebar

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

Type declaration

- (show?: boolean): void
- Sets of toggles sidebar's panels visibility
  Parameters
  - Optional show: boolean
  Returns void

toolbarLayout

toolbarLayout: ImageToolbarLayout

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

`Readonly` in17n

in17n: i18n

i18next instance.

Interface IImageViewer

Hierarchy

Implemented by

Index

Accessors

Methods

Properties

Accessors

onBeforeOpen

Example

Returns EventFan<BeforeOpenEventArgs>

isFullscreen

Returns boolean

isToolbarHidden

Returns boolean

eventBus

Example

Returns IEventBus

hasImage

Example

Returns boolean

imageFormat

Returns ImageFormatCode

Parameters

format: ImageFormatCode

Returns void

layers

Returns IImageLayer[]

naturalSize

Returns { width: number; height: number }

width: number

height: number

undoStorage

Example

Returns IUndoStorage

hostElement

Returns Element

Methods

showPanel

Parameters

panelKey: PanelHandle

Optional visible: boolean

Returns void

updatePanel

Parameters

panelKey: PanelHandle

settings: Partial<PanelSettings>

Returns void

getPanelState

Parameters

panelKey: PanelHandle

Returns null | PanelSettings

layoutPanels

Parameters

layout: string[]

Returns void

save

Example

Example

Example

Example

Example

Parameters

Optional options: string | SaveOptions

Optional original: boolean

Returns void

toggleFullscreen

Parameters

Optional fullscreen: boolean

Returns void

toggleToolbar

Parameters

Optional show: boolean

Returns void

applyToolbarLayout

Example

Example

Returns any

addKeyboardListener

Parameters

`Optional` visible: boolean

`Optional` options: string | SaveOptions

`Optional` original: boolean

`Optional` fullscreen: boolean

`Optional` show: boolean

`Optional` destinationSize: { width: number; height: number }

`Optional` container: HTMLElement

`Optional` confirmationText: string | Element

`Optional` level: "error" | "info" | "warning"