ComPDFKit Web SDK
    Preparing search index...

    Class FreeTextAnnotation

    Core.Annotations.IPathAnnotation: a retained intermediate base class whose path methods are shared by Polyline / Polygon / FreeText / Arc (setVertices / getVertices).

    Hierarchy (View Summary)

    Index
    • get CloudIntensity(): number

      Cloud intensity, integers only (truncated on set; negative and NaN become 0); see normalizeCloudIntensity.

      Returns number

    • set CloudIntensity(intensity: number): void

      Cloud intensity, integers only (truncated on set; negative and NaN become 0); see normalizeCloudIntensity.

      Parameters

      • intensity: number

      Returns void

    • get Color(): Color

      Stroke color (alias of StrokeColor).

      Returns Color

    • set Color(color: Color): void

      Stroke color (alias of StrokeColor).

      Parameters

      Returns void

    • get Dashes(): string | null

      Dash lengths (pt), comma separated, '3' by default; an array is joined into a string.

      Returns string | null

    • set Dashes(dashes: string | number[] | null): void

      Dash lengths (pt), comma separated, '3' by default; an array is joined into a string.

      Parameters

      • dashes: string | number[] | null

      Returns void

    • get Intensity(): number

      Cloud intensity (Intensity, same as CloudIntensity).

      Returns number

    • set Intensity(intensity: number): void

      Cloud intensity (Intensity, same as CloudIntensity).

      Parameters

      • intensity: number

      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

    • get Style(): string

      Border style: 'solid' (default), 'dash'; 'cloudy' when the cloud intensity is above 0 (see border-style.ts). Setting cloudy without intensity uses the default 2; setting anything else removes the cloud.

      Returns string

    • set Style(style: string): void

      Border style: 'solid' (default), 'dash'; 'cloudy' when the cloud intensity is above 0 (see border-style.ts). Setting cloudy without intensity uses the default 2; setting anything else removes the cloud.

      Parameters

      • style: string

      Returns void

    • Creates a free text annotation. With Intent 'FreeTextCallout' and no Subject, the subject defaults to the callout subject.

      Parameters

      • Optionalinit: AnnotationInit

        Initial property values.

      Returns FreeTextAnnotation

      const { annotationManager, Annotations } = instance.Core;
      const freeText = new Annotations.FreeTextAnnotation({ PageNumber: 1, X: 50, Y: 50, Width: 200, Height: 40 });
      freeText.setContents('Reviewed');
      freeText.FontSize = '16pt';
      freeText.TextColor = new Annotations.Color(0, 0, 255);
      freeText.TextAlign = 'center';
      freeText.StrokeThickness = 0; // no border
      await annotationManager.addAnnotation(freeText);
    • 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 a vertex.

      Parameters

      • x: number

        X in PDF points.

      • y: number

        Y in PDF points.

      Returns void

    • The bounding box of free text is the text box (and callout), not recomputed from 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>

    • Display uses the appearance bitmap (text layout by the engine); this draws the box and callout for previews while creating and dragging.

      Parameters

      • ctx: CanvasRenderingContext2D
      • _pageMatrix: Matrix

      Returns void

    • Resizes the text box to fit the text exactly (measuring each line's width with font and size, line height 1.2×, padding around; note: the appearance is laid out by the engine and may differ slightly).

      Returns void

    • Only recorded: the text box size is decided by the user, and the engine does not resize to the text when generating the appearance.

      Returns FreeTextAutoSize

    • The font size actually used (with unit): when auto-fitting, the largest size that fits the text box (measuring text width; 12pt without a canvas).

      Returns string

    • Gets the cloudy border intensity.

      Returns number

      The intensity; 0 means no cloudy border.

    • 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()}`));
    • 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 date format of a date text annotation, stored in the custom data key compdfkit_freetext_date.

      Returns string

      The format, such as 'MM/DD/YYYY', or an empty string when the annotation is not a date text.

    • Gets the height of the bounding box.

      Returns number

      Height in PDF points.

    • Gets the kind of free text.

      Returns FreeTextIntent

      The intent.

    • Measurement result text (such as "L = 1.00 ft"), generated by the engine; an empty string when not a measurement annotation.

      Returns string

    • 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).

    • 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.

    • Gets the line ending style at the start of the callout line.

      Returns LineEndType

      The line ending style.

    • 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 an auto size type other than 'none' is set.

      Returns boolean

      True when auto sizing is set.

    • Font size follows the text box (FontSize '0pt').

      Returns boolean

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

      Returns boolean

      Always false.

    • 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

    • Appears when printing: not hidden, printable, not a reply.

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

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

    • Records the auto size type. It is only stored: the text box size is not changed.

      Parameters

      • type: FreeTextAutoSize

        The auto size type.

      Returns void

    • Sets the cloudy border intensity and marks the annotation as modified.

      Parameters

      • intensity: number

        The intensity (integers only; 0 means no cloudy border).

      Returns void

    • 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);
    • 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 date format of a date text annotation. An empty string removes it.

      Parameters

      • format: string

        The format, such as 'MM/DD/YYYY'.

      Returns void

    • Sets the height of the bounding box.

      Parameters

      • height: number

        Height in PDF points.

      Returns void

    • Sets the kind of free text.

      Parameters

      • intent: FreeTextIntent

        The intent.

      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 padding of the text box within the annotation rectangle (/RD).

      Parameters

      • padding: Core.Annotations.Rect

        Left, top, right and bottom padding in PDF points as x1, y1, x2, y2.

      Returns void

    • Sets the page the annotation is on.

      Parameters

      • n: number

        The page number (1-based).

      Returns void

    • Moves one vertex.

      Parameters

      • index: number

        Zero-based vertex 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 the line ending style at the start of the callout line.

      Parameters

      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

    • Switches back to a fixed font size, using the currently fitted size.

      Returns void

    • Switches to an automatically fitted font size (FontSize '0pt', also in the rich text style).

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

    AutoSizeTypes: {
        AUTO: "auto";
        FIXED_HEIGHT: "fixedHeight";
        FIXED_WIDTH: "fixedWidth";
        NONE: "none";
    }

    Values of the auto size type (see setAutoSizeType).

    Type Declaration

    • ReadonlyAUTO: "auto"

      Width and height follow the text.

    • ReadonlyFIXED_HEIGHT: "fixedHeight"

      Height is fixed; width follows the text.

    • ReadonlyFIXED_WIDTH: "fixedWidth"

      Width is fixed; height follows the text.

    • ReadonlyNONE: "none"

      No auto sizing.

    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

    Font name of the text; 'Helvetica' by default.

    FontSize: string

    Font size with unit, such as '12pt' (the default); '0pt' means the size is fitted to the text box.

    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: {
        FreeText: "FreeText";
        FreeTextCallout: "FreeTextCallout";
        FreeTextTypewriter: "FreeTextTypewriter";
    }

    Values of the Intent property.

    Type Declaration

    • ReadonlyFreeText: "FreeText"

      Plain text box.

    • ReadonlyFreeTextCallout: "FreeTextCallout"

      Text box with a callout line.

    • ReadonlyFreeTextTypewriter: "FreeTextTypewriter"

      Typewriter text.

    Intent: FreeTextIntent

    Kind of free text: plain text box, callout (with a leader line) or typewriter.

    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.

    StartStyle: LineEndType

    Line ending at the callout start (/LE).

    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.

    TextAlign: "left" | "right" | "center"

    Horizontal text alignment; 'left' by default.

    TextColor: Color

    Text color; black by 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).