# 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
Font
Forms
FreeHandAnnotation
FreeTextAnnotation
FreeTextSelectionModel
HTMLAnnotation
IPathAnnotation
LineAnnotation
LineControlHandle
LineSelectionModel
Link
ListWidgetAnnotation
MarkupAnnotation
Model3D
PathControlHandle
PathSelectionModel
PolygonAnnotation
PolygonControlHandle
PolygonSelectionModel
PolylineAnnotation
PopupAnnotation
RadioButtonWidgetAnnotation
RectangleAnnotation
RedactionAnnotation
RedactionSelectionModel
RotationControlHandle
RotationUtils
SelectionAlgorithm
SelectionModel
SignatureWidgetAnnotation
SoundAnnotation
StampAnnotation
StickyAnnotation
TextHighlightAnnotation
TextMarkupAnnotation
TextRedactAnnotation
TextSelectionModel
TextSquigglyAnnotation
TextStrikeoutAnnotation
TextUnderlineAnnotation
TextWidgetAnnotation
WidgetAnnotation
WidgetFlags
XFDFUtils

### Members

#### <static> LineEndType

  An enum representing different line end types that are available for line annotations

  ##### Type:

  - string

  ##### 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

### 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` | Core.Annotations.ControlHandle | The class (constructor) of the controlHandle
  `controlHandleDrawHandler` | CustomControlHandleDrawHandler | The handler will customize the appearance of the controlHandle

  ##### 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)

  Change createInnerElement to customize the HTML element.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `annotationClass` | Core.Annotations.WidgetAnnotation | The annotation being selected to change innerElement
  `createInnerElementHandler` | Core.Annotations.CustomCreateInnerElementHandler |

  ##### Example

      Annotations.setCustomCreateInnerElementHandler(Annotations.CheckButtonWidgetAnnotation, function(annotationManager, {annotation, originalCreateInnerElement}){
       const button = this;
        const el = originalCreateInnerElement();
        el.addEventListener('click', () => {
          console.log('check button clicked', annotation.fieldName);
        });
        return el;
      })

#### <static> setCustomCreateSignHereElementHandler(createSignHereElementHandler)

  Change createSignHereElement to customize the HTML element.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `createSignHereElementHandler` | Core.Annotations.CustomCreateSignHereElementHandler |

  ##### Example

      Annotations.setCustomCreateSignHereElementHandler(function(tool, {annotation, originalCreateSignHereElement}) {
        const signHereElement = originalCreateSignHereElement(tool);
        signHereElement.style.background = "red";
        return signHereElement;
      })

