PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 1) — page 15
CHAPTER 8
Interactive Features
8
This chapter describes the PDF features that allow a user to interact with a docu-
ment on the screen, using the mouse and keyboard (with the exception of multi-
media features, which are described in Chapter 9, “Multimedia Features”):
• Preference settings to control the way the document is presented on the screen
(Section 8.1, “Viewer Preferences”)
• Navigation facilities for moving through the document in a variety of ways
(Sections 8.2, “Document-Level Navigation,” and 8.3, “Page-Level Navigation”)
• Annotations for adding text notes, sounds, movies, and other ancillary infor-
mation to the document (Section 8.4, “Annotations”)
• Actions that can be triggered by specified events (Section 8.5, “Actions”)
• Interactive forms for gathering information from the user (Section 8.6, “Interac-
tive Forms”)
• Digital signatures that authenticate the identity of a user and the validity of the
document’s contents (Section 8.7, “Digital Signatures”)
• Measurement properties that enable the display of real-world units correspond-
ing to objects on a page (Section 8.8, “Measurement Properties”)
8.1
Viewer Preferences
The ViewerPreferences entry in a document’s catalog (see Section 3.6.1, “Docu-
ment Catalog”) designates a viewer preferences dictionary (PDF 1.2) controlling
the way the document is to be presented on the screen or in print. If no such dic-
tionary is specified, viewing and printing applications should behave in accor-
dance with their own current user preference settings. Table 8.1 shows the
contents of the viewer preferences dictionary.
577
578
CHAPTER 8
Interactive Features
TABLE 8.1 Entries in a viewer preferences dictionary
KEY
TYPE
VALUE
HideToolbar
boolean
(Optional) A flag specifying whether to hide the viewer application’s tool
bars when the document is active. Default value: false.
HideMenubar
boolean
(Optional) A flag specifying whether to hide the viewer application’s
menu bar when the document is active. Default value: false.
HideWindowUI
boolean
(Optional) A flag specifying whether to hide user interface elements in
the document’s window (such as scroll bars and navigation controls),
leaving only the document’s contents displayed. Default value: false.
FitWindow
boolean
(Optional) A flag specifying whether to resize the document’s window to
fit the size of the first displayed page. Default value: false.
CenterWindow
boolean
(Optional) A flag specifying whether to position the document’s window
in the center of the screen. Default value: false.
DisplayDocTitle
boolean
(Optional; PDF 1.4) A flag specifying whether the window’s title bar
should display the document title taken from the Title entry of the docu-
ment information dictionary (see Section 10.2.1, “Document Informa-
tion Dictionary”). If false, the title bar should instead display the name
of the PDF file containing the document. Default value: false.
NonFullScreenPageMode
name
(Optional) The document’s page mode, specifying how to display the
document on exiting full-screen mode:
UseNone
Neither document outline nor thumbnail images
visible
UseOutlines Document outline visible
UseThumbs Thumbnail images visible
UseOC
Optional content group panel visible
This entry is meaningful only if the value of the PageMode entry in the
catalog dictionary (see Section 3.6.1, “Document Catalog”) is FullScreen;
it is ignored otherwise. Default value: UseNone.
Direction
name
(Optional; PDF 1.3) The predominant reading order for text:
L2R
Left to right
R2L
Right to left (including vertical writing systems, such
as Chinese, Japanese, and Korean)
This entry has no direct effect on the document’s contents or page num-
bering but can be used to determine the relative positioning of pages
when displayed side by side or printed n-up. Default value: L2R.
579
SECTION 8.1
Viewer Preferences
KEY
TYPE
VALUE
ViewArea
name
(Optional; PDF 1.4) The name of the page boundary representing the
area of a page to be displayed when viewing the document on the screen.
The value is the key designating the relevant page boundary in the page
object (see
“Page Objects” on page 144 and Section 10.10.1, “Page
Boundaries”). If the specified page boundary is not defined in the page
object, its default value is used, as specified in Table 3.27 on page 145.
Default value: CropBox.
Note: This entry is intended primarily for use by prepress applications that
interpret or manipulate the page boundaries as described in Section
10.10.1, “Page Boundaries.” Most PDF consumer applications disregard it.
ViewClip
name
(Optional; PDF 1.4) The name of the page boundary to which the con-
tents of a page are to be clipped when viewing the document on the
screen. The value is the key designating the relevant page boundary in
the page object (see “Page Objects” on page 144 and Section 10.10.1,
“Page Boundaries”). If the specified page boundary is not defined in the
page object, its default value is used, as specified in Table 3.27 on page
145. Default value: CropBox.
Note: This entry is intended primarily for use by prepress applications that
interpret or manipulate the page boundaries as described in Section
10.10.1, “Page Boundaries.” Most PDF consumer applications disregard it.
PrintArea
name
(Optional; PDF 1.4) The name of the page boundary representing the
area of a page to be rendered when printing the document. The value is
the key designating the relevant page boundary in the page object (see
“Page Objects” on page 144 and Section 10.10.1, “Page Boundaries”). If
the specified page boundary is not defined in the page object, its default
value is used, as specified in Table 3.27 on page 145. Default value:
CropBox.
Note: This entry is intended primarily for use by prepress applications that
interpret or manipulate the page boundaries as described in Section
10.10.1, “Page Boundaries.” Most PDF consumer applications disregard it.
580
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
PrintClip
name
(Optional; PDF 1.4) The name of the page boundary to which the con-
tents of a page are to be clipped when printing the document. The value
is the key designating the relevant page boundary in the page object (see
“Page Objects” on page 144 and Section 10.10.1, “Page Boundaries”). If
the specified page boundary is not defined in the page object, its default
value is used, as specified in Table 3.27 on page 145. Default value:
CropBox.
Note: This entry is intended primarily for use by prepress applications that
interpret or manipulate the page boundaries as described in Section
10.10.1, “Page Boundaries.” Most PDF consumer applications disregard it.
PrintScaling
name
(Optional; PDF 1.6) The page scaling option to be selected when a print
dialog is displayed for this document. Valid values are None, which indi-
cates that the print dialog should reflect no page scaling, and
AppDefault, which indicates that applications should use the current
print scaling. If this entry has an unrecognized value, applications
should use the current print scaling. Default value: AppDefault.
Note: If the print dialog is suppressed and its parameters are provided di-
rectly by the application, the value of this entry should still be used.
Duplex
name
(Optional; PDF 1.7) The paper handling option to use when printing the
file from the print dialog. The following values are valid:
Simplex - Print single-sided
DuplexFlipShortEdge - Duplex and flip on the short edge of the sheet
DuplexFlipLongEdge - Duplex and flip on the long edge of the sheet
Default value: none
PickTrayByPDFSize
boolean
(Optional; PDF 1.7) A flag specifying whether the PDF page size is used
to select the input paper tray. This setting influences only the preset val-
ues used to populate the print dialog presented by a PDF viewer applica-
tion. If PickTrayByPDFSize is true, the check box in the print dialog
associated with input paper tray is checked.
Note: This setting has no effect on Mac OS systems, which do not provide
the ability to pick the input tray by size.
Default value: as defined by the PDF viewer application
581
SECTION 8.2
Document-Level Navigation
KEY
TYPE
VALUE
PrintPageRange
array
(Optional; PDF 1.7) The page numbers used to initialize the print dialog
box when the file is printed. The first page of the PDF file is denoted by
1. Each pair consists of the first and last pages in the sub-range. An odd
number of integers causes this entry to be ignored. Negative numbers
cause the entire array to be ignored.
Default value: as defined by PDF viewer application
NumCopies
integer
(Optional; PDF 1.7) The number of copies to be printed when the print
dialog is opened for this file. Supported values are the integers 2 through
5. Values outside this range are ignored.
Default value: as defined by PDF viewer application, but typically 1
8.2
Document-Level Navigation
The features described in this section allow a PDF viewer application to present
the user with an interactive, global overview of a document in either of two forms:
• As a hierarchical outline showing the document’s internal structure
• As a collection of thumbnail images representing the pages of the document in
miniature form
Each item in the outline or each thumbnail image can be associated with a corre-
sponding destination in the document, so that the user can jump directly to the
destination by clicking with the mouse.
8.2.1
Destinations
A destination defines a particular view of a document, consisting of the following
items:
• The page of the document to be displayed
• The location of the document window on that page
• The magnification (zoom) factor to use when displaying the page
Destinations may be associated with outline items (see Section 8.2.2, “Document
Outline”), annotations (“Link Annotations” on page 622), or actions (“Go-To Ac-
582
CHAPTER 8
Interactive Features
tions” on page 654 and “Remote Go-To Actions” on page 655). In each case, the
destination specifies the view of the document to be presented when the outline
item or annotation is opened or the action is performed. In addition, the optional
OpenAction entry in a document’s catalog (Section 3.6.1, “Document Catalog”)
may specify a destination to be displayed when the document is opened. A desti-
nation may be specified either explicitly by an array of parameters defining its
properties or indirectly by name.
Explicit Destinations
Table 8.2 shows the allowed syntactic forms for specifying a destination explicitly
in a PDF file. In each case, page is an indirect reference to a page object. All coor-
dinate values (left, right, top, and bottom) are expressed in the default user space
coordinate system. The page’s bounding box is the smallest rectangle enclosing all
of its contents. (If any side of the bounding box lies outside the page’s crop box,
the corresponding side of the crop box is used instead; see Section 10.10.1, “Page
Boundaries,” for further discussion of the crop box.)
Note: No page object can be specified for a destination associated with a remote go-
to action (see “Remote Go-To Actions” on page 655) because the destination page is
in a different PDF document. In this case, the page parameter specifies a page num-
ber within the remote document instead of a page object in the current document.
TABLE 8.2 Destination syntax
SYNTAX
MEANING
[ page /XYZ left top zoom ]
Display the page designated by page, with the coordinates (left, top) posi-
tioned at the upper-left corner of the window and the contents of the page
magnified by the factor zoom. A null value for any of the parameters left, top,
or zoom specifies that the current value of that parameter is to be retained un-
changed. A zoom value of 0 has the same meaning as a null value.
[ page /Fit ]
Display the page designated by page, with its contents magnified just enough
to fit the entire page within the window both horizontally and vertically. If
the required horizontal and vertical magnification factors are different, use
the smaller of the two, centering the page within the window in the other
dimension.
583
SECTION 8.2
Document-Level Navigation
SYNTAX
MEANING
[ page
/FitH top ]
Display the page designated by page, with the vertical coordinate top posi-
tioned at the top edge of the window and the contents of the page magnified
just enough to fit the entire width of the page within the window. A null value
for top specifies that the current value of that parameter is to be retained un-
changed.
[ page
/FitV left ]
Display the page designated by page, with the horizontal coordinate left posi-
tioned at the left edge of the window and the contents of the page magnified
just enough to fit the entire height of the page within the window. A null val-
ue for left specifies that the current value of that parameter is to be retained
unchanged.
[ page
/FitR left bottom right top ]
Display the page designated by page, with its contents magnified just enough
to fit the rectangle specified by the coordinates left, bottom, right, and top
entirely within the window both horizontally and vertically. If the required
horizontal and vertical magnification factors are different, use the smaller of
the two, centering the rectangle within the window in the other dimension. A
null value for any of the parameters may result in unpredictable behavior.
[ page
/FitB ]
(PDF 1.1) Display the page designated by page, with its contents magnified
just enough to fit its bounding box entirely within the window both hori-
zontally and vertically. If the required horizontal and vertical magnification
factors are different, use the smaller of the two, centering the bounding box
within the window in the other dimension.
[ page
/FitBH top ]
(PDF 1.1) Display the page designated by page, with the vertical coordinate
top positioned at the top edge of the window and the contents of the page
magnified just enough to fit the entire width of its bounding box within the
window. A null value for top specifies that the current value of that parameter
is to be retained unchanged.
[ page
/FitBV left ]
(PDF 1.1) Display the page designated by page, with the horizontal coordi-
nate left positioned at the left edge of the window and the contents of the page
magnified just enough to fit the entire height of its bounding box within the
window. A null value for left specifies that the current value of that parameter
is to be retained unchanged.
Named Destinations
Instead of being defined directly with the explicit syntax shown in Table 8.2, a
destination may be referred to indirectly by means of a name object (PDF 1.1) or
a byte string (PDF 1.2). This capability is especially useful when the destination is
584
CHAPTER 8
Interactive Features
located in another PDF document. For example, a link to the beginning of Chap-
ter 6 in another document might refer to the destination by a name, such as
Chap6 . begin, instead of by an explicit page number in the other document. Then,
the location of the chapter in the other document could change without invalidat-
ing the link. If an annotation or outline item that refers to a named destination
has an associated action, such as a remote go-to action (see “Remote Go-To Ac-
tions” on page 655) or a thread action (“Thread Actions” on page 661), the desti-
nation is in the file specified by the action’s F entry, if any; if there is no F entry,
the destination is in the current file.
In PDF 1.1, the correspondence between name objects and destinations is
defined by the Dests entry in the document catalog (see Section 3.6.1, “Docu-
ment Catalog”). The value of this entry is a dictionary in which each key is a des-
tination name and the corresponding value is either an array defining the
destination, using the syntax shown in Table 8.2, or a dictionary with a D entry
whose value is such an array. The latter form allows additional attributes to be
associated with the destination, as well as enabling a go-to action (see “Go-To
Actions” on page 654) to be used as the target of a named destination.
In PDF 1.2, the correspondence between strings and destinations is defined by
the Dests entry in the document’s name dictionary (see Section 3.6.3, “Name Dic-
tionary”). The value of this entry is a name tree (Section 3.8.5, “Name Trees”)
mapping name strings to destinations. (The keys in the name tree may be treated
as text strings for display purposes.) The destination value associated with a key
in the name tree may be either an array or a dictionary, as described in the pre-
ceding paragraph.
Note: The use of strings as destination names is a PDF 1.2 feature. If compatibility
with earlier versions of PDF is required, only name objects may be used to refer to
named destinations. A document that supports PDF 1.2 can contain both types.
However, if backward compatibility is not a consideration, applications should use
the string form of representation in the Dests name tree.
8.2.2
Document Outline
A PDF document may optionally display a document outline on the screen, allow-
ing the user to navigate interactively from one part of the document to another.
The outline consists of a tree-structured hierarchy of outline items (sometimes
called bookmarks), which serve as a visual table of contents to display the docu-
ment’s structure to the user. The user can interactively open and close individual
585
SECTION 8.2
Document-Level Navigation
items by clicking them with the mouse. When an item is open, its immediate chil-
dren in the hierarchy become visible on the screen; each child may in turn be
open or closed, selectively revealing or hiding further parts of the hierarchy.
When an item is closed, all of its descendants in the hierarchy are hidden. Click-
ing the text of any visible item activates the item, causing the viewer application to
jump to a destination or trigger an action associated with the item.
The root of a document’s outline hierarchy is an outline dictionary specified by
the Outlines entry in the document catalog (see Section 3.6.1, “Document Cata-
log”). Table 8.3 shows the contents of this dictionary. Each individual outline item
within the hierarchy is defined by an outline item dictionary (Table 8.4). The
items at each level of the hierarchy form a linked list, chained together through
their Prev and Next entries and accessed through the First and Last entries in the
parent item (or in the outline dictionary in the case of top-level items). When dis-
played on the screen, the items at a given level appear in the order in which they
occur in the linked list. (See also implementation note 74 in Appendix H.)
TABLE 8.3 Entries in the outline dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be Outlines for an outline dictionary.
First
dictionary
(Required if there are any open or closed outline entries; must be an indirect ref-
erence) An outline item dictionary representing the first top-level item in the
outline.
Last
dictionary
(Required if there are any open or closed outline entries; must be an indirect ref-
erence) An outline item dictionary representing the last top-level item in the
outline.
Count
integer
(Required if the document has any open outline entries) The total number of
open items at all levels of the outline. This entry should be omitted if there
are no open outline items.
TABLE 8.4 Entries in an outline item dictionary
KEY
TYPE
VALUE
Title
text string
(Required) The text to be displayed on the screen for this item.
Parent
dictionary
(Required; must be an indirect reference) The parent of this item in the outline
hierarchy. The parent of a top-level item is the outline dictionary itself.
586
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
Prev
dictionary
(Required for all but the first item at each level; must be an indirect reference)
The previous item at this outline level.
Next
dictionary
(Required for all but the last item at each level; must be an indirect reference)
The next item at this outline level.
First
dictionary
(Required if the item has any descendants; must be an indirect reference) The
first of this item’s immediate children in the outline hierarchy.
Last
dictionary
(Required if the item has any descendants; must be an indirect reference) The
last of this item’s immediate children in the outline hierarchy.
Count
integer
(Required if the item has any descendants) If the item is open, the total num-
ber of its open descendants at all lower levels of the outline hierarchy. If the
item is closed, a negative integer whose absolute value specifies how many
descendants would appear if the item were reopened.
Dest
name,
(Optional; not permitted if an A entry is present) The destination to be dis-
byte string, or
played when this item is activated (see Section 8.2.1, “Destinations”; see also
array
implementation note 75 in Appendix H).
A
dictionary
(Optional; PDF 1.1; not permitted if a Dest entry is present) The action to be
performed when this item is activated (see Section 8.5, “Actions”).
SE
dictionary
(Optional; PDF 1.3; must be an indirect reference) The structure element to
which the item refers (see Section 10.6.1, “Structure Hierarchy”).
Note: The ability to associate an outline item with a structure element (such as
the beginning of a chapter) is a PDF 1.3 feature. For backward compatibility
with earlier PDF versions, such an item should also specify a destination (Dest)
corresponding to an area of a page where the contents of the designated struc-
ture element are displayed.
C
array
(Optional; PDF 1.4) An array of three numbers in the range 0.0 to 1.0, repre-
senting the components in the DeviceRGB color space of the color to be used
for the outline entry’s text. Default value: [ 0.0 0.0 0.0 ].
F
integer
(Optional; PDF 1.4) A set of flags specifying style characteristics for display-
ing the outline item’s text (see Table 8.5). Default value: 0.
The value of the outline item dictionary’s F entry (PDF 1.4) is an unsigned 32-bit
integer containing flags specifying style characteristics for displaying the item. Bit
positions within the flag word are numbered from 1 (low-order) to 32 (high-
587
SECTION 8.2
Document-Level Navigation
order). Table 8.5 shows the meanings of the flags; all undefined flag bits are
reserved and must be set to 0.
TABLE 8.5 Outline item flags
BIT POSITION
NAME
MEANING
1
Italic
If set, display the item in italic.
2
Bold
If set, display the item in bold.
Example 8.1 shows a typical outline dictionary and outline item dictionary. See
Appendix G for an example of a complete outline hierarchy.
Example 8.1
21 0 obj
<< /Count 6
/First
22 0 R
/Last
29 0 R
>>
endobj
22 0 obj
<< /Title ( Chapter 1 )
/Parent 21 0 R
/Next 26 0 R
/First
23 0 R
/Last
25 0 R
/Count 3
/Dest [ 3 0 R /XYZ 0 792 0 ]
>>
endobj
8.2.3
Thumbnail Images
A PDF document can define thumbnail images representing the contents of its
pages in miniature form. A viewer application can display these images on the
screen, allowing the user to navigate to a page by clicking its thumbnail image:
Note: Thumbnail images are not required, and may be included for some pages and
not for others.
588
CHAPTER 8
Interactive Features
The thumbnail image for a page is an image XObject specified by the Thumb
entry in the page object (see “Page Objects” on page 144). It has the usual struc-
ture for an image dictionary (Section 4.8.4, “Image Dictionaries”), but only the
Width, Height, ColorSpace, BitsPerComponent, and Decode entries are signifi-
cant; all of the other entries listed in Table 4.39 on page 340 are ignored if present.
(If a Subtype entry is specified, its value must be Image.) The image’s color space
must be either DeviceGray or DeviceRGB, or an Indexed space based on one of
these. Example 8.2 shows a typical thumbnail image definition.
Example 8.2
12 0 obj
<< /Width 76
/Height 99
/ColorSpace /DeviceRGB
/BitsPerComponent 8
/Length 13 0 R
/Filter
[ /ASCII85Decode /DCTDecode ]
>>
stream
s4IA>!"M;*Ddm8XA,lT0!!3,S!/(=R!<E3%!<N<(!WrK*!WrN,
… Omitted data…
endstream
endobj
13 0 obj
% Length of stream
…
endobj
8.2.4
Collections
Beginning with PDF 1.7, PDF documents can specify how a viewer application’s
user interface presents collections of file attachments, where the attachments are
related in structure or content. Such a presentation is called a portable collection.
The intent of portable collections is to present, sort, and search collections of relat-
ed documents, such as email archives, photo collections, and engineering bid
sets. There is no requirement that files in a collection have an implicit relation-
ship or even a similarity; however, showing differentiating characteristics of relat-
ed documents can be helpful for document navigation.
589
SECTION 8.2
Document-Level Navigation
A collection dictionary specifies the viewing and organizational characteristics of
portable collections. If this dictionary is present in a PDF document, the user in-
terface presents the document as a portable collection. The EmbeddedFiles name
tree specifies file attachments (see Section 3.10.3, “Embedded File Streams).
When a PDF 1.7-compliant viewer application first opens a PDF document con-
taining a collection, it must display the contents of the initial document, along
with a list of the documents present in the EmbeddedFiles name tree. The docu-
ment list must include the additional document information specified by the col-
lection schema. The initial document can be the container PDF or one of the
embedded documents.
The page content in the initial document typically contains information that
helps the viewer understand what is contained in the collection, such as a title
and an introductory paragraph.
The file attachments comprising a collection are located in the EmbeddedFiles
name tree. All attachments in that tree are in the collection; any attachments not
in that tree are not.
Table 8.6 describes the entries in a collection dictionary.
TABLE 8.6 Entries in a collection dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, must be Collection for a collection dictionary.
Schema
dictionary
(Optional) A collection schema dictionary (see Table 8.7). If absent,
the PDF viewer application may choose useful defaults that are
known to exist in a file specification dictionary, such as the file
name, file size, and modified date.
D
byte string
(Optional) A string that identifies an entry in the EmbeddedFiles
name tree, controlling the document that is initially presented in
the user interface. If the D entry is missing or in error, the initial
document is the one that contains the collection dictionary.
590
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
View
name
(Optional) The initial view. The following values are valid:
D The collection view is presented in details mode, with all
information in the Schema dictionary presented in a multi-
column format. This mode provides the most information
to the user.
T The collection view is presented in tile mode, with each file
in the collection denoted by a small icon and a subset of in-
formation from the Schema dictionary. This mode provides
top-level information about the file attachments to the user.
H The collection view is initially hidden, without preventing
the user from obtaining a file list via explicit action.
Default value: D
Sort
dictionary
(Optional) A collection sort dictionary, which specifies the order in
which items in the collection should be sorted in the user interface
(see Table 8.9 on page 592).
A collection schema dictionary consists of a variable number of individual collec-
tion field dictionaries. Each collection field dictionary has a key chosen by the
producer, which is used to associate a field with data in a file specification. Table
8.7 describes the entries in a collection schema dictionary.
TABLE 8.7 Entries in a collection schema dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, must be CollectionSchema for a collection schema dictio-
nary.
Other keys chosen by
dictionary
(Optional) Each dictionary entry is a collection field dictionary.
producer
Each key name is chosen at the discretion of the producer. The key
name of each collection field dictionary is used to identify a corre-
sponding collection item dictionary in a file specification dictio-
nary.
A collection field dictionary describes the attributes of a particular field in a porta-
ble collection, including the type of data stored in the field and the lookup key
used to locate the field data in the file specification dictionary. Table 8.8 describes
the entries in a collection field dictionary.
591
SECTION 8.2
Document-Level Navigation
TABLE 8.8 Entries in a collection field dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be CollectionField for a collection field dictionary.
Subtype
name
(Required) The subtype of collection field or file-related field that this dic-
tionary describes. This entry identifies the type of data that is stored in the
field.
The following values identify the types of fields in the collection item or
collection subitem dictionary:
S A text field. The field data is stored as a PDF text string.
D A date field. The field data is stored as a PDF date string.
N A number field. The field data is stored as a PDF number.
The following values identify the types of file-related fields:
F The field data is the file name of the embedded file stream, as iden-
tified by the UF entry of the file specification, if present; otherwise
by the F entry of the file specification (see Table 3.41).
Desc The field data is the description of the embedded file stream, as
identified by the Desc entry in the file specification dictionary (see
Table 3.41).
ModDate The field data is the modification date of the embedded file
stream, as identified by the ModDate entry in the embedded file
parameter dictionary (see Table 3.43).
CreationDate The field data is the creation date of the embedded file
stream, as identified by the CreationDate entry in the embedded
file parameter dictionary (see Table 3.43).
Size The field data is the size of the embedded file, as identified by the
Size entry in the embedded file parameter dictionary (see Table
3.43).
N
text string
(Required) The textual field name that is displayed to the user by the PDF
viewer application.
O
integer
(Optional) The relative order of the field name in the user interface. Fields
are sorted by the PDF viewer application in ascending order.
592
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
V
boolean
(Optional) The initial visibility of the field in the user interface. Default
value: true.
E
boolean
(Optional) A flag indicating whether the PDF viewer application should
provide support for editing the field value. Default value: false.
A collection sort dictionary identifies the fields that are used to sort items in the
collection. The type of sorting depends on the type of data:
• Text strings are ordered lexically from smaller to larger, if ascending order is
specified.
• Numbers are ordered numerically from smaller to larger, if ascending order is
specified.
• Dates are ordered from oldest to newest, if ascending order is specified.
Table 8.9 describes the entries in a collection sort dictionary.
TABLE 8.9 Entries in a collection sort dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be CollectionSort for a collection sort dictionary.
S
name or
(Required) The name or names of fields that the PDF viewer application uses
array
to sort the items in the collection. If the value is a name, it identifies a field
described in the parent collection dictionary.
If the value is an array, each element of the array is a name that identifies a
field described in the parent collection dictionary. The array form is used to
allow additional fields to contribute to the sort, where each additional field
is used to break ties. More specifically, if multiple collection item dictionar-
ies have the same value for the first field named in the array, the values for
successive fields named in the array are used for sorting, until a unique or-
der is determined or until the named fields are exhausted.
A
boolean or
(Optional) Specifies whether the items in the collection are sorted in ascend-
array
ing order. If the array form is used, each element of the array is a boolean
value that specifies whether the entry at the same index in the S array is sort-
ed in ascending order.
Default value: true.
593
SECTION 8.2
Document-Level Navigation
Example 8.3 shows a collection dictionary representing an email in-box, where
each item in the collection is an email message. The actual email messages are
contained in file specification dictionaries. The organizational data associated
with each email is described in a collection schema dictionary. Most actual orga-
nizational data (from, to, date, and subject) is provided in a collection item dic-
tionary, but the size data comes from the embedded file parameter dictionary.
Example 8.3
/Collection <<
/Type /Collection
/Schema <<
/Type /CollectionSchema
/from << /Subtype /S /N (From) /O 1 /V true /E false>>
/to << /Subtype /S /N (To) /O 2 /V true /E false >>
/date << /Subtype /D /N (Date received) /O 3 /V true /E false >>
/subject << /Subtype /S /N (Subject) /O 4 /V true /E false >>
/size << /Subtype /Size /N (Size) /O 5 /V true /E false >>
>>
/D (Doc1)
/View /D
/Sort << /S /date /A false >>
>>
Example 8.4 shows a collection item dictionary and a collection subitem dictio-
nary. These dictionaries contain entries that correspond to the schema entries
specified in Example 8.3. Section 3.10.5, “Collection Items” specifies the collec-
tion item and collection subitem dictionaries.
Example 8.4
/CI <<
/Type /CollectionItem
/from (Rob McAfee)
/to (Patty McAfee)
/subject <<
/Type /CollectionSubitem
/P (Re:)
/D (Let's have lunch on Friday!)
>>
/date (D:20050621094703-07’00’)
>>
594
CHAPTER 8
Interactive Features
8.3
Page-Level Navigation
This section describes PDF facilities that enable the user to navigate from page to
page within a document:
• Page labels for numbering or otherwise identifying individual pages (see Sec-
tion 8.3.1)
• Article threads, which chain together items of content within the document that
are logically connected but not physically sequential (see Section 8.3.2)
• Presentations that display the document in the form of a slide show, advancing
from one page to the next either automatically or under user control (see Sec-
tion 8.3.3)
For another important form of page-level navigation, see “Link Annotations” on
page 622.
8.3.1
Page Labels
Each page in a PDF document is identified by an integer page index that expresses
the page’s relative position within the document. In addition, a document may
optionally define page labels (PDF 1.3) to identify each page visually on the screen
or in print. Page labels and page indices need not coincide: the indices are fixed,
running consecutively through the document starting from 0 for the first page,
but the labels can be specified in any way that is appropriate for the particular
document. For example, if the document begins with 12 pages of front matter
numbered in roman numerals and the remainder of the document is numbered
in arabic, the first page would have a page index of 0 and a page label of i, the
twelfth page would have index 11 and label xii, and the thirteenth page would
have index 12 and label 1.
For purposes of page labeling, a document can be divided into labeling ranges,
each of which is a series of consecutive pages using the same numbering system.
Pages within a range are numbered sequentially in ascending order. A page’s label
consists of a numeric portion based on its position within its labeling range,
optionally preceded by a label prefix denoting the range itself. For example, the
pages in an appendix might be labeled with decimal numeric portions prefixed
with the string A−; the resulting page labels would be A−1, A−2, and so on.
A document’s labeling ranges are defined by the PageLabels entry in the docu-
ment catalog (see Section 3.6.1, “Document Catalog”). The value of this entry is a
595
SECTION 8.3
Page-Level Navigation
number tree (Section 3.8.6, “Number Trees”), each of whose keys is the page
index of the first page in a labeling range. The corresponding value is a page label
dictionary defining the labeling characteristics for the pages in that range. The
tree must include a value for page index 0. Table 8.10 shows the contents of a page
label dictionary. (See implementation note 76 in Appendix H.)
Example 8.5 shows a document with pages labeled
i, ii, iii, iv, 1, 2, 3, A−8, A−9, …
Example 8.5
1 0 obj
<< /Type /Catalog
/PageLabels << /Nums [ 0 << /S /r
>>
% A number tree containing
4 << /S /D >>
% three page label dictionaries
7 << /S /D
/P ( A− )
8
/St
>>
]
>>
…
>>
endobj
TABLE 8.10 Entries in a page label dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
PageLabel for a page label dictionary.
S
name
(Optional) The numbering style to be used for the numeric portion of each page label:
D Decimal arabic numerals
R Uppercase roman numerals
r
Lowercase roman numerals
A
Uppercase letters (A to Z for the first 26 pages, AA to ZZ for the next 26, and so on)
a
Lowercase letters (a to z for the first 26 pages, aa to zz for the next 26, and so on)
There is no default numbering style; if no S entry is present, page labels consist solely of a
label prefix with no numeric portion. For example, if the P entry (below) specifies the la-
bel prefix Contents, each page is simply labeled Contents with no page number. (If the P
entry is also missing or empty, the page label is an empty string.)
596
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
P
text string
(Optional) The label prefix for page labels in this range.
St
integer
(Optional) The value of the numeric portion for the first page label in the range. Sub-
sequent pages are numbered sequentially from this value, which must be greater than or
equal to 1. Default value: 1.
8.3.2
Articles
Some types of documents may contain sequences of content items that are logi-
cally connected but not physically sequential. For example, a news story may be-
gin on the first page of a newsletter and run over onto one or more
nonconsecutive interior pages. To represent such sequences of physically discon-
tiguous but logically related items, a PDF document may define one or more arti-
cles (PDF 1.1). The sequential flow of an article is defined by an article thread; the
individual content items that make up the article are called beads on the thread.
PDF viewer applications can provide navigation facilities to allow the user to fol-
low a thread from one bead to the next.
The optional Threads entry in the document catalog (see Section 3.6.1, “Docu-
ment Catalog”) holds an array of thread dictionaries (Table 8.11) defining the
document’s articles. Each individual bead within a thread is represented by a bead
dictionary (Table 8.12). The thread dictionary’s F entry points to the first bead in
the thread; the beads are chained together sequentially in a doubly linked list
through their N (next) and V (previous) entries. In addition, for each page on
which article beads appear, the page object (see “Page Objects” on page 144)
should contain a B entry whose value is an array of indirect references to the
beads on the page, in drawing order.
TABLE 8.11 Entries in a thread dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
Thread for a thread dictionary.
F
dictionary
(Required; must be an indirect reference) The first bead in the thread.
I
dictionary
(Optional) A thread information dictionary containing information about the thread,
such as its title, author, and creation date. The contents of this dictionary are similar
to those of the document information dictionary (see Section 10.2.1, “Document In-
formation Dictionary”).
597
SECTION 8.3
Page-Level Navigation
TABLE 8.12 Entries in a bead dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
Bead for a bead dictionary.
T
dictionary
(Required for the first bead of a thread; optional for all others; must be an indirect refer-
ence) The thread to which this bead belongs.
Note: In PDF 1.1, this entry is permitted only for the first bead of a thread. In PDF 1.2
and higher, it is permitted for any bead but required only for the first.
N
dictionary
(Required; must be an indirect reference) The next bead in the thread. In the last bead,
this entry points to the first.
V
dictionary
(Required; must be an indirect reference) The previous bead in the thread. In the first
bead, this entry points to the last.
P
dictionary
(Required; must be an indirect reference) The page object representing the page on
which this bead appears.
R
rectangle
(Required) A rectangle specifying the location of this bead on the page.
Example 8.6 shows a thread with three beads.
Example 8.6
22 0 obj
<< /F 23 0 R
/I
<< /Title ( Man Bites Dog ) >>
>>
endobj
23 0 obj
<< /T 22 0 R
/N 24 0 R
/V 25 0 R
/P 8 0 R
/R [ 158 247 318 905 ]
>>
endobj
598
CHAPTER 8
Interactive Features
24 0 obj
<< /T 22 0 R
/N 25 0 R
/V 23 0 R
/P 8 0 R
/R [ 322 246 486 904 ]
>>
endobj
25 0 obj
<< /T 22 0 R
/N 23 0 R
/V 24 0 R
/P 10 0 R
/R [ 157 254 319 903 ]
>>
endobj
8.3.3
Presentations
Some PDF viewer applications may allow a document to be displayed in the form
of a presentation or slide show, advancing from one page to the next either auto-
matically or under user control. In addition, PDF 1.5 introduces the ability to ad-
vance between different states of the same page (see “Sub-page Navigation” on
page 601).
Note: PDF 1.4 introduces a different mechanism, known as alternate presentations,
for slide show displays, described in Section 9.4, “Alternate Presentations.”
A page object (see “Page Objects” on page 144) may contain two optional entries,
Dur and Trans (PDF 1.1), to specify how to display that page in presentation
mode. The Trans entry contains a transition dictionary describing the style and
duration of the visual transition to use when moving from another page to the
given page during a presentation. Table 8.13 shows the contents of the transition
dictionary. (Some of the entries shown are needed only for certain transition
styles, as indicated in the table.)
The Dur entry in the page object specifies the page’s display duration (also called
its advance timing): the maximum length of time, in seconds, that the page is dis-
played before the presentation automatically advances to the next page. (The user
can advance the page manually before the specified time has expired.) If no Dur
entry is specified in the page object, the page does not advance automatically.
599
SECTION 8.3
Page-Level Navigation
TABLE 8.13 Entries in a transition dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
Trans for a transition dictionary.
S
name
(Optional) The transition style to use when moving to this page from another during a
presentation. Default value: R.
Split
Two lines sweep across the screen, revealing the new page. The lines may
be either horizontal or vertical and may move inward from the edges of
the page or outward from the center, as specified by the Dm and M
entries, respectively.
Blinds
Multiple lines, evenly spaced across the screen, synchronously sweep in
the same direction to reveal the new page. The lines may be either hori-
zontal or vertical, as specified by the Dm entry. Horizontal lines move
downward; vertical lines move to the right.
Box
A rectangular box sweeps inward from the edges of the page or outward
from the center, as specified by the M entry, revealing the new page.
Wipe
A single line sweeps across the screen from one edge to the other in the
direction specified by the Di entry, revealing the new page.
Dissolve
The old page dissolves gradually to reveal the new one.
Glitter
Similar to Dissolve, except that the effect sweeps across the page in a
wide band moving from one side of the screen to the other in the direc-
tion specified by the Di entry.
R
The new page simply replaces the old one with no special transition ef-
fect; the D entry is ignored.
Fly
(PDF 1.5) Changes are flown out or in (as specified by M), in the direc-
tion specified by Di, to or from a location that is offscreen except when
Di is None.
Push
(PDF 1.5) The old page slides off the screen while the new page slides in,
pushing the old page out in the direction specified by Di.
Cover
(PDF 1.5) The new page slides on to the screen in the direction specified
by Di, covering the old page.
Uncover
(PDF 1.5) The old page slides off the screen in the direction specified by
Di, uncovering the new page in the direction specified by Di.
Fade
(PDF 1.5) The new page gradually becomes visible through the old one.
600
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
D
number
(Optional) The duration of the transition effect, in seconds. Default value: 1.
Dm
name
(Optional; Split and Blinds transition styles only) The dimension in which the specified
transition effect occurs:
H
Horizontal
V
Vertical
Default value: H.
M
name
(Optional; Split, Box and Fly transition styles only) The direction of motion for the speci-
fied transition effect:
I
Inward from the edges of the page
O
Outward from the center of the page
Default value: I.
Di
number or
(Optional; Wipe, Glitter, Fly, Cover, Uncover and Push transition styles only) The direction
name
in which the specified transition effect moves, expressed in degrees counterclockwise
starting from a left-to-right direction. (This differs from the page object’s Rotate entry,
which is measured clockwise from the top.)
The following numeric values are valid:
0
Left to right
90
Bottom to top (Wipe only)
180
Right to left (Wipe only)
270
Top to bottom
315
Top-left to bottom-right (Glitter only)
The only valid name value is None, which is relevant only for the Fly transition when
the value of SS is not 1.0.
Default value: 0.
SS
number
(Optional; PDF 1.5; Fly transition style only) The starting or ending scale at which the
changes are drawn. If M specifies an inward transition, the scale of the changes drawn
progresses from SS to 1.0 over the course of the transition. If M specifies an outward
transition, the scale of the changes drawn progresses from 1.0 to SS over the course of
the transition
Default: 1.0.
B
boolean
(Optional; PDF 1.5; Fly transition style only) If true, the area to be flown in is rectangu-
lar and opaque. Default: false.
Figure 8.1 illustrates the relationship between transition duration (D in the transi-
tion dictionary) and display duration (Dur in the page object). Note that the tran-
601
SECTION 8.3
Page-Level Navigation
sition duration specified for a page (page 2 in the figure) governs the transition to
that page from another page; the transition from the page is governed by the next
page’s transition duration.
Transition from
Transition from
page 1 to page 2
Page 2 displayed
page 2 to page 3
Transition duration
Display duration for page 2
Transition duration
for page 2
for page 3
FIGURE 8.1 Presentation timing
Example 8.7 shows the presentation parameters for a page to be displayed for 5
seconds. Before the page is displayed, there is a 3.5-second transition in which
two vertical lines sweep outward from the center to the edges of the page.
Example 8.7
10 0 obj
<< /Type /Page
/Parent 4 0 R
/Contents 16 0 R
/Dur 5
/Trans <<
/Type /Trans
/D 3.5
/S /Split
/Dm /V
/M /O
>>
>>
endobj
Sub-page Navigation
Sub-page navigation (PDF 1.5) allows navigating not only between pages but also
between different states of the same page. For example, a single page in a PDF
presentation could have a series of bullet points that could be individually turned
on and off. In such an example, the bullets would be represented by optional con-
tent (see Section 4.10, “Optional Content”), and each state of the page would be
represented as a navigation node.
602
CHAPTER 8
Interactive Features
Note: Viewer applications should save the state of optional content groups when a
user enters presentation mode and restore it when presentation mode ends. This en-
sures, for example, that transient changes to bullets do not affect the printing of the
document.
A navigation node dictionary (see Table 8.14) specifies actions to execute when
the user makes a navigation request; for example, by pressing an arrow key. The
navigation nodes on a page form a doubly linked list by means of their Next and
Prev entries. The primary node on a page is determined by the optional PresSteps
entry in a page dictionary (see Table 3.27).
Note: It is recommended that a viewer application respect navigation nodes only
when in presentation mode (see Section 8.3.3, “Presentations”).
TABLE 8.14 Entries in a navigation node dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; must be NavNode
for a navigation node dictionary.
NA
dictionary
(Optional) The sequence of actions to execute when a user navigates forward.
PA
dictionary
(Optional) The sequence of actions to execute when a user navigates backward.
Next
dictionary
(Optional) The next navigation node, if any.
Prev
dictionary
(Optional) The previous navigation node, if any.
Dur
number
(Optional) The maximum number of seconds before the viewer application should
automatically advance forward to the next navigation node. If this entry is not spec-
ified, no automatic advance should occur.
A viewer application should support the notion of a current navigation node.
When a user navigates to a page, if the page dictionary has a PresSteps entry, the
node specified by that entry becomes the current node. (Otherwise, there is no
current node.) If there is a request to navigate forward (such as an arrow key
press) and there is a current navigation node, the following occurs:
1. The sequence of actions specified by NA (if present) is executed.
Note: If NA specifies an action that navigates to another page, the actions de-
scribed below for navigating to another page take place, and Next should not be
present.
603
SECTION 8.3
Page-Level Navigation
2. The node specified by Next (if present) becomes the new current navigation
node.
Similarly, if there is a request to navigate backward and there is a current naviga-
tion node, the following occurs:
1. The sequence of actions specified by PA (if present) is executed.
Note: If PA specifies an action that navigates to another page, the actions de-
scribed below for navigating to another page take place, and Prev should not be
present.
2. The node specified by Prev (if present) becomes the new current navigation
node.
When navigating between nodes, it is possible to specify transition effects. These
effects are similar to the page transitions specified in the previous section. How-
ever, they use a different mechanism; see “Transition Actions” on page 670.
Note: “Forward” and “backward” are determined by user actions, such as pressing
right or left arrow keys, not by the actual page that is the destination of an action.
If there is a request to navigate to another page (regardless of whether there is a
current node) and that page’s dictionary contains a PresSteps entry, the following
occurs:
1. The navigation node represented by PresSteps becomes the current node.
2. If the navigation request was forward, or if the navigation request was for ran-
dom access (such as by clicking on a link), the actions specified by NA are exe-
cuted and the node specified by Next becomes the new current node, as
described above.
If the navigation request was backward, the actions specified by PA are execut-
ed and the node specified by Prev becomes the new current node, as described
above.
3. The viewer application makes the new page the current page and displays it.
Any page transitions specified by the Trans entry of the page dictionary are
performed.
Большое спасибо!
Ваше мнение очень важно для нас.
Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.
Текст