Apryse WebViewer

Class: SignatureCreateTool

Core.Tools. SignatureCreateTool

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

new SignatureCreateTool(docViewer [, name])

Parameters:
Name Type Argument Default Description
docViewer Core.DocumentViewer An instance of DocumentViewer
name string <optional>
 ToolNames.SIGNATURE The name of the tool, see ToolNames
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

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

locationSelected

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

Methods

<static> setInitialsTextHandler(initialsTextHandler)

Sets the function that determines the initials text
Parameters:
Name Type Description
initialsTextHandler Core.Tools.SignatureCreateTool.TextHandler A function that should return a string that will be used as the "Initials" text when the widget requires initials

<static> setTextHandler(textHandler)

Sets the function that determines the "sign here" text
Parameters:
Name Type Description
textHandler Core.Tools.SignatureCreateTool.TextHandler 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>
 Optional options object for addEventListener
Properties
Name Type Description
once boolean If true then the handler will be called only once
Inherited From:
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 PointerEvent The event object
Inherited From:

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>
 True to 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 Default Description
exportFreeHandPaths boolean <optional>
 true True to 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:
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 MouseEvent The event object containing mouse coordinates
Inherited From:
Returns:
Returns an object with x and y coordinates representing the mouse cursor in the viewer
Type
Core.Tools.Point

getPreview(annotation [, defaultMaximumSize])

Gets the preview about how the annotation will be drawn on the document
Parameters:
Name Type Argument Description
annotation Core.Annotations.FreeHandAnnotation | Core.Annotations.StampAnnotation The annotation to get preview for
defaultMaximumSize number <optional>
 The maximum dimension size of the annotation
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 whether 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. 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.
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
Returns:
Resolves when the initials data has been loaded
Type
Promise.<void>

importSignatures(signatureData)

Loads signature data into the signature tool. 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
Parameters:
Name Type Description
signatureData string | Array.<(string|Array.<Core.Tools.SignatureCreateTool.XYCoords>)> An array containing arrays of path points or base64 image data or XFDF string
Returns:
Type
Promise.<void>

isEmptyInitialsSignature()

Checks if the initials set in the tool are empty. If the underlying annotation is a freehand, it is considered empty if it doesn't have any paths. If the underlying annotation is a stamp, it is considered empty if its ImageData property has a falsy value.
Returns:
True if the signature is empty, false otherwise
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:
True if the underlying annotation is empty, false otherwise
Type
Promise.<boolean>

keyDown(e)

The function is called when a keyboard key is down
Parameters:
Name Type Description
e KeyboardEvent The event object containing keyboard key data
Inherited From:

mouseDoubleClick(e)

The function is called when the mouse left button is double clicked
Parameters:
Name Type Description
e MouseEvent The event object containing mouse coordinates
Inherited From:

mouseLeave(e)

The function called when the mouse leaves
Parameters:
Name Type Description
e MouseEvent The event object containing mouse coordinates
Inherited From:

mouseLeftDown(e)

The function called when the left mouse button is down
Parameters:
Name Type Description
e MouseEvent The event object containing mouse coordinates
Inherited From:

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 MouseEvent The event object containing mouse coordinates
Inherited From:

mouseMove(e)

The function called when the mouse moves
Parameters:
Name Type Description
e MouseEvent The event object containing mouse coordinates
Inherited From:

mouseRightDown(e)

The function called when the right mouse button is down
Parameters:
Name Type Description
e MouseEvent The event object containing mouse coordinates
Inherited From:

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:
Returns:
Returns the object that 'removeEventListener' is being called on
Type
object
Example
myObject.removeEventListener('eventName.namespace');
myObject.removeEventListener('eventName', fn);

resizeCanvas( [signatureType])

Resize the current signature canvas
Parameters:
Name Type Argument Description
signatureType string <optional>
 The type of signature canvas to resize
Returns:
Type
Promise.<void>

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 | Array.<Core.Annotations.FreeHandAnnotation> | Array.<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 | Array.<Core.Annotations.FreeHandAnnotation> | Array.<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.
maximumInitialsDimensionSize number The maximum size of the initials' largest dimension. Default is 50.

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 Default Description
annotation Core.Annotations.FreeHandAnnotation | Core.Annotations.StampAnnotation | string | Array.<Array.<Core.Math.Point>> Annotation to set
fileSize number <optional>
 0 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)

Sets The name of the tool, see ToolNames, which can be accessed by toolObject.name
Parameters:
Name Type Description
name string The name of the tool, see ToolNames
Inherited From:

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 Default Description
annotation Core.Annotations.FreeHandAnnotation | Core.Annotations.StampAnnotation | string | Array.<Array.<Core.Math.Point>> Annotation to set
fileSize number <optional>
 0 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

setSignatureScaleFactor(factor)

Parameters:
Name Type Description
factor A number that will be multiplied to the signature's dimensions when it's drawn onto the document. The default value is 1.
Returns:
Type
void

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)

Sets the style for the tool, which will be applied to annotations drawn afterwards
Parameters:
Name Type Description
newStyles Object.<string, any> An object containing the new style properties
Inherited From:
Example
tool.setStyles({
      StrokeColor: new Annotations.Color(0, 0, 0),
      TextColor: new Annotations.Color(0, 0, 0),
      FillColor: new Annotations.Color(0, 0, 0),
      FontSize: '12pt',
      Opacity: 1,
      StrokeThickness: 1,
      Precision: 0.001,
      Scale: [[0.25, 'in'], [1, 'in']],
      OverlayText: 'Text',
      Style: 'solid',
      Dashes: '3, 3',
    });

showInitialsPreview()

Shows the preview about how the underlying annotation 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 annotation 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 used 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:

switchOut(newTool)

The function is called when this tool is deselected. Typically used 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:

tap(e)

The function called when there is a tap event
Parameters:
Name Type Description
e MouseEvent The event object containing mouse coordinates
Inherited From:

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:
Returns:
Returns the object that 'trigger' is being called on
Type
object
Example
myObject.trigger('eventName');
myObject.trigger('eventName', [eventParameter1, eventParameter2]);

triggerAsync(type [, data])

Calls the handlers of the event name with given data *asynchronously*. It's different from Core.EventHandler#trigger in that it can be awaited to ensure all async handlers have finished executing code
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:
Returns:
Returns the object that 'triggerAsync' is being called on
Type
Promise.<Object>
Example
myObject.triggerAsync('eventName');
myObject.triggerAsync('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)

TextHandler()

Returns:
Text to use
Type
string

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 accepted file size in bytes
size number Uploaded file size in bytes

initialDeleted

Triggered when the tool deletes initials
Parameters:
Name Type Description
annotation Core.Annotations.Annotation The annotation that was deleted
index number The index of the annotation in the list

initialSaved

Triggered when the tool saves initials
Parameters:
Name Type Description
annotation Core.Annotations.Annotation The annotation that was saved

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
location Core.Tools.PageCoordinate The page coordinates where the signature is placed

signatureSaved

Triggered when the tool saves a signature
Parameters:
Name Type Description
annotation Core.Annotations.Annotation The annotation that was saved