# WidgetAnnotation ## Content # Class: WidgetAnnotation Represents a widget annotation used in interactive forms to represent the appearance of fields and to manage user interactions. ## Extends - [`AnnotationBase`](AnnotationBase) ## Constructors ### Constructor ```ts new WidgetAnnotation(om): WidgetAnnotation; ``` Creates a new WidgetAnnotation. #### Parameters ##### om [`ObjectManager`](ObjectManager) [ObjectManager](ObjectManager) that controls the lifetime of the WidgetAnnotation. #### Returns `WidgetAnnotation` #### Overrides ```ts AnnotationBase.constructor ``` ### Constructor ```ts new WidgetAnnotation(): WidgetAnnotation; ``` Creates a new WidgetAnnotation. #### Returns `WidgetAnnotation` #### Overrides ```ts AnnotationBase.constructor ``` ## Accessors ### activate #### Get Signature ```ts get activate(): ActionBase; ``` Gets or sets an action to be performed when the annotation is activated. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set activate(value): void; ``` Gets or sets an action to be performed when the annotation is activated. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### annotationPageClosed #### Get Signature ```ts get annotationPageClosed(): ActionBase; ``` Gets or sets an action to be performed when the page containing the annotation is closed (for example, when the user navigates to the next or previous page, or follows a link annotation or outline item). ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set annotationPageClosed(value): void; ``` Gets or sets an action to be performed when the page containing the annotation is closed (for example, when the user navigates to the next or previous page, or follows a link annotation or outline item). ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### annotationPageHide #### Get Signature ```ts get annotationPageHide(): ActionBase; ``` Gets or sets an action to be performed when the page containing the annotation is no longer visible in the viewer application's user interface. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set annotationPageHide(value): void; ``` Gets or sets an action to be performed when the page containing the annotation is no longer visible in the viewer application's user interface. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### annotationPageOpened #### Get Signature ```ts get annotationPageOpened(): ActionBase; ``` Gets or sets an action to be performed when the page containing the annotation is opened (for example, when the user navigates to it from the next or previous page or by means of a link annotation or outline item). ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set annotationPageOpened(value): void; ``` Gets or sets an action to be performed when the page containing the annotation is opened (for example, when the user navigates to it from the next or previous page or by means of a link annotation or outline item). ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### annotationPageShow #### Get Signature ```ts get annotationPageShow(): ActionBase; ``` Gets or sets an action to be performed when the page containing the annotation becomes visible in the viewer application's user interface. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set annotationPageShow(value): void; ``` Gets or sets an action to be performed when the page containing the annotation becomes visible in the viewer application's user interface. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### appearanceStreams #### Get Signature ```ts get appearanceStreams(): AppearanceStreams; ``` Gets the [AppearanceStreams](AppearanceStreams) object providing access to the annotation's appearance streams. ##### Returns [`AppearanceStreams`](AppearanceStreams) #### Inherited from [`AnnotationBase`](AnnotationBase).[`appearanceStreams`](AnnotationBase#appearancestreams) *** ### associatedFiles #### Get Signature ```ts get associatedFiles(): AssociatedFiles; ``` Gets the list of embedded files associated with this annotation. ##### Returns [`AssociatedFiles`](AssociatedFiles) #### Inherited from [`AnnotationBase`](AnnotationBase).[`associatedFiles`](AnnotationBase#associatedfiles) *** ### backColor #### Get Signature ```ts get backColor(): Color; ``` Gets or sets the annotation's background color. ##### Returns [`Color`](../type-aliases/Color) #### Set Signature ```ts set backColor(value): void; ``` Gets or sets the annotation's background color. ##### Parameters ###### value [`Color`](../type-aliases/Color) ##### Returns `void` *** ### border #### Get Signature ```ts get border(): Border; ``` Gets or sets the annotation border. ##### Returns [`Border`](Border) #### Set Signature ```ts set border(value): void; ``` Gets or sets the annotation border. ##### Parameters ###### value \| [`BorderProperties`](../type-aliases/BorderProperties) \| [`Border`](Border) ##### Returns `void` *** ### buttonAppearance #### Get Signature ```ts get buttonAppearance(): ButtonAppearance; ``` Gets the [ButtonAppearance](ButtonAppearance) object that specifies the look of the widget if it is linked with a push button field. ##### Returns [`ButtonAppearance`](ButtonAppearance) *** ### checkStyle #### Get Signature ```ts get checkStyle(): CheckStyle; ``` Gets or sets the style of check mark that is used if this WidgetAnnotation is linked with a [CheckBoxField](CheckBoxField) or a [RadioButtonField](RadioButtonField). Note that this property works over the 'buttonAppearance.Caption' property, for example if 'checkStyle' is "Cross", then 'buttonAppearance.Caption' will be "8". If the value of this property is null, it indicates that ButtonAppearance.Caption contains an unknown value. ##### Returns [`CheckStyle`](../enumerations/CheckStyle) #### Set Signature ```ts set checkStyle(value): void; ``` Gets or sets the style of check mark that is used if this WidgetAnnotation is linked with a [CheckBoxField](CheckBoxField) or a [RadioButtonField](RadioButtonField). Note that this property works over the 'buttonAppearance.Caption' property, for example if 'checkStyle' is "Cross", then 'buttonAppearance.Caption' will be "8". If the value of this property is null, it indicates that ButtonAppearance.Caption contains an unknown value. ##### Parameters ###### value [`CheckStyle`](../enumerations/CheckStyle) ##### Returns `void` *** ### contents #### Get Signature ```ts get contents(): string; ``` Gets or sets the text to be displayed for the annotation or, if this type of annotation does not display text, an alternate description of the annotation's contents in human-readable form. In either case, this text is useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes. ##### Returns `string` #### Set Signature ```ts set contents(value): void; ``` Gets or sets the text to be displayed for the annotation or, if this type of annotation does not display text, an alternate description of the annotation's contents in human-readable form. In either case, this text is useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes. ##### Parameters ###### value `string` ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`contents`](AnnotationBase#contents) *** ### defaultAppearance #### Get Signature ```ts get defaultAppearance(): DefaultAppearance; ``` Gets the [DefaultAppearance](DefaultAppearance) object that specifies the visual properties (font, font size etc.) used to format the content of this annotation. ##### Returns [`DefaultAppearance`](DefaultAppearance) *** ### doc #### Get Signature ```ts get doc(): PdfDocument; ``` Gets the [PdfDocument](PdfDocument) owning this annotation. ##### Returns [`PdfDocument`](PdfDocument) #### Inherited from [`AnnotationBase`](AnnotationBase).[`doc`](AnnotationBase#doc) *** ### enter #### Get Signature ```ts get enter(): ActionBase; ``` Gets or sets an action to be performed when the annotation receives the input focus. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set enter(value): void; ``` Gets or sets an action to be performed when the annotation receives the input focus. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### flags #### Get Signature ```ts get flags(): AnnotationFlags; ``` Gets or sets the flags specifying various characteristics of the annotation. ##### Returns [`AnnotationFlags`](../enumerations/AnnotationFlags) #### Set Signature ```ts set flags(value): void; ``` Gets or sets the flags specifying various characteristics of the annotation. ##### Parameters ###### value [`AnnotationFlags`](../enumerations/AnnotationFlags) ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`flags`](AnnotationBase#flags) *** ### highlighting #### Get Signature ```ts get highlighting(): HighlightingMode; ``` Gets or sets the annotation's highlighting mode. ##### Returns [`HighlightingMode`](../enumerations/HighlightingMode) #### Set Signature ```ts set highlighting(value): void; ``` Gets or sets the annotation's highlighting mode. ##### Parameters ###### value [`HighlightingMode`](../enumerations/HighlightingMode) ##### Returns `void` *** ### id #### Get Signature ```ts get id(): number; ``` Gets the reference to the object. ##### Returns `number` #### Inherited from [`AnnotationBase`](AnnotationBase).[`id`](AnnotationBase#id) *** ### justification #### Get Signature ```ts get justification(): VariableTextJustification; ``` Gets or sets the justification to be used in displaying the annotation's text. Note that if this property is not specified (the value is null) then [Field#justification](Field#justification) is used. See PDF specification for details. ##### Returns [`VariableTextJustification`](../enumerations/VariableTextJustification) #### Set Signature ```ts set justification(value): void; ``` Gets or sets the justification to be used in displaying the annotation's text. Note that if this property is not specified (the value is null) then [Field#justification](Field#justification) is used. See PDF specification for details. ##### Parameters ###### value [`VariableTextJustification`](../enumerations/VariableTextJustification) ##### Returns `void` *** ### leave #### Get Signature ```ts get leave(): ActionBase; ``` Gets or sets an action to be performed when the annotation loses the input focus. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set leave(value): void; ``` Gets or sets an action to be performed when the annotation loses the input focus. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### locked #### Get Signature ```ts get locked(): boolean; ``` Gets or sets a value indicating whether the annotation can be deleted or its properties (including position and size) can be modified by the user. However, this flag does not restrict changes to the annotation's contents, such as the value of a form field. ##### Returns `boolean` #### Set Signature ```ts set locked(value): void; ``` Gets or sets a value indicating whether the annotation can be deleted or its properties (including position and size) can be modified by the user. However, this flag does not restrict changes to the annotation's contents, such as the value of a form field. ##### Parameters ###### value `boolean` ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`locked`](AnnotationBase#locked) *** ### lockedContents #### Get Signature ```ts get lockedContents(): boolean; ``` Gets or sets a value indicating whether the contents of the annotation can be modified by the user. This flag does not restrict deletion of the annotation or changes to other annotation properties, such as position and size. ##### Returns `boolean` #### Set Signature ```ts set lockedContents(value): void; ``` Gets or sets a value indicating whether the contents of the annotation can be modified by the user. This flag does not restrict deletion of the annotation or changes to other annotation properties, such as position and size. ##### Parameters ###### value `boolean` ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`lockedContents`](AnnotationBase#lockedcontents) *** ### modifiedDate #### Get Signature ```ts get modifiedDate(): PdfDateTime; ``` Gets or sets the date and time when the annotation was modified. ##### Returns [`PdfDateTime`](../type-aliases/PdfDateTime) #### Set Signature ```ts set modifiedDate(value): void; ``` Gets or sets the date and time when the annotation was modified. ##### Parameters ###### value [`PdfDateTime`](../type-aliases/PdfDateTime) ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`modifiedDate`](AnnotationBase#modifieddate) *** ### mouseDown #### Get Signature ```ts get mouseDown(): ActionBase; ``` Gets or sets an action to be performed when the mouse button is pressed inside the field's active area. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set mouseDown(value): void; ``` Gets or sets an action to be performed when the mouse button is pressed inside the field's active area. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### mouseEnter #### Get Signature ```ts get mouseEnter(): ActionBase; ``` Gets or sets an action to be performed when the mouse enters the field's active area. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set mouseEnter(value): void; ``` Gets or sets an action to be performed when the mouse enters the field's active area. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### mouseLeave #### Get Signature ```ts get mouseLeave(): ActionBase; ``` Gets or sets an action to be performed when the cursor exits the field's active area. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set mouseLeave(value): void; ``` Gets or sets an action to be performed when the cursor exits the field's active area. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### mouseUp #### Get Signature ```ts get mouseUp(): ActionBase; ``` Gets or sets an action to be performed when the mouse button is released inside the field's active area. ##### Returns [`ActionBase`](ActionBase) #### Set Signature ```ts set mouseUp(value): void; ``` Gets or sets an action to be performed when the mouse button is released inside the field's active area. ##### Parameters ###### value \| [`ActionProperties`](../type-aliases/ActionProperties) \| [`ActionBase`](ActionBase) ##### Returns `void` *** ### name #### Get Signature ```ts get name(): string; ``` Gets or sets the name of the annotation. If WidgetAnnotation is used with [RadioButtonField](RadioButtonField) then [name](#name) is used as a value. ##### Returns `string` #### Set Signature ```ts set name(value): void; ``` Gets or sets the name of the annotation. If WidgetAnnotation is used with [RadioButtonField](RadioButtonField) then [name](#name) is used as a value. ##### Parameters ###### value `string` ##### Returns `void` #### Overrides [`AnnotationBase`](AnnotationBase).[`name`](AnnotationBase#name) *** ### om #### Get Signature ```ts get om(): ObjectManager; ``` Gets the owner [ObjectManager](ObjectManager) instance. ##### Returns [`ObjectManager`](ObjectManager) #### Inherited from [`AnnotationBase`](AnnotationBase).[`om`](AnnotationBase#om) *** ### page #### Get Signature ```ts get page(): PdfPage; ``` Gets or sets the [PdfPage](PdfPage) that contains this annotation. Note that an annotation may be referenced by several pages. In that case this property returns the first element in the [pages](AnnotationBase#pages) collection. When setting this property, the following applies: If the new value is null, this annotation is removed from all pages. Otherwise, this annotation is assigned exclusively to the specified page. ##### Returns [`PdfPage`](PdfPage) #### Set Signature ```ts set page(value): void; ``` Gets or sets the [PdfPage](PdfPage) that contains this annotation. Note that an annotation may be referenced by several pages. In that case this property returns the first element in the [pages](AnnotationBase#pages) collection. When setting this property, the following applies: If the new value is null, this annotation is removed from all pages. Otherwise, this annotation is assigned exclusively to the specified page. ##### Parameters ###### value [`PdfPage`](PdfPage) ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`page`](AnnotationBase#page) *** ### pages #### Get Signature ```ts get pages(): AnnotationPagesCollection; ``` Gets the list of pages that reference this annotation. ##### Returns [`AnnotationPagesCollection`](AnnotationPagesCollection) #### Inherited from [`AnnotationBase`](AnnotationBase).[`pages`](AnnotationBase#pages) *** ### pdfRect #### Get Signature ```ts get pdfRect(): Rect; ``` Gets or sets the rectangle that defines the location and size of the annotation on a page in PDF user space coordinates. The positive X axis extends horizontally to the right, and the positive Y axis extends vertically upward, with the origin usually in the lower left corner of the page. ##### See [rect](AnnotationBase#rect) ##### Returns [`Rect`](../type-aliases/Rect) #### Set Signature ```ts set pdfRect(value): void; ``` Gets or sets the rectangle that defines the location and size of the annotation on a page in PDF user space coordinates. The positive X axis extends horizontally to the right, and the positive Y axis extends vertically upward, with the origin usually in the lower left corner of the page. ##### See [rect](AnnotationBase#rect) ##### Parameters ###### value [`Rect`](../type-aliases/Rect) ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`pdfRect`](AnnotationBase#pdfrect) *** ### rect #### Get Signature ```ts get rect(): Rect; ``` Gets or sets the rectangle that defines the location and size of the annotation on a page. The coordinates of the rectangle are relative to the upper left corner of the page's media box, with the Y (vertical) coordinates increasing from top to bottom. Note that if the annotation is associated with more than one page, the media box of the first of those pages is used to calculate the rectangle's location. ##### Returns [`Rect`](../type-aliases/Rect) #### Set Signature ```ts set rect(value): void; ``` Gets or sets the rectangle that defines the location and size of the annotation on a page. The coordinates of the rectangle are relative to the upper left corner of the page's media box, with the Y (vertical) coordinates increasing from top to bottom. Note that if the annotation is associated with more than one page, the media box of the first of those pages is used to calculate the rectangle's location. ##### Parameters ###### value [`Rect`](../type-aliases/Rect) ##### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`rect`](AnnotationBase#rect) *** ### rotationAngle #### Get Signature ```ts get rotationAngle(): number; ``` Gets or sets the angle, in degrees, by which the widget annotation is rotated counterclockwise relative to the page. The value must be a multiple of 90. ##### Returns `number` #### Set Signature ```ts set rotationAngle(value): void; ``` Gets or sets the angle, in degrees, by which the widget annotation is rotated counterclockwise relative to the page. The value must be a multiple of 90. ##### Parameters ###### value `number` ##### Returns `void` ## Methods ### createAppearanceContentStream() ```ts createAppearanceContentStream(): FormXObject; ``` Creates an instance of [FormXObject](FormXObject) that can be used to define the annotation's appearance stream. Note that when this method is called, the annotation must already have been added to the document, otherwise an exception will be thrown. #### Returns [`FormXObject`](FormXObject) The [FormXObject](FormXObject) object. #### Inherited from [`AnnotationBase`](AnnotationBase).[`createAppearanceContentStream`](AnnotationBase#createappearancecontentstream) *** ### free() ```ts free(): void; ``` Detaches the object from the [ObjectManager](ObjectManager) and deallocates its memory, if possible. #### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`free`](AnnotationBase#free) *** ### rebind() ```ts rebind(omTo): void; ``` Rebinds the object from the current [ObjectManager](ObjectManager) to the specified one. #### Parameters ##### omTo [`ObjectManager`](ObjectManager) The new [ObjectManager](ObjectManager) for the object. #### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`rebind`](AnnotationBase#rebind) *** ### removeAppearance() ```ts removeAppearance(): void; ``` Removes all appearance streams associated with the current annotation, and disables generation of appearance steams for this annotation when the document is saved. Note that if any property affecting the annotation's appearance 'rect' is then changed, the appearance streams will be regenerated. So this method would usually be called after initializing all annotation's properties. #### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`removeAppearance`](AnnotationBase#removeappearance) *** ### resetAppearance() ```ts resetAppearance(): void; ``` Forces regeneration of the annotation's appearance streams next time the document is saved. #### Returns `void` #### Inherited from [`AnnotationBase`](AnnotationBase).[`resetAppearance`](AnnotationBase#resetappearance)