EditViewer Class

Edit Viewer is used to edit the pages in document, such as, rotating, cropping, filtering, etc. as well as adjust the layout of the display.

API Index

Create and Destroy Instances

Viewer Control

Document and Page Control

Display Control

Annotation Control

Edit Operations

Events

Integrated Events

Create and Destroy Instances

EditViewer()

Default constructor of an EditViewer instance.

Syntax

new Dynamsoft.DDV.EditViewer(options?: EditViewerConstructorOptions);

Parameters

options: The constructor options for an EditViewer instance. Please refer to EditViewerConstructorOptions.

Code Snippet

const editViewer = new Dynamsoft.DDV.EditViewer({
    container: document.getElementById("viewer"),
});

// An IBrowseViewer object will be created at meanwhile. Please refer to Remark part.
const thumbnailObj = editViewer.thumbnail; 

Exception

Warning

Remark

• An IBrowseViewer object, editViewer.thumbnail, will be created at meanwhile which represents the thumbnail object in edit viewer. Please refer to IBrowseViewer.

destroy()

Destroy the EditViewer instance.

Syntax

destroy(): void;

Code Snippet

editViewer.destroy();

Remark

• The editing operations (rotating, cropping, filtering) in pages will be saved to document automatically when destroy the viewer instance.

See Also

saveOperations

Viewer Control

bindContainer()

Bind the viewer to the specified container.

Syntax

bindContainer(container: string | HTMLElement): void;

Parameters

container: The container which is used to show the viewer. Its id or HTMLElement is acceppted.

Code Snippet

// Assume there is a container with id "viewercontainer" on the page.
editViewer.bindContainer("viewercontainer");

Exception

Remark

• A viewer can only be bound to one container at once. If you bind the viewer to another container when it has been bound to a container, the viewer will be bound to the new container and unbound from the old container automatically.

unbindContainer()

Unbind the viewer from the specified container.

Syntax

unbindContainer(): void;

Code Snippet

editViewer.unbindContainer();

isBoundContainer

Return whether the viewer is bound to a container.

Syntax

readonly isBoundContainer: boolean;

getStyle()

Get the style object of EditViewer.

Syntax

getStyle(editViewerStyleName: EditViewerStyleName): EditViewerStyle | null;

Parameters

editViewerStyleName: An EditViewerStyleName can be one of five types.

type EditViewerStyleName = "canvasStyle" | "pageStyle" | "currentPageStyle" | "quadSelectionStyle" | "annotationSelectionStyle";

Return values

The style object. Please refer to Style Interfaces..

Code Snippet

// Get pageStyle object;
const pageStyle = editViewer.getStyle("pageStyle");

Warning

updateStyle()

Update the style object of EditViewer.

Syntax

updateStyle(editViewerStyleName: EditViewerStyleName, editViewerStyle: EditViewerStyle): boolean;

Parameters

editViewerStyleName: An EditViewerStyleName can be one of five types.

type EditViewerStyleName = "canvasStyle" | "pageStyle" | "currentPageStyle" | "quadSelectionStyle" | "annotationSelectionStyle";

editViewerStyle: The style object. Please refer to Style Interfaces.

Return Value

true: Successfully.

false: Failed.

Code Snippet

• First method

    // Get style object
    const pageStyle = editViewer.getStyle("pageStyle");
  
    // Modify the style object
    pageStyle.background = "red";
    pageStyle.border = "1px solid green";
  
    // Update page style
    editViewer.updateStyle("pageStyle", pageStyle);
  

• Second method

    // Update the style object directly
    editViewer.updateStyle("pageStyle", {
        background: "red",
        border: "1px solid green",
    });
  

Warning

Remark

• The updates are independent of whether the viewer is displayed and are updated in real time.

getUiConfig()

Get current UiConfig object.

Syntax

getUiConfig(): UiConfig;

Return Value

The UiConfig object.

Code Snippet

const viewerUi = editViewer.getUiConfig();

updateUiConfig()

Update UiConfig object.

Syntax

updateUiConfig(uiConfig: UiConfig): boolean;

