42
Actions
SECTION 8.5
647
In situations other than the usual case where the PDF page size equals the printed
page size, watermark annotations with a
FixedPrint
entry should be printed in the
following manner:
•
When page tiling is selected in a viewer application (that is, a single PDF page
is printed on multiple pages), the annotations are printed at the specified size
and position on each page to ensure that any enclosed content is present and
legible on each printed page.
•
When n-up printing is selected (that is, multiple PDF pages are printed on a
single page), the annotations are printed at the specified size and are positioned
as if the dimensions of the printed page were limited to a single portion of the
page. This ensures that any enclosed content does not overlap content from
other pages, thus rendering it illegible. (See implementation note 97 in Appen-
dix H.)
8.5 Actions
Instead of simply jumping to a destination in the document, an annotation or
outline item can specify an action (PDF 1.1) for the viewer application to per-
form, such as launching an application, playing a sound, or changing an annota-
tion’s appearance state. The optional
A
entry in the annotation or outline item
dictionary (see Tables 8.15 on page 606 and 8.4 on page 585) specifies an action
to be performed when the annotation or outline item is activated; in PDF 1.2, a
variety of other circumstances may trigger an action as well (see Section 8.5.2,
“Trigger Events”). In addition, the optional
OpenAction
entry in a document’s
catalog (Section 3.6.1, “Document Catalog”) may specify an action to be per-
formed when the document is opened. PDF includes a wide variety of standard
action types, described in detail in Section 8.5.3, “Action Types.”
8.5.1 Action Dictionaries
An action dictionary defines the characteristics and behavior of an action. Table
8.43 shows the required and optional entries that are common to all action
dictionaries. The dictionary may contain additional entries specific to a particu-
lar action type; see the descriptions of individual action types in Section 8.5.3,
“Action Types,” for details.
57
Interactive Features
CHAPTER 8
648
TABLE 8.43 Entries common to all action dictionaries
The action dictionary’s
Next
entry (PDF 1.2) allows sequences of actions to be
chained together. For example, the effect of clicking a link annotation with the
mouse might be to play a sound, jump to a new page, and start up a movie. Note
that the
Next
entry is not restricted to a single action but may contain an array of
actions, each of which in turn may have a
Next
entry of its own. The actions may
thus form a tree instead of a simple linked list. Actions within each
Next
array are
executed in order, each followed in turn by any actions specified in its
Next
entry,
and so on recursively. Viewer applications should attempt to provide reasonable
behavior in anomalous situations. For example, self-referential actions should not
be executed more than once, and actions that close the document or otherwise
render the next action impossible should terminate the execution sequence.
Applications should also provide some mechanism for the user to interrupt and
manually terminate a sequence of actions.
PDF 1.5 introduces transition actions, which allow the control of drawing during
a sequence of actions; see “Transition Actions” on page 670.
Note: No action should modify its own action dictionary or any other in the action
tree in which it resides. The effect of such modification on subsequent execution of
actions in the tree is undefined.
8.5.2 Trigger Events
An annotation, page object, or (beginning with PDF 1.3) interactive form field
may include an entry named
AA
that specifies an additional-actions dictionary
(PDF 1.2) that extends the set of events that can trigger the execution of an ac-
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, must be
Action
for an action dictionary.
S
name
(Required) The type of action that this dictionary describes; see Table 8.48
on page 653 for specific values.
Next
dictionary or array
(Optional; PDF 1.2) The next action or sequence of actions to be per-
formed after the action represented by this dictionary. The value is either
a single action dictionary or an array of action dictionaries to be per-
formed in order; see below for further discussion.
70
Actions
SECTION 8.5
649
tion. In PDF 1.4, the document catalog dictionary (see Section 3.6.1, “Document
Catalog”) may also contain an
AA
entry for trigger events affecting the document
as a whole. Tables 8.44 to 8.47 show the contents of this type of dictionary. (See
implementation notes 98 and 99 in Appendix H.)
PDF 1.5 introduces four trigger events to support multimedia presentations:
•
The
PO
and
PC
entries have a similar function to the
O
and
C
entries in the page
object’s additional-actions dictionary (see Table 8.45). However, associating
these triggers with annotations allows annotation objects to be self-contained
and greatly simplifies authoring. For example, annotations containing such ac-
tions can be copied or moved between pages without requiring page open/close
actions to be changed.
•
The
PV
and
PI
entries allow a distinction between pages that are open and pages
that are visible. At any one time, only a single page is considered open in the
viewer application, while more than one page may be visible, depending on the
page layout.
Note: For these trigger events, the values of the flags specified by the annotation’s
F
entry (see Section 8.4.2, “Annotation Flags”) have no bearing on whether a given
trigger event occurs.
TABLE 8.44 Entries in an annotation’s additional-actions dictionary
KEY
TYPE
VALUE
E
dictionary
(Optional; PDF 1.2) An action to be performed when the cursor enters the annotation’s
active area.
X
dictionary
(Optional; PDF 1.2) An action to be performed when the cursor exits the annotation’s
active area.
D
dictionary
(Optional; PDF 1.2) An action to be performed when the mouse button is pressed
inside the annotation’s active area. (The name
D
stands for “down.”)
U
dictionary
(Optional; PDF 1.2) An action to be performed when the mouse button is released
inside the annotation’s active area. (The name
U
stands for “up.”)
Note: For backward compatibility, the
A
entry in an annotation dictionary, if present,
takes precedence over this entry (see Table 8.15 on page 606).
Fo
dictionary
(Optional; PDF 1.2; widget annotations only) An action to be performed when the
annotation receives the input focus.
56
Interactive Features
CHAPTER 8
650
TABLE 8.45 Entries in a page object’s additional-actions dictionary
Bl
dictionary
(Optional; PDF 1.2; widget annotations only) (Uppercase B, lowercase L) An action to
be performed when the annotation loses the input focus. (The name
Bl
stands for
“blurred.”)
PO
dictionary
(Optional; PDF 1.5) An action to be performed when the page containing the annota-
tion is opened (for example, when the user navigates to it from the next or previous
page or by means of a link annotation or outline item). The action is executed after the
O
action in the page’s additional-actions dictionary (see Table 8.45) and the
OpenAction
entry in the document catalog (see Table 3.25), if such actions are present.
PC
dictionary
(Optional; PDF 1.5) An action to be performed when the page containing the annota-
tion is closed (for example, when the user navigates to the next or previous page, or fol-
lows a link annotation or outline item). The action is executed before the
C
action in
the page’s additional-actions dictionary (see Table 8.45), if present.
PV
dictionary
(Optional; PDF 1.5) An action to be performed when the page containing the annota-
tion becomes visible in the viewer application’s user interface.
PI
dictionary
(Optional; PDF 1.5) An action to be performed when the page containing the annota-
tion is no longer visible in the viewer application’s user interface.
KEY
TYPE
VALUE
O
dictionary
(Optional; PDF 1.2) An action to be performed when the page is opened (for example,
when the user navigates to it from the next or previous page or by means of a link an-
notation or outline item). This action is independent of any that may be defined by the
OpenAction
entry in the document catalog (see Section 3.6.1, “Document Catalog”)
and is executed after such an action. (See implementation note 100 in Appendix H.)
C
dictionary
(Optional; PDF 1.2) An action to be performed when the page is closed (for example,
when the user navigates to the next or previous page or follows a link annotation or an
outline item). This action applies to the page being closed and is executed before any
other page is opened. (See implementation note 100 in Appendix H.)
KEY
TYPE
VALUE
Documents you may be interested
Documents you may be interested
