PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 2) — page 1
604
CHAPTER 8
Interactive Features
8.4
Annotations
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 an-
notation types, described in detail in Section 8.4.5, “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 ob-
ject, such as by opening a pop-up window displaying a text note (Figure 8.2) or by
playing a sound or a movie.
WE HAVE BEEN TRACKING GREAT EMPLOYEES SINCE 1981,
when we began research on our book Te 100 Best
Companies to
Comment
of
more than 1,0
ost
viable candida
This is the text associated with the
to
highlight annotation.
participate. (T
en
years old and
We asked
25
randomly sele
rk
Trust Index.
he
Great Place to
ate
trust in ma
nd
camaraderie.
Each com
itt
People Practi
ge
questionnaire
ct,
Hewitt Asso
ng
management c
ur
candidates to send us additional corporate materials, such
FIGURE 8.2 Open annotation
Viewer applications may permit the user to navigate through the annotations on
a page by using the keyboard (in particular, the tab key); see implementation note
77 in Appendix H. Beginning with PDF 1.5, PDF producers may make the navi-
605
SECTION 8.4
Annotations
gation order explicit with the optional Tabs entry in a page object (see Table 3.27).
The following are the possible values for this entry:
• R (row order): Annotations are visited in rows running horizontally across the
page. The direction within a row is determined by the Direction entry in the
viewer preferences dictionary (see Section 8.1, “Viewer Preferences”). The first
annotation visited is the first annotation in the topmost row. When the end of a
row is encountered, the first annotation in the next row is visited.
• C (column order): Annotations are visited in columns running vertically up
and down the page. Columns are ordered by the Direction entry in the viewer
preferences dictionary (see Section 8.1, “Viewer Preferences”). The first anno-
tation visited is the one at the top of the first column. When the end of a col-
umn is encountered, the first annotation in the next column is visited.
• S (structure order): Annotations are visited in the order in which they appear in
the structure tree (see Section 10.6, “Logical Structure”). The order for annota-
tions that are not included in the structure tree is application-dependent.
Note: The descriptions above assume the page is being viewed in the orientation
specified by the Rotate entry.
The behavior of each annotation type is implemented by a software module
called an annotation handler. Handlers for the standard annotation types are built
directly into the PDF viewer application; handlers for additional types can be
supplied as plug-in extensions.
8.4.1
Annotation Dictionaries
The optional Annots entry in a page object (see “Page Objects” on page 144)
holds an array of annotation dictionaries, each representing an annotation associ-
ated with the given page. Table 8.15 shows the required and optional entries that
are common to all annotation dictionaries. The dictionary may contain addition-
al entries specific to a particular annotation type; see the descriptions of individ-
ual annotation types in Section 8.4.5, “Annotation Types,” for details.
Note: A given annotation dictionary may be referenced from the Annots array of
only one page. Attempting to share an annotation dictionary among multiple pages
produces unpredictable behavior. This requirement applies only to the annotation
dictionary itself, not to subsidiary objects, which can be shared among multiple an-
notations without causing any difficulty.
606
CHAPTER 8
Interactive Features
TABLE 8.15 Entries common to all annotation dictionaries
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be Annot for an annotation dictionary.
Subtype
name
(Required) The type of annotation that this dictionary describes; see Table 8.20
on page 615 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 to be displayed for the annotation or, if this type of annotation
does not display text, an alternate description of the annotation’s contents in
human-readable form. In either case, this text is useful when extracting the
document’s contents in support of accessibility to users with disabilities or for
other purposes (see Section 10.8.2, “Alternate Descriptions”). See Section 8.4.5,
“Annotation Types” for more details on the meaning of this entry for each an-
notation type.
P
dictionary
(Optional; PDF 1.3; not used in FDF files) An indirect reference to the page ob-
ject with which this annotation is associated.
Note: This entry is required for screen annotations associated with rendition ac-
tions (PDF 1.5; see “Screen Annotations” on page 639 and “Rendition Actions” on
page 668).
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
(Optional; PDF 1.1) The date and time when the annotation was most recently
text string
modified. The preferred format is a date string as described in Section 3.8.3,
“Dates,” but viewer applications should be prepared to accept and display a
string in any format. (See implementation note 78 in Appendix H.)
F
integer
(Optional; PDF 1.1) A set of flags specifying various characteristics of the anno-
tation (see Section 8.4.2, “Annotation Flags”). Default value: 0.
AP
dictionary
(Optional; PDF 1.2) An appearance dictionary specifying how the annotation is
presented visually on the page (see Section 8.4.4, “Appearance Streams” and
also implementation note 79 in Appendix H). Individual annotation handlers
may ignore this entry and provide their own appearances.
607
SECTION 8.4
Annotations
KEY
TYPE
VALUE
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 8.4.4, “Ap-
pearance Streams” and also implementation note 79 in Appendix H).
Border
array
(Optional) An array specifying the characteristics of the annotation’s border.
The border is specified as a rounded rectangle.
In 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. (See implementation note 81 in Appen-
dix H.)
In PDF 1.1, the array may have a fourth element, an optional dash array
defining a pattern of dashes and gaps to be used in drawing the border. The
dash array is specified in the same format as in the line dash pattern parameter
of the graphics state (see “Line Dash Pattern” on page 217). For example, a Bor-
der 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 that no dash phase
is specified; the phase is assumed to be 0. (See implementation note 82 in Ap-
pendix H.)
Note: In PDF 1.2 or later, this entry may be ignored in favor of the BS entry (see
above); see implementation note 82 in Appendix H.
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
color 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 color space in which the color is
defined:
0
No color; transparent
1
DeviceGray
3
DeviceRGB
4
DeviceCMYK
608
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
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 “Finding Structure El-
ements from Content Items” on page 868).
OC
dictionary
(Optional; PDF 1.5) An optional content group or optional content member-
ship dictionary (see Section 4.10, “Optional Content”) specifying the optional
content properties for the annotation. Before the annotation is drawn, its visi-
bility is determined based on this entry as well as the annotation flags specified
in the F entry (see Section 8.4.2, “Annotation Flags”). If it is determined to be
invisible, the annotation is skipped, as if it were not in the document.
8.4.2
Annotation Flags
The value of the annotation dictionary’s F entry is an unsigned 32-bit integer con-
taining flags specifying various characteristics of the annotation. Bit positions
within the flag word are numbered from 1 (low-order) to 32 (high-order). Table
8.16 shows the meanings of the flags; all undefined flag bits are reserved and must
be set to 0.
TABLE 8.16 Annotation flags
BIT POSITION NAME
MEANING
1
Invisible
If set, do not display the annotation if it does not belong to one of the stan-
dard annotation types and no annotation handler is available. If clear, display
such an unknown annotation using an appearance stream specified by its ap-
pearance dictionary, if any (see Section 8.4.4, “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. In cases where screen space is limited, the ability to hide
and show annotations selectively can be used in combination with appearance
streams (see Section 8.4.4, “Appearance Streams”) to display auxiliary pop-up
information similar in function to online help systems. (See implementation
note 83 in Appendix H.)
3
Print
(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. This
can be useful, for example, for annotations representing interactive pushbut-
tons, which would serve no meaningful purpose on the printed page. (See
implementation note 83 in Appendix H.)
609
SECTION 8.4
Annotations
BIT POSITION
NAME
MEANING
4
NoZoom
(PDF 1.3) If set, do not scale the annotation’s appearance to match the magni-
fication of the page. The location of the annotation on the page (defined by
the upper-left corner of its annotation rectangle) remains fixed, regardless of
the page magnification. See below for further discussion.
5
NoRotate
(PDF 1.3) If set, do not rotate the annotation’s appearance to match the rota-
tion of the page. The upper-left corner of the annotation rectangle remains in
a fixed location on the page, regardless of the page rotation. See below for fur-
ther discussion.
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.
Note: This flag is ignored for widget annotations; its function is subsumed by the
ReadOnly flag of the associated form field (see Table 8.70 on page 676).
8
Locked
(PDF 1.4) If set, do not allow the annotation to be deleted or its properties (in-
cluding 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. (See implementation note 84 in Appendix H.)
9
ToggleNoView
(PDF 1.5) If set, invert the interpretation of the NoView flag for certain
events. A typical use is to have an annotation that appears only when a mouse
cursor is held over it; see implementation note 85 in Appendix H.
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 always maintains the same fixed size on
the screen and is unaffected by the magnification level at which the page itself is
displayed. Similarly, if the NoRotate flag is set, the annotation retains its original
orientation on the screen when the page is rotated (by changing the Rotate entry
in the page object; see “Page Objects” on page 144).
610
CHAPTER 8
Interactive Features
In either case, the annotation’s position is 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 viewer application performs this alteration auto-
matically. However, it does not actually change the annotation’s Rect entry, which
continues to describe the annotation’s relationship with the unscaled, unrotated
user space.
For example, Figure 8.3 shows how an annotation whose NoRotate flag is set re-
mains 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.
(0, 0)
abcdefghijklm
nopqrstuvwxyz
(0, 0)
Before page rotation
After page rotation
FIGURE 8.3 Coordinate adjustment with the NoRotate flag
8.4.3
Border Styles
An annotation may optionally be surrounded by a border when displayed or
printed. If present, the border is drawn completely inside the annotation rec-
tangle. In PDF 1.1, the characteristics of the border are specified by the Border
entry in the annotation dictionary (see Table 8.15 on page 606). Beginning with
611
SECTION 8.4
Annotations
PDF 1.2, some types of annotations may instead specify their border characteris-
tics in a border style dictionary designated by the annotation’s BS entry. Such dic-
tionaries are also used to specify the width and dash pattern for the lines drawn
by line, square, circle, and ink annotations. Table 8.17 summarizes the contents of
the border style dictionary. If neither the Border nor the BS entry is present, the
border is drawn as a solid line with a width of 1 point.
TABLE 8.17 Entries in a border style dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
Border for a border style dictionary.
W
number
(Optional) The border width in points. If this value is 0, no border is drawn. Default
value: 1.
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
is specified by the D entry (see below).
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.
Other border styles may be defined in the future. Default value: S.
D
array
(Optional) A dash array defining a pattern of dashes and gaps to be used in drawing a
dashed border (border style D above). The dash array is specified in the same format
as in the line dash pattern parameter of the graphics state (see “Line Dash Pattern” on
page 217). The dash phase is not specified and is assumed to be 0. For 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) can have
a BE entry, which is a border effect dictionary that specifies an effect to be applied
to the border of the annotations. Beginning with PDF 1.6, the free text annotation
can also have a BE entry. Table 8.18 describes the entries in a border effect dictio-
nary.
612
CHAPTER 8
Interactive Features
TABLE 8.18 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 is as described by the annotation dictionary’s BS entry.
C The border should appear “cloudy”. The width and dash array specified by BS
are honored.
Default value: S.
I
number
(Optional; valid only if the value of S is C) A number describing the intensity of the ef-
fect. Suggested values range from 0 to 2. Default value: 0.
8.4.4
Appearance Streams
Beginning with PDF 1.2, an annotation can specify one or more appearance
streams as an alternative to the simple border and color characteristics available
in earlier versions. Appearance streams enable the annotation to be presented vi-
sually in different ways to reflect its interactions with the user. Each appearance
stream is a form XObject (see Section 4.9, “Form XObjects”): a self-contained
content stream to be rendered inside the annotation rectangle.
The following method is used to map from the coordinate system of the appear-
ance XObject (as defined by its Matrix entry; see Table 4.45) to the annotation’s
rectangle in default user space:
Algorithm 8.1
1.
The appearance’s bounding box (specified by its BBox entry) is transformed, using
Matrix, to produce a quadrilateral with arbitrary orientation. The transformed ap-
pearance box is the smallest upright rectangle that encompasses this quadrilateral.
2.
A matrix A is 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.
3.
Matrix is 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:
AA = A × Matrix
613
SECTION 8.4
Annotations
The annotation may be further scaled and rotated if either the NoZoom or
NoRotate flag is set (see Section 8.4.2, “Annotation Flags”). Any transformation
applied to the annotation as a whole is also applied to the appearance within it.
In PDF 1.4, an annotation appearance can include transparency. If the appear-
ance’s stream dictionary does not contain a Group entry, it is treated as a non-iso-
lated, non-knockout transparency group. Otherwise, the isolated and knockout
values specified in the group dictionary (see Section 7.5.5, “Transparency Group
XObjects”) are used.
The transparency group is 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. (See implementation
note 87 in Appendix H.)
Note: If a transparent annotation appearance is painted over an annotation that is
drawn without using an appearance stream, the effect is implementation-depen-
dent. This is because such annotations are sometimes drawn by means that do not
conform to the Adobe imaging model. Also, the effect of highlighting a transparent
annotation appearance is implementation-dependent.
An annotation can define as many as three separate appearances:
• The normal appearance is used when the annotation is not interacting with the
user. This appearance is also used for printing the annotation.
• The rollover appearance is used when the user moves the cursor into the anno-
tation’s active area without pressing the mouse button.
• The down appearance is used when the mouse button is pressed or held down
within the annotation’s active area.
Note: 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 Section 8.5.2, “Trigger Events,” for further discussion.
The normal, rollover, and down appearances are defined in an appearance
dictionary, which in turn is the value of the AP entry in the annotation dictionary
(see Table 8.15 on page 606). Table 8.19 shows the contents of the appearance dic-
tionary.
614
CHAPTER 8
Interactive Features
TABLE 8.19 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 de-
fines multiple appearance streams corresponding to different appearance states of
the annotation.
For example, an annotation representing an interactive check box might have two
appearance states named On and Off. Its appearance dictionary might be defined
as
/AP <<
/N <<
/On formXObject1
/Off formXObject2
>>
/D <<
/On formXObject3
/Off formXObject4
>>
>>
where formXObject1 and formXObject2 define the check box’s normal appearance
in its checked and unchecked states, and formXObject3 and formXObject4 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 be-
tween the checked and unchecked appearance states is determined by the AS en-
try in the annotation dictionary (see Table 8.15 on page 606).
Note: Some of the standard PDF annotation types, such as movie annotations—as
well as all custom annotation types defined by third parties—are implemented
through plug-in extensions. If the plug-in for a particular annotation type is not
available, PDF viewer applications should display the annotation with its normal
(N) appearance. Viewer applications should also attempt to provide reasonable be-
615
SECTION 8.4
Annotations
havior (such as displaying nothing) if an annotation’s AS entry designates an ap-
pearance 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 Section 3.6.3, “Name Diction-
ary”) can contain a name tree mapping name strings to appearance streams. The
name strings have no standard meanings; no PDF objects refer to appearance
streams by name.
8.4.5
Annotation Types
PDF supports the standard annotation types listed in Table 8.20. The following
sections describe each of these types in detail. Plug-in extensions may add new
annotation types, and further standard types may be added in the future. (See im-
plementation note 88 in Appendix H.)
The values in the first column of Table 8.20 represent the value of the annotation
dictionary’s Subtype entry. The third column indicates whether the annotation is
a markup annotation, as described in “Markup Annotations,” below. The section
also provides more information about the value of the Contents entry for differ-
ent annotation types.
TABLE 8.20 Annotation types
ANNOTATION TYPE DESCRIPTION
MARKUP? DISCUSSED IN SECTION
Text
Text annotation
Yes
“Text Annotations” on page 621
Link
Link annotation
No
“Link Annotations” on page 622
FreeText
(PDF 1.3) Free text annotation
Yes
“Free Text Annotations” on page 623
Line
(PDF 1.3) Line annotation
Yes
“Line Annotations” on page 626
Square
(PDF 1.3) Square annotation
Yes
“Square and Circle Annotations” on page 630
Circle
(PDF 1.3) Circle annotation
Yes
“Square and Circle Annotations” on page 630
Polygon
(PDF 1.5) Polygon annotation
Yes
“Polygon and Polyline Annotations” on page
632
PolyLine
(PDF 1.5) Polyline annotation
Yes
“Polygon and Polyline Annotations” on page
632
616
CHAPTER 8
Interactive Features
ANNOTATION TYPE DESCRIPTION
MARKUP? DISCUSSED IN SECTION
Highlight
(PDF 1.3) Highlight annotation
Yes
“Text Markup Annotations” on page 633
Underline
(PDF 1.3) Underline annotation Yes
“Text Markup Annotations” on page 633
Squiggly
(PDF 1.4) Squiggly-underline
Yes
“Text Markup Annotations” on page 633
annotation
StrikeOut
(PDF 1.3) Strikeout annotation
Yes
“Text Markup Annotations” on page 633
Stamp
(PDF 1.3) Rubber stamp annotation Yes
“Rubber Stamp Annotations” on page 635
Caret
(PDF 1.5) Caret annotation
Yes
“Caret Annotations” on page 634
Ink
(PDF 1.3) Ink annotation
Yes
“Ink Annotations” on page 636
Popup
(PDF 1.3) Pop-up annotation
No
“Pop-up Annotations” on page 637
FileAttachment
(PDF 1.3) File attachment
Yes
“File Attachment Annotations” on page 637
annotation
Sound
(PDF 1.2) Sound annotation
Yes
“Sound Annotations” on page 638
Movie
(PDF 1.2) Movie annotation
No
“Movie Annotations” on page 639
Widget
(PDF 1.2) Widget annotation
No
“Widget Annotations” on page 640
Screen
(PDF 1.5) Screen annotation
No
“Screen Annotations” on page 639
PrinterMark
(PDF 1.4) Printer’s mark annotation No
“Printer’s Mark Annotations” on page 643
TrapNet
(PDF 1.3) Trap network annotation No
“Trap Network Annotations” on page 643
Watermark
(PDF 1.6) Watermark annotation No
“Watermark Annotations” on page 644
3D
(PDF 1.6) 3D annotation
No
“3D Annotations” on page 791
Markup Annotations
As mentioned in Section 8.4.1, “Annotation Dictionaries”, the meaning of an an-
notation’s Contents entry varies by annotation type. Typically, it is the text to be
displayed for the annotation or, if the annotation does not display text, an alter-
nate 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 Sec-
tion 10.8.2, “Alternate Descriptions”).
617
SECTION 8.4
Annotations
Many annotation types are defined as markup annotations because they are used
primarily to mark up PDF documents (see Table 8.20). These annotations have
text that appears as part of the annotation and may be displayed in other ways by
a viewer application, such as in a Comments pane.
Markup annotations can 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 to 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.
Note: When separating text into paragraphs, a carriage return should be used (and
not, for example, a line feed character).
Note: A subset of markup annotations are called text markup annotations (see
“Text Markup Annotations” on page 633).
The remaining annotation types are not considered markup annotations:
• The pop-up annotation type typically does not appear by itself; it is associated
with a markup annotation that uses it to display text.
Note: The Contents entry for a pop-up annotation is relevant only if it has no par-
ent; in that case, it represents the text of the annotation.
• For all other annotation types (Link, Movie, Widget, PrinterMark, and TrapNet),
the Contents entry provides an alternate representation of the annotation’s con-
tents in human-readable form, which is useful when extracting the document’s
contents in support of accessibility to users with disabilities or for other pur-
poses (see Section 10.8.2, “Alternate Descriptions”).
Table 8.21 lists entries that apply to all markup annotations.
618
CHAPTER 8
Interactive Features
TABLE 8.21 Additional entries specific to markup annotations
KEY
TYPE
VALUE
T
text string
(Optional; PDF 1.1) The text label to be displayed in the title bar of the annota-
tion’s pop-up window when open and active. By convention, this entry identifies
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.
CA
number
(Optional; PDF 1.4) The constant opacity value to be used in painting the anno-
tation (see Sections 7.1, “Overview of Transparency,” and 7.2.6, “Shape and
Opacity Computations”). This value applies to all visible elements of the annota-
tion 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 is not used if the annotation has an appearance stream (see
Section 8.4.4, “Appearance Streams”); in that case, the appearance stream must
specify any transparency. (However, if the viewer regenerates the annotation’s
appearance stream, it may incorporate the CA value into the stream’s content.)
The implicit blend mode (see Section 7.2.4, “Blend Mode”) is Normal. Default
value: 1.0.
Note: If no explicit appearance stream is defined for the annotation, it is painted by
implementation-dependent means that do not necessarily conform to the Adobe
imaging model; in this case, the effect of this entry is implementation-dependent as
well.
RC
text string or
(Optional; PDF 1.5) A rich text string (see “Rich Text Strings” on page 680) to be
text stream
displayed in the pop-up window when the annotation is opened.
CreationDate
date
(Optional; PDF 1.5) The date and time (Section 3.8.3, “Dates”) when the annota-
tion 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 must be on the
same page of the document. The relationship between the two annotations is
specified by the RT entry.
If this entry is present in an FDF file (see Section 8.6.6, “Forms Data Format”),
its type is not a dictionary but a text string containing the contents of the NM en-
try of the annotation being replied to, to allow for a situation where the annota-
tion being replied to is not in the same FDF file.
619
SECTION 8.4
Annotations
KEY
TYPE
VALUE
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 rela-
tionship (the “reply type”) between this annotation and one specified by IRT. Val-
id values are:
R
The annotation is considered a reply to the annotation specified by
IRT. Viewer applications should not display replies to an annotation
individually but together in the form of threaded comments.
Group The annotation is grouped with the annotation specified by IRT; see
discussion below.
Default value: R.
IT
name
(Optional; PDF 1.6) A name describing the intent of the markup annotation. In-
tents allow viewer applications to distinguish between different uses and behav-
iors of a single markup annotation type. If this entry is not present or its value is
the same as the annotation type, the annotation has no explicit intent and should
behave in a generic manner in a viewer application.
Free text annotations (Table 8.25), line annotations (Table 8.26), polygon anno-
tations (Table 8.29), and (in PDF 1.7) polyline annotations (Table 8.29) have de-
fined intents, whose values are enumerated in the corresponding tables.
ExData
dictionary
(Optional; PDF 1.7) An external data dictionary specifying data to be associated
with the annotation. This dictionary contains the following entries:
Type (optional): If present, must be ExData.
Subtype (required): a name specifying the type of data that the markup anno-
tation is associated with. In PDF
1.7, the only defined value is
Markup3D.
For each value of Subtype, other entries are defined. Table 9.48 on page 835
lists the values that correspond to a subtype of Markup3D. (See also
implementation note 96 in Appendix H.)
In PDF 1.6, a set of annotations can be grouped so that they function as a single
unit when a user interacts with them. The group consists of a primary annotation,
which must not have an IRT entry, and one or more subordinate annotations,
which must have an IRT entry that refers to the primary annotation and an RT en-
try whose value is Group.
Some entries in the primary annotation are treated as “group attributes” that
should apply to the group as a whole; the corresponding entries in the subordi-
620
CHAPTER 8
Interactive Features
nate annotations should 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, should be treated by
viewer applications as acting on the entire group.
Note: A primary annotation may have replies that are not subordinate annotations;
that is, that do not have an RT value of Group.
Annotation States
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 8.24). States are grouped into a number of state models, as shown
in Table 8.22.
TABLE 8.22 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 can be thought of as initially being in the default state for each state
model. State changes made by a user are indicated in a text annotation with the
following entries:
• The T entry (see Table 8.21) specifies the user.
• The IRT entry (see Table 8.24)refers to the original annotation.
• State and StateModel (see Table 8.23) update the state of the original annota-
tion for the specified user.
621
SECTION 8.4
Annotations
Additional state changes are made by adding text annotations in reply to the pre-
vious reply for a given user.
Text Annotations
A text annotation represents a “sticky note” attached to a point in the PDF docu-
ment. When closed, the annotation appears as an icon; when open, it displays a
pop-up window containing the text of the note in a font and size chosen by the
viewer application. Text annotations do not scale and rotate with the page; they
behave as if the NoZoom and NoRotate annotation flags (see Table 8.16 on page
608) were always set. Table 8.23 shows the annotation dictionary entries specific
to this type of annotation.
TABLE 8.23 Additional entries specific to a text annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Text
for a text annotation.
Open
boolean
(Optional) A flag specifying whether the annotation should initially be displayed
open. Default value: false (closed).
Name
name
(Optional) The name of an icon to be used in displaying the annotation. Viewer
applications should provide predefined icon appearances for at least the follow-
ing standard names:
Comment
Key
Note
Help
NewParagraph
Paragraph
Insert
Additional names may be supported as well. Default value: Note.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the
Name entry; see Table 8.15 on page 606 and Section 8.4.4, “Appearance Streams.”
State
text string
(Optional; PDF 1.5) The state to which the original annotation should be set; see
“Annotation States,” above.
Default: “Unmarked” if StateModel is “Marked”; “None” if StateModel is “Re-
view”.
StateModel
text string
(Required if State is present, otherwise optional; PDF 1.5) The state model corre-
sponding to State; see “Annotation States,” above.
622
CHAPTER 8
Interactive Features
Example 8.8 shows the definition of a text annotation.
Example 8.8
22 0 obj
<< /Type /Annot
/Subtype /Text
/Rect [ 266 116 430 204 ]
/Contents ( The quick brown fox ate the lazy mouse . )
>>
endobj
Link Annotations
A link annotation represents either a hypertext link to a destination elsewhere in
the document (see Section 8.2.1, “Destinations”) or an action to be performed
(Section 8.5, “Actions”). Table 8.24 shows the annotation dictionary entries spe-
cific to this type of annotation.
TABLE 8.24 Additional entries specific to a link annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Link
for a link annotation.
A
dictionary
(Optional; PDF 1.1) An action to be performed when the link annotation is ac-
tivated (see Section 8.5, “Actions”).
Dest
array, name or
(Optional; not permitted if an A entry is present) A destination to be displayed
byte string
when the annotation is activated (see Section 8.2.1, “Destinations”; see also im-
plementation note 89 in Appendix H).
H
name
(Optional; PDF 1.2) The annotation’s highlighting mode, the visual effect to 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 as if it were being pushed below the sur-
face of the page; see implementation note 90 in Appendix H.
Default value: I.
Note: In PDF 1.1, highlighting is always done by inverting colors inside the anno-
tation rectangle.
623
SECTION 8.4
Annotations
KEY
TYPE
VALUE
PA
dictionary
(Optional; PDF 1.3) A URI action (see “URI Actions” on page 662) formerly
associated with this annotation. When Web Capture (Section 10.9, “Web Cap-
ture”) changes an annotation from a URI to a go-to action (“Go-To Actions”
on page 654), 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 subse-
quently 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
x1 y1 x2 y2 x3 y3 x4 y4
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 (x1 , y1) and (x2 , y2).
If this entry is not present or the viewer application does not recognize it, the
region specified by the Rect entry should be used. QuadPoints should be ig-
nored if any coordinate in the array lies outside the region specified by Rect.
Example 8.9 shows a link annotation that jumps to a destination elsewhere in the
document.
Example 8.9
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
Free Text Annotations
A free text annotation (PDF 1.3) displays text directly on the page. Unlike an ordi-
nary text annotation (see “Text Annotations” on page 621), a free text annotation
has no open or closed state; instead of being displayed in a pop-up window, the
text is always visible. Table 8.25 shows the annotation dictionary entries specific
to this type of annotation. “Variable Text” on page 677 describes the process of
using these entries to generate the appearance of the text in these annotations.
624
CHAPTER 8
Interactive Features
TABLE 8.25 Additional entries specific to a free text annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be
FreeText for a free text annotation.
DA
string
(Required) The default appearance string to be used in formatting the text (see
“Variable Text” on page 677).
Note: The annotation dictionary’s AP entry, if present, takes precedence over the DA
entry; see Table 8.15 on page 606 and Section 8.4.4, “Appearance Streams.”
Q
integer
(Optional; PDF 1.4) A code specifying the form of quadding (justification) to 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
(Optional; PDF 1.5) A rich text string (see “Rich Text Strings” on page 680) to be
text stream
used to generate the appearance of the annotation.
DS
text string
(Optional; PDF 1.5) A default style string, as described in “Rich Text Strings” on
page 680.
CL
array
(Optional; PDF 1.6) An array of four or six numbers specifying a callout line at-
tached to the free text annotation. Six numbers [ x1 y1 x2 y2 x3 y3 ] represent
the starting, knee point, and ending coordinates of the line in default user space,
as shown in Figure 8.4. Four numbers [ x1 y1 x2 y2 ] 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 Table 8.21). Valid values are FreeTextCallout, which means that the annota-
tion is intended to function as a callout, and FreeTextTypeWriter, which means
that the annotation is intended to function as a click-to-type or typewriter ob-
ject.
BE
dictionary
(Optional; PDF 1.6) A border effect dictionary (see Table 8.18) used in conjunc-
tion with the border style dictionary specified by the BS entry.
625
SECTION 8.4
Annotations
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 con-
tained 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, are 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 rectan-
gle, respectively. Each value must be greater than or equal to 0. The sum of the
top and bottom differences must be less than the height of Rect, and the sum of
the left and right differences must be less than the width of Rect.
BS
dictionary
(Optional; PDF 1.6) A border style dictionary (see Table 8.17 on page 611) speci-
fying the line width and dash pattern to be used in drawing the annotation’s bor-
der.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the In-
kList and BS entries; see Table 8.15 on page 606 and Section 8.4.4, “Appearance
Streams.”
LE
array
(Optional; PDF 1.6) An array of two names specifying the line ending styles to be
used in drawing the annotation’s border. The first and second elements of the ar-
ray specify the line ending styles for the endpoints defined, respectively, by the
first and second pairs of coordinates, (x1 , y1 ) and (x2 , y2 ), in the L array. Table
8.27 shows the possible values. Default value: [ /None /None ].
Free text with callouts
x2, y2
x3, y3
x1, y1
FIGURE 8.4 Free text annotation with callout
626
CHAPTER 8
Interactive Features
Line Annotations
A line annotation (PDF 1.3) displays a single straight line on the page. When
opened, it displays a pop-up window containing the text of the associated note.
Table 8.26 shows the annotation dictionary entries specific to this type of anno-
tation.
TABLE 8.26 Additional entries specific to a line annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Line
for a line annotation.
L
array
(Required) An array of four numbers, [ x1 y1 x2 y2 ], specifying the starting and
ending coordinates of the line in default user space.
Note: If the LL entry is present, this value represents the endpoints of the leader
lines rather than the endpoints of the line itself; see Figure 8.5.
BS
dictionary
(Optional) A border style dictionary (see Table 8.17 on page 611) specifying the
width and dash pattern to be used in drawing the line.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the L
and BS entries; see Table 8.15 on page 606 and Section 8.4.4, “Appearance Streams.”
LE
array
(Optional; PDF 1.4) An array of two names specifying the line ending styles to be
used in drawing the line. The first and second elements of the array specify the
line ending styles for the endpoints defined, respectively, by the first and second
pairs of coordinates, (x1 , y1 ) and (x2 , y2 ), in the L array. Table 8.27 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 with which to fill the annotation’s line endings (see Table 8.27). The
number of array elements determines the color space in which the color is de-
fined:
0
No color; transparent
1
DeviceGray
3
DeviceRGB
4
DeviceCMYK
627
SECTION 8.4
Annotations
KEY
TYPE
VALUE
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 8.5. A positive value means that the leader lines
appear in the direction that is clockwise when traversing the line from its start-
ing point to its ending point (as specified by L); a negative value indicates the op-
posite direction.
Default value: 0 (no leader lines).
LLE
number
(Optional; PDF 1.6) A non-negative number representing the length of leader
line extensions that extend from the line proper 180 degrees from the leader
lines, as shown in Figure 8.5.
Default value: 0 (no leader line extensions).
Cap
boolean
(Optional; PDF 1.6) If true, the text specified by the Contents or RC entries
should be replicated as a caption in the appearance of the line, as shown in Fig-
ure 8.6 and Figure 8.7. The text should 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 8.21). Valid values are LineArrow, which means that the annotation is in-
tended to function as an arrow, and LineDimension, which means that the anno-
tation is intended to function as a dimension line.
LLO
number
(Optional; PDF 1.7) A non-negative number representing the length of the lead-
er 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 anno-
tation’s caption positioning. Valid values are Inline, meaning the caption will be
centered inside the line, and Top, meaning the caption will be on top of the line.
Default value: Inline
Measure
dictionary
(Optional; PDF 1.7) A measure dictionary (see Table 8.110) that specifies the
scale and units that apply to the line annotation.
628
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
CO
array
(Optional; meaningful only if Cap is true; PDF 1.7) An array of two numbers
specifying the offset of the caption text from its normal position. The first value
is the horizontal offset along the annotation line from its midpoint, with a posi-
tive value indicating offset to the right and a negative value indicating offset to
the left. The second value is 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)
/LLE 10 -- 10 point leader
line extension
/LL 50 -- 50 point leader line
/LLO 10 -- 10 point leader
line offset
/LLO 10 -- 10 point leader
line offset
/LL -50 -- 50 point inverse
leader line
/LLE 10 -- 10 point leader
line extension
FIGURE 8.5 Leader lines
629
SECTION 8.4
Annotations
Figure 8.6 illustrates the effect of including a caption to a line annotation, which
is specified by setting Cap to true.
This is an inside caption
This is a top caption
This is a caption that is longer than the line
FIGURE 8.6 Lines with captions appearing as part of the line
Figure 8.7 illustrates the effect of applying a caption to a line annotation that has a
leader offset.
This is an offset caption
/CO [30, 15] -- 30 point horizontal offset along the annotation line
and 15 point vertical offset perpendicular to the annotation line
FIGURE 8.7 Line with a caption appearing as part of the offset
630
CHAPTER 8
Interactive Features
TABLE 8.27 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 (see
above) 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
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
Square and circle annotations (PDF 1.3) display, respectively, a rectangle or an
ellipse on the page. When opened, they display a pop-up window containing the
text of the associated note. The rectangle or ellipse is inscribed within the annota-
tion rectangle defined by the annotation dictionary’s Rect entry (see Table 8.15 on
page 606). Figure 8.8 shows two annotations, each with a border width of 18
points. Despite the names square and circle, the width and height of the annota-
tion rectangle need not be equal. Table 8.28 shows the annotation dictionary en-
tries specific to these types of annotations.
631
SECTION 8.4
Annotations
Rect
18 pt
18 pt
Square annotation
Circle annotation
FIGURE 8.8 Square and circle annotations
TABLE 8.28 Additional entries specific to a square or circle annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Square
or Circle for a square or circle annotation, respectively.
BS
dictionary
(Optional) A border style dictionary (see Table 8.17 on page 611) specifying the
line width and dash pattern to be used in drawing the rectangle or ellipse.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the
Rect and BS entries; see Table 8.15 on page 606 and Section 8.4.4, “Appearance
Streams.”
IC
array
(Optional; PDF 1.4) An array of numbers in the range 0.0 to 1.0 specifying the
interior color with which to fill the annotation’s rectangle or ellipse. The number
of array elements determines the color space in which the color is defined:
0
No color; 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 8.18).
632
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
RD
rectangle
(Optional; PDF 1.5) A set of four numbers describing the numerical differences
between two rectangles: the Rect entry of the annotation and the actual bound-
aries of the underlying square or circle. Such a difference can occur in situations
where a border effect (described by BE) causes the size of the Rect to increase be-
yond that of the square or circle.
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 square or cir-
cle, respectively. Each value must be greater than or equal to 0. The sum of the
top and bottom differences must be less than the height of Rect, and the sum of
the left and right differences must be less than the width of Rect.
Polygon and Polyline Annotations
Polygon annotations (PDF 1.5) display closed polygons on the page. Such poly-
gons may have any number of vertices connected by straight lines. Polyline anno-
tations (PDF 1.5) are similar to polygons, except that the first and last vertex are
not implicitly connected.
TABLE 8.29 Additional entries specific to a polygon or polyline annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be
Polygon or PolyLine for a polygon or polyline annotation, respectively.
Vertices
array
(Required) An array of numbers representing the alternating horizontal and ver-
tical coordinates, respectively, of each vertex, in default user space.
LE
array
(Optional; meaningful only for polyline annotations) An array of two names spec-
ifying the line ending styles. The first and second elements of the array specify
the line ending styles for the endpoints defined, respectively, by the first and last
pairs of coordinates in the Vertices array. Table 8.27 shows the possible values.
Default value: [ /None /None ].
BS
dictionary
(Optional) A border style dictionary (see Table 8.17 on page 611) specifying the
width and dash pattern to be used in drawing the line.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the
Vertices and BS entries; see Table 8.15 on page 606 and Section 8.4.4, “Appearance
Streams.”
633
SECTION 8.4
Annotations
KEY
TYPE
VALUE
IC
array
(Optional; PDF 1.4) An array of numbers in the range 0.0 to 1.0 specifying the
interior color with which to fill the annotation’s line endings (see Table 8.27). The
number of array elements determines the color space in which the color is de-
fined:
0
No color; transparent
1
DeviceGray
3
DeviceRGB
4
DeviceCMYK
BE
dictionary
(Optional; meaningful only for polygon annotations) A border effect dictionary de-
scribing an effect applied to the border described by the BS entry (see Table
8.18).
IT
name
(Optional; PDF 1.6) A name describing the intent of the polygon or polyline an-
notation (see also Table 8.21). The following values are valid:
PolygonCloud, which means that the annotation is intended to function as a
cloud object
PolyLineDimension (PDF 1.7), which indicates that the polyline annotation is
intended to function as a dimension
PolygonDimension (PDF 1.7), which indicates that the polygon annotation is
intended to function as a dimension
Measure
dictionary
(Optional; PDF 1.7) A measure dictionary (see Table 8.110) that specifies the
scale and units that apply to the annotation.
Text Markup Annotations
Text markup annotations 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 display a pop-up window containing the text of the associated note.
Table 8.30 shows the annotation dictionary entries specific to these types of an-
notations.
634
CHAPTER 8
Interactive Features
TABLE 8.30 Additional entries specific to text markup annotations
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must 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 quadri-
laterals in default user space. Each quadrilateral encompasses a word or
group of contiguous words in the text underlying the annotation. The coordi-
nates for each quadrilateral are given in the order
x1 y1 x2 y2 x3 y3 x4 y4
specifying the quadrilateral’s four vertices in counterclockwise order (see
Figure 8.9). The text is oriented with respect to the edge connecting points
(x1 , y1) and (x2 , y2). (See implementation note 92 in Appendix H.)
Note: The annotation dictionary’s AP entry, if present, takes precedence over
QuadPoints; see Table 8.15 and Section 8.4.4, “Appearance Streams.”
(x3 , y3 )
(x2 , y2 )
(x4 , y4 )
(x1 , y1 )
FIGURE 8.9 QuadPoints specification
Caret Annotations
A caret annotation (PDF 1.5) is a visual symbol that indicates the presence of text
edits. Table 8.31 lists the entries specific to caret annotations.
635
SECTION 8.4
Annotations
TABLE 8.31 Additional entries specific to a caret annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Caret
for a caret annotation.
RD
rectangle
(Optional; PDF 1.5) A set of four numbers describing the numerical differences
between two rectangles: the Rect entry of the annotation and the actual bound-
aries of the underlying caret. Such a difference can occur, for example, when a
paragraph symbol specified by Sy is displayed along with the caret.
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 caret, respec-
tively. Each value must be greater than or equal to 0. The sum of the top and bot-
tom differences must be less than the height of Rect, and the sum of the left and
right differences must be less than the width of Rect.
Sy
name
(Optional) A name specifying a symbol to 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.
Rubber Stamp Annotations
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 displays a
pop-up window containing the text of the associated note. Table 8.32 shows the
annotation dictionary entries specific to this type of annotation.
TABLE 8.32 Additional entries specific to a rubber stamp annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Stamp
for a rubber stamp annotation.
636
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
Name
name
(Optional) The name of an icon to be used in displaying the annotation. Viewer
applications should provide predefined icon appearances for at least the follow-
ing 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.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the
Name entry; see Table 8.15 on page 606 and Section 8.4.4, “Appearance Streams.”
Ink Annotations
An ink annotation (PDF 1.3) represents a freehand “scribble” composed of one or
more disjoint paths. When opened, it displays a pop-up window containing the
text of the associated note. Table 8.33 shows the annotation dictionary entries
specific to this type of annotation.
TABLE 8.33 Additional entries specific to an ink annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Ink for
an ink annotation.
InkList
array
(Required) An array of n arrays, each representing a stroked path. Each array is a
series of alternating horizontal and vertical coordinates in default user space,
specifying points along the path. When drawn, the points are connected by
straight lines or curves in an implementation-dependent way. (See implementa-
tion note 93 in Appendix H.)
BS
dictionary
(Optional) A border style dictionary (see Table 8.17 on page 611) specifying the
line width and dash pattern to be used in drawing the paths.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the In-
kList and BS entries; see Table 8.15 on page 606 and Section 8.4.4, “Appearance
Streams.”
637
SECTION 8.4
Annotations
Pop-up Annotations
A pop-up annotation (PDF 1.3) displays text in a pop-up window for entry and
editing. It typically does not appear alone but is associated with a markup annota-
tion, its parent annotation, and is used for editing the parent’s text. It has no
appearance stream or associated actions of its own and is identified by the Popup
entry in the parent’s annotation dictionary (see Table 8.21 on page 618). Table
8.34 shows the annotation dictionary entries specific to this type of annotation.
TABLE 8.34 Additional entries specific to a pop-up annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be
Popup for a pop-up annotation.
Parent
dictionary
(Optional; must be an indirect reference) The parent annotation with which
this pop-up annotation is associated.
Note: If this entry is present, the parent annotation’s Contents, M, C, and T
entries (see Table 8.15 on page 606) override those of the pop-up annotation
itself.
Open
boolean
(Optional) A flag specifying whether the pop-up annotation should initially
be displayed open. Default value: false (closed).
File Attachment Annotations
A file attachment annotation (PDF 1.3) contains a reference to a file, which typi-
cally is embedded in the PDF file (see Section 3.10.3, “Embedded File Streams”);
see implementation note 95 in Appendix H. 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 extracts the embedded file and gives the user an oppor-
tunity to view it or store it in the file system. Table 8.35 shows the annotation dic-
tionary entries specific to this type of annotation.
The Contents entry of the annotation dictionary may specify descriptive text re-
lating to the attached file. Viewer applications should use this entry rather than
the optional Desc entry (PDF 1.6) in the file specification dictionary (see Table
3.41) identified by the annotation’s FS entry; see implementation note 95 in Ap-
pendix H.
638
CHAPTER 8
Interactive Features
TABLE 8.35 Additional entries specific to a file attachment annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must 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 to be used in displaying the annotation.
Viewer applications should provide predefined icon appearances for at least
the following standard names:
Graph
PushPin
Paperclip
Tag
Additional names may be supported as well. Default value: PushPin.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the
Name entry; see Table 8.15 on page 606 and Section 8.4.4, “Appearance
Streams.”
Sound Annotations
A sound annotation (PDF 1.2) is analogous to a text annotation except that in-
stead 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 is played.
The annotation behaves like a text annotation in most ways, with a different icon
(by default, a speaker) to indicate that it represents a sound. Table 8.36 shows the
annotation dictionary entries specific to this type of annotation. Sound objects
are discussed in Section 9.2, “Sounds.”
TABLE 8.36 Additional entries specific to a sound annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Sound
for a sound annotation.
Sound
stream
(Required) A sound object defining the sound to be played when the annotation
is activated (see Section 9.2, “Sounds”).
639
SECTION 8.4
Annotations
KEY
TYPE
VALUE
Name
name
(Optional) The name of an icon to be used in displaying the annotation. Viewer
applications should provide predefined icon appearances for at least the stan-
dard names Speaker and Mic. Additional names may be supported as well. De-
fault value: Speaker.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the
Name entry; see Table 8.15 on page 606 and Section 8.4.4, “Appearance Streams.”
Movie Annotations
A movie annotation (PDF 1.2) contains animated graphics and sound to be pre-
sented on the computer screen and through the speakers. When the annotation is
activated, the movie is played. Table 8.37 shows the annotation dictionary entries
specific to this type of annotation. Movies are discussed in Section 9.3, “Movies.”
TABLE 8.37 Additional entries specific to a movie annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Movie
for a movie annotation.
T
text string
(Optional) The title of the movie annotation. Movie actions (page 664) can use
this title to reference the movie annotation.
Movie
dictionary
(Required) A movie dictionary describing the movie’s static characteristics (see
Section 9.3, “Movies”).
A
boolean or
(Optional) A flag or dictionary specifying whether and how to play the movie
dictionary
when the annotation is activated. If this value is a dictionary, it is a movie activa-
tion dictionary (see Section 9.3, “Movies”) specifying how to play the movie. If
the value is the boolean true, the movie should be played using default activation
parameters. If the value is false, the movie should not be played. Default value:
true.
Screen Annotations
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.
“Rendition Actions” on page 668 discusses the relationship between screen anno-
tations and rendition actions. Table 8.38 shows the annotation dictionary entries
specific to this type of annotation.
640
CHAPTER 8
Interactive Features
TABLE 8.38 Additional entries specific to a screen annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must 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 8.40). The I entry
of this dictionary provides the icon used in generating the appearance referred
to by the screen annotation’s AP entry.
A
dictionary
(Optional; PDF 1.1) An action to be performed when the annotation is activated
(see Section 8.5, “Actions”).
AA
dictionary
(Optional; PDF 1.2) An additional-actions dictionary defining the screen anno-
tation’s behavior in response to various trigger events (see Section 8.5.2, “Trigger
Events”).
In addition to the above entries, screen annotations use the common entries in
the annotation dictionary (see Table 8.15) in the following ways:
• The P entry is required for a screen annotation referenced by a rendition ac-
tion. It must reference a valid page object, and the annotation must be present
in the page’s Annots array for the action to be valid.
• The AP entry refers to an appearance dictionary (see Table 8.19) whose normal
appearance provides the visual appearance for a screen annotation that is used
for printing and default display when a media clip is not being played. If AP is
not present, the screen annotation has no default visual appearance and is not
printed.
Widget Annotations
Interactive forms (see Section 8.6, “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 (Section 8.6.2, “Field Dictionaries”) and the anno-
tation dictionary can be merged into a single dictionary containing entries that
pertain to both a field and an annotation. (This presents no ambiguity, since the
contents of the two kinds of dictionaries do not conflict.) Table 8.39 shows the
641
SECTION 8.4
Annotations
annotation dictionary entries specific to this type of annotation; interactive forms
and fields are discussed at length in Section 8.6.
TABLE 8.39 Additional entries specific to a widget annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be Widget
for a widget annotation.
H
name
(Optional) The annotation’s highlighting mode, the visual effect to 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 Section
8.4.4, “Appearance Streams”). If no down appearance is defined, offset
the contents of the annotation rectangle 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 overrides any down appearance defined for
the annotation. Default value: I.
MK
dictionary
(Optional) An appearance characteristics dictionary (see Table 8.40) to 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.
A
dictionary
(Optional; PDF 1.1) An action to be performed when the annotation is activated
(see Section 8.5, “Actions”).
AA
dictionary
(Optional; PDF 1.2) An additional-actions dictionary defining the annotation’s
behavior in response to various trigger events (see Section 8.5.2,
“Trigger
Events”).
BS
dictionary
(Optional; PDF 1.2) A border style dictionary (see Table 8.17 on page 611) speci-
fying the width and dash pattern to be used in drawing the annotation’s border.
Note: The annotation dictionary’s AP entry, if present, takes precedence over the L
and BS entries; see Table 8.15 on page 606 and Section 8.4.4, “Appearance Streams.”
642
CHAPTER 8
Interactive Features
The MK entry can be used to provide an appearance characteristics dictionary con-
taining additional information for constructing the annotation’s appearance
stream. Table 8.40 shows the contents of this dictionary.
TABLE 8.40 Entries in an appearance characteristics dictionary
KEY
TYPE
VALUE
R
integer
(Optional) The number of degrees by which the widget annotation is rotated
counterclockwise relative to the page. The value must be a multiple of 90.
Default value: 0.
BC
array
(Optional) An array of numbers in the range 0.0 to 1.0 specifying the color of the
widget annotation’s border. The number of array elements determines the color
space in which the color is defined:
0
No color; transparent
1
DeviceGray
3
DeviceRGB
4
DeviceCMYK
BG
array
(Optional) An array of numbers in the range 0.0 to 1.0 specifying the color of the
widget annotation’s background. The number of array elements determines the
color space, as described above for BC.
CA
text string
(Optional; button fields only) The widget annotation’s normal caption, displayed
when it is not interacting with the user.
Note: Unlike the remaining entries listed below, which apply only to widget annota-
tions associated with pushbutton fields (see “Pushbuttons” on page 686), the CA
entry can be used with any type of button field, including check boxes (“Check Box-
es” on page 686) and radio buttons (“Radio Buttons” on page 688).
RC
text string
(Optional; pushbutton fields only) The widget annotation’s rollover caption, dis-
played when the user rolls the cursor into its active area without pressing the
mouse button.
AC
text string
(Optional; pushbutton fields only) The widget annotation’s alternate (down)
caption, displayed when the mouse button is pressed within its active area.
I
stream
(Optional; pushbutton fields only; must be an indirect reference) A form XObject
defining the widget annotation’s normal icon, displayed when it is not interacting
with the user.
Большое спасибо!
Ваше мнение очень важно для нас.
Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.
Текст