Apryse WebViewer

Class: FreeTextAnnotation

Core.Annotations. FreeTextAnnotation

new FreeTextAnnotation( [intent] [, initializer])

Represents a free text annotation.
Parameters:
Name Type Argument Description
intent string <optional>
 The intended usage type of this freetext annotation. Could either be freetext or callout.
initializer object <optional>
 A map of values to auto-initialize certain properties of the annotation. You can only initialize properties defined on the annotation under the Members section (unless specified otherwise).
Properties:
Name Type Description
EXPORT_CALCULATED_FONT_SIZE boolean Whether to export calculated font size for auto-sized fonts. Default: true
Intent object An enumeration of possible intents for FreeText Annotations
Properties
Name Type Description
FreeText string Should treat as regular freetext
FreeTextCallout string Should treat as callout

Extends

Classes

RichTextEditor

Members

<static> AutoSizeTypes

An enum with possible auto-size types.
Properties:
Name Type Description
NONE string Freetext stays at fixed size
AUTO string Autosize to content
FIXED_WIDTH string Width cannot be changed
FIXED_HEIGHT string Height cannot be changed

<static> Intent

An enum with possible freetext intents.
Properties:
Name Type Description
FreeText string Treat as regular freetext
FreeTextCallout string Treat as callout

Author

The author of the annotation.
Inherited From:

autoSizeProperties

Object that contains all the flags to customize the auto-sizing behavior
Properties:
Name Type Description
shrinkWidth boolean Whether to shrink the width of the annotation if the size of its contents are smaller in width than the annotation
shrinkHeight boolean Whether to shrink the height of the annotation if the size of its contents are smaller in height than the annotation
expandWidth boolean Whether to expand the width of the annotation if the size of the contents are larger in width than the annotation
expandHeight boolean Whether to expand the height of the annotation if the size of the contents are larger in height than the annotation

Color

Gets or sets the annotation's stroke color.
Inherited From:

DateCreated

Gets or sets the date the annotation was created.
Inherited From:

DateModified

Gets or sets the date that the annotation was last modified.
Inherited From:

elementName

Gets or sets the name of the annotation element in XFDF.

This property cannot be initialized through the initializer.

Inherited From:

FillColor

Gets or sets the color of the annotation's interior.
Inherited From:

Font

The font to use for the annotation's text.

FontSize

The font size to use for the annotation's text, specified like a CSS font size.

Height

Gets or sets the height of the annotation.
Inherited From:

Hidden

Gets or sets whether the annotation is hidden.
Inherited From:

Id

A unique identifier for the annotation. Corresponds to the name attribute in XFDF.
Inherited From:

InReplyTo

The Id of the annotation that this annotation is replying to or the parent annotation it is grouped with.
Inherited From:

Intensity

Describes intensity of cloudy style effect. 0 for no effect.

Invisible

Gets or sets whether the annotation is invisible, only if it is an unknown annotation type. Generally for hiding annotations you should use "Hidden".
Inherited From:

IsAdded

Gets or sets whether the annotation has been added since the last time the AnnotCommand was retrieved.
Inherited From:

IsClickableOutsideRect

Gets or sets whether any parts of the annotation drawn outside of the rect are clickable.
Inherited From:

IsDeleted

Gets or sets whether the annotation has been deleted since the last time the AnnotCommand was retrieved.
Inherited From:

IsHoverable

Gets or sets whether the annotation is hoverable or not. If it is hoverable then the IsHovering property will be true on the annotation when it is currently being hovered.
Inherited From:

IsModified

Gets or sets whether the annotation has been modified since the last time the AnnotCommand was retrieved.
Inherited From:

Listable

Gets or sets whether the annotation should be listed in annotation lists. If set to false the annotation also will not be selectable.
Inherited From:

Locked

Gets or sets whether the annotation is locked or not. If it's locked it can't be edited or deleted, but the note can be edited.
Inherited From:

LockedContents

Gets or sets whether the annotation contents are locked or not. If the contents are locked then note can't be edited but the annotation can be edited or deleted.
Inherited From:

MaintainAspectRatio

Gets or sets if the annotation maintains aspect ratio when being resized.
Inherited From:

NoDelete

Gets or sets if this annotation can be deleted.
Inherited From:

NoMove

Gets or sets whether or not the annotation can be moved.
Inherited From:

