data-id=actions-and-destinations

data-id=id1

Actions and Destinations

When a user opens a file, clicks on a link, or clicks on a bookmark, several types of information need to be specified to indicate what should happen. Different pdfmark types require one or more of the following:

Actions specify what type of action should be taken. They are indicated by the Action key in a pdfmark. See Actions. File specifiers indicate the target of an action when it is not the current file. See the table File specifier keys.
Destinations specify a particular location in a file, and a zoom factor. See Destinations.

data-id=actions

data-id=id2

Actions

PDF defines several types of actions that can be specified for bookmarks and annotations. The following table outlines the types defined as of PDF 1.3.

Action types

Action type

Description

GoTo

Go to a destination in the current document.

GoToR

Go to a destination in another document.

Hide

Set an annotation’s Hidden flag.

ImportData

Import field values from a files.

JavaScript

Execute a JavaScript™ script.

Launch

Launch an application, usually to open a file.

Movie

Play a movie.

Named

Execute an action predefined by the viewer application.

ResetForm

Set fields to their default values.

Sound

Play a sound.

SubmitForm

Send data to a URL.

Thread

Begin reading an article thread.

URI

Resolve a uniform resource identifier.

When using pdfmark, the type of action for the annotation or bookmark is specified by the Action key. It takes one of the following values:

A predefined name corresponding to one of the first four items in the table Action types: GoTo, GoToR, Launch, or Article (which corresponds to the Thread type in PDF).
A dictionary specifying one of the other types, or a custom action. This dictionary must contain the key–value pairs that are to be placed into the action dictionary in the PDF file. See the PDF Reference for a detailed description of all the actions and their dictionaries. The syntax for this type of Action key is as follows:

     /Action << / Subtype
actiontype
        ...other action dictionary key–value pairs...
>>

Custom link action (URI link for the Acrobat WebLink plug-in) shows a note pdfmark containing a URI action.

If the Action key is not present, the action is assumed to be the equivalent of GoTo ; that is, jumping to a location in the current document. Actions other than GoTo may require a file-specifier key to specify an external document (see the table File specifier keys).

data-id=goto-actions

data-id=id3

GoTo actions

GoTo actions jump to a specified page and zoom factor within the current document. They require the Dest key, or both the Page and View keys. See Destinations for more information on these keys.

data-id=gotor-actions

data-id=id4

GoToR actions

GoToR actions specify a location in another PDF file. They require the Dest key, or both the Page and View keys, plus one or more file-specifier keys (see the table File specifier keys).

See Bookmarks (OUT) for an example of a GoToR action.

The following table specifies keys that can be used with the GoToR, Launch, and Article actions to specify the target file.

File specifier keys

Key

Type

Semantics

DOSFile

string

Optional. The MS-DOS path (in the PDF path format), of the PDF file. Acrobat viewer applications in Windows and DOS ignore the File key if the DOSFile key is present.

File

string

Required. The device-independent path of the PDF file.

array

Optional. An array of two strings specifying the PDF file ID. This key can be used to ensure the correct version of the destination file is found. If present, the destination PDF file’s ID is compared with ID, and the user is warned if they are different.

MacFile

string

Optional. The Mac OS file name (in the PDF path format) of the PDF file. Acrobat viewer applications in Mac OS ignore the File key if the MacFile key is present.

UnixFile

string

Optional. The UNIX file name (in the PDF path format) of the PDF file. Acrobat viewer applications in UNIX ignore the File key if the UnixFile key is present.

URI

string

Optional. The uniform resource identifier (URI) of a file on the Internet. It can be either an HTML or PDF file. Acrobat viewer applications ignore the File key if the URI key is present. Named destinations may be appended to URLs, following a “#” character, as in http://www.example.com/example.pdf#name. The Acrobat viewer displays the part of the PDF file specified by the named destination. * This key is used with the Launch action. URIs can also be specified with an action dictionary where the value of the Subtype key is /URI (see Custom link action (URI link for the Acrobat WebLink plug-in).)

The PDF Reference provides more information about the above specifiers.

data-id=launch-actions

data-id=id5

Launch actions

Launch actions launch an arbitrary application or document, specified by the File key. If an application is specified, some platforms allow passing options or filenames to the application that is launched. See Link that launches another file for an example of a launch action.

See the table File specifier keys for the file specifier keys that can be used by Launch actions. In addition, the following optional keys can be used.

Optional keys for Launch actions

Key

Type

Semantics

Dir

string

Optional. The default directory of a Windows application.

string

Optional. The operation to perform; used only under Windows. The string must be open (the default) or print. If WinFile specifies an application, not a document, this key is ignored and the application is launched.

Params

string

Optional. The parameters passed to a Windows application started with the Launch action. If the WinFile key specifies an application, Params must not be present.

WinFile

string

Optional. The MS-DOS file name of the document or application to launch.

Note

Acrobat viewer applications running under Windows use the Windows function ShellExecute to launch an application specified using the Launch action. The keys WinFile, Dir, Op, and Params correspond to the parameters of ShellExecute.

data-id=article-actions

data-id=id6

Article actions

Article actions set the Acrobat viewer to article-reading mode, at the beginning of a specified article in the current document or another PDF document.

They require the Dest key, which takes one of the following values:

An integer that specifies the article’s index in the document (the first article in a document has an index of 0).
A string that matches the article’s Title.

In addition, article actions require one or more file-specifier keys if the article is in a different PDF file (see the table File specifier keys).

