Apryse WebViewer

Class: RubberStampCreateTool

Core.Tools. RubberStampCreateTool

Represents the tool for creating Core.Annotations.StampAnnotation

new RubberStampCreateTool(docViewer [, name])

Parameters:
Name Type Argument Default Description
docViewer Core.DocumentViewer An instance of DocumentViewer
name string <optional>
 ToolNames.RUBBER_STAMP The name of the tool, see ToolNames

Extends

Methods

addCustomStamp(options)

Add a single custom stamp to tool's list
Parameters:
Name Type Description
options Core.Tools.RubberStampCreateTool.CustomStampData The custom stamp data

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:
Overrides:
Returns:
Returns the object that 'addEventListener' is being called on
Type
object
Example
myObject.addEventListener('eventName', (eventParameter1, eventParameter2) => {
  ...
});

addPresetStamps(stamps)

Appends stamps to the current preset list without replacing it. Accepts either a plain array or a Core.Tools.RubberStampCreateTool.PresetStampsConfig object so a saved config can be merged in directly. If registerPresetStamps has not yet been called, the existing standard stamp list is used as the starting point before appending.
Parameters:
Name Type Description
stamps Array.<(string|Core.Tools.RubberStampCreateTool.PresetStampEntry)> | Core.Tools.RubberStampCreateTool.PresetStampsConfig
Example
tool.addPresetStamps({ stamps: [{ icon: 'Draft', category: 'Legal' }] });

addStamp()

Add the stamp to the document
Returns:
Type
Promise.<void>

clearDocumentStamps()

Removes all registered document-backed stamps and releases associated document resources. Existing standard stamps and custom stamps are not affected.
Returns:
Type
void

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:
Overrides:

createCustomStampAnnotation(params)

Create a custom stamp annotation
Parameters:
Name Type Description
params Core.Tools.RubberStampCreateTool.CustomStampData The custom stamp data
Returns:
Type
Promise.<Core.Annotations.StampAnnotation>

deleteCustomStamps(stampsToDelete)

Deletes the provided set of custom stamps from the tool. The delete logic performs an object reference comparison therefore it is recommended to only pass in stamps retrieved from RubberStampCreateTool.getCustomStamps.
Parameters:
Name Type Description
stampsToDelete Array.<Core.Tools.RubberStampCreateTool.CustomStampData> An array of objects representing custom stamps to delete

drawCustomStamp(options)

Draw custom stamp annotation onto a canvas
Parameters:
Name Type Description
options object An object that can contain the following optional parameters
Properties
Name Type Argument Default Description
title string <optional>
 Custom stamp's main text
subtitle string <optional>
 Time format text used as a custom timestamp, e.g. "DD-MM-YYYY". To render a plain-text string as a subtitle, place the desired string inside of square brackets e.g. "[This is a subtitle]"
color Core.Annotations.Color <optional>
 Fill color value
textColor Core.Annotations.Color <optional>
 Text color value
canvas HTMLCanvasElement <optional>
 Canvas to draw this annotation
width number <optional>
 Default width of stamp
height number <optional>
 Default height of stamp
canvasParent HTMLElement <optional>
 Parent DOM element of canvas
font string <optional>
 'Arial' Font family to use for stamp text
bold boolean <optional>
 false Whether to use bold styling for the title or not
italic boolean <optional>
 false Whether to use italic styling for the title or not
underline boolean <optional>
 false Whether to underline the title or not
strikeout boolean <optional>
 false Whether to strikeout the title or not
Returns:
The width of the drawn stamp
Type
number

getCustomStampAnnotations()

Get array of custom stamp annotations
Returns:
An array of custom stamp annotations
Type
Promise.<Array.<Core.Annotations.StampAnnotation>>

getCustomStamps()

Returns array of objects representing the custom stamps
Returns:
An array of objects representing the custom stamps
Type
Array.<Core.Tools.RubberStampCreateTool.CustomStampData>

getDefaultStamps()

Returns array of strings representing the built-in, default stamps
Returns:
An array of strings representing the default stamps
Type
Array.<string>

getDocumentStampRegistration()

