PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 2) — page 2

643

SECTION 8.4

Annotations

KEY

TYPE

VALUE

stream

(Optional; pushbutton fields only; must be an indirect reference) A form XObject

defining the widget annotation’s rollover icon, displayed when the user rolls the

cursor into its active area without pressing the mouse button.

stream

(Optional; pushbutton fields only; must be an indirect reference) A form XObject

defining the widget annotation’s alternate (down) icon, displayed when the

mouse button is pressed within its active area.

dictionary

(Optional; pushbutton fields only) An icon fit dictionary (see Table 8.97 on page

719) specifying how to display the widget annotation’s icon within its annotation

rectangle. If present, the icon fit dictionary applies to all of the annotation’s icons

(normal, rollover, and alternate).

integer

(Optional; pushbutton fields only) A code indicating where to position the text of

the widget annotation’s caption relative to its icon:

No icon; caption only

No caption; icon only

Caption below the icon

Caption above the icon

Caption to the right of the icon

Caption to the left of the icon

Caption overlaid directly on the icon

Default value: 0.

Printer’s Mark Annotations

A printer’s mark annotation (PDF 1.4) represents a graphic symbol, such as a

registration target, color bar, or cut mark, added to a page to assist production

personnel in identifying components of a multiple-plate job and maintaining

consistent output during production. See Section 10.10.2, “Printer’s Marks,” for

further discussion.

Trap Network Annotations

A trap network annotation (PDF 1.3) defines the trapping characteristics for a

page of a PDF document. (Trapping is the process of adding marks to a page

along color boundaries to avoid unwanted visual artifacts resulting from mis-

registration of colorants when the page is printed.) A page may have at most one

644

CHAPTER 8

Interactive Features

trap network annotation, whose Subtype entry has the value TrapNet and which

is always the last element in the page object’s Annots array (see “Page Objects” on

page 144). See Section 10.10.5, “Trapping Support,” for further discussion.

Watermark Annotations

A watermark annotation (PDF 1.6) is used to represent graphics that are expected

to be printed at a fixed size and position on a page, regardless of the dimensions

of the printed page. The FixedPrint entry of a watermark annotation dictionary

(see Table 8.41) is a dictionary that contains values for specifying the size and po-

sition of the annotation (see Table 8.42).

Watermark annotations have no pop-up window or other interactive elements.

When displaying a watermark annotation on-screen, viewer applications should

use the dimensions of the media box as the page size so that the scroll and zoom

behavior is the same as for other annotations.

Note: Since many printing devices have nonprintable margins, it is recommended

that such margins be taken into consideration when positioning watermark annota-

tions near the edge of a page.

TABLE 8.41 Additional entries specific to a watermark annotation

KEY

TYPE

VALUE

Subtype

name

(Required) The type of annotation that this dictionary describes;

must

Watermark for a watermark annotation.

FixedPrint

dictionary

(Optional) A fixed print dictionary (see Table 8.42) that specifies how this anno-

tation should be drawn relative to the dimensions of the target media. If this en-

try is not present, the annotation is drawn without any special consideration for

the dimensions of the target media.

Note: If the dimensions of the target media are not known at the time of drawing,

drawing is done relative to the dimensions specified by the page’s MediaBox entry

(see Table 3.27).

645

SECTION 8.4

Annotations

TABLE 8.42 Entries in a fixed print dictionary

KEY

TYPE

VALUE

Type

name

(Required) Must be FixedPrint.

Matrix

array

(Optional) The matrix used to transform the annotation’s rectangle before ren-

dering.

Default value: the identity matrix [ 1 0 0 1 0 0 ].

Note: When positioning content near the edge of a page, it is recommended that

this entry be used to provide a reasonable offset to allow for nonprintable margins.

number

(Optional) The amount to translate the associated content horizontally, as a per-

centage of the width of the target media (or if unknown, the width of the page’s

MediaBox). 1.0 represents 100% and 0.0 represents 0%. Negative values are not

recommended, since they may cause content to be drawn off the page.

Default value: 0.

number

(Optional) The amount to translate the associated content vertically, as a per-

centage of the height of the target media (or if unknown, the height of the page’s

MediaBox). 1.0 represents 100% and 0.0 represents 0%. Negative values are not

recommended, since they may cause content to be drawn off the page.

Default value: 0.

When rendering a watermark annotation with a FixedPrint entry, the following

behavior occurs:

• The annotation’s rectangle (as specified by its Rect entry) is translated to the or-

igin and transformed by the Matrix entry of its FixedPrint dictionary to produce

a quadrilateral with arbitrary orientation.

• The transformed annotation rectangle is defined as the smallest upright rectan-

gle that encompasses this quadrilateral; it is used in place of the annotation

rectangle referred to in steps 2 and 3 of Algorithm 8.1 on page 612.

In addition, given a matrix B that maps a scaled and rotated page into the default

user space, a new matrix is computed that cancels out B and translates the origin

of the printed page to the origin of the default user space. This transformation is

applied to ensure the correct scaling and alignment.

Example 8.10 shows a watermark annotation that prints a text string one inch

from the left and one inch from the top of the printed page.

646

CHAPTER 8

Interactive Features

Example 8.10

8 0 obj

% Watermark appearance

/Length ...

/Subtype /Form

/Resources ...

/BBox ...

stream

/F1 1 Tf

36 0 0 36 0 -36 Tm

(Do Not Build) Tx

endstream

endobj

9 0 obj

% Watermark annotation

/Rect ...

/Type /Annot

/Subtype /Watermark

/FixedPrint 10 0 R

/AP <</N 8 0 R>>

% in the page dictionary

/Annots [9 0 R]

10 0 obj

% Fixed print dictionary

/Type /FixedPrint

/Matrix [1 0 0 1 72 -72]

% Translate one inch right and one inch down

/H 0

/V 1.0

% Translate the full height of the page vertically

endobj

647

SECTION 8.5

Actions

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.

648

CHAPTER 8

Interactive Features

TABLE 8.43 Entries common to all action dictionaries

KEY

TYPE

VALUE

Type

name

(Optional) The type of PDF object that this dictionary describes; if

present, must be Action for an action dictionary.

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) T he 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.

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-

649

SECTION 8.5

Actions

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

dictionary

(Optional; PDF 1.2) An action to be performed when the cursor enters the annotation’s

active area.

dictionary

(Optional; PDF 1.2) An action to be performed when the cursor exits the annotation’s

active area.

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.”)

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).

dictionary

(Optional; PDF 1.2; widget annotations only) An action to be performed when the

annotation receives the input focus.

650

CHAPTER 8

Interactive Features

KEY TYPE

VALUE

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.

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.

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.

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.

TABLE 8.45 Entries in a page object’s additional-actions dictionary

KEY TYPE

VALUE

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.)

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.)

651

SECTION 8.5

Actions

