Since the number of things that make up a destination is small and well defined, a destination is not based on a dictionary but instead on an array, unlike the other types of common objects that you’ve encountered so far (see Example 5-1). The first element of the array is always an indirect reference to the page object to which it refers, followed by a name object describing the type of zoom, and then any additional options needed for that zoom.

% Object 1 is assumed to be the page

[1 0 R /Fit]         % Display entire page with horizontal & vertical magnified to fit

[1 0 R /FitH]        % Display entire page with only horizontal magnified to fit
[1 0 R /FitH 100]    % FitH variant where vertical top is 100

[1 0 R /FitV]        % Display entire page with only vertical magnified to fit
[1 0 R /FitV 100]    % FitH variant where horizontal left is 100

In addition to Fit, FitH, and FitV, there are other ways to zoom into a specific part of a page; the most powerful of these is XYZ, which includes the specific left and top coordinates of the page (for the viewer to align with) along with the zoom factor. If you don’t know them or want any of the top, left, or zoom factor values to change from what they are when the destination is invoked, provide a 0 or null value. Example 5-2 illustrates the use of XYZ.

% Object 1 is assumed to be the page

[1 0 R /XYZ 36 36 50]     % Display a portion of the page, 1/2 inch in from the top and left and zoomed 50%

[1 0 R /XYZ null null 50] % Display the current portion of the page, zoomed 50%

Instead of being defined directly using the syntax shown previously, a destination may be referred to indirectly by means of a string.

This capability is especially useful when the destination is located in another PDF document. For example, a document (DocA) that wished to link to the beginning of Chapter 2 in another document (DocB) could refer to that destination by a name (e.g., Chapter2), instead of by an explicit page number in the other document. This would enable the actual physical page number of that chapter in DocB to change (due to edits, page insertions/deletions, etc.) without invalidating the destination in DocA.

Named destinations work by creating a correspondence between the name (which is represented as a string object) and the destination. This correspondence or mapping happens via the document’s name dictionary, which is the value of the Names key in the document’s catalog dictionary. In the name dictionary is a Dests key, whose value is a name tree with the string → destination mapping.

The destination value associated with a key in the name tree may be either an array or a dictionary. When the value of this entry is a dictionary, each key is a destination name and the corresponding value is either an explicit destination or a dictionary with a D entry whose value is an explicit destination.

The action dictionary is the common base dictionary for all types of actions. It consists of only one required entry: the S key, whose value declares the type of action. All other keys in this dictionary will vary based on the type of action.

The most common action is GoTo. The GoTo action corresponds to a destination, in that its invocation will cause a viewer to “go to” a specific destination. This is clear when you see that the main key in the GoTo action dictionary is the D key, whose value is a destination. See Example 5-3.

% This is the action dictionary for a GoTo action
8 0 obj
<<
    /Type /Action
    /S /GoTo
    /D [10 0 R /Fit] % GoTo the page referred by object 10 and fit it
>>
endobj

% This is an object called a link annotation
9 0 obj
<<
    /Type /Annot
    /Subtype /Link
    /Rect [100 100 150 150]
    /A 8 0 R
>>
endobj

In this example, object #8 represents a GoTo action that will take the user to a page in the document (referenced by object #10) and display it as magnified to Fit (as per the explicit destination that is the value of the D key). However, this action can’t stand by itself—it needs to be connected to some other object that will cause it to be invoked by the viewer implicitly, or the user explicitly. In this example, it is connected to an object (#9) called a link annotation.

The second most common action is URI. A URI (uniform resource identifier) is a more flexible concept than the normal URL (uniform resource locator) that most users are familiar with, though for the vast majority of cases you can use them interchangeably. So you can just think of the URI action as a web link.

Like the GoTo action, a URI action is very simple; it involves the addition of a single key (URI) to the standard action dictionary (see Example 5-4).

% This is the action dictionary for a URI action
8 0 obj
<<
    /Type /Action
    /S /URI
    /URI (http://www.oreilly.com)
>>
endobj

9 0 obj
<<
    /Type /Annot
    /Subtype /Link
    /Rect [100 100 150 150]
    /A 8 0 R
>>
endobj

The value of the URI key can be any valid URI. It is not limited to common schemes such as http or ftp; it could use a historical scheme such as gopher or a custom or private scheme such as book. The reason is that a PDF reader is not required to support any specific schemes and will usually just pass the URI off to the operating system for processing.

You’ve seen how GoTo actions can be quite useful, as long as you only need to navigate inside of the same PDF document. Similarly, the URI action enables redirecting the user to documents and web pages that are online. However, sometimes you want to refer to something in another PDF, or even another type of document (e.g., a word processing document or spreadsheet). For those situations you will need to use either a GoToR (for PDF) or a Launch (for other file types) action.

The GoToR action, also known as the “remote go-to” action, incorporates all of the aspects of a GoTo action, but with the addition of an F key in the action dictionary that points to the PDF in which the destination is to be resolved. A common use for this would be in a book that is broken up into chapters, where you want links between the chapters. Example 5-5 illustrates how to use GoToR to open up a PDF called “Chapter2.pdf” (which is in the same directory as the link’s PDF) and go to physical page #1.

% This is the action dictionary for a GoTo action
8 0 obj
<<
    /Type /Action
    /S /GoToR
    /D [0 /Fit] % NOTE: GoToR uses zero-based page #s, not indirect references
    /F <<
       /Type /Filespec
       /F (Chapter2.pdf)
       /UF (Chapter2.pdf)
    >>
endobj

For those situations where you need to externally link to a non-PDF document, the Launch action provides the solution. As you can see in Example 5-6, its syntax is almost exactly the same as that of the GoToR action.

% This is the action dictionary for a Launch action
8 0 obj
<<
    /Type /Action
    /S /Launch
    /F <<
        /Type /Filespec
        /F (Chapter2.docx)
        /UF (Chapter2.docx)
    >>
endobj

We’ve only touched the surface of actions with the four types of actions covered so far. There are also actions that enable the PDF to play sounds and movies, work with embedded 3D objects, and even run a JavaScript program. We’ll discuss these in Chapter 9; see also ISO 32000-1:2008, 12.6.

One of the other advantages of using an action over a simple destination is that you can combine multiple actions, using the Next key in the action dictionary to chain them together. For example, the effect of clicking a link annotation with the mouse might be to play a sound, jump to a new page, and start up a movie.

The Next entry is not restricted to a single action but may contain an array of actions, each of which in turn may have a Next entry of its own. The actions therefore form a tree instead of a simple linked list. Actions within each Next array are executed in order, each followed in turn by any actions specified in its Next entry, and so on recursively.