All 18 action types in PDF 1.7 and the two that PDF 2.0 adds, what each does, and every place an action can be triggered.
An action is a dictionary that tells the reader to do something: /S names the type of action, and the other entries depend on the type. << /S /URI /URI (https://example.com/) >> opens a web page. Actions run when the user clicks a link, bookmark or form field, when a page or the document opens, and on other events. Interactive features in Learning shows how they fit with annotations and forms.
Actions arrived in PDF 1.1, so the five types the specifications leave unmarked carry a PDF 1.1 badge. Each row gives the type’s own entries besides S, and the table that defines them.
Action types
PDF 2.0 lists them in its Table 201.
Navigation
| Type | What it does | Entries | Added |
|---|---|---|---|
GoTo | Go to a destination in this document. In a link or outline item it does the same as a plain /Dest, which is shorter and works in PDF 1.0 too. | D the destination: a name, a string or an array such as [7 0 R /Fit]. PDF 2.0 adds SD, a structure destination, which takes precedence over D. | |
GoToR | Go to a destination in another PDF file. | F the file. D the destination; in an explicit destination array the page is a page number, counting from 0, instead of a reference. NewWindow (PDF 1.2). | |
GoToE | Go to a destination in a PDF embedded in this one (as an embedded file or a file attachment), or from an embedded PDF to its parent. | T a target dictionary: a path of steps up to a parent (/R /P) or down to a child (/R /C). F, D, NewWindow. | |
GoToDp | Go to the start page of a document part (DPart) in this document. | Dp the DPart dictionary. | |
Thread | Start reading an article thread, optionally at a given bead. | D the thread: a thread dictionary, its index in the catalog’s /Threads, or its title. B the bead. F the file, if not this one. | |
Named | Run a command the reader defines, such as going to the next page. See named actions. | N the name of the command. |
Web links and applications
| Type | What it does | Entries | Added |
|---|---|---|---|
URI | Resolve a URI: usually, open a web page. A relative URI is resolved against the /Base in the catalog’s /URI dictionary, or else against the document’s own location. | URI the URI, in 7-bit ASCII. IsMap: if true, the click position within the link is added to the URI as ?x,y. | |
Launch | Start an application, or open or print a file. | F the application or file. Win Windows-specific parameters: file, directory, open or print, and arguments. Mac and Unix were never defined, and PDF 2.0 deprecates all three. NewWindow (PDF 1.2). |
Showing and hiding
| Type | What it does | Entries | Added |
|---|---|---|---|
Hide | Hide or show annotations by setting or clearing their Hidden flag. With the E and X triggers it can pop up a help label while the pointer is over something. | T an annotation, the full name of a form field (for its widgets), or an array of these. H true to hide (the default), false to show. | |
SetOCGState | Turn optional content groups (layers) on or off. | State names followed by the groups they apply to, read left to right: [/OFF 2 0 R /Toggle 5 0 R /ON 6 0 R]. PreserveRB (default true) keeps radio-button groups of layers consistent. | |
Trans | In a chain of actions, show the page as it is so far, using a transition effect such as a dissolve. Readers otherwise don’t redraw until the chain ends. | Trans a transition dictionary. |
Forms and scripts
| Type | What it does | Entries | Added |
|---|---|---|---|
SubmitForm | Send form field names and values to a URL, usually a web server. | F the URL. Fields the fields to send, or to leave out. Flags pick the format (FDF by default, or HTML form data, or, since PDF 1.4, XFDF or the whole PDF) and more. | |
ResetForm | Set form fields back to their default values, the DV in each field. | Fields the fields to reset, or to leave alone. Flags bit 1 picks which: include or exclude. | |
ImportData | Fill in form fields from a Forms Data Format (FDF) file. | F the FDF file. | |
JavaScript | Run a script. Scripts in the /JavaScript name tree of the document’s name dictionary run when the document opens, defining functions the others can call. PDF 2.0 calls these ECMAScript actions, but the /S value is still /JavaScript. | JS the script, as a text string or stream: PDFDocEncoding, or UTF-16 with a byte order mark. |
Multimedia and 3D
| Type | What it does | Entries | Added |
|---|---|---|---|
Sound | Play a sound. | Sound the sound object. Volume −1.0 to 1.0. Synchronous, Repeat, Mix. | |
Movie | Play, stop, pause or resume the movie in a movie annotation. | Annotation or T picks the movie annotation (PDF 1.4 calls the first key Annot). Operation Play (the default), Stop, Pause or Resume. | |
Rendition | Play, stop, pause or resume a media clip (a rendition) in a screen annotation, or run a script that does something custom. | OP the operation, 0 to 4. R the rendition. AN the screen annotation. JS a script, run instead of OP where the reader supports scripts. | |
GoTo3DView | Set the view of a 3D annotation. | TA the 3D annotation. V the view: a view dictionary, the index or the title of one of the views listed in the 3D stream, or /F, /L, /N, /P or /D for first, last, next, previous or default. | |
RichMediaExecute | Send a command to the handler of a RichMedia annotation. | TA the annotation. TI one instance of its content. CMD the command name and its arguments. |
The PDF 1.4 reference also mentions two older types: a set-state action, obsolete and not to be used, and a no-op action, defined in PDF 1.2 but never implemented and since dropped from the specification.
Chaining actions with Next
Every action dictionary can have these entries, whatever its type:
| Key | Value | Added |
|---|---|---|
Type | /Action, if present. | |
S | Required. The type of action: one of the types above. | |
Next | The action to run after this one: one action dictionary, or an array of them to run in order. |
Since each action in /Next can have a /Next of its own, a chain can branch into a tree. The reader runs it depth first: an action, then everything chained after it, then the next action in the array. This button turns on a layer of answers, swaps itself for a “hide” button, and then redraws the page with a dissolve:
<< /S /SetOCGState /State [/ON 40 0 R] % 1. turn on the answers layer
/Next [ << /S /Hide /T (showAnswers) % 2. hide this button
/Next << /S /Hide /T (hideAnswers) /H false >> >> % 3. show the other one
<< /S /Trans /Trans << /S /Dissolve >> >> ] >> % 4. redraw, dissolving- Readers normally hold off redrawing until the whole chain has run. A Trans action shows the page as it is at that point, with a transition effect.
- A reader shouldn’t run an action twice when a chain refers back to itself, and stops when an action, such as closing the document, makes the rest impossible.
- An action shouldn’t change its own dictionary or any other in its chain; the result is undefined.
Where actions are triggered
An action runs only when something points to it. /A and /OpenAction hold one action each. An /AA entry holds an additional-actions dictionary, whose keys are trigger events and whose values are the actions to run.
| Where | Key | When the action runs | Added |
|---|---|---|---|
| Document catalog | OpenAction | When the document opens. The value can be a destination array instead, as in the example. | |
| Document catalog | AA | Document triggers: before and after closing, saving and printing. | |
| Page object | AA | Page triggers: when the page opens and closes. | |
| Outline item | A | When the user clicks the bookmark. Not allowed alongside /Dest. | |
| Link, screen or widget annotation | A | When the user clicks the annotation. A link can’t have both /A and /Dest. | |
| Screen or widget annotation | AA | Annotation triggers: the pointer, the mouse button, the focus, and the page it is on. | |
| Form field | AA | Form field triggers: keystrokes, formatting, validating and calculating its value. |
PDF 1.4 lists A and AA among the entries every annotation can have, noting that only widgets used AA. ISO 32000-1 puts A in the link, screen and widget annotation tables and AA in the screen and widget tables. The trigger keys below are the same in PDF 2.0.
Annotation triggers
Keys in the /AA of a screen or widget annotation:
| Key | When the action runs | Added |
|---|---|---|
E | The pointer enters the annotation’s active area. | |
X | The pointer leaves it. | |
D | The mouse button is pressed inside it. | |
U | The mouse button is released inside it. If the annotation also has an /A, that runs instead. | |
Fo | Widgets only: the annotation gets the input focus. | |
Bl | Widgets only: it loses the focus (“blurred”). | |
PO | The page the annotation is on opens. Runs after the catalog’s /OpenAction and the page’s O. | |
PC | That page closes. Runs before the page’s C. | |
PV | That page becomes visible. | |
PI | That page is no longer visible. |
PO, PC, PV and PI let an annotation carry its own page-open and page-close actions, so it can be moved or copied to another page with them. A page can be visible without being the open page, as in a two-page layout. An X needs an E before it, and a U needs an E and a D.
Page triggers
Keys in the /AA of a page object:
| Key | When the action runs | Added |
|---|---|---|
O | The page opens. When the catalog’s /OpenAction also runs, this runs after it. | |
C | The page closes. Runs before any other page opens. |
Form field triggers
Keys in the /AA of a form field:
| Key | When the action runs | Added |
|---|---|---|
K | Keystroke: the user types into a text field or combo box, or changes the selection in a list box. The script can check the change and reject or modify it. | |
F | Format: before the field’s value is formatted for display. The script can change the value first. | |
V | Validate: the field’s value has changed. The script can check the new value. | |
C | Calculate: another field has changed, so recompute this one. The form dictionary’s /CO array sets the order. |
Each of these is a JavaScript action. None of them applies to button fields.
Document triggers
Keys in the /AA of the document catalog:
| Key | When the action runs | Added |
|---|---|---|
WC | Will close: before the document closes. | |
WS | Will save: before the document is saved. | |
DS | Did save: after it is saved. | |
WP | Will print: before it is printed. | |
DP | Did print: after it is printed. |
Each of these is a JavaScript action. The PDF 1.4 reference names the first key DC (“document close”); ISO 32000-1 and PDF 2.0 name it WC.
Named actions
A Named action (PDF 1.2) runs a command built into the reader, given in /N: << /S /Named /N /NextPage >>. Every reader should support these four:
| Name | What it does |
|---|---|
NextPage | Go to the next page. |
PrevPage | Go to the previous page. |
FirstPage | Go to the first page. |
LastPage | Go to the last page. |
Readers may support more names, but a file that uses them only works in those readers. A reader that doesn’t recognize the name, or finds it doesn’t make sense on its platform, does nothing. PDF 2.0 (Table 215) has the same four.
Example
A document that opens showing the whole first page, with one bookmark that jumps to another page and a link that opens a web address.
1 0 obj << /Type /Catalog /Pages 2 0 R /Outlines 20 0 R /OpenAction [3 0 R /Fit] >> % open on the first page, whole page in view endobj 20 0 obj % the outline (bookmarks) root << /Type /Outlines /First 21 0 R /Last 21 0 R /Count 1 >> endobj 21 0 obj % one bookmark: the top of the page in object 7 << /Title (Results) /Parent 20 0 R /A << /S /GoTo /D [7 0 R /XYZ 0 792 null] >> >> endobj 12 0 obj % a link, listed in a page's /Annots << /Type /Annot /Subtype /Link /Rect [72 600 250 614] /Border [0 0 0] /A << /S /URI /URI (https://example.com/data.csv) >> >> endobj
/OpenActionholds a destination array here. An action dictionary works too.- The bookmark’s GoTo action does the same as
/Dest [7 0 R /XYZ 0 792 null], which is shorter./XYZ left top zoomputs the point (0, 792) at the top left of the window;nullkeeps the current zoom. - An outline item’s own
/Nextand/Prev(not needed here, with only one bookmark) point to its sibling bookmarks. They have nothing to do with an action’s/Next. - The link runs a URI action when clicked. Its other entries are on Annotation types.
Checked against §8.5 of the Adobe PDF Reference, third edition (PDF 1.4), Tables 8.29 to 8.34 and 8.45 and the action tables after them; §12.6 of ISO 32000-1:2008 (PDF 1.7), Tables 193 to 198 and 211 and the action tables after them, with the form actions in §12.7.5; and ISO 32000-2:2020 (PDF 2.0), Tables 197 to 201, for what PDF 2.0 adds and deprecates.