Returns the last registration input so sibling viewer tools can replay it.
Returns:
A copy of the most recent registration input
Type
Object

getDocumentViewer()

Returns the instance of DocumentViewer for this tool
Inherited From:
Overrides:
Returns:
The instance of DocumentViewer for this tool
Type
Core.DocumentViewer

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:
Overrides:
Returns:
Returns an object with x and y coordinates representing the mouse cursor in the viewer
Type
Core.Tools.Point

getPreview(annotation, parameters)

Gets the preview about how the annotation will be drawn on the document
Parameters:
Name Type Description
annotation Core.Annotations.StampAnnotation The annotation to get the preview for
parameters object Canvas parameters and optional text for annotation, e.g. translated text
Properties
Name Type Argument Description
canvasHeight number The height of the canvas
canvasWidth number The width of the canvas
text string <optional>
 Optional text for annotation, e.g. translated text
direction 'ltr' | 'rtl' <optional>
 The direction of the viewer, either 'ltr' or 'rtl'
Returns:
Returns a promise that resolves a base64 string of the preview image
Type
Promise.<string>

getStandardStampAnnotations()

Get array of standard stamp annotations
Returns:
Type
Promise.<Array.<Core.Annotations.StampAnnotation>>

getStandardStamps()

Returns array of strings representing the standard stamps
Returns:
An array of strings representing the standard stamps
Type
Array.<string>

hasDocumentStampLabel(label)

Returns true when the registry contains a document stamp matching the given panel label.
Parameters:
Name Type Description
label string The panel label in "title pageNumber" format
Returns:
Whether a matching document stamp is registered
Type
boolean

hasDocumentStampTemplate(templateId)

Returns true if this tool's registry contains a template with the given ID.
Parameters:
Name Type Description
templateId string The document stamp template ID
Returns:
Whether the template is registered
Type
boolean

hidePreview()

Hide the preview element

isDocumentStampsLoading()

Returns whether document-backed stamps are currently loading.
Returns:
Whether a document-backed stamp registration is in progress
Type
boolean

isEmptyStamp()

Checks if the underlying annotation is empty
Returns:
True if the underlying annotation is not a StampAnnotation type, false otherwise
Type
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:
Overrides:

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:
Overrides:

mouseLeave(e)

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

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:
Overrides:

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:
Overrides:

mouseMove(e)

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

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:
Overrides:

registerPresetStamps(config)

Registers the full preset stamp list shown in the stamp panel. Replaces any previously registered preset stamps. Accepts either a plain array or a Core.Tools.RubberStampCreateTool.PresetStampsConfig object, which can be serialised to JSON and passed back directly to restore the same stamp list.
Parameters:
Name Type Description
config Array.<(string|Core.Tools.RubberStampCreateTool.PresetStampEntry)> | Core.Tools.RubberStampCreateTool.PresetStampsConfig
Example
tool.registerPresetStamps({
  stamps: [
    { icon: 'Approved', category: 'rubberStampPanel.standard' },
    { icon: 'TopSecret', category: 'rubberStampPanel.legal' },
    'Void', // plain string — falls back to default category
  ],
});

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

setCustomDrawFunction(callback)

Sets a custom function to be used for drawing extra content on top of custom stamps, enabling customization of the CanvasRenderingContext2D of the Canvas element used for Rubber Stamps
Parameters:
Name Type Description
callback Core.Tools.RubberStampCreateTool.CustomDrawFunction A callback side effect function that takes two parameters. The first is assumed to be the type CanvasRenderingContext2D, and modifies the parameter for the purposes of custom drawing behavior on top of the default stamp behavior. The second parameter is optional, and is assumed to be an instance of the Core.Annotations.Annotation class, wherein custom behavior for the stamp annotation being modified can be added (i.e. conditionally apply custom drawing on certain annotations only)
Example
WebViewer(
 // ...
).then(instance => {
  const { docViewer } = instance;
  const tool = docViewer.getTool('AnnotationCreateRubberStamp');
  tool.setCustomDrawFunction((ctx, annotation) => {
    const { Icon } = annotation;
    // `Icon` contains the text content of the stamp
    // This example conditionally renders custom content on the stamp only
    // if the contents of the stamp are in the approved list of stamps to
    // draw on
    const stampsToDrawOn = [
      'Approved',
      'Completed',
      'Final',
    ];
    if (stampsToDrawOn.includes(Icon)) {
      // Arbitrary example where an image is available in the DOM
      const img = document.getElementById('my-company-logo');
      ctx.drawImage(
        img, // The image to render
        0, // The X coordinate of where to place the image
        0, // The Y coordinate of where the place the image
        25, // The width of the image in pixels
        25, // The height of the image in pixels
      );
    }
  });
});