TABLE 8.46 Entries in a form field’s additional-actions dictionary

KEY TYPE

VALUE

dictionary

(Optional; PDF 1.3) A JavaScript action to be performed when the user types a key-

stroke into a text field or combo box or modifies the selection in a scrollable list box.

This action can check the keystroke for validity and reject or modify it.

dictionary

(Optional; PDF 1.3) A JavaScript action to be performed before the field is formatted to

display its current value. This action can modify the field’s value before formatting.

dictionary

(Optional; PDF 1.3) A JavaScript action to be performed when the field’s value is

changed. This action can check the new value for validity. (The name V stands for “val-

idate.”)

dictionary

(Optional; PDF 1.3) A JavaScript action to 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 is defined by the CO entry in the inter-

active form dictionary (see Section 8.6.1, “Interactive Form Dictionary”).

TABLE 8.47 Entries in the document catalog’s additional-actions dictionary

KEY TYPE

VALUE

WC dictionary

(Optional; PDF 1.4) A JavaScript action to be performed before closing a document.

(The name WC stands for “will close.”)

WS dictionary

(Optional; PDF 1.4) A JavaScript action to be performed before saving a document.

(The name WS stands for “will save.”)

dictionary

(Optional; PDF 1.4) A JavaScript action to be performed after saving a document. (The

name DS stands for “did save.”)

WP dictionary

(Optional; PDF 1.4) A JavaScript action to be performed before printing a document.

(The name WP stands for “will print.”)

dictionary

(Optional; PDF 1.4) A JavaScript action to be performed after printing a document.

(The name DP stands for “did print.”)

For purposes of the trigger events E (enter), X (exit), D (down), and U (up), the

term mouse denotes a generic pointing device with the following characteristics:

• A selection button that can be pressed, held down, and released. If there is more

than one mouse button, the selection button is typically the left button.

652

CHAPTER 8

Interactive Features

• A notion of location—that is, an indication of where on the screen the device is

pointing. Location is typically denoted by a screen cursor.

• A notion of focus—that is, which element in the document is currently interact-

ing with the user. In many systems, this element is denoted by a blinking caret,

a focus rectangle, or a color change.

PDF viewer applications must ensure the presence of such a device for the corre-

sponding actions to be executed correctly. Mouse-related trigger events are sub-

ject to the following constraints:

• An E (enter) event can occur only when the mouse button is up.

• An X (exit) event cannot occur without a preceding E event.

• A U (up) event cannot 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: The field-related trigger events K (keystroke), F (format), V (validate), and C

(calculate) are not defined for button fields (see “Button Fields” on page 685). The

effects of an action triggered by one of these events are limited only by the action it-

self 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 pro-

grammatically, such as in response to the NeedAppearances entry in the interactive

form dictionary (see Section 8.6.1, “Interactive Form Dictionary”), importation of

FDF data (Section 8.6.6, “Forms Data Format”), or JavaScript actions (“JavaScript

Actions” on page 709). 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.

8.5.3

Action Types

PDF supports the standard action types listed in Table 8.48. The following sec-

tions describe each of these types in detail. Plug-in extensions may add new

action types.

653

SECTION 8.5

Actions

TABLE 8.48 Action types

ACTION TYPE

DESCRIPTION

DISCUSSED IN SECTION

GoTo

Go to a destination in the current document.

“Go-To Actions” on page 654

GoToR

(“Go-to remote”) Go to a destination in another

“Remote Go-To Actions” on page 655

document.

GoToE

(“Go-to embedded”; PDF 1.6) Go to a destination in an

“Embedded Go-To Actions” on page

embedded file.

655

Launch

Launch an application, usually to open a file.

“Launch Actions” on page 659

Thread

Begin reading an article thread.

“Thread Actions” on page 661

URI

Resolve a uniform resource identifier.

“URI Actions” on page 662

Sound

(PDF 1.2) Play a sound.

“Sound Actions” on page 663

Movie

(PDF 1.2) Play a movie.

“Movie Actions” on page 664

Hide

(PDF 1.2) Set an annotation’s Hidden flag.

“Hide Actions” on page 665

Named

(PDF 1.2) Execute an action predefined by the viewer

“Named Actions” on page 666

application.

SubmitForm

(PDF 1.2) Send data to a uniform resource locator.

“Submit-Form Actions” on page 703

ResetForm

(PDF 1.2) Set fields to their default values.

“Reset-Form Actions” on page 707

ImportData

(PDF 1.2) Import field values from a file.

“Import-Data Actions” on page 708

JavaScript

(PDF 1.3) Execute a JavaScript script.

“JavaScript Actions” on page 709

SetOCGState

(PDF 1.5) Set the states of optional content groups.

“Set-OCG-State Actions” on page 667

Rendition

(PDF 1.5) Controls the playing of multimedia content.

“Rendition Actions” on page 668

Trans

(PDF 1.5) Updates the display of a document, using a

“Transition Actions” on page 670

transition dictionary.

GoTo3DView

(PDF 1.6) Set the current view of a 3D annotation

“Go-To-3D-View Actions” on page

670

Note: Previous versions of the PDF specification described an action type known as

the set-state action; this type of action is now considered obsolete and its use is no

longer recommended. An additional action type, the no-op action, was defined in

PDF 1.2 but never implemented; it is no longer defined and should be ignored.

654

CHAPTER 8

Interactive Features

Go-To Actions

A go-to action changes the view to a specified destination (page, location, and

magnification factor). Table 8.49 shows the action dictionary entries specific to

this type of action.

TABLE 8.49 Additional entries specific to a go-to action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be GoTo for a

go-to action.

name,

(Required) The destination to jump to (see Section 8.2.1, “Destinations”).

byte string,

or array

Specifying a go-to action in the A entry of a link annotation or outline item (see

Tables 8.24 on page 622 and 8.4 on page 585) has the same effect as specifying the

destination directly with the Dest entry. For example, the link annotation shown

in Example 8.11, which uses a go-to action, has the same effect as the one in Ex-

ample 8.9 on page 623, 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.

Example 8.11

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

655

SECTION 8.5

Actions

Remote Go-To Actions

A remote go-to action is similar to an ordinary go-to action but jumps to a desti-

nation in another PDF file instead of the current file. Table 8.50 shows the action

dictionary entries specific to this type of action.

Note: Remote go-to actions cannot be used with embedded files; see “Embedded Go-

To Actions” on page 655”.

TABLE 8.50 Additional entries specific to a remote go-to action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be GoToR

for a remote go-to action.

file specification

(Required) The file in which the destination is located.

name,

(Required) The destination to jump to (see Section 8.2.1, “Destinations”). If

byte string,

the value is an array defining an explicit destination (as described under

or array

“Explicit Destinations” on page 582), its first element must be a page number

within the remote document rather than an indirect reference to a page ob-

ject in the current document. The first page is numbered 0.

NewWindow boolean