NoResize

Gets or sets if this annotation can be resized by the user.
Inherited From:

NoRotate

Gets or sets if this annotation rotates with the page.
Inherited From:

NoView

Gets or sets whether the annotation is visible on the screen. Differs from Hidden in that it can still be printed if the print flag is set.
Inherited From:

NoZoom

Gets or sets if this annotation scales with the page.
Inherited From:

Opacity

Gets or sets the opacity of the annotation.
Inherited From:

PageNumber

Gets or sets the page number of a document that the annotation appears on.
Inherited From:

Printable

Gets or sets whether the annotation should be displayed when printing the page.
Inherited From:

ReadOnly

Gets or sets whether the annotation is readonly or not. If it's readonly it can't be edited or deleted.
Inherited From:

ReplyType

The type of reply.
Inherited From:

Rotation

Gets or sets the annotation's clockwise rotation in degrees. Valid values are 0, 90, 180 and 270. Only applies to Stamp, FreeText and Caret annotations.
Inherited From:

RotationControlEnabled

Enables or disables the annotation's rotation control.
Inherited From:

selectionModel

Gets or sets a selection model constructor for how an annotation gets selected.
Inherited From:

StrokeColor

Gets or sets the color of the annotation's stroke.
Inherited From:

StrokeThickness

Gets or sets the width of the annotation's stroke outline.
Inherited From:

Subject

Represents the subject of the annotation. Default is the annotation's type.
Inherited From:

TextAlign

The horizontal alignment of the annotation's text (left, right, center)

TextColor

The color of the text in the annotation.

TextVerticalAlign

The vertical alignment of the annotation's text (top, bottom, center) default: top

ToggleNoView

Gets or sets whether the ToggleNoView flag is set on the annotation.
Inherited From:

ToolName

The name of the tool that is used to create this annotation.
Inherited From:

ViewState

Gets or sets the viewer state (zoom, rotation, etc) that is associated with the annotation. This state can then be restored in the viewer at a later time.
Inherited From:

Width

Gets or sets the width of the annotation.
Inherited From:

X

Gets or sets the annotation's x-axis position.
Inherited From:

Y

Gets or sets the annotation's y-axis position.
Inherited From:

Methods

addCustomAppearance(doc [, options])

Adds a custom appearance to the annotation so that the annotation appears like the specified PDF page or object in the PDF page. This appearance will be used instead of the default WebViewer drawing of the annotation.
Parameters:
Name Type Argument Description
doc Core.Document the PDF document object.
options object <optional>
 An object that can contain the following optional parameters.
Properties
Name Type Argument Default Description
pageNumber string <optional>
 1 Page number of source document to use for custom appearance.
objnum string <optional>
 The object number from the appearance document.
gennum string <optional>
 The generation number from the appearance document.
transparentBackground string <optional>
 Transparent background, default is true.
Inherited From:

addPathPoint(x, y)

Adds a point to the path
Parameters:
Name Type Description
x number The x coordinate of the point
y number The y coordinate of the point
Inherited From:

adjustRect()

Recalculate the width and height of the annotation
Inherited From:

deleteCustomData(key)

Deletes custom data associated with the given key.
Parameters:
Name Type Description
key string The key for which to delete the associated data.
Inherited From:

deserialize(element, pageMatrix)

Deserializes the xml element into the annotation
Parameters:
Name Type Description
element Element an xml element representing the annotation
pageMatrix object the page matrix used to convert PDF coordinates to XOD coordinates.
Inherited From:

disableEnterKeypress()

Disables the Enter key for the instance of RichTextEditor

disableRotationControl()

Disables the rotation control for the annotation
Inherited From:

draw(ctx, pageMatrix)

Draws the annotation on the provide canvas context, relative to the page. The point (0,0) coresponds to the top left corner of the page.
Parameters:
Name Type Description
ctx CanvasRenderingContext2D The canvas context prepared to be drawn on.
pageMatrix object The page matrix for the page that the annotation is on. You can get this object by calling getPageMatrix on the document object.
Inherited From:

enableEnterKeypress()

Enables the Enter key for the instance of RichTextEditor

enableRotationControl()

Enables the rotation control for the annotation
Inherited From:

fitText(pageInfo, pageMatrix, pageRotation)

