Apryse WebViewer Class: SignatureCreateTool

Class: SignatureCreateTool

Core .Tools. SignatureCreateTool

Represents the tool for creating signatures, which are represented by a Core.Annotations.FreeHandAnnotation.

new SignatureCreateTool(docViewer)

Creates a new instance of the SignatureCreateTool.

Parameters:

Name	Type	Description
`docViewer`	Core.DocumentViewer	an instance of DocumentViewer.

Properties:

Name	Type	Description
`signatureAnnotations`	Object.<string, (Core.Annotations.FreeHandAnnotation\|Core.Annotations.StampAnnotation)>	Object that stores annotations used for each signature type (Initials and Full Signature)
`signatureDrawingCanvases`	Object.<string, Core.Tools.SignatureCreateTool.SignatureDrawingCanvas>	Object that stores drawing canvases used for each signature type (Initials and Full Signature)
`ACCEPTED_FILE_SIZE`	number	A number specifying the accepted file size in bytes (exclusive). A null, undefined, or value zero and below means no limit.

Extends

Core.Tools.Tool

Members

<static> SignatureTypes

An enum that defines the SignatureTypes that are available in this tool

Properties:

Name	Type	Description
`FULL_SIGNATURE`	string	Represents a full signature
`INITIALS`	string	Represents an initials signature

<static> SigningModes

An enum that defines the SigningModes that are available in this tool

Properties:

Name	Type	Description
`APPEARANCE`	string	Sets the Signature Tool to sign with appearance mode intended for use with digital signatures (default)
`ANNOTATION`	string	Sets the Signature Tool to sign with annotation mode intended for use with electronic signatures

Methods

<static> setInitialsTextHandler(initialsTextHandler)

Parameters:

Name	Type	Description
`initialsTextHandler`	function	A function that should return a string that will be used as the "Initials" text when the widget requires initials

<static> setTextHandler(textHandler)

Parameters:

Name	Type	Description
`textHandler`	function	A function that should return a string that will be used as the "sign here" text

addEventListener(type, fn [, options])

Add a handler to the given event name

Parameters:

Name Type Argument Description

type string | number The name of the event to listen to

fn function The handler to be called when the event is triggered

options

object

Optional options object for addEventListener

Properties

Name	Type	Description
`once`	boolean	If true then the handler will be called only once

Inherited From:

Core.EventHandler#addEventListener

Returns:

Returns the object that 'addEventListener' is being called on

Type: object

Example

myObject.addEventListener('eventName', (eventParameter1, eventParameter2) => {
  ...
});

addInitials()

Add initials to the document. The initials added will be those that are currently set in the tool by Core.Tools.SignatureCreateTool#setInitials

Returns:

A promise that resolves when the intials are added to the document

Type: Promise.<void>

addSignature()

Add the signature to the document. The signature added will be one that is currently set in the tool by Core.Tools.SignatureCreateTool#setSignature

Returns:

A promise that resolves when the signature is added to the document

Type: Promise.<void>

clearInitialsCanvas()

Clears the initials canvas and the underlying annotation

clearLocation()

Clear the location which is set when a mouse click is performed

clearSignatureCanvas()

Clears the signature canvas and the underlying annotation

contextMenu(e)

The function is called when a context menu should be shown. Use e.preventDefault to disable the default browser context menu.

Parameters:

Name	Type	Description
`e`		The event object

Inherited From:

Core.Tools.Tool#contextMenu

deleteAllSavedInitials()

Deletes all saved initials in the tool

deleteAllSavedSignatures()

Deletes all saved full signatures in the tool

deleteSavedInitials(index)

Delete an initials annotation in the tool using an index. Please iterate backwards through the array when calling this method

Parameters:

Name	Type	Description
`index`	number	The index of the saved initials annotation to be deleted

deleteSavedSignature(index)

Delete a full signature annotation in the tool. Please iterate backwards through the array when calling this method

Parameters:

Name	Type	Description
`index`	number	The index of the saved annotation to be deleted

exportInitials( [exportFreeHandPaths])

Exports all saved initials as an array or an XFDF string The array can be stringified using JSON.stringify and saved for later use

Parameters:

Name	Type	Argument	Description
`exportFreeHandPaths`	boolean	<optional>	A boolean when true will export only the paths for the Initials, false to export the annotation in the XFDF

Returns:

Returns a promise that resolves an array that contains arrays of path points or XFDF string if exportFreeHandPaths is true or a base64 image data

