Repository navigation
PDF Spec 12 Annotations
Part of: PDF-Spec-12-Interactive-Features
Navigation: PDF-Spec-12-Page-Navigation | PDF-Spec-Index | PDF-Spec-12-Actions
An annotation associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user by means of the mouse and keyboard. PDF includes a wide variety of standard annotation types, described in detail in 12.5.6, 'Annotation Types.'
Many of the standard annotation types may be displayed in either the open or the closed state. When closed, they appear on the page in some distinctive form, such as an icon, a box, or a rubber stamp, depending on the specific annotation type. When the user activates the annotation by clicking it, it exhibits its associated object, such as by opening a pop-up window displaying a text note (Figure 57) or by playing a sound or a movie.
Figure 57 - Open annotation
Conforming readers may permit the user to navigate through the annotations on a page by using the keyboard (in particular, the tab key). Beginning with PDF 1.5, PDF producers may make the navigation order explicit with the optional Tabs entry in a page object (see Table 30). The following are the possible values for this entry:
- R (row order): Annotations shall be visited in rows running horizontally across the page. The direction within a row shall be determined by the Direction entry in the viewer preferences dictionary (see 12.2, 'Viewer Preferences'). The first annotation that shall be visited is the first annotation in the topmost row. When the end of a row is encountered, the first annotation in the next row shall be visited.
- C (column order): Annotations shall be visited in columns running vertically up and down the page. Columns shall be ordered by the Direction entry in the viewer preferences dictionary (see 12.2, 'Viewer Preferences'). The first annotation that shall be visited is the one at the top of the first column. When the end of a column is encountered, the first annotation in the next column shall be visited.
- S (structure order): Annotations shall be visited in the order in which they appear in the structure tree (see 14.7, 'Logical Structure'). The order for annotations that are not included in the structure tree shall be determined in a manner of the conforming reader's choosing.
These descriptions assume the page is being viewed in the orientation specified by the Rotate entry.
Conceptually, the behaviour of each annotation type may be implemented by a software module called an annotation handler . A conforming reader shall provide annotation handlers for all of the conforming annotation types. The set of annotation types is extensible. A conforming reader shall provide certain expected behaviour for all annotation types that it does not recognize, as documented in 12.5.2, 'Annotation Dictionaries.'
The optional Annots entry in a page object (see 7.7.3, 'Page Tree') holds an array of annotation dictionaries , each representing an annotation associated with the given page. Table 164 shows the required and optional entries that are common to all annotation dictionaries. The dictionary may contain additional entries specific to a particular annotation type; see the descriptions of individual annotation types in 12.5.6, 'Annotation Types,' for details. A given annotation dictionary shall be referenced from the Annots array of only one page. This requirement applies only to the annotation dictionary itself, not to subsidiary objects, which may be shared among multiple annotations.
Table 164 - Entries common to all annotation dictionaries
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be Annot for an annotation dictionary. |
| Subtype | name | (Required) The type of annotation that this dictionary describes; see Table 169 for specific values. |
| Rect | rectangle | (Required) The annotation rectangle , defining the location of the annotation on the page in default user space units. |
| Contents | text string | (Optional) Text that shall 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 (see 14.9.3, 'Alternate Descriptions'). See 12.5.6, 'Annotation Types' for more details on the meaning of this entry for each annotation type. |
| P | dictionary | (Optional except as noted below; PDF 1.3; not used in FDF files) An indirect reference to the page object with which this annotation is associated. This entry shall be present in screen annotations associated with rendition actions ( PDF 1.5 ; see 12.5.6.18, 'Screen Annotations' and 12.6.4.13, 'Rendition Actions'). |
| NM | text string | (Optional; PDF 1.4) The annotation name , a text string uniquely identifying it among all the annotations on its page. |
| M | date or text string | (Optional; PDF 1.1) The date and time when the annotation was most recently modified. The format should be a date string as described in 7.9.4, 'Dates,' but conforming readers shall accept and display a string in any format. |
| F | integer | (Optional; PDF 1.1) A set of flags specifying various characteristics of the annotation (see 12.5.3, 'Annotation Flags'). Default value: 0. |
| AP | dictionary | (Optional; PDF 1.2) An appearance dictionary specifying how the annotation shall be presented visually on the page (see 12.5.5, 'Appearance Streams'). Individual annotation handlers may ignore this entry and provide their own appearances. |
| AS | name | (Required if the appearance dictionary AP contains one or more subdictionaries; PDF 1.2) The annotation's appearance state , which selects the applicable appearance stream from an appearance subdictionary (see Section 12.5.5, 'Appearance Streams'). |
Table 164 - Entries common to all annotation dictionaries (continued)
| Key | Type | Value |
|---|---|---|
| Border | array | (Optional) An array specifying the characteristics of the annotation's border, which shall be drawn as a rounded rectangle. (PDF 1.0) The array consists of three numbers defining the horizontal corner radius, vertical corner radius, and border width, all in default user space units. If the corner radii are 0, the border has square (not rounded) corners; if the border width is 0, no border is drawn. (PDF 1.1) The array may have a fourth element, an optional dash array defining a pattern of dashes and gaps that shall be used in drawing the border. The dash array shall be specified in the same format as in the line dash pattern parameter of the graphics state (see 8.4.3.6, 'Line Dash Pattern'). EXAMPLE A Border value of [0 0 1 [3 2]] specifies a border 1 unit wide, with square corners, drawn with 3-unit dashes alternating with 2-unit gaps. NOTE (PDF 1.2) The dictionaries for some annotation types (such as free text and polygon annotations) can include the BS entry. That entry specifies a border style dictionary that has more settings than the array specified for the Border entry. If an annotation dictionary includes the BS entry, then the Border entry is ignored. Default value: [0 0 1]. |
| C | array | (Optional; PDF 1.1) An array of numbers in the range 0.0 to 1.0, representing a colour used for the following purposes: The background of the annotation's icon when closed The title bar of the annotation's pop-up window The border of a link annotation The number of array elements determines the colour space in which the colour shall be defined: 0 No colour; transparent 1 DeviceGray 3 DeviceRGB 4 DeviceCMYK |
| StructParent | integer | (Required if the annotation is a structural content item; PDF 1.3) The integer key of the annotation's entry in the structural parent tree (see 14.7.4.4, 'Finding Structure Elements from Content Items'). |
| OC | dictionary | (Optional; PDF 1.5) An optional content group or optional content membership dictionary (see 8.11, 'Optional Content') specifying the optional content properties for the annotation. Before the annotation is drawn, its visibility shall be determined based on this entry as well as the annotation flags specified in the F entry (see 12.5.3, 'Annotation Flags'). If it is determined to be invisible, the annotation shall be skipped, as if it were not in the document. |
The value of the annotation dictionary's F entry is an integer interpreted as one-bit flags specifying various characteristics of the annotation. Bit positions within the flag word shall be numbered from low-order to highorder, with the lowest-order bit numbered 1. Table 165 shows the meanings of the flags; all other bits of the integer shall be set to 0.
Table 165 - Annotation flags
| Bit position | Name | Meaning |
|---|---|---|
| 1 | Invisible | If set, do not display the annotation if it does not belong to one of the standard annotation types and no annotation handler is available. If clear, display such an unknown annotation using an appearance stream specified by its appearance dictionary, if any (see 12.5.5, 'Appearance Streams'). |
| 2 | Hidden | (PDF 1.2) If set, do not display or print the annotation or allow it to interact with the user, regardless of its annotation type or whether an annotation handler is available. NOTE 1 In cases where screen space is limited, the ability to hide and show annotations selectively can be used in combination with appearance streams (see 12.5.5, 'Appearance Streams') to display auxiliary pop-up |
| 3 | (PDF 1.2) If set, print the annotation when the page is printed. If clear, never print the annotation, regardless of whether it is displayed on the screen. NOTE 2 This can be useful for annotations representing interactive pushbuttons, which would serve no meaningful purpose on the printed page. | |
| 4 | NoZoom | (PDF 1.3) If set, do not scale the annotation's appearance to match the magnification of the page. The location of the annotation on the page (defined by the upper-left corner of its annotation rectangle) shall remain fixed, regardless of the page magnification. See further discussion following this Table. |
| 5 | NoRotate | (PDF 1.3) If set, do not rotate the annotation's appearance to match the rotation of the page. The upper-left corner of the annotation rectangle shall remain in a fixed location on the page, regardless of the page rotation. See further discussion following this Table. |
| 6 | NoView | (PDF 1.3) If set, do not display the annotation on the screen or allow it to interact with the user. The annotation may be printed (depending on the setting of the Print flag) but should be considered hidden for purposes of on-screen display and user interaction. |
| 7 | ReadOnly | (PDF 1.3) If set, do not allow the annotation to interact with the user. The annotation may be displayed or printed (depending on the settings of the NoView and Print flags) but should not respond to mouse clicks or change its appearance in response to mouse motions. This flag shall be ignored for widget annotations; its function is subsumed by the ReadOnly flag of the associated form field (see Table 221). |
| 8 | Locked | (PDF 1.4) If set, do not allow the annotation to be deleted or its properties (including position and size) to 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. |
| 9 | ToggleNoView | (PDF 1.5) If set, invert the interpretation of the NoView flag for certain events. NOTE 3 A typical use is to have an annotation that appears only when a mouse cursor is held over it. |
| 10 | LockedContents | (PDF 1.7) If set, do not allow the contents of the annotation to 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. |
If the NoZoom flag is set, the annotation shall always maintain the same fixed size on the screen and shall be unaffected by the magnification level at which the page itself is displayed. Similarly, if the NoRotate flag is set, the annotation shall retain its original orientation on the screen when the page is rotated (by changing the Rotate entry in the page object; see 7.7.3, 'Page Tree').
In either case, the annotation's position shall be determined by the coordinates of the upper-left corner of its annotation rectangle, as defined by the Rect entry in the annotation dictionary and interpreted in the default user space of the page. When the default user space is scaled or rotated, the positions of the other three corners of the annotation rectangle are different in the altered user space than they were in the original user space. The conforming reader shall perform this alteration automatically. However, it shall not actually change the annotation's Rect entry, which continues to describe the annotation's relationship with the unscaled, unrotated user space.
NOTE Figure 58 shows how an annotation whose NoRotate flag is set remains upright when the page it is on is rotated 90 degrees clockwise. The upper-left corner of the annotation remains at the same point in default user space; the annotation pivots around that point.
Figure 58 - Coordinate adjustment with the NoRotate flag
An annotation may optionally be surrounded by a border when displayed or printed. If present, the border shall be drawn completely inside the annotation rectangle. In PDF 1.1, the characteristics of the border shall be specified by the Border entry in the annotation dictionary (see Table 164). Beginning with PDF 1.2, the border characteristics for some types of annotations may instead be specified in a border style dictionary designated by the annotation's BS entry. Such dictionaries may also be used to specify the width and dash pattern for the lines drawn by line, square, circle, and ink annotations. Table 166 summarizes the contents of the border style dictionary. If neither the Border nor the BS entry is present, the border shall be drawn as a solid line with a width of 1 point.
Table 166 - Entries in a border style dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be Border for a border style dictionary. |
| W | number | (Optional) The border width in points. If this value is 0, no border shall drawn. Default value: 1. |
Table 166 - Entries in a border style dictionary (continued)
| Key | Type | Value |
|---|---|---|
| S | name | (Optional) The border style: S (Solid) A solid rectangle surrounding the annotation. D (Dashed) A dashed rectangle surrounding the annotation. The dash pattern may be specified by the D entry. B (Beveled) A simulated embossed rectangle that appears to be raised above the surface of the page. I (Inset) A simulated engraved rectangle that appears to be recessed below the surface of the page. U (Underline) A single line along the bottom of the annotation rectangle. A conforming reader shall tolerate other border styles that it does not recognize and shall use the default value. |
| D | array | (Optional) A dash array defining a pattern of dashes and gaps that shall be used in drawing a dashed border (border style D in the S entry). The dash array shall be specified in the same format as in the line dash pattern parameter of the graphics state (see 8.4.3.6, 'Line Dash Pattern'). The dash phase is not specified and shall be assumed to be 0. EXAMPLE A D entry of [3 2] specifies a border drawn with 3-point dashes alternating with 2-point gaps. Default value: [3]. |
Beginning with PDF 1.5, some annotations (square, circle, and polygon) may have a BE entry, which is a border effect dictionary that specifies an effect that shall be applied to the border of the annotations. Beginning with PDF 1.6, the free text annotation may also have a BE entry. Table 167 describes the entries in a border effect dictionary.
Table 167 - Entries in a border effect dictionary
| Key | Type | Value |
|---|---|---|
| S | name | (Optional) A name representing the border effect to apply. Possible values are: S No effect: the border shall be as described by the annotation dictionary's BS entry. C The border should appear 'cloudy'. The width and dash array specified by BS shall be honored. Default value: S. |
| I | number | (Optional; valid only if the value of S is C) A number describing the intensity of the effect, in the range 0 to 2. Default value: 0. |
Beginning with PDF 1.2, an annotation may specify one or more appearance streams as an alternative to the simple border and colour characteristics available in earlier versions. Appearance streams enable the annotation to be presented visually in different ways to reflect its interactions with the user. Each appearance stream is a form XObject (see 8.10, 'Form XObjects'): a self-contained content stream that shall be rendered inside the annotation rectangle.
The algorithm outlined in this sub-clause shall be used to map from the coordinate system of the appearance XObject (as defined by its Matrix entry; see Table 97) to the annotation's rectangle in default user space:
- a) The appearance's bounding box (specified by its BBox entry) shall be transformed, using Matrix , to produce a quadrilateral with arbitrary orientation. The transformed appearance box is the smallest upright rectangle that encompasses this quadrilateral.
- b) A matrix A shall be computed that scales and translates the transformed appearance box to align with the edges of the annotation's rectangle (specified by the Rect entry). A maps the lower-left corner (the corner with the smallest x and y coordinates) and the upper-right corner (the corner with the greatest x and y coordinates) of the transformed appearance box to the corresponding corners of the annotation's rectangle.
- c) Matrix shall be concatenated with A to form a matrix AA that maps from the appearance's coordinate system to the annotation's rectangle in default user space:
The annotation may be further scaled and rotated if either the NoZoom or NoRotate flag is set (see 12.5.3, 'Annotation Flags'). Any transformation applied to the annotation as a whole shall also applied to the appearance within it.
Starting with PDF 1.4, an annotation appearance may include transparency. If the appearance's stream dictionary does not contain a Group entry, it shall be treated as a non-isolated, non-knockout transparency group. Otherwise, the isolated and knockout values specified in the group dictionary (see 11.6.6, 'Transparency Group XObjects') shall be used.
The transparency group shall be composited with a backdrop consisting of the page content along with any previously painted annotations, using a blend mode of Normal , an alpha constant of 1.0, and a soft mask of None .
- NOTE 1 If a transparent annotation appearance is painted over an annotation that is drawn without using an appearance stream, the effect is implementation-dependent. This is because such annotations are sometimes drawn by means that do not conform to the PDF imaging model. Also, the effect of highlighting a transparent annotation appearance is implementation-dependent.
An annotation may define as many as three separate appearances:
- The normal appearance shall be used when the annotation is not interacting with the user. This appearance is also used for printing the annotation.
- The rollover appearance shall be used when the user moves the cursor into the annotation's active area without pressing the mouse button.
- The down appearance shall be used when the mouse button is pressed or held down within the annotation's active area.
- NOTE 2 As used here, the term mouse denotes a generic pointing device that controls the location of a cursor on the screen and has at least one button that can be pressed, held down, and released. See 12.6.3, 'Trigger Events,' for further discussion.
The normal, rollover, and down appearances shall be defined in an appearance dictionary , which in turn is the value of the AP entry in the annotation dictionary (see Table 164). Table 168 shows the contents of the appearance dictionary.
Table 168 - Entries in an appearance dictionary
| Key | Type | Value |
|---|---|---|
| N | stream or dictionary | (Required) The annotation's normal appearance. |
| R | stream or dictionary | (Optional) The annotation's rollover appearance. Default value: the value of the N entry. |
| D | stream or dictionary | (Optional) The annotation's down appearance. Default value: the value of the N entry. |
Each entry in the appearance dictionary may contain either a single appearance stream or an appearance subdictionary . In the latter case, the subdictionary shall define multiple appearance streams corresponding to different appearance states of the annotation.
EXAMPLE An annotation representing an interactive check box may have two appearance states named On and Off. Its appearance dictionary may be defined as
/AP << /N << /On formXObject 1 /Off formXObject 2 >> /D << /On formXObject 3 /Off formXObject 4 >> >>
where formXObject 1 and formXObject 2 define the check box's normal appearance in its checked and unchecked states, and formXObject 3 and formXObject 4 provide visual feedback, such as emboldening its outline, when the user clicks it. (No R entry is defined because no special appearance is needed when the user moves the cursor over the check box without pressing the mouse button.) The choice between the checked and unchecked appearance states is determined by the AS entry in the annotation dictionary (see Table 164).
- NOTE 3 If a conforming reader does not have native support for a particular annotation type conforming readers shall display the annotation with its normal ( N ) appearance. Conforming readers shall also attempt to provide reasonable behavior (such as displaying nothing) if an annotation's AS entry designates an appearance state for which no appearance is defined in the appearance dictionary.
For convenience in managing appearance streams that are used repeatedly, the AP entry in a PDF document's name dictionary (see 7.7.4, 'Name Dictionary') may contain a name tree mapping name strings to appearance streams. The name strings have no standard meanings; no PDF objects may refer to appearance streams by name.
PDF supports the standard annotation types listed in Table 169. The following sub-clauses describe each of these types in detail.
The values in the first column of Table 169 represent the value of the annotation dictionary's Subtype entry. The third column indicates whether the annotation is a markup annotation , as described in 12.5.6.2, 'Markup Annotations.' The sub-clause also provides more information about the value of the Contents entry for different annotation types.
Table 169 - Annotation types
| Annotation type | Description | Markup | Discussed in sub-clause |
|---|---|---|---|
| Text | Text annotation | Yes | 12.5.6.4, 'Text Annotations' |
| Link | Link annotation | No | 12.5.6.5, 'Link Annotations' |
| FreeText | (PDF 1.3) Free text annotation | Yes | 12.5.6.6, 'Free Text Annotations' |
| Line | (PDF 1.3) Line annotation | Yes | 12.5.6.7, 'Line Annotations' |
| Square | (PDF 1.3) Square annotation | Yes | 12.5.6.8, 'Square and Circle Annotations' |
| Circle | (PDF 1.3) Circle annotation | Yes | 12.5.6.8, 'Square and Circle Annotations' |
| Polygon | (PDF 1.5) Polygon annotation | Yes | 12.5.6.9, 'Polygon and Polyline Annotations' |
| PolyLine | (PDF 1.5) Polyline annotation | Yes | 12.5.6.9, 'Polygon and Polyline Annotations' |
| Highlight | (PDF 1.3) Highlight annotation | Yes | 12.5.6.10, 'Text Markup Annotations' |
| Underline | (PDF 1.3) Underline annotation | Yes | 12.5.6.10, 'Text Markup Annotations' |
| Squiggly | (PDF 1.4) Squiggly-underline annotation | Yes | 12.5.6.10, 'Text Markup Annotations' |
| StrikeOut | (PDF 1.3) Strikeout annotation | Yes | 12.5.6.10, 'Text Markup Annotations' |
| Stamp | (PDF 1.3) Rubber stamp annotation | Yes | 12.5.6.12, 'Rubber Stamp Annotations' |
| Caret | (PDF 1.5) Caret annotation | Yes | 12.5.6.11, 'Caret Annotations' |
| Ink | (PDF 1.3) Ink annotation | Yes | 12.5.6.13, 'Ink Annotations' |
| Popup | (PDF 1.3) Pop-up annotation | No | 12.5.6.14, 'Pop-up Annotations' |
| FileAttachment | (PDF 1.3) File attachment annotation | Yes | 12.5.6.15, 'File Attachment Annotations' |
| Sound | (PDF 1.2) Sound annotation | Yes | 12.5.6.16, 'Sound Annotations' |
| Movie | (PDF 1.2) Movie annotation | No | 12.5.6.17, 'Movie Annotations' |
| Widget | (PDF 1.2) Widget annotation | No | 12.5.6.19, 'Widget Annotations' |
| Screen | (PDF 1.5) Screen annotation | No | 12.5.6.18, 'Screen Annotations' |
| PrinterMark | (PDF 1.4) Printer's mark annotation | No | 12.5.6.20, 'Printer's Mark Annotations' |
| TrapNet | (PDF 1.3) Trap network annotation | No | 12.5.6.21, 'Trap Network Annotations' |
| Watermark | (PDF 1.6) Watermark annotation | No | 12.5.6.22, 'Watermark Annotations' |
| 3D | (PDF 1.6) 3D annotation | No | 13.6.2, '3D Annotations' |
| Redact | (PDF 1.7) Redact annotation | Yes | 12.5.6.23, 'Redaction Annotations' |
As mentioned in 12.5.2, 'Annotation Dictionaries,' the meaning of an annotation's Contents entry varies by annotation type. Typically, it is the text that shall be displayed for the annotation or, if the annotation does not display text, an alternate description of the annotation's contents in human-readable form. In either case, the Contents entry is useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes (see 14.9.3, 'Alternate Descriptions').
Many annotation types are defined as markup annotations because they are used primarily to mark up PDF documents (see Table 170). These annotations have text that appears as part of the annotation and may be displayed in other ways by a conforming reader, such as in a Comments pane.
Markup annotations may be divided into the following groups:
- Free text annotations display text directly on the page. The annotation's Contents entry specifies the displayed text.
- Most other markup annotations have an associated pop-up window that may contain text. The annotation's Contents entry specifies the text that shall be displayed when the pop-up window is opened. These include text, line, square, circle, polygon, polyline, highlight, underline, squiggly-underline, strikeout, rubber stamp, caret, ink, and file attachment annotations.
- Sound annotations do not have a pop-up window but may also have associated text specified by the Contents entry.
When separating text into paragraphs, a CARRIAGE RETURN (0Dh) shall be used and not, for example, a LINE FEED character (0Ah).
NOTE 1 A subset of markup annotations is called text markup annotations (see 12.5.6.10, 'Text Markup Annotations').
The remaining annotation types are not considered markup annotations:
- The pop-up annotation type shall not appear by itself; it shall be associated with a markup annotation that uses it to display text.
NOTE 2 If an annotation has no parent, the Contents entry shall represent the text of the annotation, otherwise it shall be ignored by a conforming reader.
- For all other annotation types ( Link , Movie , Widget , PrinterMark , and TrapNet ), the Contents entry shall provide an alternate representation of the annotation's contents in human-readable form, which is useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes (see 14.9.3, 'Alternate Descriptions').
Table 170 lists entries that apply to all markup annotations.
Table 170 - Additional entries specific to markup annotations
| Key | Type | Value |
|---|---|---|
| T | text string | (Optional; PDF 1.1) The text label that shall be displayed in the title bar of the annotation's pop-up window when open and active. This entry shall identify the user who added the annotation. |
| Popup | dictionary | (Optional; PDF 1.3) An indirect reference to a pop-up annotation for entering or editing the text associated with this annotation. |
Table 170 - Additional entries specific to markup annotations (continued)
| Key | Type | Value |
|---|---|---|
| CA | number | (Optional; PDF 1.4) The constant opacity value that shall be used in painting the annotation (see Sections 11.2, 'Overview of Transparency,' and 11.3.7, 'Shape and Opacity Computations'). This value shall apply to all visible elements of the annotation in its closed state (including its background and border) but not to the pop-up window that appears when the annotation is opened. The specified value shall not used if the annotation has an appearance stream (see 12.5.5, 'Appearance Streams'); in that case, the appearance stream shall specify any transparency. (However, if the compliant viewer regenerates the annotation's appearance stream, it may incorporate the CA value into the stream's content.) The implicit blend mode (see 11.3.5, 'Blend Mode'') is Normal . Default value: 1.0. If no explicit appearance stream is defined for the annotation, it may be painted by implementation-dependent means that do not necessarily conform to the PDF imaging model; in this case, the effect of this entry is implementation-dependent as well. |
| RC | text string or text stream | (Optional; PDF 1.5) A rich text string (see 12.7.3.4, 'Rich Text Strings') that shall be displayed in the pop-up window when the annotation is opened. |
| CreationDate | date | (Optional; PDF 1.5) The date and time (7.9.4, 'Dates') when the annotation was created. |
| IRT | dictionary | (Required if an RT entry is present, otherwise optional; PDF 1.5) A reference to the annotation that this annotation is 'in reply to.' Both annotations shall be on the same page of the document. The relationship between the two annotations shall be specified by the RT entry. If this entry is present in an FDF file (see 12.7.7, 'Forms Data Format'), its type shall not be a dictionary but a text string containing the contents of the NM entry of the annotation being replied to, to allow for a situation where the annotation being replied to is not in the same FDF file. |
| Subj | text string | (Optional; PDF 1.5) Text representing a short description of the subject being addressed by the annotation. |
| RT | name | (Optional; meaningful only if IRT is present; PDF 1.6) A name specifying the relationship (the 'reply type') between this annotation and one specified by IRT . Valid values are: R The annotation shall be considered a reply to the annotation specified by IRT . Conforming readers shall not display replies to an annotation individually but together in the form of threaded comments. Group The annotation shall be grouped with the annotation specified by IRT ; see the discussion following this Table. Default value: R . |
| IT | name | (Optional; PDF 1.6) A name describing the intent of the markup annotation. Intents allow conforming readers to distinguish between different uses and behaviors of a single markup annotation type. If this entry is not present or its value is the same as the annotation type, the annotation shall have no explicit intent and should behave in a generic manner in a conforming reader. Free text annotations (Table 174), line annotations (Table 175), polygon annotations (Table 178), and (PDF 1.7) polyline annotations (Table 178) have defined intents, whose values are enumerated in the corresponding tables. |
Table 170 - Additional entries specific to markup annotations (continued)
| Key | Type | Value |
|---|---|---|
| ExData | dictionary | (Optional; PDF 1.7) An external data dictionary specifying data that shall be associated with the annotation. This dictionary contains the following entries: Type (optional) If present, shall be ExData . Subtype (required) a name specifying the type of data that the markup annotation shall be associated with. The only defined value is Markup3D . Table 298 lists the values that correspond to a subtype of Markup3D . |
In PDF 1.6, a set of annotations may be grouped so that they function as a single unit when a user interacts with them. The group consists of a primary annotation , which shall not have an IRT entry, and one or more subordinate annotations , which shall have an IRT entry that refers to the primary annotation and an RT entry whose value is Group .
Some entries in the primary annotation are treated as 'group attributes' that shall apply to the group as a whole; the corresponding entries in the subordinate annotations shall be ignored. These entries are Contents (or RC and DS ), M , C , T , Popup , CreationDate , Subj , and Open . Operations that manipulate any annotation in a group, such as movement, cut, and copy, shall be treated by conforming readers as acting on the entire group.
NOTE 3 A primary annotation may have replies that are not subordinate annotations; that is, that do not have an RT value of Group .
Beginning with PDF 1.5, annotations may have an author-specific state associated with them. The state is not specified in the annotation itself but in a separate text annotation that refers to the original annotation by means of its IRT ('in reply to') entry (see Table 173). States shall be grouped into a number of state models , as shown in Table 171.
Table 171 - Annotation states
| State model | State | Description |
|---|---|---|
| Marked | Marked | The annotation has been marked by the user. |
| Unmarked | The annotation has not been marked by the user (the default). | |
| Review | Accepted | The user agrees with the change. |
| Rejected | The user disagrees with the change. | |
| Cancelled | The change has been cancelled. | |
| Completed | The change has been completed. | |
| None | The user has indicated nothing about the change (the default). |
Annotations shall be thought of as initially being in the default state for each state model. State changes made by a user shall be indicated in a text annotation with the following entries:
- The T entry (see Table 170) shall specify the user.
- The IRT entry (see Table 173) shall refer to the original annotation.
- State and StateModel (see Table 172) shall update the state of the original annotation for the specified user.
Additional state changes shall be made by adding text annotations in reply to the previous reply for a given user.
A text annotation represents a 'sticky note' attached to a point in the PDF document. When closed, the annotation shall appear as an icon; when open, it shall display a pop-up window containing the text of the note in a font and size chosen by the conforming reader. Text annotations shall not scale and rotate with the page; they shall behave as if the NoZoom and NoRotate annotation flags (see Table 165) were always set. Table 172 shows the annotation dictionary entries specific to this type of annotation.
Table 172 - Additional entries specific to a text annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Text for a text annotation. |
| Open | boolean | (Optional) A flag specifying whether the annotation shall initially be displayed open. Default value: false (closed). |
| Name | name | (Optional) The name of an icon that shall be used in displaying the annotation. Conforming readers shall provide predefined icon appearances for at least the following standard names: Comment, Key, Note, Help, NewParagraph, Paragraph, Insert Additional names may be supported as well. Default value: Note. The annotation dictionary's AP entry, if present, shall take precedence over the Name entry; see Table 168 and 12.5.5, 'Appearance Streams.' |
| State | text string | (Optional; PDF 1.5) The state to which the original annotation shall be set; see 12.5.6.3, 'Annotation States.' Default: 'Unmarked' if StateModel is 'Marked'; 'None' if StateModel is 'Review'. |
| StateModel | text string | (Required if State is present, otherwise optional; PDF 1.5) The state model corresponding to State ; see 12.5.6.3, 'Annotation States.' |
EXAMPLE The following example shows the definition of a text annotation.
22 0 obj << /Type /Annot /Subtype /Text /Rect [ 266 116 430 204 ] /Contents ( The quick brown fox ate the lazy mouse . ) >> endobj
A link annotation represents either a hypertext link to a destination elsewhere in the document (see 12.3.2, 'Destinations') or an action to be performed (12.6, 'Actions'). Table 173 shows the annotation dictionary entries specific to this type of annotation.
Table 173 - Additional entries specific to a link annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Link for a link annotation. |
| A | dictionary | (Optional; PDF 1.1) An action that shall be performed when the link annotation is activated (see 12.6, 'Actions'). |
Table 173 - Additional entries specific to a link annotation (continued)
| Key | Type | Value |
|---|---|---|
| Dest | array, name or byte string | (Optional; not permitted if an A entry is present) A destination that shall be displayed when the annotation is activated (see 12.3.2, 'Destinations'). |
| H | name | (Optional; PDF 1.2) The annotation's highlighting mode , the visual effect that shall be used when the mouse button is pressed or held down inside its active area: N (None) No highlighting. I (Invert) Invert the contents of the annotation rectangle. O I(Outline) Invert the annotation's border. P (Push) Display the annotation as if it were being pushed below the surface of the page. Default value: I. |
| PA | dictionary | (Optional; PDF 1.3) A URI action (see 12.6.4.7, 'URI Actions') formerly associated with this annotation. When Web Capture (14.10, ' Web Capture') changes an annotation from a URI to a go-to action (12.6.4.2, 'Go-To Actions'), it uses this entry to save the data from the original URI action so that it can be changed back in case the target page for the go- to action is subsequently deleted. |
| QuadPoints | array | (Optional; PDF 1.6) An array of 8 × n numbers specifying the coordinates of n quadrilaterals in default user space that comprise the region in which the link should be activated. The coordinates for each quadrilateral are given in the order x 1 y 1 x 2 y 2 x 3 y 3 x 4 y 4 specifying the four vertices of the quadrilateral in counterclockwise order. For orientation purposes, such as when applying an underline border style, the bottom of a quadrilateral is the line formed by ( x 1 , y 1 ) and ( x 2 , y 2 ). If this entry is not present or the conforming reader does not recognize it, the region specified by the Rect entry should be used. QuadPoints shall be ignored if any coordinate in the array lies outside the region specified by Rect . |
| BS | dictionary | ( Optional; PDF 1.6 ) A border style dictionary (see Table 166) specifying the line width and dash pattern to be used in drawing the annotation's border. The annotation dictionary's AP entry, if present, takes precedence over the BS entry; see Table 164 and 12.5.5, 'Appearance Streams'. |
EXAMPLE The following example shows a link annotation that jumps to a destination elsewhere in the document.
93 0 obj << /Type /Annot /Subtype /Link /Rect [ 71 717 190 734 ] /Border [ 16 16 1 ] /Dest [ 3 0 R /FitR -4 399 199 533 ] >> endobj
A free text annotation (PDF 1.3) displays text directly on the page. Unlike an ordinary text annotation (see 12.5.6.4, 'Text Annotations'), a free text annotation has no open or closed state; instead of being displayed in a pop-up window, the text shall be always visible. Table 174 shows the annotation dictionary entries specific to
this type of annotation. 12.7.3.3, 'Variable Text' describes the process of using these entries to generate the appearance of the text in these annotations.
Table 174 - Additional entries specific to a free text annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be FreeText for a free text annotation. |
| DA | string | (Required) The default appearance string that shall be used in formatting the text (see 12.7.3.3, 'Variable Text'). The annotation dictionary's AP entry, if present, shall take precedence over the DA entry; see Table 168 and 12.5.5, 'Appearance Streams.' |
| Q | integer | (Optional; PDF 1.4) A code specifying the form of quadding (justification) that shall be used in displaying the annotation's text: 0 Left-justified 1 Centered 2 Right-justified Default value: 0 (left-justified). |
| RC | text string or text stream | (Optional; PDF 1.5) A rich text string (see 12.7.3.4, 'Rich Text Strings') that shall be used to generate the appearance of the annotation. |
| DS | text string | (Optional; PDF 1.5) A default style string, as described in 12.7.3.4, 'Rich Text Strings.' |
| CL | array | (Optional; meaningful only if IT is FreeTextCallout ; PDF 1.6) An array of four or six numbers specifying a callout line attached to the free text annotation. Six numbers [ x 1 y 1 x 2 y 2 x 3 y 3 ] represent the starting, knee point, and ending coordinates of the line in default user space, as shown in Figure 8.4. Four numbers [ x 1 y 1 x 2 y 2 ] represent the starting and ending coordinates of the line. |
| IT | name | ( Optional; PDF 1.6 ) A name describing the intent of the free text annotation (see also the IT entry in Table 170). The following values shall be valid: FreeText The annotation is intended to function as a plain free-text annotation. A plain free-text annotation is also known as a text box comment. FreeTextCallout The annotation is intended to function as a callout. The callout is associated with an area on the page through the callout line specified in CL . FreeTextTypeWriter The annotation is intended to function as a click- to-type or typewriter object and no callout line is drawn. Default value: FreeText |
| BE | dictionary | ( Optional; PDF 1.6 ) A border effect dictionary (see Table 167) used in conjunction with the border style dictionary specified by the BS entry. |
Table 174 - Additional entries specific to a free text annotation (continued)
| Key | Type | Value |
|---|---|---|
| RD | rectangle | (Optional; PDF 1.6) A set of four numbers describing the numerical differences between two rectangles: the Rect entry of the annotation and a rectangle contained within that rectangle. The inner rectangle is where the annotation's text should be displayed. Any border styles and/or border effects specified by BS and BE entries, respectively, shall be applied to the border of the inner rectangle. The four numbers correspond to the differences in default user space between the left, top, right, and bottom coordinates of Rect and those of the inner rectangle, respectively. Each value shall be greater than or equal to 0. The sum of the top and bottom differences shall be less than the height of Rect , and the sum of the left and right differences shall be less than the width of Rect . |
| BS | dictionary | ( Optional; PDF 1.6 ) A border style dictionary (see Table 166) specifying the line width and dash pattern that shall be used in drawing the annotation's border. The annotation dictionary's AP entry, if present, takes precedence over the BS entry; see Table 164 and 12.5.5, 'Appearance Streams'. |
| LE | name | ( Optional; meaningful only if CL is present; PDF 1.6 ) A name specifying the line ending style that shall be used in drawing the callout line specified in CL . The name shall specify the line ending style for the endpoint defined by the pairs of coordinates ( x 1 , y 1 ). Table 176 shows the possible line ending styles. Default value: None . |
Figure 59 - Free text annotation with callout
The purpose of a line annotation (PDF 1.3) is to display a single straight line on the page. When opened, it shall display a pop-up window containing the text of the associated note. Table 175 shows the annotation dictionary entries specific to this type of annotation.
Table 175 - Additional entries specific to a line annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Line for a line annotation. |
| L | array | (Required) An array of four numbers, [ x 1 y 1 x 2 y 2 ], specifying the starting and ending coordinates of the line in default user space. If the LL entry is present, this value shall represent the endpoints of the leader lines rather than the endpoints of the line itself; see Figure 60. |
| BS | dictionary | (Optional) A border style dictionary (see Table 166) specifying the width and dash pattern that shall be used in drawing the line. The annotation dictionary's AP entry, if present, shall take precedence over the L and BS entries; see Table 168 and 12.5.5, 'Appearance Streams.' |
| LE | array | (Optional; PDF 1.4) An array of two names specifying the line ending styles that shall be used in drawing the line. The first and second elements of the array shall specify the line ending styles for the endpoints defined, respectively, by the first and second pairs of coordinates, ( x 1 , y 1 ) and ( x 2 , y 2 ), in the L array. Table 176 shows the possible values. Default value: [/None /None]. |
| IC | array | (Optional; PDF 1.4) An array of numbers in the range 0.0 to 1.0 specifying the interior color that shall be used to fill the annotation's line endings (see Table 176). The number of array elements shall determine the colour space in which the colour is defined: 0 No colour; transparent 1 DeviceGray 3 DeviceRGB 4 DeviceCMYK |
| LL | number | (Required if LLE is present, otherwise optional; PDF 1.6) The length of leader lines in default user space that extend from each endpoint of the line perpendicular to the line itself, as shown in Figure 60. A positive value shall mean that the leader lines appear in the direction that is clockwise when traversing the line from its starting point to its ending point (as specified by L ); a negative value shall indicate the opposite direction. Default value: 0 (no leader lines). |
| LLE | number | (Optional; PDF 1.6) A non-negative number that shall represents the length of leader line extensions that extend from the line proper 180 degrees from the leader lines, as shown in Figure 60. Default value: 0 (no leader line extensions). |
| Cap | boolean | (Optional; PDF 1.6) If true , the text specified by the Contents or RC entries shall be replicated as a caption in the appearance of the line, as shown in Figure 61 and Figure 62. The text shall be rendered in a manner appropriate to the content, taking into account factors such as writing direction. Default value: false . |
| IT | name | (Optional; PDF 1.6) A name describing the intent of the line annotation (see also Table 170). Valid values shall be LineArrow , which means that the annotation is intended to function as an arrow, and LineDimension , which means that the annotation is intended to function as a dimension line. |
Table 175 - Additional entries specific to a line annotation (continued)
| Key | Type | Value |
|---|---|---|
| LLO | number | ( Optional; PDF 1.7 ) A non-negative number that shall represent the length of the leader line offset, which is the amount of empty space between the endpoints of the annotation and the beginning of the leader lines. |
| CP | name | ( Optional; meaningful only if Cap is true ; PDF 1.7 ) A name describing the annotation's caption positioning. Valid values are Inline , meaning the caption shall be centered inside the line, and Top , meaning the caption shall be on top of the line. Default value: Inline |
| Measure | dictionary | ( Optional; PDF 1.7 ) A measure dictionary (see Table 261) that shall specify the scale and units that apply to the line annotation. |
| CO | array | ( Optional; meaningful only if Cap is true ; PDF 1.7 ) An array of two numbers that shall specify the offset of the caption text from its normal position. The first value shall be the horizontal offset along the annotation line from its midpoint, with a positive value indicating offset to the right and a negative value indicating offset to the left. The second value shall be the vertical offset perpendicular to the annotation line, with a positive value indicating a shift up and a negative value indicating a shift down. Default value: [0, 0] (no offset from normal positioning) |
Figure 60 - Leader lines
Figure 61 illustrates the effect of including a caption to a line annotation, which is specified by setting Cap to true .
Figure 61 - Lines with captions appearing as part of the line
Figure 62 illustrates the effect of applying a caption to a line annotation that has a leader offset.
Figure 62 - Line with a caption appearing as part of the offset
Table 176 - Line ending styles
| Name | Appearance | Description |
|---|---|---|
| Square | A square filled with the annotation's interior color, if any | |
| Circle | A circle filled with the annotation's interior color, if any | |
| Diamond | A diamond shape filled with the annotation's interior color, if any | |
| OpenArrow | Two short lines meeting in an acute angle to form an open arrowhead | |
| ClosedArrow | Two short lines meeting in an acute angle as in the OpenArrow style and connected by a third line to form a triangular closed arrowhead filled with the annotation's interior color , if any | |
| None | No line ending |
Table 176 - Line ending styles (continued)
| Name | Appearance | Description |
|---|---|---|
| Butt | (PDF 1.5) A short line at the endpoint perpendicular to the line itself | |
| ROpenArrow | (PDF 1.5) Two short lines in the reverse direction from OpenArrow | |
| RClosedArrow | (PDF 1.5) A triangular closed arrowhead in the reverse direction from ClosedArrow | |
| Slash | (PDF 1.6) A short line at the endpoint approximately 30 degrees clockwise from perpendicular to the line itself |
Square and circle annotations (PDF 1.3) shall display, respectively, a rectangle or an ellipse on the page. When opened, they shall display a pop-up window containing the text of the associated note. The rectangle or ellipse shall be inscribed within the annotation rectangle defined by the annotation dictionary's Rect entry (see Table 168).
Figure 63 shows two annotations, each with a border width of 18 points. Despite the names square and circle , the width and height of the annotation rectangle need not be equal. Table 177 shows the annotation dictionary entries specific to these types of annotations.
Figure 63 - Square and circle annotations
Table 177 - Additional entries specific to a square or circle annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Square or Circle for a square or circle annotation, respectively. |
| BS | dictionary | (Optional) A border style dictionary (see Table 166) specifying the line width and dash pattern that shall be used in drawing the rectangle or ellipse. The annotation dictionary's AP entry, if present, shall take precedence over the Rect and BS entries; see Table 168 and 12.5.5, 'Appearance Streams.' |
Table 177 - Additional entries specific to a square or circle annotation (continued)
| Key | Type | Value |
|---|---|---|
| IC | array | (Optional; PDF 1.4) An array of numbers that shall be in the range 0.0 to 1.0 and shall specify the interior color with which to fill the annotation's rectangle or ellipse. The number of array elements determines the colour space in which the colour shall be defined: 0 No colour; transparent 1 DeviceGray 3 DeviceRGB 4 DeviceCMYK |
| BE | dictionary | (Optional; PDF 1.5) A border effect dictionary describing an effect applied to the border described by the BS entry (see Table 167). |
| RD | rectangle | (Optional; PDF 1.5) A set of four numbers that shall describe the numerical differences between two rectangles: the Rect entry of the annotation and the actual boundaries of the underlying square or circle. Such a difference may occur in situations where a border effect (described by BE ) causes the size of the Rect to increase beyond that of the square or circle. The four numbers shall correspond to the differences in default user space between the left, top, right, and bottom coordinates of Rect and those of the square or circle, respectively. Each value shall be greater than or equal to 0. The sum of the top and bottom differences shall be less than the height of Rect , and the sum of the left and right differences shall be less than the width of Rect . |
Polygon annotations (PDF 1.5) display closed polygons on the page. Such polygons may have any number of vertices connected by straight lines. Polyline annotations (PDF 1.5) are similar to polygons, except that the first and last vertex are not implicitly connected.
Table 178 - Additional entries specific to a polygon or polyline annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Polygon or PolyLine for a polygon or polyline annotation, respectively. |
| Vertices | array | (Required) An array of numbers (see Table 174) specifying the width and dash pattern that shall represent the alternating horizontal and vertical coordinates, respectively, of each vertex, in default user space. |
| LE | array | (Optional; meaningful only for polyline annotations) An array of two names that shall specify the line ending styles. The first and second elements of the array shall specify the line ending styles for the endpoints defined, respectively, by the first and last pairs of coordinates in the Vertices array. Table 176 shows the possible values. Default value: [/ None /None]. |
| BS | dictionary | (Optional) A border style dictionary (see Table 166) specifying the width and dash pattern that shall be used in drawing the line. The annotation dictionary's AP entry, if present, shall take precedence over the Vertices and BS entries; see Table 168 and 12.5.5, 'Appearance Streams.' |
Table 178 - Additional entries specific to a polygon or polyline annotation (continued)
| Key | Type | Value |
|---|---|---|
| IC | array | (Optional; PDF 1.4) An array of numbers that shall be in the range 0.0 to 1.0 and shall specify the interior color with which to fill the annotation's line endings (see Table 176). The number of array elements determines the colour space in which the colour shall be defined: 0 No colour; transparent 1 DeviceGray 3 DeviceRGB 4 DeviceCMYK |
| BE | dictionary | (Optional; meaningful only for polygon annotations) A border effect dictionary that shall describe an effect applied to the border described by the BS entry (see Table 167). |
| IT | name | (Optional; PDF 1.6) A name that shall describe the intent of the polygon or polyline annotation (see also Table 170). The following values shall be valid: PolygonCloud The annotation is intended to function as a cloud object. PolyLineDimension ( PDF 1.7 ) The polyline annotation is intended to function as a dimension. PolygonDimension ( PDF 1.7 ) The polygon annotation is intended to function as a dimension. |
| Measure | dictionary | ( Optional; PDF 1.7 ) A measure dictionary (see Table 261) that shall specify the scale and units that apply to the annotation. |
Text markup annotations shall appear as highlights, underlines, strikeouts (all PDF 1.3) , or jagged ('squiggly') underlines (PDF 1.4) in the text of a document. When opened, they shall display a pop-up window containing the text of the associated note. Table 179 shows the annotation dictionary entries specific to these types of annotations.
Table 179 - Additional entries specific to text markup annotations
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Highlight , Underline , Squiggly , or StrikeOut for a highlight, underline, squiggly-underline, or strikeout annotation, respectively. |
| QuadPoints | array | (Required) An array of 8 × n numbers specifying the coordinates of n quadrilaterals in default user space. Each quadrilateral shall encompasses a word or group of contiguous words in the text underlying the annotation. The coordinates for each quadrilateral shall be given in the order x 1 y 1 x 2 y 2 x 3 y 3 x 4 y 4 specifying the quadrilateral's four vertices in counterclockwise order (see Figure 64). The text shall be oriented with respect to the edge connecting points ( x 1 , y 1 ) and ( x 2 , y 2 ). The annotation dictionary's AP entry, if present, shall take precedence over QuadPoints ; see Table 168 and 12.5.5, 'Appearance Streams.' |
A caret annotation (PDF 1.5) is a visual symbol that indicates the presence of text edits. Table 180 lists the entries specific to caret annotations.
Table 180 - Additional entries specific to a caret annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Caret for a caret annotation. |
| RD | rectangle | (Optional; PDF 1.5) A set of four numbers that shall describe the numerical differences between two rectangles: the Rect entry of the annotation and the actual boundaries of the underlying caret. Such a difference can occur. When a paragraph symbol specified by Sy is displayed along with the caret. The four numbers shall correspond to the differences in default user space between the left, top, right, and bottom coordinates of Rect and those of the caret, respectively. Each value shall be greater than or equal to 0. The sum of the top and bottom differences shall be less than the height of Rect , and the sum of the left and right differences shall be less than the width of Rect . |
| Sy | name | (Optional) A name specifying a symbol that shall be associated with the caret: P A new paragraph symbol (¶) should be associated with the caret. None No symbol should be associated with the caret. Default value: None. |
A rubber stamp annotation (PDF 1.3) displays text or graphics intended to look as if they were stamped on the page with a rubber stamp. When opened, it shall display a pop-up window containing the text of the associated note. Table 181 shows the annotation dictionary entries specific to this type of annotation.
Figure 64 - QuadPoints specification
Table 181 - Additional entries specific to a rubber stamp annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Stamp for a rubber stamp annotation. |
| Name | name | (Optional) The name of an icon that shall be used in displaying the annotation. Conforming readers shall provide predefined icon appearances for at least the following standard names: Approved, Experimental, NotApproved, AsIs, Expired , NotForPublicRelease, Confidential, Final, Sold, Departmental, ForComment, TopSecret, Draft, ForPublicRelease Additional names may be supported as well. Default value: Draft. The annotation dictionary's AP entry, if present, shall take precedence over the Name entry; see Table 168 and 12.5.5, 'Appearance Streams.' |
An ink annotation (PDF 1.3) represents a freehand 'scribble' composed of one or more disjoint paths. When opened, it shall display a pop-up window containing the text of the associated note. Table 182 shows the annotation dictionary entries specific to this type of annotation.
Table 182 - Additional entries specific to an ink annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Ink for an ink annotation. |
| InkList | array | (Required) An array of n arrays, each representing a stroked path. Each array shall be a series of alternating horizontal and vertical coordinates in default user space, specifying points along the path. When drawn, the points shall be connected by straight lines or curves in an implementation-dependent way. |
| BS | dictionary | (Optional) A border style dictionary (see Table 166) specifying the line width and dash pattern that shall be used in drawing the paths. The annotation dictionary's AP entry, if present, shall take precedence over the InkList and BS entries; see Table 168 and 12.5.5, 'Appearance Streams.' |
A pop-up annotation (PDF 1.3) displays text in a pop-up window for entry and editing. It shall not appear alone but is associated with a markup annotation, its parent annotation , and shall be used for editing the parent's text. It shall have no appearance stream or associated actions of its own and shall be identified by the Popup entry in the parent's annotation dictionary (see Table 174). Table 183 shows the annotation dictionary entries specific to this type of annotation.
Table 183 - Additional entries specific to a pop-up annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Popup for a pop-up annotation. |
| Parent | dictionary | (Optional; shall be an indirect reference) The parent annotation with which this pop-up annotation shall be associated. If this entry is present, the parent annotation's Contents , M , C , and T entries (see Table 168) shall override those of the pop-up annotation itself. |
| Open | boolean | (Optional) A flag specifying whether the pop-up annotation shall initially be displayed open. Default value: false (closed). |
A file attachment annotation (PDF 1.3) contains a reference to a file, which typically shall be embedded in the PDF file (see 7.11.4, 'Embedded File Streams').
NOTE A table of data might use a file attachment annotation to link to a spreadsheet file based on that data; activating the annotation extracts the embedded file and gives the user an opportunity to view it or store it in the file system. Table 184 shows the annotation dictionary entries specific to this type of annotation.
The Contents entry of the annotation dictionary may specify descriptive text relating to the attached file. Conforming readers shall use this entry rather than the optional Desc entry (PDF 1.6) in the file specification dictionary (see Table 44) identified by the annotation's FS entry.
Table 184 - Additional entries specific to a file attachment annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be FileAttachment for a file attachment annotation. |
| FS | file specification | (Required) The file associated with this annotation. |
| Name | name | (Optional) The name of an icon that shall be used in displaying the annotation. Conforming readers shall provide predefined icon appearances for at least the following standard names: GraphPushPin PaperclipTag Additional names may be supported as well. Default value: PushPin. The annotation dictionary's AP entry, if present, shall take precedence over the Name entry; see Table 168 and 12.5.5, 'Appearance Streams.' |
A sound annotation (PDF 1.2) shall analogous to a text annotation except that instead of a text note, it contains sound recorded from the computer's microphone or imported from a file. When the annotation is activated, the sound shall be played. The annotation shall behave like a text annotation in most ways, with a different icon (by default, a speaker) to indicate that it represents a sound. Table 185 shows the annotation dictionary entries specific to this type of annotation. Sound objects are discussed in 13.3, 'Sounds.'
Table 185 - Additional entries specific to a sound annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Sound for a sound annotation. |
| Sound | stream | (Required) A sound object defining the sound that shall be played when the annotation is activated (see 13.3, 'Sounds'). |
| Name | name | (Optional) The name of an icon that shall be used in displaying the annotation. Conforming readers shall provide predefined icon appearances for at least the standard names Speaker and Mic. Additional names may be supported as well. Default value: Speaker. The annotation dictionary's AP entry, if present, shall take precedence over the Name entry; see Table 168 and 12.5.5, 'Appearance Streams.' |
A movie annotation (PDF 1.2) contains animated graphics and sound to be presented on the computer screen and through the speakers. When the annotation is activated, the movie shall be played. Table 186 shows the annotation dictionary entries specific to this type of annotation. Movies are discussed in 13.4, 'Movies.'
Table 186 - Additional entries specific to a movie annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Movie for a movie annotation. |
| T | text string | ( Optional ) The title of the movie annotation. Movie actions (12.6.4.9, 'Movie Actions') may use this title to reference the movie annotation. |
| Movie | dictionary | (Required) A movie dictionary that shall describe the movie's static characteristics (see 13.4, 'Movies'). |
| A | boolean or dictionary | (Optional) A flag or dictionary specifying whether and how to play the movie when the annotation is activated. If this value is a dictionary, it shall be a movie activation dictionary (see 13.4, 'Movies') specifying how to play the movie. If the value is the boolean true , the movie shall be played using default activation parameters. If the value is false , the movie shall not be played. Default value: true . |
A screen annotation (PDF 1.5) specifies a region of a page upon which media clips may be played. It also serves as an object from which actions can be triggered. 12.6.4.13, 'Rendition Actions' discusses the relationship between screen annotations and rendition actions. Table 187 shows the annotation dictionary entries specific to this type of annotation.
Table 187 - Additional entries specific to a screen annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Screen for a screen annotation. |
| T | text string | ( Optional ) The title of the screen annotation. |
| MK | dictionary | (Optional) An appearance characteristics dictionary (see Table 189). The I entry of this dictionary provides the icon used in generating the appearance referred to by the screen annotation's AP entry. |
Table 187 - Additional entries specific to a screen annotation (continued)
| Key | Type | Value |
|---|---|---|
| A | dictionary | (Optional; PDF 1.1) An action that shall be performed when the annotation is activated (see 12.6, 'Actions'). |
| AA | dictionary | (Optional; PDF 1.2) An additional-actions dictionary defining the screen annotation's behaviour in response to various trigger events (see 12.6.3, 'Trigger Events'). |
In addition to the entries in Table 187, screen annotations may use the common entries in the annotation dictionary (see Table 164) in the following ways:
- The P entry shall be used for a screen annotation referenced by a rendition action. It shall reference a valid page object, and the annotation shall be present in the page's Annots array for the action to be valid.
- The AP entry refers to an appearance dictionary (see Table 168) whose normal appearance provides the visual appearance for a screen annotation that shall be used for printing and default display when a media clip is not being played. If AP is not present, the screen annotation shall not have a default visual appearance and shall not be printed.
Interactive forms (see 12.7, 'Interactive Forms') use widget annotations (PDF 1.2) to represent the appearance of fields and to manage user interactions. As a convenience, when a field has only a single associated widget annotation, the contents of the field dictionary (12.7.3, 'Field Dictionaries') and the annotation dictionary may be merged into a single dictionary containing entries that pertain to both a field and an annotation.
NOTE This presents no ambiguity, since the contents of the two kinds of dictionaries do not conflict.
Table 188 shows the annotation dictionary entries specific to this type of annotation; interactive forms and fields are discussed at length in 12.7, 'Interactive Forms.'
Table 188 - Additional entries specific to a widget annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be Widget for a widget annotation. |
| H | name | (Optional) The annotation's highlighting mode , the visual effect that shall be used when the mouse button is pressed or held down inside its active area: N (None) No highlighting. I (Invert) Invert the contents of the annotation rectangle. O (Outline) Invert the annotation's border. P (Push) Display the annotation's down appearance, if any (see 12.5.5, 'Appearance Streams'). If no down appearance is defined, the contents of the annotation rectangle shall be offset to appear as if it were being pushed below the surface of the page. T (Toggle) Same as P (which is preferred). A highlighting mode other than P shall override any down appearance defined for the annotation. Default value: I. |
| MK | dictionary | (Optional) An appearance characteristics dictionary (see Table 189) that shall be used in constructing a dynamic appearance stream specifying the annotation's visual presentation on the page. The name MK for this entry is of historical significance only and has no direct meaning. |