Resize the annotation's text box to fit its contents
Parameters:
Name Type Description
pageInfo Core.Document.PageInfo An object representing the page info. Contains the properties "width" and "height".
pageMatrix object The transformation matrix for the page that the annotation is on.
pageRotation number The internal degrees of rotation of the current page.
Example
const freetextAnnot = annotManager.getAnnotationsList()[0];
const doc = docViewer.getDocument();
const pageNumber = 1;
const pageInfo = doc.getPageInfo(pageNumber);
const pageMatrix = doc.getPageMatrix(pageNumber);
const pageRotation = doc.getPageRotation(pageNumber);
freetextAnnot.fitText(pageInfo, pageMatrix, pageRotation);
annotManager.drawAnnotationsFromList([freetextAnnot]);

getAssociatedNumber()

Gets the number associated with this annotation, if any.
Inherited From:
See:
Returns:
The number associated with this annotation. If no number is associated then undefined is returned.
Type
number | undefined

getAttachments()

Gets the attachments of the annotation.
Inherited From:
Returns:
Type
Array.<Core.Annotations.Annotation.AnnotationAttachment>

getAutoSizeType()

Gets the auto-sizing method if any.
Returns:
The type of autosizing method
Type
string

getCalculatedFontSize()

Gets the calculated font size when auto-sizing the text font size to fit the free text annotation's bounding box. This method retrieves the font size that has been dynamically calculated to fit the content within the bounding box of the free text annotation when Core.Annotations.FreeTextAnnotation#switchToAutoFontSize is used to enable auto-sizing of the font size. If Core.Annotations.FreeTextAnnotation#switchToAutoFontSize has not been called, it will return the current font size.
Returns:
The calculated font size of the annotation, including the unit (e.g., "16px").
Type
string
Example
WebViewer(...)
  .then(instance => {
    const { annotationManager, Annotations } = instance.Core;

    annotationManager.addEventListener('annotationSelected', (annotations, action) => {
      if(action === 'selected' && annotations[0] instanceof Annotations.FreeTextAnnotation) {
        annotations[0].switchToAutoFontSize();
      }
    });

    annotationManager.addEventListener('annotationChanged', (annotations, action) => {
      if(action === 'modify' && annotations[0] instanceof Annotations.FreeTextAnnotation) {
        console.log(annotations[0].getCalculatedFontSize())
      }
    });
  });

getCloudIntensity()

Returns the intensity of the cloudy style border effect.
Returns:
value the intensity of the cloud style effect
Type
number

getContentEditAnnotationId()

Returns the Content Annotation Id associated with a FreeText annotation that is used for inline editing, if there is one.
Inherited From:
Returns:
Type
string

getContentEditingFormat()

Returns the content editing format for the content editing placeholder. These are used to determine properties for inline editing styles.
Inherited From:
Returns:
The content editing format
Type
Core.Annotations.Annotation.ContentEditingFormat

getContentEditType()

Returns the content edit type, if there is one. Only applicable to content edit placeholder annotations.
Inherited From:
Returns:
Type
string

getContents()

Gets the text content for the annotation. Contents may be displayed in an annotation's popup or directly on the page (in the case of FreeTextAnnotation).
Inherited From:
Returns:
the text content for the annotation.
Type
string

getContentStyleProperties()

Returns the content style properties for the content editing placeholder
Inherited From:
Returns:
The content style properties
Type
Core.Annotations.Annotation.ContentStyleProperties

getCustomData(key)

Returns custom data associated with the given key.
Parameters:
Name Type Description
key string The key for which to retrieve the associated data.
Inherited From:
Returns:
value The custom data. If no data is available an empty string is returned.
Type
string

getDateFormat()

Gets the date format of the FreeText (if any)
Returns:
Returns Date format
Type
string

getEditor()

Returns:
Returns the rich text editor instance associated with the annotation
Type
Core.Annotations.FreeTextAnnotation.RichTextEditor

getFormFieldPlaceHolderType()

Returns what type of form field place holder it is, if it is a form field place holder
Inherited From:
Returns:
Form field place holder type as described by the Form Field Annotations enum
Type
string

getGroupedChildren()

Gets the list of group children to this annotation.
Inherited From:
Returns:
The list of group children
Type
Array.<Core.Annotations.Annotation>

getHeight()

