Repository navigation
PDF Spec 12 Navigation
Part of: PDF-Spec-12-Interactive-Features
Navigation: PDF-Spec-12-General | PDF-Spec-Index | PDF-Spec-12-Page-Navigation
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 catalogue (7.7.2, 'Document Catalog') 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.
Table 151 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'). 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.)
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 151 - 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, centering 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, centering 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, 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 shall be retained unchanged. |
Table 151 - Destination syntax (continued)
| 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. |
Instead of being defined directly with the explicit syntax shown in Table 151, 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.
- NOTE 1 A link to the beginning of Chapter 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 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.6, 'Thread Actions'), the destination 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 shall be defined by the Dests entry in the document catalogue (see 7.7.2, 'Document Catalog'). 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 151, or a dictionary with a D entry whose value is such an array.
- 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 shall 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.
- NOTE 3 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.
A PDF document may contain a document outline that the conforming reader 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 conforming reader 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 catalogue (see 7.7.2, 'Document Catalog'). Table 152 shows the contents of this dictionary. Each individual outline item within the hierarchy shall be defined by an outline item dictionary (Table 153). 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 152 - 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 153 - 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. |
| 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. |
Table 153 - Entries in an outline item dictionary (continued)
| Key | Type | Value |
|---|---|---|
| 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'). (PDF 1.0) An item may also specify a destination ( Dest ) corresponding to an area of a page where the contents of the designated structure element are displayed. |
| 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 154). 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 loworder to high-order bits, with the lowest-order bit numbered 1. Table 154 shows the meanings of the flags; all other bits of the integer shall be 0.
Table 154 - Outline item flags
| 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. |
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
A PDF document may contain thumbnail images representing the contents of its pages in miniature form. A conforming reader 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 may 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 89 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 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 % Length of stream … endobj
Beginning with PDF 1.7, PDF documents may specify how a conforming reader'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 organizational characteristics of portable collections. If this dictionary is present in a PDF document, the conforming reader shall present the document as a portable collection. The EmbeddedFiles name tree specifies file attachments (see 7.11.4, 'Embedded File Streams').
When a conforming reader first opens a PDF document containing a collection, it shall display the contents of the initial document, along with a list of the documents present in the EmbeddedFiles name tree. The document list shall include the additional document information specified by the collection schema. The initial document may be the container PDF or one of the embedded documents.
NOTE 2 The page content in the initial document should 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.
Table 155 describes the entries in a collection dictionary.
Table 155 - Entries in a collection dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | ( Optional ) The type of PDF object that this dictionary describes; if present, shall be Collection for a collection dictionary. |
| Schema | dictionary | ( Optional ) A collection schema dictionary (see Table 156). If absent, the conforming reader 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 in error, the initial document shall be the one that contains the collection dictionary. |
| 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 multi-column 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 conforming reader shall provide means for the user to view the collection by some explicit action. Default value: D |
| 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 158). |
A collection schema dictionary consists of a variable number of individual collection field dictionaries. Each collection field dictionary has a key chosen by the conforming writer, which shall be used to associate a field with data in a file specification. Table 156 describes the entries in a collection schema dictionary.
Table 156 - 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 conforming 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 44). |
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 157 describes the entries in a collection field dictionary.
Table 157 - 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. 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 44). 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 44). 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 46). 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 46). Size The field data shall be the size of the embedded file, |
| N | text string | ( Required ) The textual field name that shall be presented to the user by the conforming reader. |
| O | integer | ( Optional ) The relative order of the field name in the user interface. Fields shall be sorted by the conforming reader 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 conforming reader 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:
- Text strings shall be ordered lexically from smaller to larger, if ascending order is specified.
NOTE 3 Lexical ordering is an implementation dependency for conforming readers.
- 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 158 describes the entries in a collection sort dictionary.
Table 158 - 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 conforming reader 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 array | ( Optional ) If the value is a boolean, it specifies whether the conforming reader 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 . |
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 organizational data associated with each email is described in a collection schema dictionary. Most actual organizational 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 (Rob McAfee) /to (Patty McAfee) /subject << /Type /CollectionSubitem /P (Re:) /D (Let's have lunch on Friday!) >> /date (D:20050621094703-07'00') >>
This sub-clause 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 12.4.2, 'Page Labels').
- Article threads , which chain together items of content within the document that are logically connected but not physically sequential (see 12.4.3, 'Articles').
- 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 12.4.4, 'Presentations').
For another important form of page-level navigation, see 12.5.6.5, 'Link Annotations.'
Navigation: PDF-Spec-12-General | PDF-Spec-Index | PDF-Spec-12-Page-Navigation