71
©
Adobe Systems Incorporated 2008 – All rights reserved
413
PDF 32000-1:2008
b) Content removal. The user instructs the viewer application to apply the redact annotations, after which the
content in the area specified by the redact annotations is removed. In the removed content’s place, some
marking appears to indicate the area has been redacted. Also, the redact annotations are removed from
the PDF document.
Redaction annotations provide a mechanism for the first step in the redaction process (content identification).
This allows content to be marked for redaction in a non-destructive way, thus enabling a review process for
evaluating potential redactions prior to removing the specified content.
Redaction annotations shall provide enough information to be used in the second phase of the redaction
process (content removal). This phase is application-specific and requires the conforming reader to remove all
content identified by the redaction annotation, as well as the annotation itself.
Conforming readers that support redaction annotations shall provide a mechanism for applying content
removal, and they shall remove all traces of the specified content. If a portion of an image is contained in a
redaction region, that portion of the image data shall be destroyed; clipping or image masks shall not be used
to hide that data. Such conforming readers shall also be diligent in their consideration of all content that can
exist in a PDF document, including XML Forms Architecture (XFA) content and Extensible Metadata Platform
(XMP) content.
Table 192 – Additional entries specific to a redaction annotation
Key
Type
Value
Subtype
name
(Required) The type of annotation that this dictionary describes; shall
be Redact for a redaction annotation.
QuadPoints
array
(Optional) An array of 8 x n numbers specifying the coordinates of n
quadrilaterals in default user space, as described in Table 175 for text
markup annotations. If present, these quadrilaterals denote the
content region that is intended to be removed. If this entry is not
present, the Rect entry denotes the content region that is intended to
be removed.
IC
array
(Optional) An array of three numbers in the range 0.0 to 1.0
specifying the components, in the DeviceRGB colour space, of the
interior colour with which to fill the redacted region after the affected
content has been removed. If this entry is absent, the interior of the
redaction region is left transparent. This entry is ignored if the RO
entry is present.
RO
stream
(Optional) A form XObject specifying the overlay appearance for this
redaction annotation. After this redaction is applied and the affected
content has been removed, the overlay appearance should be drawn
such that its origin lines up with the lower-left corner of the annotation
rectangle. This form XObject is not necessarily related to other
annotation appearances, and may or may not be present in the AP
dictionary. This entry takes precedence over the IC , OverlayText,
DA, and Q entries.
OverlayText
text string
(Optional) A text string specifying the overlay text that should be
drawn over the redacted region after the affected content has been
removed. This entry is ignored if the RO entry is present.
Repeat
boolean
(Optional) If true , then the text specified by OverlayText should be
repeated to fill the redacted region after the affected content has been
removed. This entry is ignored if the RO entry is present. Default
value: false.
DA
byte string
(Required if OverlayText is present, ignored otherwise ) The
appearance string to be used in formatting the overlay text when it is
drawn after the affected content has been removed (see 12.7.3.3,
“Variable Text”). This entry is ignored if the RO entry is present.
66
PDF 32000-1:2008
414
©
Adobe Systems Incorporated 2008 – All rights reserved
12.6
Actions
12.6.1
General
In addition to jumping to a destination in the document, an annotation or outline item may specify an action
(PDF 1.1) to perform, such as launching an application, playing a sound, changing an annotation’s appearance
state. The optional A entry in the annotation or outline item dictionary (see Tables 168 and 153) specifies an
action 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 12.6.3, “Trigger Events”). In addition, the optional OpenAction entry in a
document’s catalogue (7.7.2, “Document Catalog”) may specify an action that shall be performed when the
document is opened. PDF includes a wide variety of standard action types, described in detail in 12.6.4, “Action
Types.”
12.6.2
Action Dictionaries
An action dictionary defines the characteristics and behaviour of an action. Table 193 shows the required and
optional entries that are common to all action dictionaries. The dictionary may contain additional entries specific
to a particular action type; see the descriptions of individual action types in 12.6.4, “Action Types,” for details.
NOTE 1
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. Conforming readers 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
12.6.4.14, “Transition Actions.”
Q
integer
(Optional) A code specifying the form of quadding (justification) to be
used in laying out the overlay text:
0 Left-justified
1 Centered
2 Right-justified
This entry is ignored if the RO entry is present. Default value: 0 (left-
justified).
Table 193 – Entries common to all action dictionaries
Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, shall be Action for an action dictionary.
S
name
(Required) The type of action that this dictionary describes; see
Table 194 for specific values.
Next
dictionary or array
(Optional; PDF 1.2) The next action or sequence of actions that
shall be performed after the action represented by this dictionary.
The value is either a single action dictionary or an array of action
dictionaries that shall be performed in order; see the Note for
further discussion.
Table 192 – Additional entries specific to a redaction annotation (continued)
Key
Type
Value
70
©
Adobe Systems Incorporated 2008 – All rights reserved
415
PDF 32000-1:2008
NOTE 2
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.
12.6.3
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 action. In PDF 1.4, the document catalogue dictionary (see 7.7.2, “Document Catalog”) may
also contain an AA entry for trigger events affecting the document as a whole. Tables 194 to 197 show the
contents of this type of dictionary.
PDF 1.5 introduces four trigger events in annotation’s additional-actions dictionary 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 194). However, associating these triggers with annotations allows annotation
objects to be self-contained.
EXAMPLE
Annotations containing such actions 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, while more than one page may be visible, depending on the page layout.
NOTE 1
For these trigger events, the values of the flags specified by the annotation’s F entry (see 12.5.3, “Annotation
Flags”) have no bearing on whether a given trigger event occurs.
Table 194 – Entries in an annotation’s additional-actions dictionary
Key
Type
Value
E
dictionary
(Optional; PDF 1.2) An action that shall be performed when the cursor enters
the annotation’s active area.
X
dictionary
(Optional; PDF 1.2) An action that shall be performed when the cursor exits the
annotation’s active area.
D
dictionary
(Optional; PDF 1.2) An action that shall be performed when the mouse button is
pressed inside the annotation’s active area.
U
dictionary
(Optional; PDF 1.2) An action that shall be performed when the mouse button is
released inside the annotation’s active area.
For backward compatibility, the A entry in an
annotation dictionary, if present,
takes precedence over this entry (see Table 168).
Fo
dictionary
(Optional; PDF 1.2; widget annotations only) An action that shall be performed
when the annotation receives the input focus.
Bl
dictionary
(Optional; PDF 1.2; widget annotations only) (Uppercase B, lowercase L) An
action that shall be performed when the annotation loses the input focus.
PO
dictionary
(Optional; PDF 1.5) An action that shall be performed when the page containing
the annotation is opened.
EXAMPLE 1
When the user navigates to it from the next or previous page
or by means of a link annotation or outline item.
The action shall be executed after the O action in the page’s additional-actions
dictionary (see Table 195) and the OpenAction entry in the document Catalog
(see Table 28), if such actions are present.
70
PDF 32000-1:2008
416
©
Adobe Systems Incorporated 2008 – All rights reserved
PC
dictionary
(Optional; PDF 1.5) An action that shall be performed when the page containing
the annotation is closed.
EXAMPLE 2
When the user navigates to the next or previous page, or
follows a link annotation or outline item.
The action shall be executed before the C action in the page’s additional-
actions dictionary (see Table 195), if present.
PV
dictionary
(Optional; PDF 1.5) An action that shall be performed when the page containing
the annotation becomes visible.
PI
dictionary
(Optional; PDF 1.5) An action that shall be performed when the page containing
the annotation is no longer visible in the conforming reader’s user interface.
Table 195 – Entries in a page object’s additional-actions dictionary
Key
Type
Value
O
dictionary
(Optional; PDF 1.2) An action that shall 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 annotation or outline item). This action is independent of any
that may be defined by the OpenAction entry in the document Catalog (see
7.7.2, “Document Catalog”) and shall be executed after such an action.
C
dictionary
(Optional; PDF 1.2) An action that shall 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 shall be executed before any other page is opened.
Table 196 – Entries in a form field’s additional-actions dictionary
Key
Type
Value
K
dictionary
(Optional; PDF 1.3) A JavaScript action that shall be performed when the user
modifies a character in a text field or combo box or modifies the selection in a
scrollable list box. This action may check the added text for validity and reject or
modify it.
F
dictionary
(Optional; PDF 1.3) A
JavaScript action that shall be performed before the field
is formatted to display its value. This action may modify the field’s value before
formatting.
V
dictionary
(Optional; PDF 1.3) A JavaScript action that shall be performed when the field’s
value is changed. This action may check the new value for validity. (The name
V stands for “validate.”)
C
dictionary
(Optional; PDF 1.3) A JavaScript action that shall be performed to recalculate
the value of this field when that of another field changes. (The name C stands
for “calculate.”) The order in which the document’s fields are recalculated shall
be defined by the CO entry in the interactive form dictionary (see 12.7.2,
“Interactive Form Dictionary”).
Table 194 – Entries in an annotation’s additional-actions dictionary (continued)
Key
Type
Value
72
©
Adobe Systems Incorporated 2008 – All rights reserved
417
PDF 32000-1:2008
Conforming readers shall ensure the presence of such a device, or equivalent controls for simulating one, for
the corresponding actions to be executed correctly. Mouse-related trigger events are subject to the following
constraints:
•
An E (enter) event may occur only when the mouse button is up.
•
An X (exit) event may not occur without a preceding E event.
•
A U (up) event may not occur without a preceding E and D event.
•
In the case of overlapping or nested annotations, entering a second annotation’s active area causes an X
event to occur for the first annotation.
NOTE 2
The field-related trigger events K (keystroke), F (format), V (validate), and C (calculate) are not defined for
button fields (see 12.7.4.2, “Button Fields”). The effects of an action triggered by one of these events are
limited only by the action itself and can occur outside the described scope of the event. For example, even
though the F event is used to trigger actions that format field values prior to display, it is possible for an action
triggered by this event to perform a calculation or make any other modification to the document.
These field-related trigger events can occur either through user interaction or programmatically, such as in
response to the NeedAppearances entry in the interactive form dictionary (see 12.7.2, “Interactive Form
Dictionary”), importation of FDF data (12.7.7, “Forms Data Format”), or JavaScript actions (12.6.4.16,
“JavaScript Actions”). For example, the user’s modifying a field value can trigger a cascade of calculations and
further formatting and validation for other fields in the document.
12.6.4
Action Types
12.6.4.1
General
PDF supports the standard action types listed in Table 198. The following sub-clauses describe each of these
types in detail.
Table 197 – Entries in the document catalog’s additional-actions dictionary
Key
Type
Value
WC
dictionary
(Optional; PDF 1.4) A JavaScript action that shall be performed before closing a
document. (The name WC stands for “will close.”)
WS
dictionary
(Optional; PDF 1.4) A JavaScript action that shall be performed before saving a
document. (The name WS stands for “will save.”)
DS
dictionary
(Optional; PDF 1.4) A JavaScript action that shall be performed after saving a
document. (The name DS stands for “did save.”)
WP
dictionary
(Optional; PDF 1.4) A JavaScript action that shall be performed before printing
a document. (The name WP stands for “will print.”)
DP
dictionary
(Optional; PDF 1.4) A JavaScript action that shall be performed after printing a
document. (The name DP stands for “did print.”)
Table 198 – Action types
Action type
Description
Discussed in sub-clause
GoTo
Go to a destination in the current document.
12.6.4.2, “Go-To Actions”
GoToR
(“Go-to remote”) Go to a destination in another
document.
12.6.4.3, “Remote Go-To Actions”
GoToE
(“Go-to embedded”; PDF 1.6) Go to a destination in
an embedded file.
12.6.4.4, “Embedded Go-To Actions”
80
PDF 32000-1:2008
418
©
Adobe Systems Incorporated 2008 – All rights reserved
NOTE
The set-state action is considered obsolete and should not be used.
12.6.4.2
Go-To Actions
A go-to action changes the view to a specified destination (page, location, and magnification factor). Table 199
shows the action dictionary entries specific to this type of action.
NOTE
Specifying a go-to action in the A entry of a link annotation or outline item (see Table 173 and Table 153) has
the same effect as specifying the destination directly with the Dest entry. For example, the link annotation
shown in the Example in 12.6.4.12, “Set-OCG-State Actions,” which uses a go-to action, has the same effect
as the one in the following Example, which specifies the destination directly. However, the go-to action is less
compact and is not compatible with PDF 1.0; therefore, using a direct destination is preferable.
Launch
Launch an application, usually to open a file.
12.6.4.5, “Launch Actions”
Thread
Begin reading an article thread.
12.6.4.6, “Thread Actions”
URI
Resolve a uniform resource identifier.
12.6.4.7, “URI Actions”
Sound
(PDF 1.2) Play a sound.
12.6.4.8, “Sound Actions”
Movie
(PDF 1.2) Play a movie.
12.6.4.9, “Movie Actions”
Hide
(PDF 1.2) Set an annotation’s Hidden flag.
12.6.4.10, “Hide Actions”
Named
(PDF 1.2) Execute an action predefined by the
conforming reader.
12.6.4.11, “Named Actions”
SubmitForm
(PDF 1.2) Send data to a uniform resource locator.
12.7.5.2, “Submit-Form Action”
ResetForm
(PDF 1.2) Set fields to their default values.
12.7.5.3, “Reset-Form Action”
ImportData
(PDF 1.2) Import field values from a file.
12.7.5.4, “Import-Data Action”
JavaScript
(PDF 1.3) Execute a JavaScript script.
12.6.4.16, “JavaScript Actions”
SetOCGState
(PDF 1.5) Set the states of optional content groups.
12.6.4.12, “Set-OCG-State Actions”
Rendition
(PDF 1.5) Controls the playing of multimedia content. . 12.6.4.13, “Rendition Actions”
Trans
(PDF 1.5) Updates the display of a document, using
a transition dictionary.
12.6.4.14, “Transition Actions”
GoTo3DView
(PDF 1.6) Set the current view of a 3D annotation
12.6.4.15, “Go-To-3D-View Actions,”
Table 199 – Additional entries specific to a go-to action
Key
Type
Value
S
name
(Required) The type of action that this dictionary describes; shall be GoTo
for a go-to action.
D
name,
byte string,
or array
(Required)
The destination to jump to (see 12.3.2, “Destinations”).
Table 198 – Action types (continued)
Action type
Description
Discussed in sub-clause
69
©
Adobe Systems Incorporated 2008 – All rights reserved
419
PDF 32000-1:2008
EXAMPLE
93 0 obj
<< /Type /Annot
/Subtype /Link
/Rect [ 71 717 190 734 ]
/Border [ 16 16 1 ]
/A << /Type /Action
/S /GoTo
/D [ 3 0 R /FitR –4 399 199 533 ]
>>
>>
endobj
12.6.4.3
Remote Go-To Actions
A remote go-to action is similar to an ordinary go-to action but jumps to a destination in another PDF file
instead of the current file. Table 200 shows the action dictionary entries specific to this type of action.
NOTE
Remote go-to actions cannot be used with embedded files; see 12.6.4.4, “Embedded Go-To Actions.”
12.6.4.4
Embedded Go-To Actions
An embedded go-to action (PDF 1.6) is similar to a remote go-to action but allows jumping to or from a PDF file
that is embedded in another PDF file (see 7.11.4, “Embedded File Streams”). Embedded files may be
associated with file attachment annotations (see 12.5.6.15, “File Attachment Annotations”) or with entries in the
EmbeddedFiles name tree (see 7.7.4, “Name Dictionary”). Embedded files may in turn contain embedded
files. Table 201 shows the action dictionary entries specific to embedded go-to actions.
Embedded go-to actions provide a complete facility for linking between a file in a hierarchy of nested
embedded files and another file in the same or different hierarchy. The following terminology shall be used:
•
The source is the document containing the embedded go-to action.
•
The target is the document in which the destination lives.
•
The T entry in the action dictionary is a target dictionary that locates the target in relation to the source, in
much the same way that a relative path describes the physical relationship between two files in a file
system. Target dictionaries may be nested recursively to specify one or more intermediate targets before
reaching the final one. As the hierarchy is navigated, each intermediate target shall be referred to as the
current document. Initially, the source is the current document.
Table 200 – Additional entries specific to a remote go-to action
Key
Type
Value
S
name
(Required) The type of action that this dictionary describes; shall be
GoToR for a remote go-to action.
F
file specification
(Required) The file in which the destination shall be located.
D
name,
byte string, or
array
(Required) The destination to jump to (see 12.3.2, “Destinations”). If
the value is an array defining an explicit destination (as described
under 12.3.2.2, “Explicit Destinations”), its first element shall be a page
number within the remote document rather than an indirect reference
to a page object in the current document. The first page shall be
numbered 0.
NewWindow
boolean
(Optional; PDF 1.2) A flag specifying whether to open the destination
document in a new window. If this flag is false , the destination
document replaces the current document in the same window. If this
entry is absent, the conforming reader should behave in accordance
with its preference.
85
PDF 32000-1:2008
420
©
Adobe Systems Incorporated 2008 – All rights reserved
NOTE
It is an error for a target dictionary to have an infinite cycle (for example, one where a target dictionary refers to
itself). Conforming readers should attempt to detect such cases and refuse to execute the action if found.
•
A child document shall be one that is embedded within another PDF file.
•
The document in which a file is embedded shall be its parent.
•
A root document is one that is not embedded in another PDF file. The target and source may be contained
in root documents or embedded documents.
Table 201 – Additional entries specific to an embedded go-to action
Key
Type
Value
S
name
(Required) The type of action that this dictionary describes; shall be
GoToE for an embedded go-to action.
F
file
specification
(Optional) The root document of the target relative to the root
document of the source. If this entry is absent, the source and target
share the same root document.
D
name,
byte string,
or array
(Required) The destination in the target to jump to (see 12.3.2,
“Destinations”).
NewWindow
boolean
(Optional) If true, the destination document should be opened in a new
window; if false, the destination document should replace the current
document in the same window. If this entry is absent, the conforming
reader should act according to its preference.
T
dictionary
(Optional if F is present; otherwise required) A target dictionary (see
Table 202) specifying path information to the target document. Each
target dictionary specifies one element in the full path to the target and
may have nested target dictionaries specifying additional elements.
Table 202 – Entries specific to a target dictionary
Key
Type
Value
R
name
(Required) Specifies the relationship between the current document
and the target (which may be an intermediate target). Valid values are
P (the target is the parent of the current document) and C (the target is
a child of the current document).
N
byte string
(Required if the value of R is C an
d the target is located in the
EmbeddedFiles name tree; otherwise, it shall be absent) The name of
the file in the EmbeddedFiles name tree.
P
integer or
byte string
(Required if the value of R is C and the target is associated with a file
attachment annotation; otherwise, it shall be absent) If the value is an
integer, it specifies the page number (zero-based) in the current
document containing the file attachment annotation. If the value is a
string, it specifies a named destination in the current document that
provides the page number of the file attachment annotation.
A
integer or text
string
(Required if the value of R is C and the target is associated with a file
attachment annotation; otherwise, it shall be absent) If the value is an
integer, it specifies the index (zero-based) of the annotation in the
Annots array (see Table 30) of the page specified by P. If the value is a
text string, it specifies the value of NM in the annotation dictionary (see
Table 164).
T
dictionary
(Optional) A target dictionary specifying additional path information to
the target document. If this entry is absent, the current document is the
target file containing the destination.
69
©
Adobe Systems Incorporated 2008 – All rights reserved
421
PDF 32000-1:2008
EXAMPLE
The following example illustrates several possible relationships between source and target. Each object
shown is an action dictionary for an embedded go-to action.
1 0 obj
% Link to a child
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /C
/N (Embedded document) >>
>>
endobj
2 0 obj
% Link to the parent
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /P >>
>>
endobj
3 0 obj
% Link to a sibling
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /P
/T << /R /C
/N (Another embedded document) >>
>>
>>
endobj
4 0 obj
% Link to an embedded file in an external document
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/F (someFile.pdf)
/T << /R /C
/N (Embedded document) >>
>>
endobj
5 0 obj
% Link from an embedded file to a normal file
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/F (someFile.pdf)
>>
endobj
6 0 obj
% Link to a grandchild
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /C
/N (Embedded document)
/T << /R /C
/P (A destination name)
/A (annotName)
>>
>>
>>
endobj
7 0 obj
% Link to a niece/nephew through the source’s parent
69
PDF 32000-1:2008
422
©
Adobe Systems Incorporated 2008 – All rights reserved
<< /Type /Action
/S /GoToE
/D (destination)
/T << /R /P
/T << /R /C
/N (Embedded document)
/T << /R /C
/P 3
/A (annotName)
>>
>>
>>
>>
endobj
12.6.4.5
Launch Actions
A launch action launches an application or opens or prints a document. Table 203 shows the action dictionary
entries specific to this type of action.
The optional Win, Mac, and Unix entries allow the action dictionary to include platform-specific parameters for
launching the designated application. If no such entry is present for the given platform, the F entry shall be
used instead. Table 203 shows the platform-specific launch parameters for the Windows platform. Parameters
for the Mac OS and UNIX platforms are not yet defined at the time of publication.
Table 203 – Additional entries specific to a launch action
Key
Type
Value
S
name
(Required) The type of action that this dictionary describes; shall be
Launch for a launch action.
F
file specification
(Required if none of the entries Win, Mac, or Unix is present) The
application that shall be launched or the document that shall be
opened or printed. If this entry is absent and the conforming reader
does not understand any of the alternative entries, it shall do nothing.
Win
dictionary
(Optional) A dictionary containing Windows-specific launch
parameters (see Table 204).
Mac
(undefined)
(Optional) Mac OS–specific launch parameters; not yet defined.
Unix
(undefined)
(Optional) UNIX-specific launch parameters; not yet defined.
NewWindow
boolean
(Optional; PDF 1.2) A flag specifying whether to open the destination
document in a new window. If this flag is false , the destination
document replaces the current document in the same window. If this
entry is absent, the conforming reader should behave in accordance
with its current preference. This entry shall be ignored if the file
designated by the F entry is not a PDF document.
Table 204 – Entries in a Windows launch parameter dictionary
Key
Type
Value
F
byte string
(Required) The file name of the application that shall be launched or
the document that shall be opened or printed, in standard Windows
pathname format. If the name string includes a backslash character (\),
the backslash shall itself be preceded by a backslash.
This value shall be a simple string; it is not a file specification.
Documents you may be interested
Documents you may be interested
