Apryse WebViewer

Namespace: Annotations

Core. Annotations

The namespace for anything to do with PDF annotations.

Classes

Annotation
ArcAnnotation
Border
BoxControlHandle
BoxSelectionModel
ButtonWidgetAnnotation
CalloutControlHandle
CalloutSelectionModel
CanvasHelper
CaretAnnotation
CheckButtonWidgetAnnotation
ChoiceWidgetAnnotation
Color
ControlHandle
CustomAnnotation
DatePickerWidgetAnnotation
EllipseAnnotation
FileAttachmentAnnotation
FileAttachmentUtils
Font
Forms
FreeHandAnnotation
FreeTextAnnotation
FreeTextSelectionModel
HTMLAnnotation
IPathAnnotation
LineAnnotation
LineControlHandle
LineSelectionModel
Link
ListWidgetAnnotation
MarkupAnnotation
Model3DAnnotation
PathControlHandle
PathSelectionModel
PDFCustomAnnotation
PolygonAnnotation
PolygonControlHandle
PolygonSelectionModel
PolylineAnnotation
PopupAnnotation
PushButtonWidgetAnnotation
RadioButtonWidgetAnnotation
RectangleAnnotation
RedactionAnnotation
RedactionSelectionModel
RotationControlHandle
RotationUtils
SelectionAlgorithm
SelectionModel
SignatureWidgetAnnotation
SoundAnnotation
StampAnnotation
StickyAnnotation
TextHighlightAnnotation
TextMarkupAnnotation
TextRedactAnnotation
TextSelectionModel
TextSquigglyAnnotation
TextStrikeoutAnnotation
TextUnderlineAnnotation
TextWidgetAnnotation
WidgetAnnotation
WidgetFlags
WidgetSelectionModel
XFDFUtils

Namespaces

Utilities

Members

<static> LineEndType

An enum representing different line end types that are available for line annotations
Properties:
Name Type Description
NONE string No line endings
OPEN_ARROW string An arrow that points outward
R_OPEN_ARROW string An arrow that points inward
CLOSED_ARROW string A triangle that points outward
R_CLOSED_ARROW string A triangle that points inward
BUTT string A vertical line
SQUARE string A square
DIAMOND string A diamond
CIRCLE string A circle
SLASH string A slash

<static> LineStyleType

An enum representing different line types that are available for line annotations
Properties:
Name Type Description
SOLID string Solid line style
DASH_1_2_2 string Dashed line with [1,2,2] style
DASH_3_3 string Dashed line with [3,3] style
DASH_3_3_4 string Dashed line with [3,3,4] style
DASH_1_3_5 string Dashed line with [1,3,5] style
DASH_2_2_4 string Dashed line with [2,2,4] style
DASH_4_3_16_3 string Dashed line with [4,3,16,3] style
CLOUDY string Cloudy line style

Methods

<static> restoreDeserialize(annotationClass)

Restores the deserialize function back to the default.
Parameters:
Name Type Description
annotationClass Core.Annotations.Annotation The class (constructor) of the annotation

<static> restoreDraw(annotationClass)

Restores the draw function back to the default.
Parameters:
Name Type Description
annotationClass Core.Annotations.Annotation The class (constructor) of the annotation

<static> restoreSerialize(annotationClass)

Restores the serialize function back to the default.
Parameters:
Name Type Description
annotationClass Core.Annotations.Annotation The class (constructor) of the annotation

<static> setCustomControlHandleDrawHandler(controlHandle, controlHandleDrawHandler)

Change ControlHandle's draw to customize appearance on the provided canvas context
Parameters:
Name Type Description
controlHandle Class.<Core.Annotations.ControlHandle> Control handle class
controlHandleDrawHandler Core.Annotations.CustomControlHandleDrawHandler Handler that performs custom drawing
Example
Annotations.setCustomControlHandleDrawHandler(Core.Annotations.ControlHandle, function(ctx, annotation, selectionBox, zoom, {controlHandle, originalDraw}) {
  if(controlHandle instanceof Core.Annotations.BoxControlHandle) {
    const dim = this.getDimensions(annotation, selectionBox, zoom);
    ctx.fillStyle = '#FFFFFF';
    ctx.beginPath();
    ctx.moveTo(dim.x1 + (dim.getWidth() / 2), dim.y1);
    ctx.lineTo(dim.x1 + dim.getWidth(), dim.y1 + dim.getHeight());
    ctx.lineTo(dim.x1, dim.y1 + dim.getHeight());
    ctx.closePath();
    ctx.stroke();
    ctx.fill();
  } else {
     originalDraw(ctx, annotation, selectionBox, zoom);
  }
})

<static> setCustomCreateInnerElementHandler(annotationClass, createInnerElementHandler)