Parameters

uiConfig: The UiConfig to update.

Return Value

true: Successfully.

false: Failed.

Code Snippet

const viewerUi = Dynamsoft.DDV.getDefaultUiConfig("editViewer");
const header = viewerUi.children[0];
header.children.splice(0,0,Dynamsoft.DDV.Elements.Delete); //Add `Delete` element in header.
editViewer.updateUiConfig(viewerUi);

Warning

Remark

• The updates are independent of whether the viewer is displayed and are updated in real time.

show()

Show the viewer.

Syntax

show(): void;

Code Snippet

editViewer.show();

Remark

• The viewer is shown automatically when it is created.

hide()

Hide the viewer.

Syntax

hide(): void;

Code Snippet

editViewer.hide();

isVisible

Return whether the viewer is shown or hidden.

Syntax

readonly isVisible: boolean;

Remark

• The viewer is shown automatically when it is created which means the default value of isVisible is true.

toolMode

Specify or return the tool mode of the viewer.

Syntax

toolMode: ToolMode; 

A ToolMode can be one of three types.

type ToolMode = "pan" | "crop" | "annotation";

pan: The default tool mode.

crop: A mode what allows to draw a rectangle by setCropRect().

annotation: A mode that allows to annotations to be manipulated via the UI.

Code Snippet

editViewer.toolMode = "crop";

Warning

Remark

• If toolMode is set to annotation, can use annotationMode to clarify the specific operation.

annotationMode

Specify or return the annotation mode of the viewer.

Syntax

annotationMode: AnnotationMode;

An AnnotationMode can be one of eleven types.

type AnnotationMode = "select" | "erase" | "rectangle" | "ellipse" | "line" | "polygon" | "polyline" | "ink" | "textBox" | "textTypewriter" | "stamp";

select: A mode that allows to select annotation(s) via UI.

erase: A mode that allows to delete annotation(s) via UI.

rectangle: A mode that allows to draw rectangle annotation(s) via UI.

ellipse: A mode that allows to draw ellipse annotation(s) via UI.

line: A mode that allows to draw line annotation(s) via UI.

polygon: A mode that allows to draw polygon annotation(s) via UI.

polyline: A mode that allows to draw polyline annotation(s) via UI.

ink: A mode that allows to draw ink annotation(s) via UI.

textBox: A mode that allows to draw text box annotation(s) via UI.

textTypewriter: A mode that allows to draw text typewriter annotation(s) via UI.

stamp: A mode that allows to draw stamp annotation(s) via UI.

Code Snippet

editViewer.toolMode = "annotation";
editViewer.annotationMode = "select";

Warning

Remark

• It only take effect when toolMode is annotation.
• Default value is select.
• When enableContinuousDrawing is false, please note that the toolMode will automatically switch to pan after completing an annotation drawing interaction, unless the annotationMode is set to select, erase, or ink mode.

Document and Page Control

openDocument()

Open the specified document.

Syntax

openDocument(docUid: string | doc: IDocument): void;

Parameters

docUid: The uid of the specified document.

doc: The object of the document to open. Please refer to IDocument.

Code Snippet

// Assume there is a document whose id is "lnn0ll9o124".
editViewer.openDocument("lnn0ll9o124");

// OR
// Assume there is a document object firstDoc.
const docUid = firstDoc.uid;
editViewer.openDocument(docUid);
editViewer.openDocument(firstDoc);

Exception

Remark

• If another ducument is opened when there is a document already opened, the opened document will be closed automatically.

closeDocument()

Close current document.

Syntax

closeDocument(): boolean; 

Return Value

true: Successfully.

false: Failed.

Code Snippet

editViewer.closeDocument();

Warning

currentDocument

Return the object of the current document.

Syntax

readonly currentDocument: IDocument | null;

Code Snippet

const currentDoc = editViewer.currentDocument;

See Also

IDocument

getPageCount()

Get the page count in the viewer.

Syntax

getPageCount(): number;

Return Value

The page count.

Code Snippet

const pageCount = editViewer.getPageCount();

