Annotation types

Subtypes

1.4 Table 8.141.7 Table 169

Each row lists the subtype’s main entries of its own, besides the common ones, and the table that defines them. PDF 2.0 lists the subtypes in its Table 171.

Notes and comments

Text markup

The four text markup annotations mark up the text under them and share one set of entries. QuadPoints holds 8 numbers per quadrilateral, one quadrilateral for each word or run of words: see the example. In PDF 1.4 these four were the only “markup annotations”; ISO 32000-1 widened that term to every annotation with Yes in its Markup column.

Edits and redaction

Shapes and drawing

Each of these draws a shape on the page and, like a sticky note, opens a pop-up window with its text. IC is the interior (fill) color; the line width and dash pattern come from a border style dictionary in BS.

Links and form fields

Multimedia and 3D

Printing and production

Entries in every annotation

1.4 Table 8.101.7 Table 164

Any annotation dictionary can have these, whatever its subtype. Only Subtype and Rect are required.

• PDF 1.4’s table is longer. It also lists T, Popup and CA, which ISO 32000-1 moved to the markup entries, and A, AA and BS, which it moved to the subtypes that use them: A to Link, Screen and Widget, AA to Screen and Widget.
• PDF 2.0 adds four more (ISO 32000-2 Table 166): AF for associated files, ca for the fill opacity to use when regenerating the appearance, BM for the blend mode used to paint the annotation onto the page, and Lang for its language. It also makes CA available to every annotation, not just markup annotations.

Entries in markup annotations

1.4 Table 8.101.7 Table 170

ISO 32000-1 gives these to every subtype with Yes in the Markup column. Together they turn annotations into a comment thread: who wrote each one, when, and what it replies to. In PDF 1.4, T, Popup and CA were common to all annotations and the rest didn’t exist yet.

A reply is another markup annotation whose IRT points at the original. Since PDF 1.5 a reply can also record a reviewer’s decision: a Text annotation in reply sets StateModel to Marked or Review and State to a state of that model, such as Accepted, Rejected or Completed (1.7 Table 171).

Annotation flags

1.4 Table 8.111.7 Table 165

/F is an integer whose bits each switch one behavior on. Bit 1 is the lowest; add up the values of the bits you want. /F 4 sets only Print. /F 36 (4 + 32) sets Print and NoView: the annotation prints but doesn’t show on screen. Bits not listed must be 0.

NoZoom and NoRotate keep the annotation’s upper-left corner where /Rect puts it in default user space and leave /Rect itself unchanged; the reader moves the other three corners. A Text annotation behaves as if both were always set.

Appearance streams

1.4 §8.4.41.7 §12.5.5

/AP (PDF 1.2) says exactly how to draw the annotation. Each appearance is a form XObject: a self-contained content stream using the same operators as a page. The reader takes the form’s /BBox, transforms it by the form’s /Matrix, and scales and moves the result to fill /Rect.

1.4 Table 8.131.7 Table 168

Each value is either one stream or a dictionary of streams, one per appearance state, and the annotation’s /AS names the state to draw. A check box widget, for example, has an “on” state, which should be named /Yes, and /Off. Clicking it switches /AS:

/AP << /N << /Yes 20 0 R /Off 21 0 R >>      % checked and unchecked
       /D << /Yes 22 0 R /Off 23 0 R >> >>   % the same, while pressed
/AS /Yes

• A reader that doesn’t support a subtype still draws its N appearance, if it has one.
• Since PDF 1.4 an appearance can use transparency. It is composited over the page’s content and any annotations drawn before it.
• Without /AP, each reader draws the annotation its own way from entries such as QuadPoints and C, and results vary. PDF 2.0 requires /AP on nearly every annotation (see AP above).

Example

A page with two annotations: a link to a web page, and a highlight with its appearance stream.

3 0 obj
<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792]
   /Contents 4 0 R /Resources 5 0 R
   /Annots [10 0 R 11 0 R] >>
endobj

10 0 obj   % a link to a web page
<< /Type /Annot /Subtype /Link
   /Rect [72 640 230 654]
   /Border [0 0 0]
   /A << /S /URI /URI (https://example.com/) >> >>
endobj

11 0 obj   % a highlight over one line of text
<< /Type /Annot /Subtype /Highlight
   /Rect [72 700 180 714]
   /QuadPoints [72 700  180 700  180 714  72 714]
   /C [1 1 0]
   /T (Reviewer) /Contents (Check this figure.)
   /F 4
   /AP << /N 12 0 R >> >>
endobj

12 0 obj   % its appearance: a yellow box, multiplied into the text
<< /Type /XObject /Subtype /Form /BBox [72 700 180 714]
   /Resources << /ExtGState << /GS0 << /BM /Multiply >> >> >>
   /Length 35 >>
stream
/GS0 gs 1 1 0 rg 72 700 108 14 re f
endstream
endobj

• The link has a zero-width /Border, so no box is drawn around it. Its /A is a URI action; for a jump inside the document it would use /Dest or a GoTo action. In PDF 2.0, links are one of the few annotations that may leave out /AP.
• The highlight’s /QuadPoints give the four corners of the highlighted line counterclockwise from the lower left, the order the specification describes, with the text running along the edge from the first corner to the second. Not every writer follows that order, so readers tend to accept others.
• /F 4 sets the Print flag, /C is yellow (used for the pop-up’s title bar too), and /T and /Contents are the author and the note shown in the pop-up.
• The appearance fills a yellow rectangle with the Multiply blend mode, so the black text underneath stays visible. Its /BBox equals the annotation’s /Rect, so the reader draws it without scaling.

1.4 Table 8.211.7 Table 179