Sets a custom inner element creation handler for a widget annotation class
Parameters:
Name Type Description
annotationClass any The annotation class to customize
createInnerElementHandler Core.Annotations.CustomCreateInnerElementHandler Handler returning a custom inner element
Example
Annotations.setCustomCreateInnerElementHandler(Annotations.CheckButtonWidgetAnnotation, function(annotationManager, { annotation, originalCreateInnerElement }) {
  const el = originalCreateInnerElement();
  el.addEventListener('click', () => {
    console.log('check button clicked', annotation.fieldName);
  });
  return el;
});

<static> setCustomCreateSignHereElementHandler(createSignHereElementHandler)

Sets a custom sign-here element creation handler for signature widget annotations
Parameters:
Name Type Description
createSignHereElementHandler Core.Annotations.CustomCreateSignHereElementHandler Handler that returns the custom sign-here element
Example
Annotations.setCustomCreateSignHereElementHandler(function(tool, { annotation, originalCreateSignHereElement }) {
  const signHereElement = originalCreateSignHereElement(tool);
  signHereElement.style.background = 'red';
  return signHereElement;
});
// If you are on the signature form field create tool and have a cursor preview
// created already, you can use tool.switchOut(tool) to refresh the preview
const tool = WebViewer.getInstance().Core.documentViewer.getToolMode();
tool.switchOut(tool);

<static> setCustomDeserializeHandler(annotationClass, deserializeHandler)

Changes how an annotation type is deserialized within WebViewer. If your custom property/attribute is stored in the CustomData, please consider using getCustomData instead
Parameters:
Name Type Description
annotationClass Class.<Core.Annotations.Annotation> Annotation class to customize
deserializeHandler Core.Annotations.CustomAnnotationDeserializeHandler Handler that performs custom deserialization
Example
Annotations.setCustomDeserializeHandler(Annotations.RectangleAnnotation, function(element, pageMatrix, { annotation, originalDeserialize }) {
  originalDeserialize(element, pageMatrix);
  if (annotation.Width > 100) {
    annotation.myProperty = element.getAttribute('myAttr');
  }
});

<static> setCustomDrawHandler(annotationClass, drawHandler [, options])

Changes how an annotation type is drawn within WebViewer. By default, this will also generate an appearance for the annotation when the document is downloaded, so it will appear the same in other viewers. Please note that changes to the annotation may cause the appearance to be discarded, reverting it back to normal.
Please note that NoZoom annotations do render slightly differently from standard annotations. Nonetheless, please draw at the annotation coordinates. The appearance set by addCustomAppearance will take priority.
Parameters:
Name Type Argument Description
annotationClass Class.<Core.Annotations.Annotation> The class of the annotation
drawHandler Core.Annotations.CustomAnnotationDrawHandler A handler function that will draw the annotation
options Core.Annotations.CustomDrawOptions <optional>
 Optional options
Properties
Name Type Argument Description
generateAppearance boolean <optional>
 Whether to generate a custom appearance. Defaults to true
canvasMultiplier number <optional>
 The quality value of the generated custom appearance. The higher the value, the more memory is required. By default, this will use the canvas multiplier value set in WebViewer
Example
Annotations.setCustomDrawHandler(Annotations.RectangleAnnotation, function(ctx, pageMatrix, rotation, options) {
  options.originalDraw(ctx, pageMatrix); // Draw original annotation
  const annot = options.annotation;

  // Draw annotation ID overtop the rectangle
  ctx.fillStyle = '#FF0000';
  ctx.strokeStyle = '#000000';
  const fontSize = 12;
  ctx.fillText(annot.Id, annot.X, annot.Y + fontSize);   // Draw at annotation location
  ctx.strokeText(annot.Id, annot.X, annot.Y + fontSize);
});

<static> setCustomSerializeHandler(annotationClass, serializeHandler)

Changes how an annotation type is serialized within WebViewer. Note that custom attributes will not be persisted in the downloaded PDF and are only useful if you're saving the XFDF separately from the PDF. If you are looking to save your custom property/attribute, please consider using setCustomData which will be persisted
Parameters:
Name Type Description
annotationClass Class.<Core.Annotations.Annotation> Annotation class to customize
serializeHandler Core.Annotations.CustomAnnotationSerializeHandler Handler that performs custom serialization
Example
Annotations.setCustomSerializeHandler(Annotations.RectangleAnnotation, function(element, pageMatrix, options) {
  const annot = options.annotation;
  options.originalSerialize(element, pageMatrix)
  if (annot.Width > 100) {
    element.setAttribute('myAttr', '1');
  }
  return element;
});

Type Definitions

AdditionalOptions

Additional data passed to a custom draw handler
Type:
  • Object
Properties:
Name Type Description
originalDraw Core.Annotations.AnnotationDrawFunction Original draw function for the annotation
annotation Core.Annotations.Annotation Annotation instance being drawn

AnnotationDrawFunction(ctx, pageMatrix [, rotation])

Annotation draw function signature.
Parameters:
Name Type Argument Description
ctx CanvasRenderingContext2D A canvas context
pageMatrix Core.Math.Matrix The transformation matrix for the page that the annotation is on
rotation number <optional>
 Certain annotations, such as sticky notes, get rotation as a third parameter. Default: undefined