Warning

goToPage()

Navigate to the specified page by index.

Syntax

goToPage(index: number): number;

Parameters

index: The index of the page which need to navigate to.

Return Value

The index of the page which navigate to.

Code Snippet

// Navigate to page 4.
editViewer.goToPage(3);

Warning

getCurrentPageIndex()

Get the index of the current page.

Syntax

getCurrentPageIndex(): number; 

Return Value

The index of the current page.

Code Snippet

const currentIndex = editViewer.getCurrentPageIndex();

Warning

getCurrentPageUid()

Get the uid of the current page.

Syntax

getCurrentPageUid(): string;

Return Value

The uid of the current page.

Code Snippet

const curPageUid = editViewer.getCurrentPageUid();

Warning

indexToUid()

Get the uid of the specified page by its index.

Syntax

indexToUid(index: number): string;

Parameters

index: The index of the specified page.

Return Value

The uid of the page.

Code Snippet

// Get the first page's uid
const firstPageUid = editViewer.indexToUid(0);

Warning

uidToIndex()

Get the index of the specified page by its uid.

Syntax

uidToIndex(pageUid: string): number;

Parameters

pageUid: The uid of the specified page.

Return Value

The index of the page.

Code Snippet

const curPageUid = editViewer.getCurrentPageUid();
editViewer.uidToIndex(curPageUid);

Warning

Annotation Control

selectAnnotations()

Select the specified annotations on the current page.

Syntax

selectAnnotations(annotationUids: string[]): boolean;

Parameters

annotationUids: Specify the array of annotation uids to select. If set to [], no annotation will be selected.

Return value

true: Successfully.

false: Failed.

Warning

getSelectedAnnotations()

Get selected annotation(s).

Syntax

getSelectedAnnotations(): Annotation[];

Return value

An array of selected Annotation object.

Code Snippet

const selectAnnots = editViewer.getSelectAnnotations();

Warning

Display Control

displayMode

Specify or return the display mode of the viewer.

Syntax

displayMode: DisplayMode; 

A DisplayMode can be one of two types.

type DisplayMode = "single" | "continuous";

single: The pages in the viewer is displayed page by page.

continuous: The pages in the viewer is displayed continuously.

Code Snippet

editViewer.displayMode = "single";

Warning

Remark

• Default displayMode is continuous.
• When displayMode is continuous, the default number of pages to scroll in parallel is 1 and which can be configure by setParallelScrollCount.

setParallelScrollCount()

Specify the number of pages to scroll in parallel.

Syntax

setParallelScrollCount(count: number): boolean;

Parameters

count: The number of pages to scroll in parallel. The maximum value is 20.

Return Value

true: Successfully.

false: Failed.

Code Snippet

// Set three pages to scroll in parallel
editViewer.setParallelScrollCount(3); 

Warning

Remark

• The setting will be applied when displayMode is continuous mode.

fitMode

Specify or return the fit mode of the viewer.

Syntax

fitMode: FitMode; 

A FitMode can be one of four types.

type FitMode = "width" | "height" | "window" | "actualSize";

width: The page is displayed to fit the width.

height: The page is displayed to fit the height.

window: The page is displayed to fit the window.

actualSize: The page is displayed at its actual size, equal to zoom set to 1.

Code Snippet

editViewer.fitMode = "width";

Warning

Remark

• The default fitMode is window, which means fit window.
• Since the specified fitMode is calculated by zoom ratio, if the zoom ratio which set by zoom does not match any of fitMode, the page will be displayed in specified zoom ratio and fitMode will return none.

zoom

Specify or return zoom ratio.

Syntax

zoom: number; 

Code Snippet

//Actual size
editViewer.zoom = 1;

//Twice the actual size
editViewer.zoom = 2; 

//10% the actual size
editViewer.zoom = 0.1;

Warning

Remark

• The interval of available values depends on minZoom and maxZoom which is set in EditViewerConfig when create EditViewer object.
• 1 means actual size of the page and equals to actualSize in fitMode.
• Return value will be rounded to four decimal places.

