AspPDF.com -- PdfAnnot Object

PdfAnnot represents PDF annotations and form fields. This object is creatable via PdfAnnots' Add method, and also PdfPage's form-related methods such as CreateCheckbox, etc. For more information, see Section 10.3 - Annotation of User Manual.

Properties

Children

Contents

Children As PdfAnnots (Read-only)

Returns a PdfAnnots collection of annotations that are children to this annotation. This property is only relevant when this annotation represents a form field.

For more information, see Chapter 11 - Forms.

Contents As String (Read/Write)

Returns or specifies this annotation's contents string (such as text displayed in a pop-up window when a text annotation is opened).

For more information, see Section 10.3 - Annotations.

FieldActiveState As String (Read/Write)

Returns or specifies the active state of a form field represented by this annotation object. If this annotation does not represent a form field, or it represents a stateless field (such as a text field or pushbutton) this property returns an empty string. For checkbox fields, the active state values are usually "Yes" and "Off" for checked and unchecked boxes, respectively.

For more information, see Section 11.4 - Existing Form Fill-in.

FieldAlternateName As String (Read/Write)

Returns or specifies the alternate name of a form field represented by this annotation. An alternate field name is used in place of the actual field name wherever the field must be identified in the user interface.

This property can also be used to specify a "short description" value for a link annotation.

For more information, see Section 10.3 - Annotations.

FieldDefaultValue As String (Read/Write)

Returns or specifies the default value of a form field represented by this annotation object. If this annotation does not represent a form field, this property returns an empty string.

For more information, see Chapter 11 - Forms.

FieldFlags As Long (Read/Write)

Returns or changes the field flags of a form field represented by this annotation object. Field flags have the following meaning:

Bit 1: Read-only. If set, the field cannot be changed.
Bit 2: Required. If set, the field must be filled in to be able to submit the form.
Bit 3: No export. If set, the field must not be exported when the form is submitted.
Bit 13: Multiline. Specific to text fields. If set, the field may contain multiple lines of text.
Bit 14: Password. Specific to text fields. If set, this is a password field.
Bit 15: No toggle to off. Specific to radio buttons. If set, exactly one radio button can be selected in a group. If clear, clicking the selected radio button deselects it, leaving no buttons selected.
Bit 16: Radio. If set, this field is a radio button.
Bit 17: Pushbutton. If set, this field is a pushbutton.
Bit 18: Combo. Specific to choice fields. If set, the field is a combo box, otherwise it is a list box.
Bit 19: Edit. Specific to choice fields. If set, the combo box includes an editable box as well as a drop list. Otherwise, the combo only includes a drop list.
Bit 20: Sort. Specific to choice fields. If set, the field's option items should be sorted alphabetically.
Bit 21: File select. Specific to text fields. If set, this is a file selection field.
Bit 23: Do not spell-check. Specific to text and choice fields. If set, the field will not be spell-checked.
Bit 22: Multi-select. Specific to choice fields. If set, more than one of the field's option items can be selected.
Bit 24: Do not scroll. Specific to text fields. If set, the field will not scroll.

For more information, see Chapter 11 - Forms.

FieldName As String (Read/Write)

Returns or specifies the name of a form field represented by this annotation.

This property can also be used to specify the text box title for a text annotation.

For more information, see Chapter 11 - Forms.

FieldOnValue As String (Read-only)

Returns the "on" value for a form field such as a checkbox. A string returned by this property is referred to as an "export value" by Adobe Acrobat's Form Tool. This property is useful for programmatically selecting a checkbox field, as follows:

Set Field = Doc.Form.FindField("MyCheckbox")
Field.SetFieldValue Field.FieldOnValue, Font

FieldType As String (Read-only)

Returns the type of a form field represented by this annotation. Possible values are: "Tx" (text field), "Ch" (choice field), "Btn" (button) or "Sig" (signature). If this annotation does not represent a form field, this property returns an empty string.

For more information, see Chapter 11 - Forms.

FieldValue As String (Read/Write)

Returns or specifies the current value of a form field represented by this annotation. If this annotation does not represent a form field, this property returns an empty string.

For more information, see Chapter 11 - Forms.

Flags As Long (Read/Write)

Returns or changes flags that control various characteristics of this annotation. The flags have the following meaning:

Bit 1: Invisible
Bit 2: Hidden
Bit 3: Print
Bit 4: No Zoom
Bit 5: No Rotate
Bit 6: No View
Bit 7: Read-only