setCustomStamps(stamps)

Accepts and sets an array of objects representing custom stamps
Parameters:
Name Type Description
stamps Array.<Core.Tools.RubberStampCreateTool.CustomStampData> An array of objects representing custom stamps
Example
[
 {
   "title": "Sample Text",
   "subtitle": "DD-MM-YYYY",
   "color": window.Core.Annotations.Color(0,0,0)
 }
]

setDocumentStamps(sources [, options])

Registers one or more PDF documents as document-backed stamps available in the Rubber Stamp panel. Each page of a successfully prepared document becomes a selectable stamp entry. Sources that fail to load or prepare are isolated and do not prevent other sources from being registered. Repeated calls replace all previously registered document-backed stamps.
Parameters:
Name Type Argument Description
sources Array.<Core.Tools.RubberStampCreateTool.DocumentStampSource> An array of document sources to register as stamps
options Core.Tools.RubberStampCreateTool.SetDocumentStampsOptions <optional>
 Optional registration settings
Returns:
A result object containing the registered stamp count and any per-source failures
Type
Promise.<Core.Tools.RubberStampCreateTool.SetDocumentStampsResult>
Example
const tool = docViewer.getTool('AnnotationCreateRubberStamp');
const { registeredCount, failures } = await tool.setDocumentStamps([
  { source: 'https://example.com/approved.pdf' },
  { source: myFileBlob, title: 'Company Seal', pages: [1] },
]);

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:
Overrides:

setRubberStamp(annotation [, text])

Sets the underlying annotation used by the tool
Parameters:
Name Type Argument Description
annotation Core.Annotations.StampAnnotation The annotation to set, or `null` to clear the tool's current stamp
text string <optional>
 The text to be set in the stamp. Ignored when `annotation` is `null`
Returns:
Type
Promise.<void>

setStampScaleFactor(factor)

Parameters:
Name Type Description
factor The scale factor to apply to the stamp size. The default value is 1.
Returns:
Type
void

setStandardStamps(stamps)

Accepts and sets an array of strings representing standard stamps
Parameters:
Name Type Description
stamps Array.<string> An array of strings representing the standard stamps

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:
Overrides:
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',
      StrokeStyle: 'solid',
      Dashes: '3, 3',
    });

showPreview()

Shows the preview about how the underlying annotation looks like if it's drawn
Returns:
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:
Overrides:

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:
Overrides:

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:
Overrides:

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

useStamp(options)

Have this rubber stamp tool always create a single type of stamp with the specified icon value
Parameters:
Name Type Description
options object An object that can contain the following optional parameters
Properties
Name Type Argument Description
Icon string The name of the icon to use, e.g.: 'SBRejected' | 'SHAccepted' | 'Dot'
FillColor Core.Annotations.Color <optional>
 The color of the stamp. Defaults to black.
Width number <optional>
 The width of the stamp
Height number <optional>
 The height of the stamp
Opacity number <optional>
 The opacity of the stamp

Type Definitions

CustomDrawFunction(ctx [, annotation])

Parameters:
Name Type Argument Description
ctx CanvasRenderingContext2D The CanvasRenderingContext2D of the Canvas element used for Rubber Stamps
annotation Core.Annotations.Annotation <optional>
 An instance of the Core.Annotations.Annotation class
Returns:
Type
void

CustomStampData

Type:
  • Object
Properties:
Name Type Argument Description
title string <optional>
 Custom stamp's main text
subtitle string <optional>
 Time format text used as a custom timestamp, e.g. "DD-MM-YYYY" To render a plain-text string as a subtitle, place the desired string inside of square brackets e.g. "[This is a subtitle]".