See Article action for an example of an article action.

data-id=destinations

data-id=id7

Destinations

There are two ways of specifying a location within a document that is the target of an action:

View destinations explicitly specify a page, a location on the page, and a fit type. View destinations require a Page key and a View key. Typically they are used along with an Action key; if there is no Action key, the action is the equivalent of GoTo, meaning to jump to the destination in the current file. See View destinations.
Named destinations specify the target as a name which has been defined. Named destinations are specified by the Dest key. They specify a destination in the same file or another file, by name. See Defining named destinations.

data-id=view-destinations

data-id=id8

View destinations

View destinations require the following two keys.

Keys for view destinations

Key

Type

Semantics

Page

integer or name

The destination page. An integer value represents the sequence number of the page within the PDF file. The first page in a file is page 1, not page 0. The name objects Next and Prev are valid destination page values for links and articles. If the destination of a link is on the same page, the Page key should be omitted. If the value of the Page key is 0, the bookmark or link has a NULL destination.

View

array

Specifies a link or bookmark’s destination on a page, and its fit type. The first array entry is one of the fit type names shown in the table Fit type names and parameters. The remaining entries, if any, specify the location as either a rectangle, a point, or an x– or y–coordinate, depending on the fit type.

All distances and coordinates specified in the following table are in default user space.

Fit type names and parameters

Name

Parameters

Description

Fit

None

Fit the page to the window. This is a shortcut for specifying FitR with the rectangle being the crop box for the page.

FitB

None

Fit the bounding box of the page contents to the window.

FitBH

top

Fit the width of the bounding box of the page contents to the window. top specifies the distance from the page origin to the top of the window.

FitBV

left

Fit the height of the bounding box of the page contents to the window. left specifies the distance from the page origin to the left edge of the window.

FitH

top

Fit the width of the page to the window. top specifies the distance from the page origin to the top of the window. This is a shortcut for specifying FitR with the rectangle having the width of the page, and both y-coordinates equal to top.

FitR

x1 y1 x2 y2

Fit the rectangle specified by the parameters to the window.

FitV

left

Fit the height of the page to the window. left specifies the distance in from the page origin to the left edge of the window. This is a shortcut for specifying FitR with the rectangle having the height of the page, and both x-coordinates equal to left.

XYZ

left top zoom

left and top specify the distance from the origin of the page to the top-left corner of the window. zoom specifies the zoom factor, with 1 being 100% magnification. If left, top or zoom is NULL, the current value of that parameter is retained. For example, specifying a view destination of /View [/XYZ NULL NULL NULL] goes to the specified page and retains the same horizontal and vertical offset and zoom as the current page. A zoom of 0 has the same meaning as a zoom of NULL.

The zoom factors for the horizontal and vertical directions are identical; there are not separate zoom factors for the two directions. As a result, more of the page may be shown than specified by the destination. For example, when using FitR, portions of the page outside the destination rectangle appear in the window unless the window happens to have the same aspect ratio (height-to-width ratio) as the destination rectangle.

A common destination is “upper left corner of the specified page, with a zoom factor of 1.” This can be obtained using the XYZ destination form, with a left of -4 and a top equal to the top of the CropBox (or the page size if no CropBox was specified) plus 4. The offset of 4 is used to slightly move the page corner from the corner of the window, to provide a visual cue that the corner of the page is being shown.

The following sections have examples related to destinations: Links, Bookmarks (OUT), File Open action, and Defining named destinations.

data-id=defining-named-destinations

data-id=id9

Defining named destinations

Locations in PDF files can be specified by name instead of by page number and view. These names can then be used as destinations of bookmarks or links. Using named destinations is particularly advantageous for cross-document links, because if the document containing a link’s destination is revised, the link still works, regardless of whether its location in the file has changed.

A named destination is specified by using the pdfmark operator with the name DEST. The syntax for a named destination pdfmark is as follows:

 [ /Dest
name

        /Page
pagenum

        /View
destination

        /DEST pdfmark

Named destination attributes

Key

Type

Description

Dest

name

Required. The destination’s name.

Page

integer

Optional. The sequence number of the destination page. If present, the named destination pdfmark can be placed anywhere in the PostScript language file. If omitted, the pdfmark must occur within the PostScript language description for the destination page.

View

array

Optional. The view to display on the destination page. If omitted, defaults to a null destination (lower left corner of the page at a zoom of 100%). See Destinations for information on specifying a view destination.

In addition to the keys listed in the table Named destination attributes, named destinations can also specify arbitrary key–value pairs.

Named destinations can be appended to URLs, following a “#” character, as in http://www.example.com/example.pdf#nameddest=name. The Acrobat viewer displays the part of the PDF file specified in the named destination.

Definition of named destination

[ /Dest /MyNamedDest
    /Page 1
    /View [/FitH 5]
    /DEST pdfmark

Link to a named destination

[ /Rect [70 650 210 675]
    /Border [16 16 1 [3 10]]
    /Color [0 .7 1]
    /Dest /MyNamedDest
    /Subtype /Link
    /ANN pdfmark

data-id=referencing-named-destinations

data-id=id10

Referencing named destinations

Named destinations that have been defined with the DEST pdfmark can be used as the target of a bookmark or link, or by the optional open action in a document’s Catalog dictionary. They are specified using the Dest key.

See Defining named destinations for examples of named destinations.

Note

When used with the Article action, Dest has a different syntax. See Article actions.