Gets the height of the annotation.
Inherited From:
Returns:
the height of the annotation.
Type
number

getIntent()

Gets the intent of the FreeText annotation e.g. FreeTextCallout
Returns:
The intent of the annotation
Type
string

getNoZoomReferencePoint()

Gets the x and y zoom reference point for NoZoom annotation.
Inherited From:
Returns:
The (x, y) no zoom reference factor.
Type
Core.Math.Point

getPadding()

Get the rectangle difference of the annotation bounding rect and the text rect
Returns:
the rectangle difference
Type
Core.Math.Rect

getPageNumber()

Gets the page number of the annotation. Note: page number starts from 1.
Inherited From:
Returns:
The annotation's page number
Type
number

getPath()

Gets the path array
Inherited From:
Returns:
The array of path points
Type
Array.<Core.Math.Point>

getPathPoint(index)

Gets the point in the path at the specified index
Parameters:
Name Type Description
index number The index in the path array
Inherited From:
Returns:
The path point as an object with x and y properties
Type
object

getRect()

Get annotation bounding rectangle
Inherited From:
Returns:
Type
Core.Math.Rect

getRectPadding()

Gets the padding that will be applied by default on the annotation's rectangle.
Inherited From:
Returns:
The amount of padding
Type
number

getReplies()

Gets the list of replies to this annotation.
Inherited From:
Returns:
The list of replies
Type
Array.<Core.Annotations.Annotation>

getRichTextStyle()

Gets the rich text style of the annotation.
Inherited From:
Returns:
the current rich text style
Type
Core.Annotations.Annotation.RichTextStyle

getStartStyle()

Gets the start style of the line. Only applicable for callout annotations
Returns:
The start style
Type
string

getStatus()

Gets the status of the annotation, and returns an empty string if no status set.
Inherited From:
Returns:
The last status update.
Type
string

getWidth()

Gets the width of the annotation.
Inherited From:
Returns:
the width of the annotation.
Type
number

getX()

Gets the x position measured in page coordinates of an annotation.
Inherited From:
Returns:
the x position
Type
number

getY()

Gets the y position measured in page coordinates.
Inherited From:
Returns:
Type
number

hasRotationControlEnabled()

Returns true if the rotation control is enabled for the annotation and false otherwise.
Inherited From:
Returns:
Type
boolean

isAutoSized()

Returns:
Returns a boolean which indicates if the bounding box of the freetext will be resized automatically when its contents are being edited
Type
boolean

isAutoSizeFont()

Returns whether the current font is Automatically sized
Returns:
Type
boolean

isContentEditPlaceholder()

Returns whether the annotation is a content editing placeholder, which are annotations used as placeholders for content edit boxes when the content editing tool is active
Inherited From:
Returns:
Whether the annotation is a content edit placeholder or not
Type
boolean

isFormFieldPlaceholder()

Returns whether the annotation is a form field place holder annotation, which are annotations used as place holders for fields in the Form Field Creation mode
Inherited From:
Returns:
Type
boolean

isFullSignature()

Checks if the annotation is a full signature
Inherited From:
Returns:
Returns whether the annotation is a full signature or not
Type
boolean

isGrouped()

Gets whether the annotation is a child of a group
Inherited From:
Returns:
Returns true if the annotation is a child of a group, false otherwise.
Type
boolean

isInContentEditFocusMode(contentEditManager)

Checks if a content edit annotation is being edited and has focus.
Parameters:
Name Type Description
contentEditManager Core.ContentEditManager An instance of contentEditManager
Inherited From:
Returns:
Returns whether an annotation is on content edit focus mode or not
Type
boolean

isInitials()

Checks if the annotation is initials
Inherited From:
Returns:
Returns whether the annotation is initials or not
Type
boolean

isInternal()

Returns true if annotation is part of the original document, false otherwise.
Inherited From:
Returns:
Whether the annotation is internal to the document or not
Type
boolean

isPrintVisible()

Whether the annotation is visible on the document or not **when printed**. If Hidden or if the annotation is a reply to another annotation then it won't be visible.
Inherited From:
Returns:
Whether the annotation is visible on the document or not when printed
Type
boolean

isReply()

Gets whether the annotation is a reply to another annotation.
Inherited From:
Returns:
Returns true if it does reply to another annotation, false otherwise.
Type
boolean

isUncommittedContentEditPlaceholder()