color Core.Annotations.Color <optional>
 Background color value
id string <optional>
 Stamp ID
font string <optional>
 Font family to use for stamp text
bold boolean <optional>
 Whether to use bold styling for the title or not
italic boolean <optional>
 Whether to use italic styling for the title or not
underline boolean <optional>
 Whether to underline the title or not
strikeout boolean <optional>
 Whether to strikeout the title or not
category string <optional>
 The category of the custom stamp. If not provided, defaults to "Custom Stamp".

DocumentStampPageFailure

Type:
  • Object
Properties:
Name Type Description
title string The title of the document source
pageNumber number The 1-indexed page number that failed to register
reason Error The error that caused the page-level failure

DocumentStampPageSuccess

Type:
  • Object
Properties:
Name Type Description
title string The title of the document source
pageNumber number The 1-indexed page number that was successfully registered

DocumentStampRegistrationFailure

Type:
  • Object
Properties:
Name Type Description
title string The title of the document that could not be registered
reason Error The error that caused the failure

DocumentStampSource

Type:
  • Object
Properties:
Name Type Argument Description
source string | File | Blob | ArrayBuffer The document source (URL string, File, Blob, or ArrayBuffer)
title string <optional>
 Optional display title used for stamp labels and search in the stamp panel
filename string <optional>
 Optional filename hint used when loading the source via createDocument
extension string <optional>
 Optional file extension override, e.g. 'pdf'
pages Array.<number> <optional>
 Specific page numbers to register (1-indexed). Registers all pages if omitted.
cropVisibleContent boolean <optional>
 Whether to auto-crop each page to its visible content bounds. Defaults to true.
category string <optional>
 Optional category name for the stamp. Falls back to the standard stamp category if omitted.

PresetStampEntry

Type:
  • Object
Properties:
Name Type Argument Description
icon string The stamp to display. Accepts either a named icon from the built-in stamp or an absolute image URL / base64 data URI.
category string <optional>
 i18n translation key or literal display string for the category. The panel translates the key at render time; if no match is found the value itself is shown. Omit to fall back to the default "Standard Stamps" category (`'rubberStampPanel.standard'`).

PresetStampsConfig

Type:
  • Object
Properties:
Name Type Description
stamps Array.<(string|Core.Tools.RubberStampCreateTool.PresetStampEntry)> The list of stamps. Each entry is either a plain icon string (backwards-compatible) or a PresetStampEntry object with an optional category. Can be serialised to and restored from JSON.

SetDocumentStampsOptions

Type:
  • Object
Properties:
Name Type Argument Description
pages Array.<number> <optional>
 Default page numbers applied to sources that do not specify their own pages.
cropVisibleContent boolean <optional>
 Default crop-to-visible-content policy applied to all sources that do not specify their own value. Defaults to true.

SetDocumentStampsResult

Type:
  • Object
Properties:
Name Type Description
registeredCount number The number of stamp pages successfully registered
failures Array.<Core.Tools.RubberStampCreateTool.DocumentStampRegistrationFailure> Details of any sources that failed to register
pageSuccesses Array.<Core.Tools.RubberStampCreateTool.DocumentStampPageSuccess> Details of successfully registered pages
pageFailures Array.<Core.Tools.RubberStampCreateTool.DocumentStampPageFailure> Details of page-level failures

Events

annotationAdded

Triggered when an annotation has been added to the document by the tool
Parameters:
Name Type Description
annotation Core.Annotations.StampAnnotation The annotation that was added

customStampsDeleted

Triggered when a set of custom stamps has been deleted
Parameters:
Name Type Description
stamps Array.<Core.Tools.RubberStampCreateTool.CustomStampData> The set of custom stamps to delete

documentStampsLoadingChanged

Triggered when document-backed stamps start or finish loading
Parameters:
Name Type Description
isLoading boolean Whether document-backed stamps are loading

stampsUpdated

Triggered when a set of either standard or custom stamps has been updated
Parameters:
Name Type Description
stamps Array.<string> | Array.<Core.Tools.RubberStampCreateTool.CustomStampData> The updated set of standard or custom stamps