(Optional; PDF 1.2) A flag specifying whether to open the destination docu-

ment 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 viewer

application should behave in accordance with the current user preference.

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 “Embed-

ded File Streams” on page 184). Embedded files may be associated with file at-

tachment annotations (see “File Attachment Annotations” on page 637) or with

entries in the EmbeddedFiles name tree (see Section 3.6.3, “Name Dictionary”).

Embedded files may in turn contain embedded files. Table 8.51 shows the action

dictionary entries specific to embedded go-to actions.

656

CHAPTER 8

Interactive Features

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 hier-

archy. The following terminology is 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 is

referred to as the current document. Initially, the source is the current docu-

ment.

Note: It is an error for a target dictionary to have an infinite cycle (for example,

one where a target dictionary refers to itself). Viewer applications should attempt

to detect such cases and refuse to execute the action if found.

• A child document is one that is embedded within another PDF file.

• The document in which a file is embedded is 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 8.51 Additional entries specific to an embedded go-to action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be GoToE

for an embedded go-to action.

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.

name,

(Required) The destination in the target to jump to (see Section 8.2.1, “Desti-

byte string,

nations”).

or array

NewWindow boolean

(Optional) If true, the destination document should be opened in a new win-

dow; if false, the destination document should replace the current document

in the same window. If this entry is absent, the viewer application should hon-

or the current user preference.

657

SECTION 8.5

Actions

KEY

TYPE

VALUE

dictionary

(Optional if F is present; otherwise required) A target dictionary (see Table 8.52)

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 8.52 Entries specific to a target dictionary

KEY

TYPE

VALUE

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).

byte string

(Required if the value of R is C and the target is located in the EmbeddedFiles

name tree; otherwise, it must be absent) The name of the file in the

EmbeddedFiles name tree.

integer or

(Required if the value of R is C and the target is associated with a file attachment

byte string

annotation; otherwise, it must be absent) If the value is an integer, it specifies

the page number (zero-based) in the current document containing the file at-

tachment 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.

integer or text

(Required if the value of R is C and the target is associated with a file attachment

string

annotation; otherwise, it must be absent) If the value is an integer, it specifies

the index (zero-based) of the annotation in the Annots array (see Table 3.27)

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 8.15).

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.

658

CHAPTER 8

Interactive Features

Example 8.12 illustrates several possible relationships between source and target.

Each object shown is an action dictionary for an embedded go-to action.

Example 8.12

1 0 obj

% Link to a child

<< /Type /Action

/S /GoToE

/D (Chapter 1)

<< /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

659

SECTION 8.5

Actions

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

<< /Type /Action

/S /GoToE

/D (destination)

/T << /R /P

/T << /R /C

/N (Embedded document)

/T << /R /C

/P 3

/A (annotName)

endobj

Launch Actions

A launch action launches an application or opens or prints a document. Table

8.53 shows the action dictionary entries specific to this type of action.

660

CHAPTER 8

Interactive Features

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 is used instead. Table

8.54 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 8.53 Additional entries specific to a launch action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Launch

for a launch action.

file specification

(Required if none of the entries Win, Mac, or Unix is present) The application to

be launched or the document to be opened or printed. If this entry is absent

and the viewer application does not understand any of the alternative entries,

it should do nothing.

Win

dictionary

(Optional) A dictionary containing Windows-specific launch parameters (see

Table 8.54; see also implementation note 101 in Appendix H).

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 docu-

ment 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 viewer

application should behave in accordance with the current user preference.

This entry is ignored if the file designated by the F entry is not a PDF docu-

ment.

TABLE 8.54 Entries in a Windows launch parameter dictionary

KEY

TYPE

VALUE

byte string

(Required) The file name of the application to be launched or the document

to be opened or printed, in standard Windows pathname format. If the name

string includes a backslash character (\), the backslash must itself be preceded

by a backslash.

Note: This value must be a simple string; it is not a file specification.

661

SECTION 8.5

Actions

KEY

TYPE

VALUE

byte string

(Optional) A bye string specifying the default directory in standard DOS syn-

tax.

ASCII string

(Optional) An ASCII string specifying the operation to perform:

open

Open a document.

print

Print a document.

If the F entry designates an application instead of a document, this entry is ig-

nored and the application is launched. Default value: open.

byte string

(Optional) A parameter string to be passed to the application designated by

the F entry. This entry should be omitted if F designates a document.

Thread Actions

A thread action jumps to a specified bead on an article thread (see Section 8.3.2,

“Articles”), in either the current document or a different one. Table 8.55 shows

the action dictionary entries specific to this type of action.

TABLE 8.55 Additional entries specific to a thread action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Thread

for a thread action.

file specification

(Optional) The file containing the thread. If this entry is absent, the thread is

in the current file.

dictionary, integer,

(Required) The destination thread, specified in one of the following forms:

or text string

• An indirect reference to a thread dictionary (see Section 8.3.2, “Articles”).

In this case, the thread must be in the current file.

• The index of the thread within the Threads array of its document’s catalog

(see Section 3.6.1, “Document Catalog”). The first thread in the array has

index 0.

• The title of the thread as specified in its thread information dictionary (see

Table 8.11 on page 596). If two or more threads have the same title, the one

appearing first in the document catalog’s Threads array is used.

662

CHAPTER 8

Interactive Features

KEY

TYPE

VALUE

dictionary or integer

(Optional) The bead in the destination thread, specified in one of the follow-

ing forms:

• An indirect reference to a bead dictionary (see Section 8.3.2, “Articles”). In

this case, the thread must be in the current file.

• The index of the bead within its thread. The first bead in a thread has

index 0.

URI Actions

A uniform resource identifier (URI) is a string that identifies (resolves to) a re-

source on the Internet—typically a file that is the destination of a hypertext link,

although it can also resolve to a query or other entity. (URIs are described in In-

ternet RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax; see the Bib-

liography.)

A URI action causes a URI to be resolved. Table 8.56 shows the action dictionary

entries specific to this type of action. (See implementation notes 102 and 103 in

Appendix H.)

TABLE 8.56 Additional entries specific to a URI action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be URI for a URI ac-

tion.

URI

ASCII

(Required) The uniform resource identifier to resolve, encoded in 7-bit ASCII.

string

IsMap

boolean

(Optional) A flag specifying whether to track the mouse position when the URI is re-

solved (see below). Default value: false.

This entry applies only to actions triggered by the user’s clicking an annotation; it is

ignored for actions associated with outline items or with a document’s OpenAction

entry.

If the IsMap flag is true and the user has triggered the URI action by clicking an

annotation, the coordinates of the mouse position at the time the action is per-

formed should be transformed from device space to user space and then offset

relative to the upper-left corner of the annotation rectangle (that is, the value of

663

SECTION 8.5

Actions

the Rect entry in the annotation with which the URI action is associated). For ex-