Returns whether the annotation is an uncommitted content editing placeholder, which are annotations that will become document content but were not committed yet.
Inherited From:
Returns:
Whether the annotation is an uncommitted content edit placeholder or not
Type
boolean

isVisible()

Whether the annotation is visible on the document or not **when viewing**. If the Hidden or NoView flags are set, or if the annotation is a reply to another annotation then it won't be visible.
Inherited From:
Returns:
Whether the annotation is visible on the document or not when viewing
Type
boolean

move(rect)

Move the annotation based on a new given Core.Math.Rect. Use this method instead of setRect when internal properties (other than x, y, width and height) need to be modified on move.
Parameters:
Name Type Description
rect Core.Math.Rect the new bounding rectangle
Inherited From:

popPath()

Removes the last point from the path
Inherited From:
Returns:
The path point as an object with x and y properties
Type
object

removeCustomAppearance()

Removes the custom appearance of the annotation.
Inherited From:

resize(rect)

Resize the annotation based on a new given Core.Math.Rect. Use this method instead of setRect when internal properties (other than x, y, width and height) need to be modified on resize.
Parameters:
Name Type Description
rect Core.Math.Rect the new bounding rectangle
Inherited From:

resourcesLoaded()

Resolves when all required resources have finished loading. Currently only applicable to stamp annotations that use images.
Inherited From:
Returns:
A promise that resolves when the resources have finished loading
Type
Promise.<void>

rotate(angle, rotationPoint)

Rotate the annotation by angle and origin point to rotate around.
Parameters:
Name Type Description
angle number The angle in radians
rotationPoint Core.Math.Point The rotation point to do the rotation around. The default is the center point of the annotation
Inherited From:

serialize(element, pageMatrix)

Serialize the annotation to an xml element
Parameters:
Name Type Description
element Element an xml element representing the annotation
pageMatrix object the page matrix used to convert XOD coordinates to PDF coordinates.
Inherited From:
Returns:
the resulting xml element representing the annotation
Type
Element

setAssociatedNumber(number)

Sets the number to be associated with this annotation.
Parameters:
Name Type Description
number number The number to be associated with this annotation.
Inherited From:
See:

setAttachments(files)

Sets the attachments of the annotation.
Parameters:
Name Type Description
files Array.<(File|Core.Annotations.Annotation.AnnotationAttachment)> Array of attachments data.
Inherited From:

setAutoSizeType(type)

Sets how the freetext annotation auto-sizes to content. If you are passing 'AUTO' as the parameter, you will need to invoke the Core.Annotations.FreeTextAnnotation#fitText method afterwards.
Parameters:
Name Type Description
type string Use one of the types provided by AutoSizeTypes

setCloudIntensity(value)

Sets the intensity of cloudy style effect. 0 for no effect.
Parameters:
Name Type Description
value number the intensity value

setContents(value)

Set the text content for the annotation. Note that this will not refresh the text in the UI.
Parameters:
Name Type Description
value string the text content to be set
Inherited From:

setCustomData(key, value)

Sets the custom data associated with the specified key.
Parameters:
Name Type Description
key string The key under which to store this custom data. Data will automatically be saved in the exported XFDF and merged into the PDF when downloading.
value string The custom data to store
Inherited From:

setDateFormat(format)

Set FreeText as a date type annotation with the specified format. A viewer can use this information to allow easier updating of the text to represent a date, for example by using a date picker.
Parameters:
Name Type Description
format string Set Annotation Date format

setHeight(value)

Sets the height of the annotation.
Parameters:
Name Type Description
value number the height of the annotation.
Inherited From:

setIntent(intent)

Sets the intent of the FreeText annotation
Parameters:
Name Type Description
intent string The new intent for the annotation

setModified( [shouldKeepAppearance])

Flags the annotation as modified if it has been before the last call to exportAnnotationCommand Removes the annotation's appearance if no parameter is passed Should be called if changing a custom property on the annotation that is used for serialization Otherwise the annotation will serialize the original deserialized value
Parameters:
Name Type Argument Description
shouldKeepAppearance boolean <optional>
 If true then the annotation's appearance will be maintained
Inherited From:

setNoZoomReferencePoint(referencePoint)

