- Text Annotations
A text annotation represents a "sticky note" attached to a point
in the PDF document. When closed, the annotation appears as an icon,
when closed it displays a pop-up window containing the text of the note.
The Name argument of the PdfAnnots.Add method
controls the type of an icon used in displaying the annotation
and can be set to the following values: "Note" (default),
"Comment", "Key", "Help", "NewParagraph",
"Paragraph", "Insert".
See Section 10.3.1 for a code sample.
- Link Annotations
A link annotation represents either a hypertext link
or a destination elsewhere in the document. A link annotation
has to be assigned an action or destination.
The Type parameter must be set to link (1).
This type of annotation accepts an additional parameter,
HighlightMode, which specifies the visual effects
to be used when the button is pressed or held down inside its active area.
The possible values are 0, 1 (default), 2, 3 meaning
none, invert, outline or push, respectively.
The following code fragment displays a hyperlink. Actions are described below.
page.Canvas.DrawText "www.persits.com", "x=1;y=712;color=blue", Doc.fonts("Courier")
Set annot = page.Annots.Add("", "Type=Link; x=1,y=700,width=100,height=10; Border=0")
annot.SetAction Doc.CreateAction("type=URI", "http://www.persits.com")
- Free Text Annotations
A free text annotation displays text directly on the page. Unlike an ordinary
text annotation, a free text annotation has no open or closed state. Its text is
always visible.
The Type parameter must be set to freetext (2).
This type of annotation accepts an additional parameter,
Alignment, which controls text alignment.
Possible values are
left (0, default), right (1) and center (2).
- Line Annotations
A line annotation displays a single straight line on the page.
When opened, it displays a pop-up window containing the text of the associated note.
The Type parameter must be set to line (3).
This type of annotation accepts additional parameters:
X1, Y1, X2, Y2 (required) - the line's starting and ending coordinates in the default user space.
InnerColor (optional) - the line color.
Beginning, Ending (optional) - controls the line's ending style.
Values are 0 (none, default) 1 (square), 2 (circle) 3 (diamond), 4 (open arrow), 5 (closed arrow).
LineWidth (optional) - the line width (1 by default).
LineStyle (optional) - the line style.
Values are 0 (solid) and (1-dashed). If LineStyle is set to 1, also
accepts Dash1 and Dash2 parameters to define the dash pattern.
- Square and Circle Annotations
Square and circle annotations display a rectangle or circle
on the page, respectively. The rectangle or circle is inscribed
within the annotation's rectangle defined by the x, y, width and height parameters.
The Type parameter must be set to square (4)
or circle (5). Additional parameters are
InnerColor, LineWidth, LineStyle, Dash1,
and Dash2 (see Line Annotations for descriptions).
- Highlight, Underline, Strikeout and Squiggly Annotations
These are also referred to as Markup annotations. Markup annotations
appear as highlights, underlines, strikeouts, or jagged (squiggly)
underlines in the text of a document. When opened, they display
a pop-up window containing the text of the associated note.
The Type parameter must be set to
highlight (6), underline (7),
strikeout (8), or squiggly (9).
Additional parameters are X1, Y1,
X2, Y2, X3, Y3,
X4, Y4 specifying the coordinates
of a quadrilateral encompassing a word or group
of contiguous words in the text underlying the annotation.
- Rubber Stamp Annotations
A rubber stamp annotation displays text or graphics intended
to look as if they were stamped on the page with a rubber stamp.
When opened, they display
a pop-up window containing the text of the associated note.
The Type parameter must be set to stamp (10).
The Name argument of the PdfAnnots.Add method
specifies an icon type to be used in displaying the annotation.
The possible values are: "Approved",
"Asis", "Confidential", "Departmental",
"Draft" (default), "Experimental", "Expired",
"Final", "ForComment", "ForPiblicRelease",
"NotApproved", "NotForPublicRelease",
"Sold" and "TopSecret".
- FileAttachment Annotations
A file attachment annotation contains a reference to a file
embedded in the PDF document. For example,
a table of data might use a file attachment annotation
to link to a spreadsheet file based on that data. Activating
the annotation will extract the embedded file
and give the user an opportunity to
view it or save it on disk.
The Type parameter must be set to fileattachment (11).
The Name argument of the PdfAnnots.Add method
specifies an icon type to be used to display the annotation. Possible values are
"Graph", "Paperclip", "PushPin" (default) and "Tag".
The Path argument of the PdfAnnots.Add method
specifies a file to be associated with the annotation.
The following code fragment creates a file attachment annotation:
Set annot = page.Annots.Add("", "x=1,y=700;width=10;height=10;Type=FileAttachment;", "Paperclip", "c:\file.txt")
It is recommended that Acrobat Reader 6.0 and higher be used
to view file attachment annotations.
As of Version 3.7, two more parameters have been added to the Add method for PDF/A-3 compliance. These parameters are:
- Names (Boolean). If set to True, the new FileAttachment annotation is added to the document catalog's Names array instead of the Annots array,
where it would normally reside. This is a PDF/A-3 requirement.
- AF (Integer) - stands for "associated files relationship". This parameter is responsible for adding the
AFRelationship entry to the file annotation object, which is yet another PDF/A-3 requirement.
The AF value can be one of the following: 0 (Source), 1 (Data), 2 (Alternative), 3 (Supplement), 4 (Unspecified), 5 (EncryptedPayload) and 6 (None).
For more information on the Names and AF parameters, see Section 12.4.4 - PDF/A-3 Compliance.
- Screen Annotations
Screen annotations (introduced in Version 3.4.0.4) are useful for embedding video clips in a PDF page.
A screen annotation is created similarly to a file attachment annotation described above, by passing the path to
the video file as the 4th argument to the PdfAnnots.Add method.
The Type parameter must be set to screen (15).
The Contents argument of the PdfAnnots.Add method becomes the name of the movie being embedded.
The Name argument of the PdfAnnots.Add method becomes the name of the rendering object (per PDF specifications)
and its value is arbitrary.
The Path argument of the PdfAnnots.Add method
must point to the video file being embedded.
The screen annotation currently recognizes one additional parameter that is specific to this annotation: AutoPlay. If
this parameter is set to True, the video starts playing automatically when it becomes visible in the PDF viewer.
The following code fragment creates a screen annotation:
Set annot = page.Annots.Add("My little movie", "x=10, y=300; width=450; height=300; Type=screen; AutoPlay=true", "Movie", "c:\movie.avi")
- Rich Media Annotations
Rich Media annotations (introduced in Version 3.6) embed 3D objects, Flash, video and audio files in a PDF document.
These annotations are similar to file attachment annotations described above, but support additional parameters pertaining to various aspects of rich media appearance.
Rich media annotations are documented in Adobe Supplement to the ISO 32000 available online.
- The Type parameter must be set to richmedia (16). The required Subtype parameter
must be set to 0 (3D), 1 (Flash), 2 (Sound), or 3 (Video).
- The Contents argument of the PdfAnnots.Add method becomes the name of the rich media file being embedded.
- The Name argument of the PdfAnnots.Add method is optional, it can be left empty or specify formatted name/value pairs passed to the Flash player when activated.
These pairs are referred to as FlashVars in the Adobe documentation.
Here is an example of a FlashVars value: source=videotest.mp4&skin=SkinOverAllNoFullNoCaption.swf&skinAutoHide=true&skinBackgroundColor=0x5F5F5F&skinBackgroundAlpha=0.75&volume=1.00
- The Path argument of the PdfAnnots.Add method must point to the rich media file being embedded.
The following optional parameters are supported:
- Activation - 0 (explicitly activated by user action, default), 1 (annotation is activated when the page receives focus), 2 (annotation is activated when the page becomes visible).
- Deactivation - 0 (explicitly deactivated by user action, default), 1 (annotation is deactivated when the page loses focus), 2 (annotation is deactivated when the page is no longer visible).
- Binding - 0 (None, default), 1 (Foreground), 2 (Background).
- NavigationPane - If set to True, the navigation pane is visible when the content is initially activated. If set to False or omitted, the navigation pane
is not displayed by default.
- PassContextClick - If set to False or omitted, the conforming reader handles the context click. If set to True, the conforming reader's context menu is not visible
and the user sees the context menu and any custom items generated by the media player run-time.
- Toolbar - If set to True, a toolbar is displayed when the annotation is activated and given focus. If set to False or omitted, a toolbar is not displayed.
- Transparent - If set to True, the rich media artwork is composited over the page content using an alpha channel. If set to False or omitted, the artwork
is drawn over an opaque background prior to composition over the page content.
The following code fragment creates a rich media annotation of the subtype Video (3):
Set annot = page.Annots.Add("Cute Kittens", "x=10, y=300; width=360; height=240; Type=RichMedia; SubType=3; Activation=1", "", "c:\path\kittens.mp4")
- Other types of PDF annotations are currently not supported.