zoomOrigin

Specify or return the zoom origin of the viewer.

Syntax

zoomOrigin: ZoomOrigin;

Code Snippet

// Set the zoom origin to upper left
const newZoomOrigin = {
    x: "start",
    y: "start",
};

editViewer.zoomOrigin = newZoomOrigin;

Warning

Remark

• The default zoomOrigin is center point of the viewer.

See Also

ZoomOrigin

Edit Operations

rotate()

Rotate the specified pages.

Syntax

rotate(
    angle: number,
    indices?: number[] 
): boolean; 

Parameters

angle: Specify the angle. Only multiples of 90 degrees are supported. Positive value means clockwise rotation, negative value means counterclockwise rotation.

indices: The array of the pages indices which will be rotated. If not set, the current page will be rotated.

Return Value

true: Successfully.

false: Failed.

Code Snippet

// Rotate the first and second pages 90 degrees clockwise.
editViewer.rotate(90, [0,1]);

// Rotate current page 90 degrees counterclockwise.
editViewer.rotate(-90);

Warning

crop()

Crop the specified page(s) with the specified rectangle.

Syntax

crop(
    rect: Rect, 
    indices?: number[]
): boolean; 

Parameters

rect: Specify the rectangle. Please refer to Rect.

indices: Specify the indices of the pages to be cropped. If not set, the current page will be cropped.

Return Value

true: Successfully.

false: Failed.

Code Snippet

const rect = {
    left: 100,
    top: 100,
    width: 200,
    height: 200,
};

editViewer.crop(rect, [0]); // Crop the first page

Warning

Remark

If one of the points of the rectangle is out of page range, crop operation does not take effect in this page and report warning.

getCropRect()

Get the crop rectangular selection.

Syntax

getCropRect(): Rect | null;

Return Value

The rectangular selection. Please refer to Rect.

Code Snippet

editViewer.getCropRect();

Warning

Remark

• If there is no crop rectangular selection, returns null.

setCropRect()

This method is only available when toolMode is crop mode.

Set a crop rectangular selection on the current page.

Syntax

setCropRect(rect: Rect): boolean;

Parameters

rect: Specify the rectangular selection. Please refer to Rect.

Return Value

true: Successfully.

false: Failed.

Code Snippet

editViewer.toolMode = "crop"; // Set toolMode to "crop"

const rect = {
    left: 100,
    top: 100,
    width: 200,
    height: 200,
};

editViewer.setCropRect(rect); 

Warning

Remark

• In the viewer, only one rectangular selection can exist on the page at a time, which means if there is a rectangular selection existed when a new selection is drawn, the old one will be clear automatically.
• When toolMode is set to pan, the drawn rectangular selection will be clear.

undo()

This method takes effect only for crop, rotate operations.

Undo the last editing operation.

Syntax

undo(): boolean;

Return Value

true: Successfully.

false: Failed.

Code Snippet

editViewer.undo();

Warning

redo()

This method takes effect only for crop, rotate operations.

Redo the last undo operation.

Syntax

redo(): boolean;

Return Value

true: Successfully.

false: Failed.

Code Snippet

editViewer.redo();

Warning

saveOperations()

This method takes effect only for crop, rotate & filter(which is operated by using UI Element) operations.

Save the edit operations in pages to document.

Syntax

saveOperations(): boolean;

Return Value

true: Successfully.

false: Failed.

Code Snippet

editViewer.saveOperations();

Warning

Events

on()

Bind a listener to the specified event.

Syntax

on(eventName: EventName, listener:(event:EventObject)=>void): void;

Parameters

eventName: Specify the event name. It can be an integrated event name or a custom event name configured through UiConfig-events.

listener: Specify the listener.

Code Snippet

// Bind a listener to the integrated event resized.
const eventFunc = (e)=>{
    console.log(e);
    console.log(e.oldWidth);
    console.log(e.newWidth);
};

editViewer.on("resized", eventFunc);

Warning

off()

Unbind event listener(s) from the specified event.

Syntax

off(eventName: EventName, listener?:(event:EventObject)=>void): void;