This property is useful for modifying the properties of existing annotations. When creating new annotations, use the appropriate parameters of the PdfAnnots.Add method instead.

Graphics( Type As Integer, Optional State ) As PdfGraphics (Read/Write)

This is a parameterized property returning or specifying a PdfGraphics object that defines this annotation's appearance. In a simple scenario, an annotation only has one ("normal") appearance. An annotation may also have two more optional appearances displayed when the mouse is clicked on, or moved over, the active area, referred to as "down" and "rollover" appearances, respectively. The Type argument specifies the type of appearance. Possible values are: 0 (normal), 1 (down) and 2 (rollover).

If the annotation represents a form field, such as a checkbox, it may be in multiple states (such as "On" and "Off" in case of a checkbox). Each state must have its own "normal" appearance, and optionally the "down" and "rollover" appearances as well. The optional State argument is a string specifying a state, if applicable. Possible values depend on the field type and may vary.

Usage:

MyAnnot.Graphics(0) = MyGraphics (VB Script)

MyAnnot.Graphics[0, Missing.Value] = MyGraphics (C#)

For more information, see Section 10.3 - Annotations.

Index As Long (Read-only)

Returns the 1-based index of this annotation object in the Page.Annots collection.

Modified As Date (Read/Write)

Returns or specifies the last-modified date of the annotation, if present. Otherwise returns 0.

Name As String (Read/Write)

Returns or specifies this annotation's Name attribute. The meaning of this attribute depends on the annotation type and may be empty. This property is always empty if the annotation represents a form field.

Parent As PdfAnnot (Read-only)

Returns this annotation's parent annotation object. This property is relevant only if this annotation represents a form field. Returns Nothing if this is not a form field, or if this a top-level form field.

For more information, see Chapter 11 - Forms.

Rect As PdfRect (Read-only)

Returns an instance of the PdfRect object containing this annotation's coordinates.

Type As String (Read-only)

Returns the annotation type, such as "Text", "Link", "FreeText", etc. If this is a form field, usually returns "Widget".

For more information, see Section 10.3 - Annotations.

Sub SetAction(Action As PdfAction)

Specifies an action to be associated with this annotation. Action is an object of the type PdfAction. This method cannot be called if SetDest has already been called on this annotation object.

For more information, see Section 10.4 - Actions.

Sub SetDest(Dest As PdfDest)

Specifies a destination to be associated with this annotation. Dest is an object of the type PdfDest. This method cannot be called if SetAction has already been called on this annotation object.

For more information, see Section 10.1 - Destinations.

Sub SetFieldImage(Image As PdfImage, Optional Param )

Fills in an image field with Image.

Param is a PdfParam object or parameter string specifying the following parameters (all optional):

Mode - Controls the image stretching mode. Possible values: 1 (default) - Scale to fit; 2 - Stretch to fit; 3 - Do not scale or fit.

ReadOnly - If set to False, leaves the field clickable. True by default, which means the field is made read-only.

Alignment - specifies vertical or horizontal alignment when Mode is set to 1 (Scale-to-fit mode). Ignored in all other cases. Possible values: 0 (default) - alignment to the left or top; 1 - alignment to the right or bottom; 2 - alignment to the center. This parameter was introduced in Version 3.1.0.2.

For more information, see Section 12.4 - Image Field Handling.

This method was introduced in Version 2.4.

Sub SetFieldValue(Text As String, Font As PdfFont)

Fills in a text form field associated with this annotation. The field must be part of a form residing in an existing PDF document.

When placing Text into a form field, this method takes into account the field's pre-defined text alignment and font size parameters. If the default font size is not specified, the method calculates it based on the field's height. It also preserves a field border if there is one.

For more information, see Chapter 12 - Existing Form Fill-in.

Sub SetFieldValueEx(Text As String)

Same as SetFieldValue, but does not require a font argument. This method internally calls SetFieldValue with a font object it automatically creates from the information embedded in the PDF form being filled in.

This method was introduced in Version 2.6.

For more information, see Chapter 12 - Existing Form Fill-in.

Sub SetRect(X As Single, Y As Single, Width As Single, Height As Single)

Specifies an active area for this annotation. (X, Y) specify the coordinates of the area's lower-left corner within a page.

PdfAnnot Object

Overview

Member List

Properties

Methods