Type: Promise.<Array.<(string|Array.<Array.<Core.Math.Point>>)>>

exportSignatures( [exportFreeHandPaths])

Exports all saved signatures as an array or an XFDF string The array can be stringified using JSON.stringify and saved for later use

Parameters:

Name	Type	Argument	Description
`exportFreeHandPaths`	boolean	<optional>	A boolean when true will export only the paths for the Signature, false to export the annotation in the XFDF

Returns:

Returns a promise that resolves an array that contains arrays of path points or XFDF string if exportFreeHandPaths is true or a base64 image data

Type: Promise.<Array.<(string|Array.<Array.<Core.Math.Point>>)>>

getDocumentViewer()

Returns the instance of DocumentViewer for this tool.

Inherited From:

Core.Tools.Tool#getDocumentViewer

Returns:

The instance of DocumentViewer for this tool.

Type: Core.DocumentViewer

getFullSignatureAnnotation()

Returns the annotation used as a full signature

Returns:

a signature annotation

Type: Core.Annotations.FreeHandAnnotation | Core.Annotations.StampAnnotation

getInitialsAnnotation()

Returns the annotation used as initials

Returns:

an initials annotation

Type: Core.Annotations.FreeHandAnnotation | Core.Annotations.StampAnnotation

getMouseLocation(e)

Takes an event object from a mouse event and converts the location into window coordinates

Parameters:

Name	Type	Description
`e`		The event object containing mouse coordinates

Inherited From:

Core.Tools.Tool#getMouseLocation

Returns:

Returns an object with x and y coordinates of the mouse cursor in the viewer

Type: Core.Math.Point

getPreview(annotation)

Gets the preview about how the annot will be drawn on the document

Parameters:

Name	Type	Description
`annotation`	Core.Annotations.FreeHandAnnotation \| Core.Annotations.StampAnnotation

Returns:

A promise that resolves with a base64 string of the preview image

Type: Promise.<string>

getSavedInitials()

Returns the array of saved annotations used as initials

Returns:

an array of annotations

Type: Array.<(Core.Annotations.FreeHandAnnotation|Core.Annotations.StampAnnotation)>

getSavedSignatures()

Returns the array of saved annotations used as full signatures

Returns:

an array of annotations

Type: Array.<(Core.Annotations.FreeHandAnnotation|Core.Annotations.StampAnnotation)>

getSigningMode()

Gets the current signing mode.

Returns:

Returns the current signing mode;

Type: Core.Tools.SignatureCreateTool.SigningModes

hasLocation()

Returns if the signature tool has any location to draw the signature

Returns:

Type: boolean

hidePreview()

Hide the preview element

importInitials(initialsData)

Loads initials data into the signature tool

Parameters:

Name	Type	Description
`initialsData`	string \| Array.<(string\|Array.<Core.Tools.SignatureCreateTool.XYCoords>)>	An array contains arrays of path points or base64 image data or XFDF string If the element is a base64 string, a stamp annotation will be saved and the string will be the value of its ImageData property If the element is an XFDF string the annotation represented by the XFDF will be saved

Returns:

Promise Resolves when the initials data has been loaded

importSignatures(signatureData)

Loads signature data into the signature tool

Parameters:

Name	Type	Description
`signatureData`	string \| Array.<(string\|Array.<Core.Tools.SignatureCreateTool.XYCoords>)>	An array contains arrays of path points or base64 image data or XFDF string If the element is a base64 string, a stamp annotation will be saved and the string will be the value of its ImageData property If the element is an XFDF string the annotation represented by the XFDF will be saved

Returns:

Promise

isEmptyInitialsSignature()

Checks if the initials set in the tool are empty. If the underlying annotation is a freehand, it's empty if it doesn't have any paths If the underlying annotation is a stamp, it's empty if its ImageData property has a falsy value

Returns:

If number of drawn paths is 0.

Type: Promise.<boolean>

isEmptySignature()

Checks if the underlying annotation is empty. If the underlying annotation is a freehand, it's empty if it doesn't have any paths If the underlying annotation is a stamp, it's empty if its ImageData property has a falsy value

Returns:

If number of drawn paths is 0.

Type: Promise.<boolean>

keyDown(e)

The function is called when a keyboard key is down.

Parameters:

Name	Type	Description
`e`		The event object containing keyboard key data.

Inherited From:

Core.Tools.Tool#keyDown

mouseDoubleClick(e)

The function is called when the mouse left button is double clicked.

Parameters:

Name	Type	Description
`e`		The event object containing mouse coordinates.

