# Class: Annotation

## Core.Annotations. Annotation

Represents an annotation.

#### new Annotation( [initializer])

  The base class for all annotations

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `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).

### Members

#### <static> MeasurementDisplayFormats

  An object containing the different display formats for measurement annotations.

  ##### Type:

  - string

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `DECIMAL` | string | Decimal format eg. 12.75
  `FRACTION` | string | Decimal format eg. 12 3/4
  `ROUND` | string | Decimal format eg. 12.8
  `TRUNCATE` | string | Decimal format eg. 12.7

  ##### Example

      const fractionMeasurementDisplayFormat = Annotations.Annotation.MeasurementDisplayFormats.FRACTION

#### <static> MeasurementSystems

  An object containing the different measurement systems for measurement annotations.

  ##### Type:

  - string

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `METRIC` | string | The Metric measurement system
  `IMPERIAL` | string | The Imperial measurement system
  `TYPOGRAPHIC` | string | The Typographic measurement system

  ##### Example

      const metricMeasurementSystem = Annotations.Annotation.MeasurementSystems.METRIC

#### <static> MeasurementUnits

  An object containing the different display measurement units for measurement annotations.

  ##### Type:

  - string

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `MM` | string | Millimeter measurement unit
  `CM` | string | Centimeter measurement unit
  `M` | string | Meter measurement unit
  `KM` | string | Kilometer measurement unit
  `IN` | string | Inch measurement unit
  `FT` | string | Foot measurement unit
  `YD` | string | Yard measurement unit
  `MI` | string | Mile measurement unit
  `PT` | string | Point measurement unit
  `DOUBLE_PRIME_IN` | string | Inch" measurement unit
  `PRIME_FT` | string | Foot' measurement unit

  ##### Example

      const centimeterMeasurementUnit = Annotations.Annotation.MeasurementUnits.CM

#### Author

  The author of the annotation.

  ##### Type:

  - string

#### Color

  Gets or sets the annotation's stroke color.

  ##### Type:

  - Core.Annotations.Color

#### DateModified

  Gets or sets the date that the annotation was last modified.

  ##### Type:

  - Date

#### elementName

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

  This property cannot be initialized through the initializer.

  ##### Type:

  - string

#### Height

  Gets or sets the height of the annotation.

  ##### Type:

  - number

#### Hidden

  Gets or sets whether the annotation is hidden.

  ##### Type:

  - boolean

#### Id

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

  ##### Type:

  - string

#### InReplyTo

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

  ##### Type:

  - string

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

  ##### Type:

  - boolean

#### IsAdded

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

  ##### Type:

  - boolean

#### IsClickableOutsideRect

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

  ##### Type:

  - boolean

#### IsDeleted

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

  ##### Type:

  - boolean

#### IsModified

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

  ##### Type:

  - boolean

#### Listable

  Gets or sets whether the annotation should be listed in annotation lists. If set to true the annotation also will not be selectable.

  ##### Type:

  - boolean

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

  ##### Type:

  - boolean

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

  ##### Type:

  - boolean

#### MaintainAspectRatio

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

  ##### Type:

  - boolean

#### NoDelete

  Gets or sets if this annotation can be deleted.

  ##### Type:

  - boolean

#### NoMove

  Gets or sets whether or not the annotation can be moved.

  ##### Type:

  - boolean

#### NoResize

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

  ##### Type:

  - boolean

#### NoRotate

  Gets or sets if this annotation can be rotated.

  ##### Type:

  - boolean

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

  ##### Type:

  - boolean

#### NoZoom

  Gets or sets if this annotation scales with the page.

  ##### Type:

  - boolean

#### PageNumber

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

  ##### Type:

  - number

#### Printable

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

  ##### Type:

  - boolean

#### ReadOnly

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

  ##### Type:

  - boolean

#### ReplyType

  The type of reply.

  ##### Type:

  - string

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

  ##### Type:

  - number

#### RotationControlEnabled

  Enabled or disables the annotation's rotation control.

  ##### Type:

  - boolean

#### selectionModel

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

  ##### Type:

  - Core.Annotations.SelectionModel

#### Subject

  Represents the subject of the annotation. Default is the annotation's type.

  ##### Type:

  - string

#### ToggleNoView

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

  ##### Type:

  - boolean

#### ToolName

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

  ##### Type:

  - string

#### Width

  Gets or sets the width of the annotation.

  ##### Type:

  - number

#### X

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

  ##### Type:

  - number

#### Y

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

  ##### Type:

  - number

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

#### adjustRect()

  Adjusts the annotation's bounding rectangle to take into account changes to the annotation e.g. stroke thickness, start/end points, etc

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

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

#### disableRotationControl()

  Disables the rotation control for the annotation

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

#### enableRotationControl()

  Enables the rotation control for the annotation

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

  ##### Returns:

  the text content for the annotation.
  Type
    string

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

  ##### Returns:

  value The custom data. If no data is available an empty string is returned.
  Type
    string

#### getFormFieldPlaceHolderType()

  Returns what type of form field place holder it is, if it is a form field place holder

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

  ##### Returns:

  The list of group children
  Type
    Array.<Core.Annotations.Annotation>

#### getHeight()

  Gets the height of the annotation.

  ##### Returns:

  the height of the annotation.
  Type
    number

#### getInternal()

  Returns true if annotation is part of the original document, false otherwise.

  ##### Returns:

  Whether the annotation is internal to the document or not
  Type
    boolean

#### getPageNumber()

  Gets the page number of the annotation. Note: page number starts from 1.

  ##### Returns:

  The annotation's page number
  Type
    number

#### getRect()

  Get annotation bounding rectangle

  ##### Returns:

  Type
    Core.Math.Rect

#### getRectPadding()

  Gets the padding that will be applied by default on the annotation's rectangle.

  ##### Returns:

  The amount of padding
  Type
    number

#### getReplies()

  Gets the list of replies to this annotation.

  ##### Returns:

  The list of replies
  Type
    Array.<Core.Annotations.Annotation>

#### getRichTextStyle()

  Gets the rich text style of the annotation.

  ##### Returns:

  the current rich text style
  Type
    Core.Annotations.Annotation.RichTextStyle

#### getStatus()

  Gets the status of the annotation, and returns an empty string if no status set.

  ##### Returns:

  The last status update.
  Type
    string

#### getWidth()

  Gets the width of the annotation.

  ##### Returns:

  the width of the annotation.
  Type
    number

#### getX()

  Gets the x position measured in page coordinates of an annotation.

  ##### Returns:

  the x position
  Type
    number

#### getY()

  Gets the y position measured in page coordinates.

  ##### Returns:

  Type
    number

#### hasRotationControlEnabled()

  Returns true if the rotation control is enabled for the annotation and false otherwise.

  ##### Returns:

  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

  ##### Returns:

  Type
    boolean

#### isGrouped()

  Gets whether the annotation is a child of a group

  ##### Returns:

  Returns true if the annotation is a child of a group, false otherwise.
  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.

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

  ##### Returns:

  Returns true if it does reply to another annotation, false otherwise.
  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.

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

#### removeCustomAppearance()

  Removes the custom appearance of the annotation.

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

#### resourcesLoaded()

  Resolves when all required resources have finished loading. Currently only applicable to stamp annotations that use images.

  ##### Returns:

  A promise that resolves when the resources have finished loading
  Type
    Promise.<void>

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

  ##### Returns:

  the resulting xml element representing the annotation
  Type
    Element

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

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

#### setHeight(value)

  Sets the height of the annotation.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `value` | number | the height of the annotation.

#### setModified( [shouldKeepAppearance])

  Flags the annotation as modified if it has been before the last call to exportAnnotCommand 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

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

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

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

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

#### setRotationControlEnabled(rotationControlEnabled)

  Enables or disables the rotation control for the annotation

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `rotationControlEnabled` | boolean | true if the rotation control should be enabled

  Deprecated:
    - since version 8.0 Please use enableRotationControl or disableRotationControl instead

#### setWidth(value)

  Sets the width of the annotation.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `value` | number | the width of the annotation.

#### setX(value)

  Sets the x position measured in page coordinates of an annotation.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `value` | number | the x position

#### setY(value)

  Sets the y position measured in page coordinates.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `value` | number | the y position

#### 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` | StyleObject |  | The new rich text style of the annotation ###### Properties
  Name | Type | Description
  --- | --- | ---
  `underline` | boolean | boolean value for whether string should be underlined
  `lineThrough` | boolean | boolean value for whether string should be strike through
  `fontWeight` | string | String for the font weight of the rich text (can be 'bold')
  `fontStyle` | 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

### Type Definitions

#### RichTextCSSStyle

  ##### Type:

  - Object

  ##### Properties:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `'font-style'` | 'normal' | 'italic' | <optional> |
  `'font-weight'` | 'normal' | 'bold' | <optional> |
  `'text-decoration'` | 'word' | 'line-through' | 'underline' | string | <optional> | text-decoration: 'word' is equivalent to text-decoration: 'underline'. Values of text-decorations can also be joined by a space. For example, text-decoration: 'word line-through'
  `color` | string | <optional> | color in RGB hex format

#### RichTextStyle

  an object that maps between a text style location(character index) to css styles.

  ##### Type:

  - Object.<string, Core.Annotations.Annotation.RichTextCSSStyle>

  ##### Example

      {
        0: {
          'font-weight': 'bold',
          'color': '#ff0000',
        },
        10: {
          'font-style': 'italic'
          'font-weight': 'bold',
          'color': '#0000ff',
        },
        12: {
          'text-decoration': 'underline',
        }
      }

      this object means that the first 9 characters are bold and red, the following 2 characters are italic, bold, and blue, and the rest of characters have underline.

#### Search results