ComPDFKit Web SDK
    Preparing search index...

    Class FreeHandAnnotation

    Base class of all annotations. Property names start with a capital letter; changes are applied to the view immediately and committed to the document with AnnotationManager.updateAnnotation.

    Hierarchy (View Summary)

    Index
    • get Color(): Color

      Stroke color (alias of StrokeColor).

      Returns Color

    • set Color(color: Color): void

      Stroke color (alias of StrokeColor).

      Parameters

      Returns void

    • get Measure(): MeasureData | null

      Measurement info of a measurement annotation; null when not a measurement annotation.

      Returns MeasureData | null

    • set Measure(measure: MeasureData | null): void

      Measurement info of a measurement annotation; null when not a measurement annotation.

      Parameters

      • measure: MeasureData | null

      Returns void

    • get Precision(): number | null

      Result precision (0.01 for two decimals).

      Returns number | null

    • set Precision(precision: number | null): void

      Result precision (0.01 for two decimals).

      Parameters

      • precision: number | null

      Returns void

    • get RotationControlEnabled(): boolean

      Whether the rotation handle is shown when selected (property form of hasRotationControlEnabled / enableRotationControl / disableRotationControl).

      Returns boolean

    • set RotationControlEnabled(enabled: boolean): void

      Whether the rotation handle is shown when selected (property form of hasRotationControlEnabled / enableRotationControl / disableRotationControl).

      Parameters

      • enabled: boolean

      Returns void

    • get Scale(): ScaleRatio | null

      Scale [[page value, unit], [real value, unit]]; when set without measurement info, one is created from the annotation type.

      Returns ScaleRatio | null

    • set Scale(ratio: ScaleRatio | null): void

      Scale [[page value, unit], [real value, unit]]; when set without measurement info, one is created from the annotation type.

      Parameters

      • ratio: ScaleRatio | null

      Returns void

    • A highlighter when init.intent is InkHighlight.

      Parameters

      • Optionalinit: AnnotationInit & { intent?: string }
        • Optionalintent?: string

          Ink intent (/IT), such as 'InkHighlight'.

      Returns FreeHandAnnotation

      const { annotationManager, Annotations, Math: CoreMath } = instance.Core;
      const ink = new Annotations.FreeHandAnnotation({ PageNumber: 1 });
      ink.setPath([new CoreMath.Point(100, 100), new CoreMath.Point(150, 130), new CoreMath.Point(200, 100)], 0);
      ink.setPath([new CoreMath.Point(100, 160), new CoreMath.Point(200, 160)], 1); // a second stroke
      ink.StrokeColor = new Annotations.Color(0, 128, 0);
      ink.StrokeThickness = 3;
      await annotationManager.addAnnotation(ink); // the bounding box is computed from the strokes
    • Adds a listener (annotations are EventHandlers; form widgets fire focus / blur of WidgetAnnotation.Events).

      Parameters

      • name: string
      • fn: AnnotationListener
      • Optionaloptions: { once?: boolean }
        • Optionalonce?: boolean

          Remove the listener after it is called once.

      Returns void

    • Appends to the last path when index is omitted.

      Parameters

      • x: number
      • y: number
      • Optionalindex: number

      Returns void

    • Recomputes the result text from the current control points and scale, and records control points, scale, precision and text style in custom data (the engine does not know curve measurement, as with ellipse measurement). Called by AnnotationManager on save.

      Returns void

    • Recomputes the bounding box from the content; unchanged in the base class (geometric types compute from their points).

      Returns void

    • Removes a custom data entry; commit with updateAnnotation afterwards.

      Parameters

      • key: string

        Custom data key.

      Returns void

    • Changes this annotation from an XFDF element (or a whole XFDF containing it): the element's name is replaced with this annotation's Id and imported, updating in place.

      Parameters

      • xfdf: string

      Returns Promise<void>

    • The path of an arc length measurement (Measure.type arc) is three points: start, a point on the arc, end, drawn as the arc through them (sketch before the three points are fixed: see below).

      Parameters

      • ctx: CanvasRenderingContext2D
      • pageMatrix: Matrix

      Returns void

    • Removes all strokes.

      Returns void

    • Id of the content editing element this annotation represents; always undefined (content editing does not use annotations).

      Returns string | undefined

      Always undefined.

    • Type of the content editing element this annotation represents; always undefined (content editing does not use annotations).

      Returns string | undefined

      Always undefined.

    • Gets the text contents (/Contents) of the annotation.

      Returns string

      The contents; an empty string when none.

      const { annotationManager } = instance.Core;
      annotationManager.getAnnotationsList()
      .filter(annot => annot.getContents())
      .forEach(annot => console.log(`${annot.Author}: ${annot.getContents()}`));
    • Result text ('1.2cm', the value followed immediately by the unit); feet-inches use feet.

      Returns string

    • Control points of a curve measurement (start, two middle control points, end); null when not a curve measurement.

      Returns Core.Annotations.Point[] | null

    • Curve length (real units); undefined when the scale is invalid.

      Returns number | undefined

    • Gets a custom data value stored on the annotation.

      Parameters

      • key: string

        Custom data key.

      Returns string

      The value; an empty string when the key is missing.

      const { annotationManager } = instance.Core;
      const pending = annotationManager.getAnnotationsList()
      .filter(annot => annot.getCustomData('status') === 'pending');
    • Gets the height of the bounding box.

      Returns number

      Height in PDF points.

    • Gets the ink intent (/IT).

      Returns string | null

      The intent, such as 'InkHighlight', or null when none.

    • Which items the result text of arc measurements shows: radius, arcLength, angle; only the angle by default; undefined when not an arc measurement.

      Returns MeasurementDisplayOptions | undefined

    • Gets the point of the bounding box that stays fixed while zooming a NoZoom annotation.

      Returns { x: number; y: number }

      A copy of the point; x and y are fractions of the width and height (0 to 1), default { x: 0, y: 0 }.

      • x: number

        Horizontal position as a fraction of the width (0 to 1).

      • y: number

        Vertical position as a fraction of the height (0 to 1).

    • Gets the page the annotation is on.

      Returns number

      The page number (1-based).

    • Gets one stroke.

      Parameters

      • Optionalindex: number

        Zero-based stroke index; defaults to 0.

      Returns Core.Annotations.Point[]

      The points of the stroke; an empty array when it does not exist.

    • Gets one point of a stroke.

      Parameters

      • pathIndex: number

        Zero-based stroke index.

      • pointIndex: number

        Zero-based point index.

      Returns Core.Annotations.Point | undefined

      The point, or undefined when it does not exist.

    • Previous interactive page transition, or the page at first query if none was recorded. Plain PageNumber writes do not imply a pointer transition. Page remapping resets this baseline. Viewer state only: not part of the PDF or annotation undo properties.

      Returns number

    • Margin by which the bounding box exceeds the geometry; 0 in the base class.

      Returns number

    • Gets the rich text style of the contents.

      Returns RichTextStyle | null

      A copy of the style (character position to CSS style), or null when none.

    • State of the latest review state reply (a hidden note with State); an empty string when none.

      Returns string

    • The most specific class name (the last of types).

      Returns string

    • The unrotated box as { x, y, width, height } (getUnrotatedDimensions, a runtime method not declared in the d.ts; same as getUnrotatedBox, optionally given a rectangle in place of the annotation's own, derived by the annotation's Rotation).

      Parameters

      Returns { height: number; width: number; x: number; y: number }

      • height: number

        Height in PDF points.

      • width: number

        Width in PDF points.

      • x: number

        Left edge in PDF points.

      • y: number

        Top edge in PDF points.

    • Point-defined annotations: viewport coordinates of each point; others log a warning and return an empty array.

      Parameters

      Returns readonly Readonly<{ x: number; y: number }>[]

    • Point-defined annotations: gets one point in viewport coordinates.

      Parameters

      • index: number

        Zero-based point index.

      • viewer: DocumentViewer

        The document viewer used to convert the coordinates.

      Returns Readonly<{ x: number; y: number }> | null

      The point, or null when the annotation is not point-defined or the index is out of range.

    • Position and rotation of the bounding box in the viewport.

      Parameters

      Returns Readonly<
          {
              height: number;
              rotation: number;
              width: number;
              x: number;
              y: number;
          },
      >

    • Gets the width of the bounding box.

      Returns number

      Width in PDF points.

    • Gets the left edge of the bounding box.

      Returns number

      X in PDF points.

    • Gets the top edge of the bounding box.

      Returns number

      Y in PDF points.

    • Shows the rotation handle when selected (the AnnotationManager rotation option must be on too; only point-defined annotations can rotate, see rotatable in tools/annotation-select-tool.ts).

      Returns boolean

    • Whether this is a content editing placeholder; always false (content editing does not use annotations).

      Returns boolean

      Always false.

    • Whether this ink annotation is a curve measurement.

      Returns boolean

      True for a curve measurement.

    • Whether this annotation is a member of a group (has InReplyTo and ReplyType 'group').

      Returns boolean

      True for a group member.

    • Whether the annotation is in content editing focus mode; always false (content editing does not use annotations).

      Parameters

      • Optional_contentEditManager: unknown

        Unused.

      Returns boolean

      Always false.

    • Internal annotation (not listed or exported); there are no such annotations here.

      Returns boolean

    • Whether this annotation is a reply to another annotation (has InReplyTo and is not a group member).

      Returns boolean

      True for a reply.

    • Whether the annotation class or one of its base classes has the given name (such as 'MarkupAnnotation' or 'WidgetAnnotation').

      Parameters

      • type: string

        Class name to check.

      Returns boolean

      True when the name is in the class chain.

    • Invisible when hidden (/F Hidden) or not viewed (NoView).

      Returns boolean

    • Whether this is a form field widget; false in the base class.

      Returns boolean

      True for widget annotations.

    • Removes the last stroke.

      Returns void

    • Removes a listener; without fn, removes all listeners of this event.

      Parameters

      • name: string
      • Optionalfn: AnnotationListener

      Returns void

    • Resizes to the new rectangle (use it instead of setRect when internal properties must change too; here each class's setRect already carries points / paths along, so it is setRect).

      Parameters

      Returns void

    • Appearance resources are all ready (our appearances are in the Worker, so always true).

      Returns boolean

    • Read back: restores a curve measurement from custom data (the file holds a sampled ink; control points and scale are in custom data).

      Returns void

    • Rotates by radians around the bounding box center (or center); Rotation follows and the bounding box is recomputed from the points.

      Parameters

      • radians: number
      • Optionalcenter: { x: number; y: number }
        • x: number

          X of the rotation center in PDF points.

        • y: number

          Y of the rotation center in PDF points.

      Returns void

    • The XFDF element of this annotation (such as <square .../>); asynchronous (exported by the Worker); the annotation must be added to the document first.

      Returns Promise<string>

    • Sets the text contents (/Contents) of the annotation.

      Parameters

      • text: string

        New contents.

      Returns void

      const { annotationManager } = instance.Core;
      const annot = annotationManager.getAnnotationById('my-annotation-id');
      annot.setContents('Approved');
      await annotationManager.updateAnnotation(annot);
    • Moves one control point of a curve measurement; the curve is resampled. Does nothing when not a curve measurement or the index is out of range.

      Parameters

      • index: number

        Zero-based control point index (0 to 3).

      • x: number

        X in PDF points.

      • y: number

        Y in PDF points.

      Returns void

    • Sets the control points: the paths are resampled along the curve, and the bounding box and result text are recomputed.

      Parameters

      Returns void

    • Commit with updateAnnotation after changing.

      Parameters

      • key: string
      • value: string

      Returns void

      const { annotationManager } = instance.Core;
      const annot = annotationManager.getAnnotationById('my-annotation-id');
      annot.setCustomData('status', 'pending');
      annot.setCustomData('ticket', JSON.stringify({ id: 42 })); // values are strings
      await annotationManager.updateAnnotation(annot);
    • Sets the height of the bounding box.

      Parameters

      • height: number

        Height in PDF points.

      Returns void

    • Setting InkHighlight changes BlendMode to multiply (other intents leave BlendMode unchanged).

      Parameters

      • intent: string | null

      Returns void

    • Changes only the given keys (inapplicable ones are ignored); then updateAnnotation commits and the result text and appearance are rewritten.

      Parameters

      • options: MeasurementDisplayOptions

      Returns void

    • Marks as changed; keepDate does not update the modification date.

      Parameters

      • Optional_keepAppearance: boolean
      • Optional_keepSerialized: boolean
      • OptionalkeepDate: boolean

      Returns void

    • Sets the point of the bounding box that stays fixed while zooming a NoZoom annotation. Values outside 0 to 1 are rejected with a warning.

      Parameters

      • point: { x: number; y: number }

        x and y as fractions of the width and height (0 to 1).

        • x: number

          Horizontal position as a fraction of the width (0 to 1).

        • y: number

          Vertical position as a fraction of the height (0 to 1).

      Returns void

    • Sets the page the annotation is on.

      Parameters

      • n: number

        The page number (1-based).

      Returns void

    • Replaces one stroke. Call adjustRect afterwards to update the bounding box.

      Parameters

      • points: Core.Annotations.Point[]

        The points of the stroke in page coordinates.

      • Optionalindex: number

        Zero-based stroke index; defaults to 0.

      Returns void

    • Sets one point of a stroke (creating the stroke if needed).

      Parameters

      • pathIndex: number

        Zero-based stroke index.

      • pointIndex: number

        Zero-based point index.

      • x: number

        X in PDF points.

      • y: number

        Y in PDF points.

      Returns void

    • Record the origin before a pointer page transition; null resets the first-query baseline.

      Parameters

      • pageNumber: number | null

      Returns void

    • Replaces the rich text style of the contents and marks the annotation as modified.

      Parameters

      • style: RichTextStyle | null

        Character position to CSS style, or null to remove the rich text style.

      Returns void

    • Sets stroke / fill / opacity of ctx for subclasses' draw().

      Parameters

      • ctx: CanvasRenderingContext2D
      • _pageMatrix: Matrix

      Returns void

    • Point-defined annotations: sets all points from viewport coordinates (points are fitted into the page). Other annotations log a warning.

      Parameters

      • points: { x: number; y: number }[]

        New points in viewport coordinates.

        • x: number

          X in viewport units.

        • y: number

          Y in viewport units.

      • viewer: DocumentViewer

        The document viewer used to convert the coordinates.

      Returns void

    • Point-defined annotations: moves one point to a position in viewport coordinates. Invalid indexes and other annotations log a warning.

      Parameters

      • index: number

        Zero-based point index.

      • point: { x: number; y: number }

        New position in viewport coordinates.

        • x: number

          X in viewport units.

        • y: number

          Y in viewport units.

      • viewer: DocumentViewer

        The document viewer used to convert the coordinates.

      Returns void

    • Sets the bounding box from a viewport position, size (clamped into the page) and rotation.

      Parameters

      • props: { height: number; rotation?: number; width: number; x: number; y: number }
        • height: number

          Height in viewport units.

        • Optionalrotation?: number

          Rotation in degrees relative to the display orientation; defaults to 0.

        • width: number

          Width in viewport units.

        • x: number

          Left edge in viewport units.

        • y: number

          Top edge in viewport units.

      • viewer: DocumentViewer

      Returns void

    • Sets the width of the bounding box.

      Parameters

      • width: number

        Width in PDF points.

      Returns void

    • Sets the left edge of the bounding box.

      Parameters

      • x: number

        X in PDF points.

      Returns void

    • Sets the top edge of the bounding box.

      Parameters

      • y: number

        Y in PDF points.

      Returns void

    • Fires an event with arguments spread by position.

      Parameters

      • name: string
      • Optionalargs: unknown[]

      Returns void

    • Like trigger, awaiting the Promise returned by each listener in turn.

      Parameters

      • name: string
      • Optionalargs: unknown[]

      Returns Promise<void>

    • Applies style to the characters in [start, end) (break points are added at both ends of the range first, then segments are merged).

      Parameters

      • style: Record<string, unknown>
      • Optionalstart: number
      • Optionalend: number

      Returns void

    Author: string

    Author of the annotation (the /T entry).

    BlendMode: string | undefined

    Blend mode for drawing onto the page (canvas globalCompositeOperation name): 'multiply' multiplies with the page (text highlights, ink with intent InkHighlight); normal blending by default.

    DateCreated: Date | null

    Creation date, or null when unknown.

    DateModified: Date | null

    Last modification date, or null when unknown; updated by setModified.

    elementName: string

    XFDF element name of this annotation type (such as 'square'); 'annotation' in the base class.

    FillColor: Color | null

    Fill color; null means no fill (the engine clears the fill color on commit). A color written with opacity 0 is also treated as no fill.

    Font: string

    Result text style (changed in the style panel; an empty string / null means unchanged: the engine default Helvetica 9 black); see MeasureTextStyle in utils/measurement-caption.ts.

    FontSize: string

    Font size of the measurement result text in points, as a string; an empty string keeps the default.

    Height: number

    Height of the bounding box in PDF points.

    Hidden: boolean

    Whether the annotation is hidden (the /F Hidden flag).

    Icon: string

    Icon name (the /Name entry), used by notes, stamps and file attachments.

    Id: string

    Unique annotation name (the /NM entry); used to look the annotation up and to link replies and groups.

    InReplyTo: string

    Id of the parent annotation of a reply or group.

    Intent: { InkHighlight: "InkHighlight" }

    Values of the ink intent (see setIntent).

    Type Declaration

    • ReadonlyInkHighlight: "InkHighlight"

      Highlighter ink, drawn with multiply blending.

    Invisible: boolean

    The /F Invisible bit (1): only meaningful for unknown annotation types; use Hidden to hide annotations.

    IsAdded: boolean

    Whether the annotation was added since the last exportAnnotationCommand.

    IsClickableOutsideRect: boolean

    Whether parts drawn outside the rectangle can be clicked too (hit testing here only uses the rectangle; currently only the value is stored).

    IsDeleted: boolean

    Deleted since the last exportAnnotationCommand (set by deleteAnnotation(s), cleared when added to the document again).

    IsModified: boolean

    Changed since the last exportAnnotationCommand.

    Listable: boolean

    Whether the annotation is shown in annotation lists; defaults to true.

    Locked: boolean

    Whether the annotation cannot be deleted or have its properties changed (the /F Locked flag).

    LockedContents: boolean

    Whether the contents of the annotation cannot be changed (the /F LockedContents flag).

    MaintainAspectRatio: boolean

    Whether resizing keeps the width-to-height ratio.

    MeasurementDisplayFormats: {
        DECIMAL: "Decimal";
        FRACTION: "Fraction";
        ROUND: "Round";
        TRUNCATE: "Truncate";
    }

    Display format of measurement annotations (values of DisplayFormat).

    Type Declaration

    • ReadonlyDECIMAL: "Decimal"

      Decimal number.

    • ReadonlyFRACTION: "Fraction"

      Fraction.

    • ReadonlyROUND: "Round"

      Rounded value.

    • ReadonlyTRUNCATE: "Truncate"

      Truncated value.

    MeasurementSystems: {
        IMPERIAL: "Imperial";
        METRIC: "Metric";
        TYPOGRAPHIC: "Typographic";
    }

    Unit system of measurement annotations (values of System).

    Type Declaration

    • ReadonlyIMPERIAL: "Imperial"

      Imperial units (in, ft, yd, mi).

    • ReadonlyMETRIC: "Metric"

      Metric units (mm, cm, m, km).

    • ReadonlyTYPOGRAPHIC: "Typographic"

      Typographic points.

    MeasurementUnits: {
        CM: "cm";
        DOUBLE_PRIME_IN: "in\"";
        FT: "ft";
        FT_IN: "ft-in";
        IN: "in";
        KM: "km";
        M: "m";
        MI: "mi";
        MM: "mm";
        PRIME_FT: "ft'";
        PT: "pt";
        YD: "yd";
    }

    Display units of measurement annotations (values of DisplayUnits, Annotation.MeasurementUnits).

    Type Declaration

    • ReadonlyCM: "cm"

      Centimeters.

    • ReadonlyDOUBLE_PRIME_IN: "in\""

      Inches written with a double prime.

    • ReadonlyFT: "ft"

      Feet.

    • ReadonlyFT_IN: "ft-in"

      Feet and inches.

    • ReadonlyIN: "in"

      Inches.

    • ReadonlyKM: "km"

      Kilometers.

    • ReadonlyM: "m"

      Meters.

    • ReadonlyMI: "mi"

      Miles.

    • ReadonlyMM: "mm"

      Millimeters.

    • ReadonlyPRIME_FT: "ft'"

      Feet written with a prime.

    • ReadonlyPT: "pt"

      Points (1/72 inch).

    • ReadonlyYD: "yd"

      Yards.

    NoDelete: boolean

    Cannot be deleted: AnnotationManager deleteAnnotation(s) skips it (memory only, not written to the file).

    NoMove: boolean

    Whether the annotation cannot be moved by the user.

    NoResize: boolean

    Whether the annotation cannot be resized by the user.

    NoRotate: boolean

    Whether the annotation does not rotate with the page (the /F NoRotate flag).

    NoView: boolean

    Whether the annotation is not displayed (the /F NoView flag).

    NoZoom: boolean

    Whether the annotation keeps its size regardless of zoom (the /F NoZoom flag).

    Opacity: number

    Opacity from 0 (transparent) to 1 (opaque); defaults to 1.

    PageNumber: number

    Page the annotation is on (1-based).

    Printable: boolean

    Whether the annotation is printed (the /F Print flag); defaults to true.

    ReadOnly: boolean

    Whether the annotation cannot be interacted with (the /F ReadOnly flag).

    ReplyType: string | null

    'group' means a group; otherwise a reply.

    Rotation: number

    Rotation of the annotation in degrees, counterclockwise.

    selectionModel: typeof SelectionModel

    Selection model class (a prototype property; each class's default is set in selection/model-of.ts): when selected, new selectionModel(annotation, canModify, true, docViewer) and its draw draws the selection box. Replace it with another class on a subclass prototype or a single annotation (for example one whose draw draws nothing); hit testing and handles still follow the built-in rules.

    shouldSimplifyPath: boolean

    simplifyPaths simplifies only when true (turned on when a stylus stroke ends).

    StrokeColor: Color

    Stroke (border or line) color; defaults to black.

    StrokeThickness: number

    Stroke width in PDF points; defaults to 1.

    Subject: string

    Subject of the annotation; defaults to the subject of the annotation class.

    TextColor: Color | null

    Color of the measurement result text; null keeps the default.

    ToggleNoView: boolean

    The /F ToggleNoView bit (256).

    ToolName: string

    Name of the tool that created it (written when a tool creates it, not saved to the PDF).

    Width: number

    Width of the bounding box in PDF points.

    X: number

    Left edge of the bounding box in PDF points (page coordinates).

    Y: number

    Top edge of the bounding box in PDF points (page coordinates).