Inherited From:

Core.Tools.Tool#mouseDoubleClick

mouseLeftDown(e)

The function called when the left mouse button is down

Parameters:

Name	Type	Description
`e`		The event object containing mouse coordinates.

Inherited From:

Core.Tools.Tool#mouseLeftDown

mouseLeftUp(e)

The function called when the left mouse button is up. Typically, annotations are created and added to the annotation manager at this point.

Parameters:

Name	Type	Description
`e`		The event object containing mouse coordinates.

Inherited From:

Core.Tools.Tool#mouseLeftUp

mouseMove(e)

The function called when the mouse moves.

Parameters:

Name	Type	Description
`e`		The event object containing mouse coordinates.

Inherited From:

Core.Tools.Tool#mouseMove

mouseRightDown(e)

The function called when the right mouse button is down.

Parameters:

Name	Type	Description
`e`		The event object containing mouse coordinates.

Inherited From:

Core.Tools.Tool#mouseRightDown

removeEventListener( [type] [, fn])

Remove a handler of the given event name and namespace (if given) or with a function reference

Parameters:

Name	Type	Argument	Description
`type`	string \| number	<optional>	The name of the event to remove the handler of with an optional namespace.
`fn`	function	<optional>	The handler associated with this event to be removed. If fn is undefined, all the handlers of the given event namespace will be removed. If you are not passing in this parameter then a namespace must be used with the event name.

Inherited From:

Core.EventHandler#removeEventListener

Returns:

Returns the object that 'removeEventListener' is being called on

Type: object

Example

myObject.removeEventListener('eventName.namespace');
myObject.removeEventListener('eventName', fn);

resizeCanvas()

Resize the current signature canvas

saveInitials(annotations)

Save an array of freehand or stamp annotations to the signature tool as initials

Parameters:

Name	Type	Description
`annotations`	Core.Annotations.FreeHandAnnotation \| Core.Annotations.StampAnnotation	Annotations to be saved to the signature tool

saveSignatures(annotations)

Save an array of freehand or stamp annotations to the signature tool

Parameters:

Name	Type	Description
`annotations`	Core.Annotations.FreeHandAnnotation \| Core.Annotations.StampAnnotation	Annotations to be saved to the signature tool

setDefaultSignatureOptions(options)

Sets the default options for signatures created with the signature tool.

Parameters:

Name Type Description

options

object

Signature options that should become the default

Properties

Name	Type	Description
`maximumDimensionSize`	number	The maximum size of the signature's largest dimension. Default is 200.

setInitials(annotation [, fileSize])

Sets the underlying annotation used by the tool as initials If a base64 string is passed, the underlying annotation will be a stamp annotation with the string being its ImageData

Parameters:

Name	Type	Argument	Description
`annotation`	Core.Annotations.FreeHandAnnotation \| Core.Annotations.StampAnnotation \| string \| Array.<object>		Annotation to set
`fileSize`	number	<optional>	A number specifying the size in bytes of the signature file which will be compared with 'ACCEPTED_FILE_SIZE'.

Returns:

A promise that will resolve when the initials are set in the tool

Type: Promise.<void>

setInitialsCanvas(canvas)

Sets the canvas to be used by the signature tool for initials.

Parameters:

Name	Type	Description
`canvas`	HTMLCanvasElement	The canvas that the signature tool uses to draw initials on.

setName(name)

Set the name of the tool, which can be accessed by toolObject.name

Parameters:

Name	Type	Description
`name`	string	Name of the tool

Inherited From:

Core.Tools.Tool#setName

setSignature(annotation [, fileSize])

Sets the underlying annotation used by the tool as a full signature If a base64 string is passed, the underlying annotation will be a stamp annotation with the string being its ImageData

Parameters:

Name	Type	Argument	Description
`annotation`	Core.Annotations.FreeHandAnnotation \| Core.Annotations.StampAnnotation \| string \| Array.<object>		Annotation to set
`fileSize`	number	<optional>	A number specifying the size in bytes of the signature file which will be compared with 'ACCEPTED_FILE_SIZE'.

Returns:

A promise that will resolve when the signature is set in the tool

Type: Promise.<void>

setSignatureCanvas(canvas)

Sets the canvas to be used by the signature tool for full signatures.

Parameters:

Name	Type	Description
`canvas`	HTMLCanvasElement	The canvas that the signature tool uses to draw on.

setSigningMode(signingMode)

Sets the signing mode for the tool

Parameters:

Name	Type	Description
`signingMode`	Core.Tools.SignatureCreateTool.SigningModes	The signing mode to select
`signingModes.appearance`	string	Sets the Signature Tool to sign with appearance mode intended for use with digital signatures

Example

WebViewer(...).then(instance => {
 const tool = instance.Core.documentViewer.getTool('AnnotationCreateSignature');
 tool.setSigningMode(instance.Core.Tools.SignatureCreateTool.SigningModes.APPEARANCE);
})

setStyles(newStyles)

Set the style for the tool, which will be applied to annotations drawn afterwards

Parameters:

Name	Type	Description
`newStyles`	object	if an object is used, it should contain properties of the new styles. Example of valid properties: StrokeColor, TextColor, FillColor, FontSize, Opacity, StrokeThickness, Precision, Scale, OverlayText, Style and Dashes.

Inherited From:

Core.Tools.Tool#setStyles

showInitialsPreview()

Shows the preview about how the underlying annot looks like if it's drawn.

Returns:

A promise that resolves when the preview is appended to the DOM and shown in the viewer

Type: Promise.<void>

showPreview()

Shows the preview about how the underlying annot looks like if it's drawn.

Returns:

A promise that resolves when the preview is appended to the DOM and shown in the viewer

Type: Promise.<void>

switchIn(oldTool)

The function is called when this tool is selected. Typically use for changing mouse cursors, and initializing states for the tool.

Parameters:

Name	Type	Description
`oldTool`	Core.Tools.Tool	The Tool class that was previously selected.

Inherited From:

Core.Tools.Tool#switchIn

switchOut(newTool)

The function is called when this tool is deselected. Typically use for changing mouse cursors, and cleaning up states for the tool.

Parameters:

Name	Type	Description
`newTool`	Core.Tools.Tool	The Tool class that was newly selected.

Inherited From:

Core.Tools.Tool#switchOut

trigger(type [, data])

Calls the handlers of the event name with given data

Parameters:

Name	Type	Argument	Description
`type`	string \| number		event name of which the handlers will be called.
`data`	*	<optional>	data that will be passed to the handlers. If data is an array, it will be spread and then passed to the handlers

Inherited From:

Core.EventHandler#trigger

Returns:

Returns the object that 'trigger' is being called on

Type: object

Example

myObject.trigger('eventName');
myObject.trigger('eventName', [eventParameter1, eventParameter2]);

Type Definitions

SignatureDrawingCanvas

Object that has information about a Signature Canvas

Type:

object

Properties:

Name	Type	Description
`signatureType`	number	The key representing which signature this canvas is for (fullSignature or initialsSignature)
`canvas`	HTMLCanvasElement	The canvas used for the signature
`context`	CanvasRenderingContext2D	The canvas rendering context for the signature
`pathIndex`	number	Current path index for FreeHand signatures
`isEditing`	boolean	Whether the signature is being edited (FreeHand only)

XYCoords

Object that has information about a Coordinate Point

Type:

object

Properties:

Name	Type	Description
`x`	number	Represents the x-value of the coordinates
`y`	number	Represents the y-value of the coordinates

Events

annotationAdded

Triggered when an annotation has been added to the document by the tool

Parameters:

Name	Type	Description
`annotation`	Core.Annotations.Annotation	The annotation that was added

fileRejected

Triggered when a file has been rejected because of exceeding file size limit

Parameters:

Name Type Description

reasons

Object

The rejection reasons object

Properties

Name	Type	Description
`reason`	string	Reason why the file was rejected
`maxSize`	number	Maximum accpted file size in bytes
`size`	number	Uploaded file size in bytes

locationSelected

Triggered when a page location has been clicked on by the tool

Parameters:

Name	Type	Argument	Description
`pageCoordinates`	Core.Tools.PageCoordinate		Indicates where the tool clicked
`signatureWidget`	Core.Annotations.SignatureWidgetAnnotation	<optional>	The signature widget that was clicked to trigger the event

signatureDeleted

Triggered when the tool deletes a signature

Parameters:

Name	Type	Description
`annotation`	Core.Annotations.Annotation	The annotation that was deleted
`index`	number	The index of the annotation in the list

signatureReady

Triggered when a signature has been added to the document by the tool

Parameters:

Name	Type	Description
`annotation`	Core.Annotations.Annotation	The signature that was added

signatureSaved

Triggered when the tool saves a signature

Parameters:

Name	Type	Description
`annotation`	Core.Annotations.Annotation	The annotation that was saved