ample, if the mouse coordinates in user space are (x_m , y_m ) and the annotation

rectangle extends from (ll_x , ll_y ) at the lower-left to (ur_x , ur_y ) at the upper-right,

the final coordinates (x_f , y_f ) are as follows:

(

x_f = x_m ll_x

)

y_f

ur_y – y_m

If the resulting coordinates (x_f , y_f ) are fractional, they should be rounded to the

nearest integer values. They are then appended to the URI to be resolved, separat-

ed by commas and preceded by a question mark, as shown in this example:

http : / / www. adobe . com / intro ?100 , 200

To support URI actions, a PDF document’s catalog (see Section 3.6.1, “Document

Catalog”) may include a URI entry whose value is a URI dictionary. At the time of

publication, only one entry is defined for such a dictionary (see Table 8.57).

TABLE 8.57 Entry in a URI dictionary

KEY

TYPE

VALUE

Base

ASCII

(Optional) The base URI to be used in resolving relative URI references. URI actions

string

within the document may specify URIs in partial form, to be interpreted relative to

this base address. If no base URI is specified, such partial URIs are interpreted rela-

tive to the location of the document itself. The use of this entry is parallel to that of

the body element <BASE >, as described in the HTML 4.01 Specification (see the Bibli-

ography).

The Base entry allows the URI of the document to be recorded in situations in

which the document may be accessed out of context. For example, if a document

has been moved to a new location but contains relative links to other documents

that have not been moved, the Base entry could be used to refer such links to the

true location of the other documents, rather than that of the moved document.

Sound Actions

A sound action (PDF 1.2) plays a sound through the computer’s speakers. Table

8.58 shows the action dictionary entries specific to this type of action. Sounds are

discussed in Section 9.2, “Sounds.”

664

CHAPTER 8

Interactive Features

TABLE 8.58 Additional entries specific to a sound action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Sound

for a sound action.

Sound

stream

(Required) A sound object defining the sound to be played (see Section 9.2,

“Sounds”; see also implementation note 104 in Appendix H).

Volume

number

(Optional) The volume at which to play the sound, in the range −1.0 to 1.0;

see implementation note 106 in Appendix H. Default value: 1.0.

Synchronous

boolean

(Optional) A flag specifying whether to play the sound synchronously or

asynchronously; see implementation note 106 in Appendix H. If this flag is

true, the viewer application retains control, allowing no further user interac-

tion other than canceling the sound, until the sound has been completely

played. Default value: false.

Repeat

boolean

(Optional) A flag specifying whether to repeat the sound indefinitely. If this

entry is present, the Synchronous entry is ignored. Default value: false.

Mix

boolean

(Optional) A flag specifying whether to mix this sound with any other sound

already playing; see implementation note 107 in Appendix H. If this flag is

false, any previously playing sound is stopped before starting this sound; this

can be used to stop a repeating sound (see Repeat, above). Default value:

false.

Movie Actions

A movie action (PDF 1.2) can be used to play a movie in a floating window or

within the annotation rectangle of a movie annotation (see “Movie Annotations”

on page 639 and Section 9.3, “Movies”). The movie annotation must be asso-

ciated with the page that is the destination of the link annotation or outline item

containing the movie action, or with the page object with which the action is

associated. (See implementation note 108 in Appendix H.)

Note: A movie action by itself does not guarantee that the page the movie is on will

be displayed before attempting to play the movie; such page change actions must be

done explicitly.

The contents of a movie action dictionary are identical to those of a movie activa-

tion dictionary (see Table 9.31 on page 785), with the additional entries shown in

Table 8.59. The contents of the activation dictionary associated with the movie

665

SECTION 8.5

Actions

annotation provide the default values. Any information specified in the movie ac-

tion dictionary overrides these values.

TABLE 8.59 Additional entries specific to a movie action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Movie for a

movie action.

Annotation

dictionary

(Optional) An indirect reference to a movie annotation identifying the movie to be

played.

text string

(Optional) The title of a movie annotation identifying the movie to be played.

Note: The dictionary must include either an Annotation or a T entry but not both.

Operation

name

(Optional) The operation to be performed on the movie:

Play

Start playing the movie, using the play mode specified by the dic-

tionary’s Mode entry (see Table 9.31 on page 785). If the movie is

currently paused, it is repositioned to the beginning before play-

ing (or to the starting point specified by the dictionary’s Start en-

try, if present).

Stop

Stop playing the movie.

Pause

Pause a playing movie.

Resume

Resume a paused movie.

Default value: Play.

Hide Actions

A hide action (PDF 1.2) hides or shows one or more annotations on the screen by

setting or clearing their Hidden flags (see Section 8.4.2, “Annotation Flags”). This

type of action can be used in combination with appearance streams and trigger

events (Sections 8.4.4, “Appearance Streams,” and 8.5.2, “Trigger Events”) to dis-

play pop-up help information on the screen. For example, the E (enter) and X (ex-

it) trigger events in an annotation’s additional-actions dictionary can be used to

show and hide the annotation when the user rolls the cursor in and out of its ac-

tive area on the page. This can be used to pop up a help label, or tool tip,

describing the effect of clicking at that location on the page. Table 8.60 shows the

action dictionary entries specific to this type of action. (See implementation

notes 109 and 110 in Appendix H.)

666

CHAPTER 8

Interactive Features

TABLE 8.60 Additional entries specific to a hide action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Hide for a hide

action.

dictionary,

(Required) The annotation or annotations to be hidden or shown, specified in any

text string, or

of the following forms:

array

• An indirect reference to an annotation dictionary

• A text string giving the fully qualified field name of an interactive form field

whose associated widget annotation or annotations are to be affected (see “Field

Names” on page 676)

• An array of such dictionaries or text strings

boolean

(Optional) A flag indicating whether to hide the annotation (true) or show it (false).

Default value: true.

Named Actions

Table 8.61 lists several named actions (PDF 1.2) that PDF viewer applications are

expected to support; further names may be added in the future. (See implementa-

tion notes 111 and 112 in Appendix H.)

TABLE 8.61 Named actions

NAME

ACTION

NextPage

Go to the next page of the document.

PrevPage

Go to the previous page of the document.

FirstPage

Go to the first page of the document.

LastPage

Go to the last page of the document.

Note: Viewer applications may support additional, nonstandard named actions, but

any document using them is not portable. If the viewer encounters a named action

that is inappropriate for a viewing platform, or if the viewer does not recognize the

name, it should take no action.

Table 8.62 shows the action dictionary entries specific to named actions.

667

SECTION 8.5

Actions

TABLE 8.62 Additional entries specific to named actions

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Named for a named

action.

name

(Required) The name of the action to be performed (see Table 8.61).

Set-OCG-State Actions

A set-OCG-state action (PDF 1.5) sets the state of one or more optional content

groups (see Section 4.10, “Optional Content”). Table 8.63 shows the action dictio-