AppearanceReferencesSetType

An object mapping annotation states to appearance references
Type:

BorderParameters

Type:
  • Object
Properties:
Name Type Argument Description
border Core.Annotations.BorderParameters <optional>
 The border parameters
color Core.Annotations.Color <optional>
 The color of the border
width number <optional>
 The width of the border
style string <optional>
 The style of the border
cornerRadius number | Array.<number> <optional>
 The corner radius size

CustomAnnotationDeserializeHandler(element, pageMatrix, options)

Custom deserialize callback used by setCustomDeserializeHandler. Mirrors deserialize with an additional options object.
Parameters:
Name Type Description
element Element XML element representing the annotation
pageMatrix Core.Math.Matrix Matrix used to convert PDF coordinates to viewer coordinates
options Object Additional options
Properties
Name Type Description
annotation Core.Annotations.Annotation The annotation instance being deserialized
originalDeserialize function Original deserialize implementation bound to the annotation

CustomAnnotationDrawHandler(ctx, pageMatrix, rotation, options)

Callback that gets passed to drawHandler in setCustomDrawHandler. Mirrors draw with an additional options object.
Parameters:
Name Type Description
ctx CanvasRenderingContext2D Canvas context
pageMatrix Core.Math.Matrix The transformation matrix for the page that the annotation is on
rotation number Rotation value (sticky notes may receive this). Default: undefined
options Core.Annotations.AdditionalOptions Additional options
Properties
Name Type Description
annotation Core.Annotations.Annotation Annotation instance
originalDraw Core.Annotations.AnnotationDrawFunction Original draw implementation bound to the annotation

CustomAnnotationSerializeHandler(element, pageMatrix, options)

Custom serialize callback used by setCustomSerializeHandler. The signature is similar to serialize except with an additional options parameter
Parameters:
Name Type Description
element Element XML element representing the annotation
pageMatrix Core.Math.Matrix Matrix used to convert PDF coordinates to viewer coordinates
options Object Additional options
Properties
Name Type Description
annotation Core.Annotations.Annotation The annotation instance being serialized
originalSerialize function The original serialize function of this annotation
Returns:
XML element representing the annotation after custom serialization
Type
Element

CustomControlHandleDrawHandler(ctx, annotation, selectionBox, zoom, options)

Custom control handle draw callback used by setCustomControlHandleDrawHandler. Mirrors draw with an additional options object.
Parameters:
Name Type Description
ctx CanvasRenderingContext2D Annotation canvas context
annotation Core.Annotations.Annotation Annotation being modified
selectionBox Core.Math.Rect Selection bounding box
zoom number Current zoom level
options Object Additional options
Properties
Name Type Description
controlHandle Core.Annotations.ControlHandle Control handle instance
originalDraw function Original draw implementation bound to the control handle

CustomCreateInnerElementHandler(annotationManager, options)

Custom inner element creation callback used by setCustomCreateInnerElementHandler. Mirrors createInnerElement except with an additional options parameter
Parameters:
Name Type Description
annotationManager Core.AnnotationManager Annotation manager instance
options Object Additional options
Properties
Name Type Description
annotation Core.Annotations.WidgetAnnotation Widget annotation being customized
originalCreateInnerElement function Original createInnerElement implementation bound to the annotation
Returns:
Custom inner HTML element
Type
HTMLElement

CustomCreateSignHereElementHandler(signatureTool, options)

Custom sign-here element creation callback used by setCustomCreateSignHereElementHandler. Mirrors createSignHereElement with an additional options object.
Parameters:
Name Type Description
signatureTool Core.Tools.SignatureCreateTool Signature creation tool instance
options Object Additional options
Properties
Name Type Description
annotation Core.Annotations.SignatureWidgetAnnotation Signature widget annotation being customized
originalCreateSignHereElement function Original createSignHereElement implementation bound to the annotation
Returns:
Custom sign-here element
Type
HTMLElement

CustomDrawOptions

Options controlling custom draw appearance generation
Type:
  • Object
Properties:
Name Type Argument Default Description
generateAppearance boolean <optional>
 true Whether to generate a custom appearance
canvasMultiplier number <optional>
 The quality value of the generated custom appearance. The higher the value, the more memory is required. By default, this will use the canvas multiplier value set in WebViewer

measurementCaptionOptions

Type:
  • Object
Properties:
Name Type Argument Description
isEnabled boolean The flag for enabling or disabling measurement captions on the annotation.
captionRect Core.Math.Rect <optional>
 The caption's text bounding rect. The bounding rect will be auto-adjusted to the annotation's visual center if the annotation is resized.
captionStyle Object <optional>
 The object containing caption style properties
Properties
Name Type Argument Description
color string <optional>
 The caption's text color. Default to measurement annotation's color when not set. Accepts CSS HEX or CSS RGBA values.
staticSize string <optional>
 The static size for caption text. This option is ignored when it's set to 0pt.
maximumSize string <optional>
 The maximum caption text size. This option is ignored when it's set to 0pt or when staticSize is set to positive values.