#### <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` | Core.Annotations.Annotation | The class (constructor) of the annotation
  `deserializeHandler` | Core.Annotations.CustomAnnotationDeserializeHandler | A handler function that will deserialize the annotation

  ##### Example

      Annotations.setCustomDeserializeHandler(Annotations.RectangleAnnotation, function(element, pageMatrix, options) {
        const annot = options.annotation;
        options.originalDeserialize(element, pageMatrix)
        if (annot.Width > 100) {
          annot.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` | Core.Annotations.Annotation |  | The class (constructor) 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` | Core.Annotations.Annotation | The class (constructor) of the annotation
  `serializeHandler` | Core.Annotations.CustomAnnotationSerializeHandler | A handler function that will serialize the annotation

  ##### 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

#### AnnotationDrawFunction(ctx, pageMatrix [, rotation])

  Annotation draw function signature.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `ctx` | CanvasRenderingContext2D |  | A canvas context
  `pageMatrix` | object |  | 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

#### CustomAnnotationDeserializeHandler(element, pageMatrix, options)

  Callback that gets passed to deserializeHandler in setCustomDeserializeHandler. The signature is similar to deserialize except with an additional options parameter.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `element` | Element | An xml element representing the annotation
  `pageMatrix` | object | The page matrix used to convert PDF coordinates to viewer coordinates
  `options` | object | Additional options and parameters ###### Properties
  Name | Type | Description
  --- | --- | ---
  `annotation` | Core.Annotations.Annotation | The annotation being deserialized
  `originalDeserialize` | function | The original deserialize function of this annotation

#### CustomAnnotationDrawHandler(ctx, pageMatrix, rotation, options)

  Callback that gets passed to drawHandler in setCustomDrawHandler. The signature is similar to draw except with an additional options parameter.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `ctx` | CanvasRenderingContext2D | A canvas context
  `pageMatrix` | object | The transformation matrix for the page that the annotation is on
  `rotation` | number | Certain annotations, such as sticky notes, get rotation as a third parameter. Default: undefined
  `options` | Core.Annotations.AdditionalOptions | Additional options and parameters ###### Properties
  Name | Type | Description
  --- | --- | ---
  `annotation` | Core.Annotations.Annotation | The annotation being drawn
  `originalDraw` | Core.Annotations.AnnotationDrawFunction | The original draw function of this annotation

#### CustomAnnotationSerializeHandler(element, pageMatrix, options)

  Callback that gets passed to serializeHandler in setCustomSerializeHandler. The signature is similar to serialize except with an additional options parameter.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `element` | Element | An xml element representing the annotation
  `pageMatrix` | object | The page matrix used to convert PDF coordinates to viewer coordinates
  `options` | object | Additional options and parameters ###### Properties
  Name | Type | Description
  --- | --- | ---
  `annotation` | Core.Annotations.Annotation | The annotation being serialized
  `originalSerialize` | function | The original serialize function of this annotation

  ##### Returns:

  The resulting xml element representing the annotation
  Type
    Element

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

  Callback that gets passed to controlHandleDrawHandler in setCustomControlHandleDrawHandler. The signature is similar to draw except with an additional options parameter.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `ctx` | CanvasRenderingContext2D | The annotation canvas context
  `annotation` | Core.Annotations.Annotation | The annotation to modify
  `selectionBox` | Core.Math.Rect | The selection rect
  `zoom` | number | The current zoom level of the document
  `options` | object | Additional options and parameters ###### Properties
  Name | Type | Description
  --- | --- | ---
  `controlHandle` | Core.Annotations.ControlHandle | The selected controlHandle instance
  `originalDraw` | function | The original draw function of the controlHandle

#### CustomCreateInnerElementHandler(annotationManager, options)

  Callback that gets passed to createInnerElementHandler in setCustomCreateInnerElementHandler. The signature is similar to createInnerElement except with an additional options parameter.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `annotationManager` | Core.AnnotationManager |
  `options` | object | Additional options and parameters ###### Properties
  Name | Type | Description
  --- | --- | ---
  `annotation` | Core.Annotations.WidgetAnnotation | The annotation being selected to change innerElement
  `originalCreateInnerElement` | function | The original createInnerElement function of this annotation

  ##### Returns:

  An HTML element
  Type
    HTMLElement

#### CustomCreateSignHereElementHandler(signatureTool, options)

  Callback that gets passed to createSignHereElementHandler in setCustomCreateSignHereElementHandler. The signature is similar to createSignHereElement except with an additional options parameter.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `signatureTool` | Core.Tools.SignatureCreateTool | The tool that create signature annotation widget
  `options` | object | Additional options and parameters ###### Properties
  Name | Type | Description
  --- | --- | ---
  `annotation` | Core.Annotations.SignatureWidgetAnnotation | The annotation being selected to create sign here element
  `originalCreateSignHereElement` | function | The original createSignHereElement function of this annotation

  ##### Returns:

  An HTML element
  Type
    HTMLElement

#### 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.color` | string | <optional> | The caption's text color. Default to measurement annotation's color when not set. Accepts CSS HEX or CSS RGBA values.
  `captionStyle.staticSize` | string | <optional> | The static size for caption text. This option is ignored when it's set to 0pt.
  `captionStyle.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.

#### Search results