nary entries specific to this type of action.

TABLE 8.63 Additional entries specific to a set-OCG-state action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be SetOCGState

for a set-OCG-state action.

State

array

(Required) An array consisting of any number of sequences beginning with a name

object (ON, OFF, or Toggle) followed by one or more optional content group dictio-

naries. The array elements are processed from left to right; each name is applied to

the subsequent groups until the next name is encountered:

• ON sets the state of subsequent groups to ON

• OFF sets the state of subsequent groups to OFF

• Toggle reverses the state of subsequent groups.

PreserveRB

boolean

(Optional) If true, indicates that radio-button state relationships between optional

content groups (as specified by the RBGroups entry in the current configuration

dictionary; see Table 4.51 on page 376) should be preserved when the states in the

State array are applied. That is, if a group is set to ON (either by ON or Toggle) dur-

ing processing of the State array, any other groups belonging to the same radio-but-

ton group are turned OFF. If a group is set to OFF, there is no effect on other groups.

If PreserveRB is false, radio-button state relationships, if any, are ignored.

Default value: true.

668

CHAPTER 8

Interactive Features

When a set-OCG-state action is performed, the State array is processed from left

to right. Each name is applied to subsequent groups in the array until the next

name is encountered, as shown in the following example.

Example 8.13

<< /S /SetOCGState

/State [/OFF 2 0 R 3 0 R /Toggle 16 0 R 19 0 R /ON 5 0 R]

A group can appear more than once in the State array; its state is set each time it

is encountered, based on the most recent name. For example, if the array con-

tained [/OFF 1 0 R /Toggle 1 0 R], the group’s state would be ON after the action was

performed. ON, OFF and Toggle sequences have no required order. More than

one sequence in the array may contain the same name.

Note: While the specification allows a group to appear more than once in the State

array, this is not intended to implement animation or any other sequential drawing

operations. PDF processing applications are free to accumulate all state changes and

apply only the net changes simultaneously to all affected groups before redrawing.

Rendition Actions

A rendition action (PDF 1.5) controls the playing of multimedia content (see Sec-

tion 9.1, “Multimedia”). This action can be used in the following ways:

• To begin the playing of a rendition object (see Section 9.1.2, “Renditions”), as-

sociating it with a screen annotation (see “Screen Annotations” on page 639).

The screen annotation specifies where the rendition is played unless otherwise

specified.

• To stop, pause, or resume a playing rendition.

• To trigger the execution of a JavaScript script that may perform custom opera-

tions.

Table 8.64 lists the entries in a rendition action dictionary.

669

SECTION 8.5

Actions

TABLE 8.64 Additional entries specific to a rendition action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Rendition for a

rendition action.

dictionary

(Required when OP is present with a value of 0 or 4; otherwise optional) A rendition ob-

ject (see Section 9.1.2, “Renditions”).

dictionary

(Required if OP is present with a value of 0, 1, 2, 3 or 4; otherwise optional) An indirect

reference to a screen annotation (see “Screen Annotations” on page 639).

integer

(Required if JS is not present; otherwise optional) The operation to perform when the

action is triggered. Valid values are:

If no rendition is associated with the annotation specified by AN, play the ren-

dition specified by R, associating it with the annotation. If a rendition is al-

ready associated with the annotation, it is stopped, and the new rendition is

associated with the annotation.

Stop any rendition being played in association with the annotation specified

by AN, and remove the association. If no rendition is being played, there is no

effect.

Pause any rendition being played in association with the annotation specified

by AN. If no rendition is being played, there is no effect.

Resume any rendition being played in association with the annotation speci-

fied by AN. If no rendition is being played or the rendition is not paused, there

is no effect.

Play the rendition specified by R, associating it with the annotation specified

by AN. If a rendition is already associated with the annotation, resume the

rendition if it is paused; otherwise, do nothing.

text string

(Required if OP is not present; otherwise optional) A text string or stream containing a

or stream

JavaScript script to be executed when the action is triggered.

Either the JS entry or the OP entry must be present. If both are present, OP is con-

sidered a fallback to be executed if the viewer application is unable to execute

JavaScripts. If OP has an unrecognized value and there is no JS entry, the action is

invalid.

In some situations, a pause (OP value of 2) or resume (OP value of 3) operation may

not make sense (for example, for a JPEG image) or the player may not support it. In

such cases, the user should be notified of the failure to perform the operation.

670

CHAPTER 8

Interactive Features

Before a rendition action is executed, the viewer application must make sure that

the P entry of the screen annotation dictionary references a valid page object and

that the annotation is present in the page object’s Annots array (see Table 3.27).

A rendition may play in the rectangle occupied by a screen annotation, even if the

annotation itself is not visible; for example, if its Hidden or NoView flags (see Ta-

ble 8.16) are set. If a screen annotation is not visible because its location on the

page is not being displayed by the viewer, the rendition is not visible. However, it

may become visible if the view changes, such as by scrolling.

Transition Actions

A transition action (PDF 1.5) can be used to control drawing during a sequence of

actions. As discussed in Section 8.5.1, “Action Dictionaries,” the Next entry in an

action dictionary can specify a sequence of actions. Viewer applications should

normally suspend drawing when such a sequence begins and resume drawing

when it ends. If a transition action is present during a sequence, the viewer should

render the state of the page viewing area as it exists after completion of the previous

action and display it using a transition specified in the action dictionary (see Table

8.65). Once this transition completes, drawing should be suspended again.

TABLE 8.65 Additional entries specific to a transition action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be Trans for a

transition action.

Trans

dictionary

(Required) The transition to use for the update of the display (see Table 8.13).

Go-To-3D-View Actions

A go-to-3D-view action (PDF 1.6) identifies a 3D annotation and specifies a view

for the annotation to use (see Section 9.5, “3D Artwork”). Table 8.66 shows the

entries in a go-to-3D-view action dictionary.

TABLE 8.66 Additional entries specific to a go-to-3D-view action

KEY

TYPE

VALUE

name

(Required) The type of action that this dictionary describes; must be GoTo3DView

for a transition action.

671

SECTION 8.6

Interactive Forms

KEY

TYPE

VALUE

dictionary

(Required) The target annotation for which to set the view.

(various)

(Required) The view to use. It can be one of the following types:

• A 3D view dictionary (see Section 9.5.3, “3D Views”).

• An integer specifying an index into the VA array in the 3D stream (see Table

9.35).

• A text string matching the IN entry in one of the views in the VA array (see Table

9.39).

• A name that indicates the first (F), last (L), next (N), previous (P), or default (D)

entries in the VA array; see discussion below.

The V entry selects the view to apply to the annotation specified by TA. This view

may be one of the predefined views specified by the VA entry of the 3D stream

(see Table 9.35) or a unique view specified here.

If the predefined view is specified by the names N (next) or P (previous), it should

be interpreted in the following way:

• When the last view applied was specified by means of the VA array, N and P in-

dicate the next and previous entries, respectively, in the VA array (wrapping

around if necessary).

• When the last view was not specified by means of VA, using N or P should result

in reverting to the default view.

8.6

Interactive Forms

An interactive form (PDF 1.2)—sometimes referred to as an AcroForm—is a

collection of fields for gathering information interactively from the user. A PDF

document may contain any number of fields appearing on any combination of

pages, all of which make up a single, global interactive form spanning the entire

document. Arbitrary subsets of these fields can be imported or exported from the

document; see Section 8.6.4, “Form Actions.”

Note: Interactive forms should not be confused with form XObjects (see Section 4.9,

“Form XObjects”). Despite the similarity of names, the two are different, unrelated

types of objects.

672

CHAPTER 8

Interactive Features

Each field in a document’s interactive form is defined by a field dictionary (see

Section 8.6.2, “Field Dictionaries”). For purposes of definition and naming, the

fields can be organized hierarchically and can inherit attributes from their an-

cestors in the field hierarchy. A field’s children in the hierarchy may also include

widget annotations (see “Widget Annotations” on page 640) that define its ap-

pearance on the page. A field whose children are widget annotations is called a

terminal field.

As a convenience, when a field has only a single associated widget annotation, the

contents of the field dictionary and the annotation dictionary (Section 8.4.1, “An-

notation Dictionaries”) may 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.) If such an object de-

fines an appearance stream, the appearance must be consistent with the object’s

current value as a field.

Note: Fields containing text whose contents are not known in advance may need to

construct their appearance streams dynamically instead of defining them statically

in an appearance dictionary; see “Variable Text” on page 677.

8.6.1

Interactive Form Dictionary

The contents and properties of a document’s interactive form are defined by an

interactive form dictionary that is referenced from the AcroForm entry in the doc-

ument catalog (see Section 3.6.1, “Document Catalog”). Table 8.67 shows the

contents of this dictionary.

TABLE 8.67 Entries in the interactive form dictionary

KEY

TYPE

VALUE

Fields

array

(Required) An array of references to the document’s root fields (those

with no ancestors in the field hierarchy).

NeedAppearances boolean

(Optional) A flag specifying whether to construct appearance streams

and appearance dictionaries for all widget annotations in the docu-

ment (see “Variable Text” on page 677). Default value: false.

SigFlags

integer

(Optional; PDF 1.3) A set of flags specifying various document-level

characteristics related to signature fields (see Table 8.68, below, and

“Signature Fields” on page 695). Default value: 0.

673

SECTION 8.6

Interactive Forms

KEY

TYPE

VALUE

array

(Required if any fields in the document have additional-actions dictio-

naries containing a C entry; PDF 1.3) An array of indirect references to

field dictionaries with calculation actions, defining the calculation or-

der in which their values will be recalculated when the value of any

field changes (see Section 8.5.2, “Trigger Events”).

dictionary

(Optional) A resource dictionary (see Section 3.7.2, “Resource Dic-

tionaries”) containing default resources (such as fonts, patterns, or col-

or spaces) to be used by form field appearance streams. At a

minimum, this dictionary must contain a Font entry specifying the re-

source name and font dictionary of the default font for displaying text.

(See implementation notes 113 and 114 in Appendix H.)

string

(Optional) A document-wide default value for the DA attribute of vari-

able text fields (see “Variable Text” on page 677).

integer

(Optional) A document-wide default value for the Q attribute of vari-

able text fields (see “Variable Text” on page 677).

XFA

stream or array

(Optional; PDF 1.5) A stream or array containing an XFA resource,

whose format is described by the Data Package (XDP) Specification.

(see the Bibliography).

The value of this entry must be either a stream representing the entire

contents of the XML Data Package or an array of text string and

stream pairs representing the individual packets comprising the XML

Data Package.

See Section 8.6.7, “XFA Forms,” for more information.

Note: In the original version of the PDF 1.5 specification, the value of

this entry was defined as a stream only; see implementation note 115 in

Appendix H.

The value of the interactive form dictionary’s SigFlags entry is an unsigned 32-bit

integer containing flags specifying various document-level characteristics related

to signature fields (see “Signature Fields” on page 695). Bit positions within the

flag word are numbered from 1 (low-order) to 32 (high-order). Table 8.68 shows

the meanings of the flags; all undefined flag bits are reserved and must be set to 0.

674

CHAPTER 8

Interactive Features

TABLE 8.68 Signature flags

BIT POSITION

NAME

MEANING

SignaturesExist

If set, the document contains at least one signature field. This flag allows a

viewer application to enable user interface items (such as menu items or

pushbuttons) related to signature processing without having to scan the

entire document for the presence of signature fields.

AppendOnly

If set, the document contains signatures that may be invalidated if the file

is saved (written) in a way that alters its previous contents, as opposed to

an incremental update. Merely updating the file by appending new infor-

mation to the end of the previous version is safe (see Section G.6, “Up-

dating Example”). Viewer applications can use this flag to present a user

requesting a full save with an additional alert box warning that signatures

will be invalidated and requiring explicit confirmation before continuing

with the operation.

8.6.2

Field Dictionaries

Each field in a document’s interactive form is defined by a field dictionary, which

must be an indirect object. The field dictionaries may be organized hierarchically

into one or more tree structures. Many field attributes are inheritable, meaning

that if they are not explicitly specified for a given field, their values are taken from

those of its parent in the field hierarchy. Such inheritable attributes are designated

as such in the tables below. The designation (Required; inheritable) means that an

attribute must be defined for every field, whether explicitly in its own field dictio-

nary or by inheritance from an ancestor in the hierarchy. Table 8.69 shows those

entries that are common to all field dictionaries, regardless of type. Entries that

pertain only to a particular type of field are described in the relevant sections be-

low.

675

SECTION 8.6

Interactive Forms

TABLE 8.69 Entries common to all field dictionaries

KEY

TYPE

VALUE

name

(Required for terminal fields; inheritable) The type of field that this dictionary

describes:

Btn

Button (see “Button Fields” on page 685)

Text (see “Text Fields” on page 691)

Choice (see “Choice Fields” on page 693)

Sig

(PDF 1.3) Signature (see “Signature Fields” on page 695)

Note: This entry may be present in a nonterminal field (one whose descendants

are fields) to provide an inheritable FT value. However, a nonterminal field does

not logically have a type of its own; it is merely a container for inheritable at-

tributes that are intended for descendant terminal fields of any type.

Parent

dictionary

(Required if this field is the child of another in the field hierarchy; absent other-

wise) The field that is the immediate parent of this one (the field, if any,

whose Kids array includes this field). A field can have at most one parent; that

is, it can be included in the Kids array of at most one other field.

Kids

array

(Sometimes required, as described below) An array of indirect references to the

immediate children of this field.

In a non-terminal field, the Kids array is required to refer to field dictionaries

that are immediate descendants of this field. In a terminal field, the Kids array

ordinarily must refer to one or more separate widget annotations that are as-

sociated with this field. However, if there is only one associated widget anno-

tation, and its contents have been merged into the field dictionary, Kids must

be omitted.

text string

(Optional) The partial field name (see “Field Names,” below; see also imple-

mentation notes 116 and 117 in Appendix H).

text string

(Optional; PDF 1.3) An alternate field name to be used in place of the actual

field name wherever the field must be identified in the user interface (such as

in error or status messages referring to the field). This text is also 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 Descrip-

tions”).

text string

(Optional; PDF 1.3) The mapping name to be used when exporting inter-

active form field data from the document.

integer

(Optional; inheritable) A set of flags specifying various characteristics of the

field (see Table 8.70). Default value: 0.

676

CHAPTER 8

Interactive Features

KEY

TYPE

VALUE

(various)

(Optional; inheritable) The field’s value, whose format varies depending on

the field type. See the descriptions of individual field types for further infor-

mation.

(various)

(Optional; inheritable) The default value to which the field reverts when a

reset-form action is executed (see “Reset-Form Actions” on page 707). The

format of this value is the same as that of V.

dictionary

(Optional; PDF 1.2) An additional-actions dictionary defining the field’s

behavior in response to various trigger events (see Section 8.5.2, “Trigger

Events”). This entry has exactly the same meaning as the AA entry in an

annotation dictionary (see Section 8.4.1, “Annotation Dictionaries”).

The value of the field dictionary’s Ff entry is an unsigned 32-bit integer contain-

ing flags specifying various characteristics of the field. Bit positions within the

flag word are numbered from 1 (low-order) to 32 (high-order). The flags shown

in Table 8.70 are common to all types of fields. Flags that apply only to specific

field types are discussed in the sections describing those types. All undefined flag

bits are reserved and must be set to 0.

TABLE 8.70 Field flags common to all field types

BIT POSITION

NAME

MEANING

ReadOnly

If set, the user may not change the value of the field. Any associated widget

annotations will not interact with the user; that is, they will not respond to

mouse clicks or change their appearance in response to mouse motions. This

flag is useful for fields whose values are computed or imported from a data-

base.

Required

If set, the field must have a value at the time it is exported by a submit-form

action (see “Submit-Form Actions” on page 703).

NoExport

If set, the field must not be exported by a submit-form action (see “Submit-

Form Actions” on page 703).

Field Names

The T entry in the field dictionary (see Table 8.69 on page 675) holds a text string

defining the field’s partial field name. The fully qualified field name is not explicit-

ly defined but is constructed from the partial field names of the field and all of its

677

SECTION 8.6

Interactive Forms

ancestors. For a field with no parent, the partial and fully qualified names are the

same. For a field that is the child of another field, the fully qualified name is

formed by appending the child field’s partial name to the parent’s fully qualified

name, separated by a period ( . ):

parent’s_full_name . child’s_partial_name

For example, if a field with the partial field name PersonalData has a child whose

partial name is Address, which in turn has a child with the partial name ZipCode,

the fully qualified name of this last field is

PersonalData . Address . ZipCode

Thus, all fields descended from a common ancestor share the ancestor’s fully

qualified field name as a common prefix in their own fully qualified names.

It is possible for different field dictionaries to have the same fully qualified field

name if they are descendants of a common ancestor with that name and have no

partial field names (T entries) of their own. Such field dictionaries are different

representations of the same underlying field; they should differ only in properties

that specify their visual appearance. In particular, field dictionaries with the same

fully qualified field name must have the same field type (FT), value (V), and de-

fault value (DV).

Variable Text

When the contents and properties of a field are known in advance, its visual ap-

pearance can be specified by an appearance stream defined in the PDF file (see

Section 8.4.4, “Appearance Streams,” and “Widget Annotations” on page 640). In

some cases, however, the field may contain text whose value is not known until

viewing time. Examples include text fields to be filled in with text typed by the

user from the keyboard and scrollable list boxes whose contents are determined

interactively at the time the document is displayed.

In such cases, the PDF document cannot provide a statically defined appearance

stream for displaying the field. Instead, the viewer application must construct an

appearance stream dynamically at viewing time. The dictionary entries shown in

Table 8.71 provide general information about the field’s appearance that can be

combined with the specific text it contains to construct an appearance stream.

678

CHAPTER 8

Interactive Features

TABLE 8.71 Additional entries common to all fields containing variable text

KEY

TYPE

VALUE

string

(Required; inheritable) The default appearance string containing a sequence of valid

page-content graphics or text state operators that define such properties as the field’s

text size and color.

integer

(Optional; inheritable) A code specifying the form of quadding (justification) to be

used in displaying the text:

Left-justified

Centered

Right-justified

Default value: 0 (left-justified).

text string

(Optional; PDF 1.5) A default style string, as described in “Rich Text Strings” on page

680.

text string or

(Optional; PDF 1.5) A rich text string, as described in “Rich Text Strings” on page 680.

text stream

The new appearance stream becomes the normal appearance (N) in the appear-

ance dictionary associated with the field’s widget annotation (see Table 8.19 on

page 614). (If the widget annotation has no appearance dictionary, the viewer ap-

plication must create one and store it in the annotation dictionary’s AP entry.)

In PDF 1.5, form fields that have the RichText flag set (see Table 8.77) specify for-

matting information as described in “Rich Text Strings” on page 680. For these

fields, the conventions described below are not used, and the entire annotation

appearance is regenerated each time the value is changed.

For non-rich text fields, the appearance stream—which, like all appearance

streams, is a form XObject—has the contents of its form dictionary initialized as

follows:

• The resource dictionary (Resources) is created using resources from the inter-

active form dictionary’s DR entry (see Table 8.67); see also implementation note

118 in Appendix H.

• The lower-left corner of the bounding box (BBox) is set to coordinates (0, 0) in

the form coordinate system. The box’s top and right coordinates are taken from

679

SECTION 8.6

Interactive Forms

the dimensions of the annotation rectangle (the Rect entry in the widget anno-

tation dictionary).

• All other entries in the appearance stream’s form dictionary are set to their

default values (see Section 4.9, “Form XObjects”).

The appearance stream includes the following section of marked content, which

represents the portion of the stream that draws the text:

Example 8.14

/Tx BMC

% Begin marked content with tag Tx

% Save graphics state

… Any required graphics state changes, such as clipping…

% Begin text object

… Default appearance string ( DA )…

…Text-positioning and text-showing operators to show the variable text…

% End text object

% Restore graphics state

EMC

% End marked content

The BMC (begin marked content) and EMC (end marked content) operators are

discussed in Section 10.5, “Marked Content”. q (save graphics state) and Q (re-

store graphics state) are discussed in Section 4.3.3, “Graphics State Operators”. BT