Parameters

eventName: Specify the event name. It can be an integrated event name or a custom event name configured through UiConfig-events.

listener: Specify the listener. If no listener is specified, unbind all event listeners from the specified event.

Code Snippet

const eventFunc = (e)=>{
    console.log(e);
    console.log(e.oldWidth);
    console.log(e.newWidth);
};

editViewer.on("resized", eventFunc);

// Unbind the specified event listener.
editViewer.off("resized", eventFunc);

Warning

Integrated Events

resized

Triggered when the viewer is resized.

Callback

ResizedEvent: An EventObject.

Attributes

oldWidth: The old width of the viewer.

oldHeight: The old height of the viewer.

newWidth: The new width of the viewer.

newHeight: The new height of the viewer.

pageRendered

Triggered when a page has been completely rendered. We only render the pages that are visible on the screen, so this event won’t get fired for every page in the document at once. This event will get called when the user scrolls up and down the document, or when a page is zoomed or rotated, or anything else that makes it rerender.

Callback

PageRenderedEvent: An EventObject.

Attributes

index: The index of the rendered page.

pageUid: The pageUid of the rendered page.

currentIndexChanged

Triggered when currentIndex is changed.

Callback

CurrentindexChangedEvent: An EventObject.

Attributes

oldIndex: The old current index.

newIndex: The new current index. If there is no index in the viewer, return -1.

currentPageChanged

Triggered when current page is changed.

Callback

CurrentPageChangedEvent: An EventObject.

Attributes

oldPageUid: The uid of the page which is old current index. If the old page is removed, return ''.

newPageUid: The uid of the page which is new current index. If there is no index in the viewer, return ''.

displayModeChanged

Triggered when the display mode is changed.

Callback

DisplayModeChangedEvent: An EventObject.

Attributes

oldDisplayMode: The old display mode.

newDisplayMode: The new display mode.

fitModeChanged

Triggered when the fit mode has changed.

Callback

FitModeChangedEvent: An EventObject.

Attributes

oldFitMode: The old fit mode.

newFitmode: The new fit mode.

zoomChanged

Triggered when the zoom ratio has been changed.

Callback

ZoomChangedEvent: An EventObject.

Attributes

oldZoomRatio: The old zoom ratio.

newZoomRatio: The new zoom ratio.

toolModeChanged

Triggered when the tool mode has changed.

Callback

ToolModeChangedEvent: An EventObject.

Attributes

oldToolMode: The old tool mode.

newToolMode: The new tool mode.

cropRectDrawn

Triggered when a rectangular selection is drawn.

Callback

CropRectDrawnEvent: An EventObject.

Attributes

rect: The drawn rectangle.

cropRectDeleted

Triggered when the rectangular selection is deleted.

Callback

CropRectDeletedEvent: An EventObject.

Attributes

rect: The deleted rectangle.

cropRectModified

Triggered when the crop rectangular selection is modified.

Callback

CropRectModifiedEvent: An EventObject.

Attributes

oldRect: The old rectangle.

newRect: The new rectangle.

selectedAnnotationsChanged

Triggered when selected annotation(s) is changed.

Callback

SelectedAnnotationsChanged: An EventObject.

Attributes

oldAnnotationUids: The array of old selected annotations uids.

newAnnotationUids: The array of new selected annotations uids.

Mouse Events

click

Triggered when click in the viewer’s viewing area. On mobile device, triggered when tap in the viewer’s viewing area.

dblclick

Triggered when double click in the viewer’s viewing area.

rightclick

Triggered when right click in the viewer’s viewing area. On mobile device, triggered when long-tap in the viewer’s viewing area.

Callback for mouse events

VPointerEvent: An EventObject.

Attributes

index: The page index.

pageUid: The page uid.

imageX: The relative x-coordinate of the click pointer on the image.

imageY: The relative y-coordinate of the click pointer on the image.

canvasX: The relative x-coordinate of the click pointer on the canvas.

canvasY: The relative x-coordinate of the click pointer on the canvas.

nativeEvent: PointerEvent