Repository navigation
PDF20 Spec 12 Doc Navigation
Part of: PDF20-Spec-12-Interactive
Navigation: PDF20-Spec-12-Viewer-Prefs | PDF20-Spec-Index | PDF20-Spec-12-Page-Navigation
12.3 Document-level navigation 12.3.1
General
The features described in this subclause allow an interactive PDF processor 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 may be associated with a corresponding destination in the document, so that the user can jump directly to the destination by clicking with the mouse.
12.3.2
Destinations
12.3.2.1
General
A destination defines a particular view of a document, consisting of the following items: •
The page of the document that shall be displayed
•
The location of the document window on that page
•
The magnification (zoom) factor
Destinations may be associated with outline items (see 12.3.3, "Document outline"), annotations (12.5.6.5, "Link annotations"), or actions (12.6.4.2, "Go-To actions" and 12.6.4.3, "Remote Go-To actions"). In each case, the destination specifies the view of the document that shall 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 dictionary (7.7.2, "Document catalog dictionary") may specify a destination that shall be displayed when the document is opened. A destination may be specified either explicitly by an array of parameters defining its properties or indirectly by name.
12.3.2.2
Explicit destinations
"Table 149 — Destination syntax" 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 (except in a remote go-to action; see 12.6.4.3, "Remote Go-To actions", or an embedded go-to action; see 12.6.4.4, "Embedded Go-To actions"). All coordinate values (left, right, top, and bottom) shall be 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 shall be used instead; see 14.11.2, "Page boundaries" for further discussion of the crop box.) © ISO 2020 – All rights reserved
441
ISO 32000-2:2020(E)
NOTE
The above paragraph was corrected to also include embedded go-to actions (2020).
No page object can be specified for a destination associated with a remote go-to action (see 12.6.4.3, "Remote Go-To actions") because the destination page is in a different PDF document. In this case, the page parameter specifies an integer page number within the remote document instead of a page object in the current document. Table 149 — Destination syntax Syntax
Meaning
[page /XYZ left top zoom]
Display the page designated by page, with the coordinates (left, top) positioned 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 shall be retained unchanged. 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, centring the page within the window in the other dimension.
[page /FitH top]
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 the page within the window. A null value for top specifies that the current value of that parameter shall be retained unchanged.
[page /FitV left]
Display the page designated by page, with the horizontal coordinate left positioned 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 value for left specifies that the current value of that parameter shall 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, centring the rectangle within the window in the other dimension. [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 horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centring 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 shall be retained unchanged.
442
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
Syntax
Meaning
[page /FitBV left]
(PDF 1.1) Display the page designated by page, with the horizontal coordinate 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 shall be retained unchanged.
12.3.2.3
Structure destinations
A destination provides a view within a given document, however there is no direct connection between the location of the view on the page and the content displayed. Structure elements (see 14.7.2, "Structure hierarchy") allow specific sequences of content on a page to be identified. A structure destination provides the same view mechanism as a destination, but references a structure element instead of a page. A structure destination shall use the same syntax as a destination (see "Table 149 — Destination syntax"), except that the first entry in the array shall be an indirect reference to a structure element dictionary instead of to a page dictionary. EXAMPLE
A regular destination of the following syntax [page /FitH 500] could be represented as a structure destination with the following syntax [elem /FitH 500] where elem represents an indirect reference to a structure element dictionary.
The structure element shall be used to identify the page to which the content belongs and, using that page, the structure destination shall behave identically to a destination. To identify the page to which a structure destination refers, the following algorithm shall be used. The kids of the structure element shall be processed in linear array order. If the first kid is a marked-content reference or an object reference (see 14.6, "Marked content"), then the page to which that reference belongs shall be used as the page. If the first kid is a structure element, then processing shall continue down to that element using the same algorithm recursively. If no content or object reference is found under the first entry, processing should proceed to next entry, repeating the process. This shall continue until all entries have been processed or until the first page is identified. In the case where no page content is identified, then the page reference shall be assumed to be the first page in the document. No structure element dictionary can be specified for a structure destination associated with a remote go-to action (see 12.6.4.3, "Remote Go-To actions") or embedded go-to actions (see 12.6.4.4, "Embedded Go-To actions") because the destination structure element is in a different PDF document. In this case, the indirect reference to the structure element dictionary shall be replaced by a byte string representing a structure element ID (see "Table 355 — Entries in a structure element dictionary"). NOTE 1
The above paragraph was corrected to also include embedded go-to actions (2020).
NOTE 2
There is no requirement that a given structure element will have an ID associated with it, nor that it will remain consistent across edits to a PDF document. For remote go-to actions which rely on a target PDF having an ID, it is important that such an ID exist and that it remain consistent across versions of the target document.
12.3.2.4
Named destinations
Instead of being defined directly with the explicit syntax shown in "Table 149 — Destination syntax", 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 located in another PDF document. © ISO 2020 – All rights reserved
443
ISO 32000-2:2020(E)
NOTE 1
A link to the beginning of Chapter 6 in another document can 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 invalidating 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 12.6.4.3, "Remote Go-To actions") or a thread action (12.6.4.7, "Thread actions"), the destination is in the PDF file specified by the action’s F entry, if any; if there is no F entry, the destination is in the current PDF file.
In PDF 1.1, the correspondence between name objects and destinations shall be defined by the Dests entry in the document catalog dictionary (see 7.7.2, "Document catalog dictionary"). The value of this entry shall be a dictionary in which each key is a destination name and the corresponding value is either an array defining the destination, using the syntax shown in "Table 149 — Destination syntax", or a dictionary with a D entry whose value is such an array and may optionally contain an SD entry as defined in "Table 201 — Action types". NOTE 2
The latter form allows additional attributes to be associated with the destination, as well as enabling a go-to action (see 12.6.4.2, "Go-To actions") that can be used as the target of a named destination.
In PDF 1.2 and later, the correspondence between strings and destinations may alternatively be defined by the Dests entry in the document’s name dictionary (see 7.7.4, "Name dictionary"). The value of this entry shall be a name tree (7.9.6, "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 preceding paragraph. When trying to locate a named destination in a names tree, either in the same or in remote PDF files, the algorithms specified in J.3.3, "String objects" or J.3.4, "Name objects" shall be used (depending on the type of object being compared). NOTE 3
The above paragraph was added in this document (2020).
NOTE 4
The use of strings as destination names is a PDF 1.2 feature. If compatibility with versions of PDF prior to PDF 1.2 is required, only name objects can be used to refer to named destinations. A document that supports PDF 1.2 or later can contain both types. However, if backward compatibility to PDF 1.2 is not a consideration, it is recommended that applications use the string form of representation in the Dests name tree.
12.3.3
Document outline
A PDF document may contain a document outline that the interactive PDF processor may display on the screen, allowing 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 document’s structure to the user. The user may interactively open and close individual items by clicking them with the mouse. When an item is open, its immediate children in the hierarchy shall 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 shall be hidden. Clicking the text of any visible item activates the item, causing the interactive PDF processor 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 dictionary (see 7.7.2, "Document catalog dictionary"). "Table 150 — Entries in 444
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
the outline dictionary" shows the contents of this dictionary. Each individual outline item within the hierarchy shall be defined by an outline item dictionary ("Table 151 — Entries in an outline item dictionary"). 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 displayed on the screen, the items at a given level shall appear in the order in which they occur in the linked list. Table 150 — Entries in the outline dictionary Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, shall be Outlines for an outline dictionary.
First
dictionary
(Required if there are any open or closed outline entries; shall be an indirect reference) 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; shall be an indirect reference) An outline item dictionary representing the last top-level item in the outline.
Count
integer
(Required if the document has any open outline entries) Total number of visible outline items at all levels of the outline. The value cannot be negative. This entry shall be omitted if there are no open outline items.
Table 151 — Entries in an outline item dictionary Key
Type
Value
Title
text string
(Required) The text that shall be displayed on the screen for this item.
Parent
dictionary
(Required; shall be an indirect reference) The parent of this item in the outline hierarchy. The parent of a top-level item shall be the outline dictionary itself.
Prev
dictionary
(Required for all but the first item at each level; shall be an indirect reference) The previous item at this outline level.
Next
dictionary
(Required for all but the last item at each level; shall be an indirect reference) The next item at this outline level.
First
dictionary
(Required if the item has any descendants; shall 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; shall be an indirect reference) The last of this item’s immediate children in the outline hierarchy.
© ISO 2020 – All rights reserved
445
ISO 32000-2:2020(E)
Key
Type
Value
Count
integer
(Required if the item has any descendants) If the outline item is open, Count is the sum of the number of visible descendent outline items at all levels. The number of visible descendent outline items shall be determined by the following recursive process: Step 1. Initialize Count to zero. Step 2. Add to Count the number of immediate children. During repetitions of this step, update only the Count of the original outline item. Step 3. For each of those immediate children whose Count is positive and non-zero, repeat steps 2 and 3. If the outline item is closed, Count is negative and its absolute value is the number of descendants that would be visible if the outline item were opened.
Dest
name, byte string, or array
(Optional; shall not be present if an A entry is present) The destination that shall be displayed when this item is activated (see 12.3.2, "Destinations").
A
dictionary
(Optional; PDF 1.1; shall not be present if a Dest entry is present) The action that shall be performed when this item is activated (see 12.6, "Actions").
SE
dictionary
(Optional; PDF 1.3; shall be an indirect reference) The structure element to which the item refers (see 14.7.2, "Structure hierarchy"). NOTE
This value is not intended for navigation. Structure Destinations (Dest entry) are the method to provide structure-based navigation.
C
array
(Optional; PDF 1.4) An array of three numbers in the range 0.0 to 1.0, representing the components in the DeviceRGB colour space of the colour that shall 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 displaying the outline item’s text (see "Table 152 — Outline item flags"). Default value: 0.
The value of the outline item dictionary’s F entry (PDF 1.4) shall be an integer interpreted as one-bit flags specifying style characteristics for displaying the item. Bit positions within the flag word are numbered from low-order to high-order bits, with the lowest-order bit numbered 1. "Table 152 — Outline item flags" shows the meanings of the flags; all other bits of the integer shall be 0. Table 152 — Outline item flags
446
Bit position
Name
Meaning
1
Italic
If set to 1, display the item in italic.
2
Bold
If set to 1, display the item in bold.
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
EXAMPLE
The following example shows a typical outline dictionary and outline item dictionary. See H.6, "Outline hierarchy example" for an example of a complete outline hierarchy.
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
12.3.4
Thumbnail images
A PDF document may contain thumbnail images representing the contents of its pages in miniature form. An interactive PDF processor may 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 can be included for some pages and not for others.
The thumbnail image for a page shall be an image XObject specified by the Thumb entry in the page object (see 7.7.3, "Page tree"). It has the usual structure for an image dictionary (8.9.5, "Image dictionaries"), but only the Width, Height, ColorSpace, BitsPerComponent, and Decode entries are significant; all of the other entries listed in "Table 87 — Additional entries specific to an image dictionary" shall be ignored if present. (If a Subtype entry is specified, its value shall be Image.) The image’s colour space shall be either DeviceGray or DeviceRGB, or an Indexed colour space based on one of these. EXAMPLE
This example shows a typical thumbnail image definition.
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 … endobj
© ISO 2020 – All rights reserved
%Length of stream
447
ISO 32000-2:2020(E)
12.3.5
Collections
12.3.5.1
General
Beginning with PDF 1.7, PDF documents may specify how an interactive PDF processor’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. NOTE 1
The intent of portable collections is to present, sort, and search collections of related documents embedded in the containing PDF document, such as email archives, photo collections, and engineering bid sets. There is no requirement that documents in a collection have an implicit relationship or even a similarity; however, showing differentiating characteristics of related documents can be helpful for document navigation.
A collection dictionary specifies the viewing and organisational characteristics of portable collections. If this dictionary is present in a PDF document, the interactive PDF processor shall present the document as a portable collection. The EmbeddedFiles name tree specifies file attachments (see "Table 32 — Entries in the name dictionary"). When an interactive PDF processor first opens a PDF document containing a collection, it shall display the contents according to the View key of the collection dictionary. The initial document may be the container PDF or one of the embedded documents as specified by the D key in the collection dictionary. NOTE 2
The page content in the initial document needs to contain information that helps the user understand what is contained in the collection, such as a title and an introductory paragraph.
The file attachments comprising a collection shall be located in the EmbeddedFiles name tree. All attachments in that tree are in the collection; any attachments not in that tree are not. For a PDF document that is an unencrypted wrapper for an encrypted payload document (see 7.6.7, "Unencrypted wrapper document"), the EmbeddedFiles name tree shall contain exactly one entry, for the encrypted payload document. Beginning with PDF 2.0, a portable collection may include an interactive layout, or presentation, of the collection contents. The collection layout or presentation is called a navigator. For more information about navigators, see 12.3.6, "Navigators". When a navigator is used the collection dictionary shall contain some entries that support navigators. The Navigator entry shall be an indirect reference to a navigator dictionary that describes the interactive layout. The value of the Colors entry shall be a collection colors dictionary that specifies a suggested set of colours for use by a collection layout. The Folders entry shall be an indirect reference to the root folder of the collection’s folder structure. “Table 153 — Entries in a collection dictionary” describes the entries in a collection dictionary. Table 153 — Entries in a collection dictionary
448
Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, shall be Collection for a collection dictionary.
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
Key
Type
Value
Schema
dictionary
(Optional) A collection schema dictionary (see "Table 154 — Entries in a collection schema dictionary"). If absent, the interactive PDF processor 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, determining the document that shall be initially presented in the user interface. If the D entry is missing or is not a valid byte string, the initial document shall be the one that contains the collection dictionary. If the D entry is a valid byte string that does not match any file in the EmbeddedFiles name tree, the interactive PDF processor shall select the first item from the list of files to display in its user interface; if no files exist in the name tree, the interactive PDF processor shall display an empty preview window. (PDF 2.0) For unencrypted wrapper documents for an encrypted payload document (see 7.6.7, "Unencrypted wrapper document") the D entry is required, and shall identify the encrypted payload entry in the EmbeddedFiles name tree.
View
name
(Optional) The initial view. The following values are valid: D The collection view shall be presented in details mode, with all information in the Schema dictionary presented in a multicolumn format. This mode provides the most information to the user. T The collection view shall be presented in tile mode, with each file in the collection denoted by a small icon and a subset of information from the Schema dictionary. This mode provides top-level information about the file attachments to the user. H The collection view shall be initially hidden. The interactive PDF processor shall provide means for the user to view the collection by some explicit action. The PDF processor should display the document specified by the D entry. NOTE How the PDF processor chooses to display the collection is implementation specific. C (PDF 2.0, valid only when Navigator is present) The collection view shall be presented by the navigator specified by the Navigator entry. Default value: D (PDF 2.0) For unencrypted wrapper documents for an encrypted payload document (see 7.6.7, "Unencrypted wrapper document") the View entry is required, and shall have a value of H.
Navigator
dictionary
(Required if the value of View is C; PDF 2.0) An indirect reference to the navigator dictionary that describes the navigator that provides the collection view. See "Table 160 — Entries in a navigator dictionary".
Colors
dictionary
(Optional; PDF 2.0) A collection colors dictionary specifying a suggested set of colours for use by a collection layout. See "Table 157 — Entries in a collection colors dictionary". NOTE
© ISO 2020 – All rights reserved
It is recommended that a layout use the colours provided.
449
ISO 32000-2:2020(E)
Key
Type
Value
Sort
dictionary
(Optional) A collection sort dictionary, which specifies the order in which items in the collection shall be sorted in the user interface (see "Table 156 — Entries in a collection sort dictionary").
Folders
dictionary
(Required if the collection has folders; PDF 2.0) An indirect reference to a folder dictionary that is the single common ancestor of all other folders in a portable collection. See "Table 159 — Entries in a folder dictionary".
Split
dictionary
(Optional; PDF 2.0) A collection split dictionary that specifies the orientation of the splitter bar in the user interface provided by the interactive PDF processor. See "Table 158 — Entries in a collection split dictionary". If Split is not present, the preferred orientation is determined by the value of the View key. A value of D (or no value) shall indicate a horizontal orientation, while a value of T shall indicate a vertical orientation. No splitter shall be used if the View key has a value of H or C.
A collection schema dictionary consists of a variable number of individual collection field dictionaries. Each collection field dictionary has a key chosen by the interactive PDF writer, which shall be used to associate a field with data in a file specification. "Table 154 — Entries in a collection schema dictionary" describes the entries in a collection schema dictionary. Table 154 — Entries in a collection schema dictionary Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, shall be CollectionSchema for a collection schema dictionary.
Other keys
dictionary
(Optional) A collection field dictionary. Each key name is chosen at the discretion of the PDF writer. The key name shall be used to identify a corresponding collection item dictionary referenced from the file specification dictionary's CI entry (see CI key in "Table 43 — Entries in a file specification dictionary").
A collection field dictionary describes the attributes of a particular field in a portable 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 155 — Entries in a collection field dictionary" describes the entries in a collection field dictionary.
450
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
Table 155 — Entries in a collection field dictionary Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, shall be CollectionField for a collection field dictionary.
Subtype
name
(Required) The subtype of collection field or file-related field that this dictionary describes. This entry identifies the type of data that shall be 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 shall be stored as a PDF text string. D A date field. The field data shall be stored as a PDF date string (see 7.9.4, "Dates"). N A number field. The field data shall be stored as a PDF number. The following values identify the types of file-related fields: F The field data shall be the file name of the embedded file stream, as identified by the UF entry of the file specification, if present; otherwise by the F entry of the file specification (see "Table 43 — Entries in a file specification dictionary"). Desc The field data shall be the description of the embedded file stream, as identified by the Desc entry in the file specification dictionary (see "Table 43 — Entries in a file specification dictionary"). ModDate The field data shall be the modification date of the embedded file stream, as identified by the ModDate entry in the embedded file parameter dictionary (see "Table 45 — Entries in an embedded file parameter dictionary"). CreationDate The field data shall be the creation date of the embedded file stream, as identified by the CreationDate entry in the embedded file parameter dictionary (see "Table 45 — Entries in an embedded file parameter dictionary"). Size The field data shall be the size of the embedded file, as identified by the Size entry in the embedded file parameter dictionary (see "Table 45 — Entries in an embedded file parameter dictionary"). CompressedSize (PDF 2.0) The field data shall be the length of the embedded file stream, as identified by the Length entry in the embedded file stream dictionary (see 7.11.4, "Embedded file streams"), and the two values shall be identical.
N
text string
(Required) The textual field name that shall be presented to the user by the interactive PDF processor.
O
integer
(Optional) The relative order of the field name in the user interface. Fields shall be sorted by the interactive PDF processor in ascending order.
V
boolean
(Optional) The initial visibility of the field in the user interface. Default value: true.
E
boolean
(Optional) A flag indicating whether the interactive PDF processor should provide support for editing the field value. Default value: false.
A collection sort dictionary identifies the fields that shall be used to sort items in the collection. The type of sorting depends on the type of data: © ISO 2020 – All rights reserved
451
ISO 32000-2:2020(E)
Text strings shall be ordered lexically from smaller to larger, if ascending order is specified.
•
NOTE 3
Lexical ordering is an implementation dependency for interactive PDF processors.
•
Numbers shall be ordered numerically from smaller to larger, if ascending order is specified.
•
Dates shall be ordered from oldest to newest, if ascending order is specified.
"Table 156 — Entries in a collection sort dictionary" describes the entries in a collection sort dictionary. Table 156 — Entries in a collection sort dictionary Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, shall be CollectionSort for a collection sort dictionary.
S
name or array
(Required) The name or names of fields that the interactive PDF processor shall use 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 shall be a name that identifies a field described in the parent collection dictionary. The array form shall be used to allow additional fields to contribute to the sort, where each additional field shall be used to break ties. More specifically, if multiple collection item dictionaries have the same value for the first field named in the array, the values for successive fields named in the array shall be used for sorting, until a unique order is determined or until the named fields are exhausted.
A
boolean or (Optional) If the value is a boolean, it specifies whether the interactive PDF array processor shall sort the items in the collection in ascending order (true) or descending order (false). If the value is an array, each element of the array shall be a boolean value that specifies whether the entry at the same index in the S array shall be sorted in ascending or descending order. If the number of entries in the A array is larger than the number of entries in the S array the extra entries in the A array shall be ignored. If the number of entries in the A array is less than the number of entries in the S array the missing entries in the A array shall be assumed to be true. Default value: true.
Table 157 — Entries in a collection colors dictionary Key
Type
Value
Type
name
(Optional; PDF 2.0) The type of PDF object that this dictionary describes; if present, shall be CollectionColors for a collection colors dictionary.
Background
array
(Optional; PDF 2.0) An array of three numbers in the range 0.0 to 1.0, representing a DeviceRGB colour used for the background of the view.
CardBackground
array
(Optional; PDF 2.0) An array of three numbers in the range 0.0 to 1.0, representing a DeviceRGB colour used for the background of the card.
CardBorder
array
(Optional; PDF 2.0) An array of three numbers in the range 0.0 to 1.0, representing a DeviceRGB colour used for the border of the card.
452
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
Key
Type
Value
PrimaryText
array
(Optional; PDF 2.0) An array of three numbers in the range 0.0 to 1.0, representing a DeviceRGB colour used for the primary text in a navigator.
SecondaryText
array
(Optional; PDF 2.0) An array of three numbers in the range 0.0 to 1.0, representing a DeviceRGB colour used for other text in a navigator.
When displaying a collection, an interactive PDF processor presents an initial view in which the available display area may be divided by a splitter bar into two areas; one area containing a display of the navigation controls of the collection as defined by the View and related entries of the collection dictionary, and one area containing a preview of the initial or currently selected document of the collection. The visibility, orientation or position of the splitter bar may be interactively adjusted by user action subsequent to its initial view as defined by the collection split dictionary, if provided. Table 158 — Entries in a collection split dictionary Key
Type
Value
Type
name
(Optional; PDF 2.0) The type of PDF object that this dictionary describes; if present, shall be CollectionSplit for a collection split dictionary.
Direction
name
(Optional; PDF 2.0) The orientation of the splitter bar. The following values are valid: H indicates that the window is split horizontally V indicates that the window is split vertically. N indicates that the window is not split. The entire window region shall be dedicated to the file navigation view.
Position
number
(Optional; PDF 2.0) The initial position of the splitter bar, specified as a percentage of the available window area. Values shall range from 0 to 100. The entry shall be ignored if Direction is set to N.
12.3.5.2
Collection hierarchical folders
Beginning with PDF 2.0, a portable collection can contain a Folders object for the purpose of organising files into a hierarchical structure. The structure is represented by a tree with a single root folder acting as the common ancestor for all other folders and files in the collection. The single root folder is referenced in the Folders entry of "Table 153 — Entries in a collection dictionary". Table 159 — Entries in a folder dictionary Key
Type
Value
Type
name
(Optional; PDF 2.0) The type of PDF object that this dictionary describes; if present, shall be Folder for a folder dictionary.
© ISO 2020 – All rights reserved
453
ISO 32000-2:2020(E)
Key
Type
Value
ID
integer
(Required; PDF 2.0) A non-negative integer value representing the unique folder identification number. Two folders, in the same PDF document, shall not share the same ID value. The folder ID value appears as part of the name tree key of any file associated with this folder. A detailed description of the association between folder and files can be found after this table.
Name
text string
(Required; PDF 2.0) A file name representing the name of the folder. Two sibling folders shall not share the same name following case normalization. NOTE
Descriptions of file name and case normalization follow this table.
Parent
dictionary
(Required for child folders; PDF 2.0) An indirect reference to the parent folder of this folder. This entry shall be absent for a root folder.
Child
dictionary
(Required if the folder has any descendents; PDF 2.0) An indirect reference to the first child folder of this folder.
Next
dictionary
(Required for all but the last item at each level; PDF 2.0) An indirect reference to the next sibling folder at this level. Siblings should be ordered according to the collection Sort key ("Table 153 — Entries in a collection dictionary") or by folder name if no collection Sort key is present.
CI (uppercase ci)
dictionary
(Optional; PDF 2.0) The collection item dictionary. Beginning with PDF 1.7, a collection item dictionary shall contain the data described by the collection schema dictionary for a particular file in a collection (see 12.3.5, "Collections"). "Table 46 — Entries in a collection item dictionary" describes the entries in a collection item dictionary.
Desc
text string
(Optional; PDF 2.0) A text description associated with this folder.
CreationDate
date
(Optional; PDF 2.0) The date the folder was first created.
ModDate
date
(Optional; PDF 2.0) The date of the most recent change to immediate child files or folders of this folder.
Thumb
stream
(Optional; PDF 2.0) A stream object defining the thumbnail image for the folder See 12.3.4, "Thumbnail images".
Free
array
(Optional; only used by root folder; PDF 2.0) An array containing ID values that are not currently in use by the folder structure. The array shall contains zero or more pairs of numbers, a low value followed by a high value. Each pair represents an endpointinclusive range of values that are available for use when a new folder is added. Each low value shall be less than or equal to its corresponding high value.
New values for the ID key shall be obtained by an interactive PDF processor by accessing the Free entry in the root folder. If an ID value is used from the Free entry array, the array shall be updated. 454
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
As previously described, the Name entry is a file name for a folder. A folder, as well as its associated files, have naming restrictions. Strings that conform to these restrictions are known as file names. A valid file name conforms to the following requirements: •
The string shall be a PDF text string.
•
The string shall not contain any embedded NULL (U+0000) characters.
•
The number of characters in the string shall be between 1 and 255 inclusive.
•
The string shall not contain any of the eight special characters: SOLIDUS (U+002F) (/), REVERSE SOLIDUS (U+005C) (), COLON (U+003A) (:), ASTERISK (U+002A) (*), QUOTATION MARK (U+0022) ("), LESS-THAN SIGN (U+003C) (<), GREATER-THAN SIGN (U+003E) (>) and VERTICAL LINE (U+007C) (|).
•
The last character shall not be a FULL STOP (U+002E) (.).
An interactive PDF processor may choose to support invalid names or not. If not, an appropriate error message shall be provided. In addition to the restriction on naming folders, as just described, it is further required that two file names in the same folder do not map to the same string following case normalization. Two file names that differ only in case are disallowed within the same folder. See "Unicode Standard Annex #21, Case Mappings" for information on case normalization. The CI entry, a collection item dictionary, allows user-defined metadata to be associated with a folder, just as it does for embedded files in a collection. Folders are indirect objects, and relationships between folders in the tree are specified using Parent, Child, and Next keys. When folders are used, all files in the EmbeddedFiles name tree (see "Table 32 — Entries in the name dictionary") shall be treated as members of the folder structure by an interactive PDF processor. The association between files and folders is accomplished using a special naming convention on the key strings of the name tree. See 7.9.6, "Name trees", for a discussion of the key strings. If no folder structure is specified, interactive PDF processors should show all files in the collection in a flat list. As previously mentioned, files in the EmbeddedFiles name tree are associated with folders by a special naming convention applied to the name tree key strings. Strings that conform to the following rules serve to associate the corresponding file with a folder: •
The name tree keys are PDF text strings.
•
The first character, excluding any byte order marker, is LESS-THAN SIGN (U+003C) (<).
•
The following characters shall be one or more digits (0 to 9) followed by the closing GREATERTHAN SIGN (U+003E) (>)
•
The remainder of the string is a file name.
The section of the string enclosed by LESS-THAN SIGN GREATER-THAN SIGN(<>) is interpreted as a numeric value that specifies the ID value of the folder with which the file is associated. The value shall correspond to a folder ID. The section of the string following the folder ID tag shall represent the file name of the embedded file.
© ISO 2020 – All rights reserved
455
ISO 32000-2:2020(E)
Files in the EmbeddedFiles name tree that do not conform to these rules shall be treated as associated with the root folder. EXAMPLE 1
This example 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 organisational data associated with each email is described in a collection schema dictionary. Most actual organisational data (from, to, date, and subject) is provided in a collection item dictionary, but the size data comes from the embedded file parameter dictionary. /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 2
This example shows a collection item dictionary and a collection subitem dictionary. These dictionaries contain entries that correspond to the schema entries specified in the Example in 12.4.2, "Page labels". 7.11.6, "Collection items" specifies the collection item and collection subitem dictionaries. /CI << /Type /CollectionItem /from (Tom Jones) /to (Marry Jones) /subject << /Type /CollectionSubitem /P (Re:) /D (Let's have lunch on Friday!)
/date (D:20050621094703-07’00)
12.3.6
Navigators
A portable collection can include an interactive layout, or presentation, for the collection contents (PDF 2.0) called a navigator. When a navigator is specified, a PDF processor should display that interactive layout and allow it to drive the presentation of the collection. Navigators are specified by identifying a named layout, used to identify a presentation for the content within a collection. These interactive layouts provide more choice in presenting the collection contents than the simple views specified by the View key in the collection dictionary (see "Table 153 — Entries in a collection dictionary"). When a navigator dictionary is present, a PDF processor should use the value of the Layout entry to present the collection to the user. Named layouts provide a number of options for presenting the contents of the collection to a user. These options are provided to allow the choice of a navigator that is best suited to presenting the collection’s contents, including the folder structures and file attachments. The Layout key may consist of a single name value, to specify the named layout, or an array of names. When an array of names is provided, a PDF processor should select the first named layout it recognises. This mechanism is inherently extensible and allows inclusion of custom named layouts, but at least one of the values of 456
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
the Layout entry shall be one of the values listed in the entry (see "Table 160 — Entries in a navigator dictionary"). Table 160 — Entries in a navigator dictionary Key
Type
Value
Type
name
(Optional; PDF 2.0) The type of PDF object that this dictionary describes; if present, shall be Navigator for a navigator dictionary.
Layout
name or (Required; PDF 2.0) One or more names specifying the named layout of the array of navigator that should be used. When multiple names are provided, an interactive names PDF processor should present the first one it is capable of displaying in the order present in the array. One of the following names shall always be present, either singly or as the final entry in the array. D Corresponding to the value of D in the View key in "Table 153 — Entries in a collection dictionary". T Corresponding to the value of T in the View key in "Table 153 — Entries in a collection dictionary". H Corresponding to the value of H in the View key in "Table 153 — Entries in a collection dictionary". FilmStrip
A layout which displays a strip of thumbnails, providing an index to the file attachments within the collection. The selected attachment should be previewed alongside the index.
FreeForm
A layout which places thumbnails of the file attachments within the collection randomly in the view.
Linear
A layout which provides a large size preview of one file attachment in the collection and displays alongside the preview the metadata for the file attachment, including the name, description and other collection schema entries.
Tree
A layout presenting the contents of the collection in a tree view, showing the folder structure and the files as leaf nodes of the tree, akin to a traditional file system folder view.
The D, T and H values for the Layout entry match those present in the View entry of a collection dictionary (see "Table 153 — Entries in a collection dictionary"). An interactive PDF processor should present the same display mode when encountering these values as it would if processing the View entry. The FilmStrip layout describes a presentation of the collection contents in the form of a single strip of thumbnails. These thumbnails provide an index into the files and folders present within the collection. When a user selects a file from the index, an interactive PDF processor should either display that file or provide a preview of the file. NOTE 1
A common implementation for this is to have the strip of thumbnails across the bottom of the view and a large preview of the selected file or folder shown above it.
The FreeForm layout provides a simple layout, in which thumbnails for each item in the collection contents are displayed at a random location on the view. When a thumbnail is selected, an interactive PDF processor should display the attachment. © ISO 2020 – All rights reserved
457
ISO 32000-2:2020(E)
The Linear layout provides a view of an attachment, which is usually larger than just a thumbnail, with the metadata for the file displayed alongside it. An interactive PDF should display the first page of the file and should use the file schema and file specification dictionary to provide information about the attachment. The Tree layout is intended to provide a classic folder view of the contents of a collection, akin to that found on many operating systems. An interactive PDF should present the folder structure as the nodes of the tree, with the attachments being presented as the leaves of the tree.
Navigation: PDF20-Spec-12-Viewer-Prefs | PDF20-Spec-Index | PDF20-Spec-12-Page-Navigation