(begin text object) and ET (end text object) are discussed in Section 5.3, “Text

Objects.” See Example 8.18 for an example.

The default appearance string (DA) contains any graphics state or text state oper-

ators needed to establish the graphics state parameters, such as text size and color,

for displaying the field’s variable text. Only operators that are allowed within text

objects may occur in this string (see Figure 4.1 on page 197). At a minimum, the

string must include a Tf (text font) operator along with its two operands, font and

size. The specified font value must match a resource name in the Font entry of the

default resource dictionary (referenced from the DR entry of the interactive form

dictionary; see Table 8.67). A zero value for size means that the font is to be auto-

sized: its size is computed as a function of the height of the annotation rectangle.

The default appearance string should contain at most one Tm (text matrix) opera-

tor. If this operator is present, the viewer application should replace the horizon-

tal and vertical translation components with positioning values it determines to

be appropriate, based on the field value, the quadding (Q) attribute, and any lay-

out rules it employs. If the default appearance string contains no Tm operator, the

680

CHAPTER 8

Interactive Features

viewer should insert one in the appearance stream (with appropriate horizontal

and vertical translation components) after the default appearance string and be-

fore the text-positioning and text-showing operators for the variable text.

To update an existing appearance stream to reflect a new field value, the viewer

application should first copy any needed resources from the document’s DR dic-

tionary (see Table 8.67) into the stream’s Resources dictionary. (If the DR and

Resources dictionaries contain resources with the same name, the one already in

the Resources dictionary should be left intact, not replaced with the correspond-

ing value from the DR dictionary.) The viewer application should then replace the

existing contents of the appearance stream from /Tx BMC to the matching EMC

with the corresponding new contents as shown in Example 8.14. (If the existing

appearance stream contains no marked content with tag Tx, the new contents

should be appended to the end of the original stream.) Also see implementation

note 119 in Appendix H.

Rich Text Strings

Beginning with PDF 1.5, the text contents of variable text form fields, as well as

markup annotations, can include formatting (style) information. These rich text

strings are fully-formed XML documents that conform to the rich text conven-

tions specified for the XML Forms Architecture (XFA) specification, which is it-

self a subset of the XHTML 1.0 specification, augmented with a restricted set of

CSS2 style attributes (see the Bibliography for references to all these standards).

Table 8.72 lists the XHTML elements that can appear in rich text strings. The

<body> element is the root element; its required attributes are listed in Table 8.73.

Other elements ( and ) contain enclosed text that may take style at-

tributes, which are listed in Table 8.74. These style attributes are CSS inline style

property declarations of the form name:value, with each declaration separated by

a semicolon, as illustrated in Example 8.15 on page 684.

In PDF 1.6, PDF supports the rich text elements and attributes specified in the

XML Forms Architecture (XFA) Specification, 2.2 (see Bibliography). These rich

text elements and attributes are a superset of those described in Table 8.72, Table

8.73 and Table 8.73. In PDF 1.7, PDF supports the rich text elements and at-

tributes specified in the XML Forms Architecture (XFA) Specification, 2.4 (see Bib-

liography). XFA 2.2 and XFA 2.4 describe the same rich text elements and

attributes; however, XFA 2.4 expands the range of supported character codes.

681

SECTION 8.6

Interactive Forms

TABLE 8.72 XHTML elements used in rich text strings

ELEMENT

DESCRIPTION

<body>

The element at the root of the XML document. Table 8.73 lists the required attributes for this

element.

Encloses text that is interpreted as a paragraph. It may take the style attributes listed in Table

8.74.

Encloses text that is displayed in an italic font.

Encloses text that is displayed in a bold font.

Groups text solely for the purpose of applying styles (using the attributes in Table 8.74).

TABLE 8.73 Attributes of the <body> element

ATTRIBUTE

DESCRIPTION

xmlns

The default namespaces for elements within the rich text string. Must be xmlns="http://

www.w3.org/1999/xhtml"

xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0".

xfa:contentType

Must be "text/html".

xfa:APIVersion

A string that identifies the software used to generate the rich text string. It must be of the

form software_name:software_version, where

• software_name identifies the software by name. It must not contain spaces.

• software_version identifies the version of the software. It consists of a series of integers

separated by decimal points. Each integer is a version number, the leftmost value being a

major version number, with values to the right increasingly minor. When comparing

strings, the versions are compared in order. For example “5.2” is less than “5.13” because

2 is less than 13; the string is not treated as a decimal number. When comparing strings

with different numbers of sections, the string with fewer sections is implicitly padded on

the right with sections containing “0” to make the number of sections equivalent.

xfa:spec

The version of the XML Forms Architecture (XFA) specification to which the rich text

string complies. PDF 1.5 supports XFA 2.0; PDF 1.6 supports XFA 2.2; and PDF 1.7 sup-

ports XFA 2.4.

682

CHAPTER 8

Interactive Features

TABLE 8.74 CSS2 style attributes used in rich text strings

ATTRIBUTE

VALUE

DESCRIPTION

text-align

keyword

Horizontal alignment. Possible values: left, right, and center.

vertical-align

decimal

An amount by which to adjust the baseline of the enclosed text. A positive

value indicates a superscript; a negative value indicates a subscript. The value

is of the form <decimal number>pt, optionally preceded by a sign, and fol-

lowed by “pt”. Examples: -3pt, 4pt.

font-size

decimal

The font size of the enclosed text. The value is of the form

<decimal number>pt.

font-style

keyword

Specifies whether the enclosed text should be displayed using a normal or

italic (oblique) font. Possible values: normal, italic.

font-weight

keyword

The weight of the font for the enclosed text. Possible values: normal, bold,

100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: normal is equivalent to 400, and bold is equivalent to 700.

font-family

list

A font name or list of font names to be used to display the enclosed text. (If a

list is provided, the first one containing glyphs for the specified text is used.)

font

list

A shorthand CSS font property of the form

font:<font-style> <font-weight> <font-size> <font-family>

color

RGB value

The color of the enclosed text. It can be in one of two forms:

• #rrggbb with a 2-digit hexadecimal value for each component

• rgb(rrr,ggg,bbb) with a decimal value for each component.

Note: Although the values specified by the color property are interpreted as

sRGB values, they are transformed into values in a non-ICC based color space

when used to generate the annotation’s appearance.

text-decoration

keyword

One of the following keywords:

• underline: The enclosed text should be underlined.

• line-through: The enclosed text should have a line drawn through it.

font-stretch

keyword

Specifies a normal, condensed or extended face from a font family. Support-

ed values from narrowest to widest are ultra-condensed, extra-condensed,

condensed, semi-condensed, normal, semi-expanded, expanded, extra-

expanded, and ultra-expanded.

Была ли эта страница вам полезна?

Да!Нет

6 посетителей считают эту страницу полезной.

PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 2) — page 2

Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.