Set the x and y zoom reference point for NoZoom annotation. When this value is set, the NoZoom annotation will stay relative to the given point after the page zoom changes.
Parameters:
Name Type Description
referencePoint object The proportional factor for calculating the reference point which is relative to the top left of the annotation. For example, setting this value to {x:0.5, y:1} will set the reference point to the center bottom of the annotation.
Properties
Name Type Description
x number The x value of the reference point. Needs to be a value between 0 and 1.
y number The y value of the reference point. Needs to be a value between 0 and 1.
Inherited From:

setPadding(rect)

Sets the rectangle difference of the annotation bounding rect and the text rect
Parameters:
Name Type Description
rect Core.Math.Rect The new rectangle difference

setPageNumber(value)

Sets the page number of the annotation. Note: page numbers start from 1.
Parameters:
Name Type Description
value number the page number to be set
Inherited From:

setPathPoint(index, x, y)

Sets the path point at a specific index
Parameters:
Name Type Description
index number The index in the path array to set
x number The x coordinate of the point
y number The y coordinate of the point
Inherited From:

setRect(rect)

Sets the size and location of the annotation's bounding rectangle. Use this method instead of resize when only the x, y, width and height needs to be modified. Beware: this method ignores coordinates if they are the wrong way around. (It hasn't been fixed for reasons of maintaining backward compatibility. use setRectWithNormalization instead if you want it to reverse the wrong-way-round coordinates instead of ignoring them.)
Parameters:
Name Type Description
rect Core.Math.Rect the new bounding rectangle
Inherited From:

setRectWithNormalization(rect)

Sets the size and location of the annotation's bounding rectangle. Use this method instead of resize when only the x, y, width and height needs to be modified. Use setRectWithNormalization instead of setRect if you want to reverse any wrong-way-round coordinates instead of ignoring them.
Parameters:
Name Type Description
rect Core.Math.Rect the new bounding rectangle
Inherited From:

setRichTextStyle(richTextStyle)

Sets the rich text style of the annotation. New style will replace the old one
Parameters:
Name Type Description
richTextStyle Core.Annotations.Annotation.RichTextStyle The new rich text style of the annotation
Inherited From:

setStartStyle(startStyle)

Sets the start style of the line. Only applicable for callout annotations.
Parameters:
Name Type Description
startStyle string The starting style

setStyles(ctx, pageMatrix)

Sets the annotation's styles for stroke, fill and opacity on the canvas context
Parameters:
Name Type Description
ctx CanvasRenderingContext2D A canvas context
pageMatrix object The transformation matrix for the page that the annotation is on
Inherited From:

setWidth(value)

Sets the width of the annotation.
Parameters:
Name Type Description
value number the width of the annotation.
Inherited From:

setX(value)

Sets the x position measured in page coordinates of an annotation.
Parameters:
Name Type Description
value number the x position
Inherited From:

setY(value)

Sets the y position measured in page coordinates.
Parameters:
Name Type Description
value number the y position
Inherited From:

switchToAutoFontSize()

Sets the font size of the free text annotation to automatically adjust to fit its bounding box when resized. This method is used to switch the font size behavior of the free text annotation to "auto," which means that the font size will adapt dynamically to the size of the annotation's bounding box when it is resized.
Returns:
Type
void
Example
WebViewer(...)
 .then(instance => {
   const { documentViewer, annotationManager, Annotations } = instance.Core;

   documentViewer.addEventListener('annotationsLoaded', () => {
     const annotList = annotationManager.getAnnotationsList();
     annotList.forEach(annot => {
       if (annot instanceof Annotations.FreeTextAnnotation) {
         annot.switchToAutoFontSize();
       }
     });
   });
 });

updateRichTextStyle(object [, startIndex] [, endIndex])

Update the rich text style of the annotation. Can provide a range to set the which characters the style should apply to
Parameters:
Name Type Argument Description
object Core.Annotations.Annotation.StyleObject The new rich text style of the annotation
Properties
Name Type Description
'underline' boolean boolean value for whether string should be underlined
'line-through' boolean boolean value for whether string should be strike through
'font-weight' string String for the font weight of the rich text (can be 'bold')
'font-style' string String for font style of the rich text (can be 'italic')
'color' string string for what color to set text to
startIndex number <optional>
 Starting character to apply style, if null apply to every character
endIndex number <optional>
 Last character to apply style. If null, apply till end
Inherited From: