Actions

PDF allows you to associate actions with events. These actions are provided through the Action class and its specializations.

The following actions are supported:  

  • FormAction: Submit or clear form data
  • GoToAction: Jump to a destination in the same document or to a page in another PDF document
  • HideAction: Show or hide an annotation
  • ImportDataAction: Import an FDF file
  • JavaScriptAction: Perform scripted operations against the document (Professional edition only)
  • LaunchAction: Launch an application
  • NamedAction: Execute a named action
  • UriAction: Jump to a URI
  Each action type is discussed in detail below.

Events

It is the responsibility of the PDF reader to execute the actions that are associated with an event whenever the event occurs. The following properties are of type Action. The properties correspond to events.  

  • Document.OpenActions: These actions are executed after the document has been opened
  • Document.AfterPrint: These actions are executed after the document has been printed
  • Document.AfterSave: These actions are executed after the document has been saved
  • Document.BeforeClose: These actions are executed before the document is closed
  • Document.BeforePrint: These actions are executed before the document is printed
  • Document.BeforeSave: These actions are executed before the document has been saved
  • Link.MouseUpActions: These actions are executed when the mouse button is released while the pointer is inside the link
  • Widget.GotFocusActions: These actions are executed when the widget receives keyboard focus
  • Widget.LostFocusActions: These actions are executed when the widget loses keyboard focus
  • Widget.MouseDownActions: These actions are executed when the mouse button is pressed while the pointer is inside the widget
  • Widget.MouseEntrerActions: These actions are executed when the mouse pointer enters the widget
  • Widget.MouseExitActions: These actions are executed when the mouse pointer leaves the widget
  • Widget.MouseUpActions: These actions are executed when the mouse button is released while the pointer is inside the widget
  • Bookmark.Actions: These actions are executed when the bookmark is selected
  Note that all properties are of type ActionCollection. All actions in the collection are executed in order.

FormAction

FormAction is the abstract base class of the following actions:  

  • ResetFormAction: reset all form fields in the document to their default value
  • SubmitFormAction: Submits the form data to a given destination. The URL and submit options such as the format can be specified as properties of this action.
  Note that all properties are of type ActionCollection. All actions in the collection are executed in order.

GoToAction

The GoToAction jumps to a destination. The destination is set by assigning the GoToAction.Destination property.

The following types of destinations exist.

Internal destination

The InternalDestination points to a page inside the same document. It is possible to specify the exact location of the viewer, the zoom factor and the way that the page is displayed.

Remote destination

The RemoteDestination points to a page in an external PDF document. It is specified by the path of the PDF document and a page index. You can also specify additional settings such as zoom factor and the exact scroll position after jumping to the location.

Named destination

Class Document has a property called NamedDestinations which is a collection of name-destination pairs. The NamedDestination class lets you specify a destination by specifying the name of a destination in this collection.

HideAction

This action hides or shows one or more annotations or fields.

ImportDataAction

This action lets you import an FDF file by specifying the path.

JavaScriptAction

This action executes JavaScript against the current document. A PDF document is fully scriptable on the client side. Typical usage includes setting a text field value after clicking a button or showing/hiding a field after entering/leaving a form field. Here is the full JavaScript reference.

The following code sample generates a PDF document so that a text field is filled with the current date just before it is printed. This way, you can always see on the print out when it was printed. (How to add fields to a PDF document is discussed in Section Field Shapes.)

Document document = new Document();

JavaScriptAction action = new JavaScriptAction( 
  string.Format( 
    "this.getField('printed').value = 'Printed: {0}'", DateTime.Now));
document.BeforePrintAction = action;

using (FileStream file = new FileStream(
   @"..\..\out.pdf", FileMode.Create, FileAccess.Write))
{
   document.Write(file);
}

Code sample: Add a BeforePrintAction to a document in C#

Document Level JavaScript

The property Document.JavaScripts lets you declare document level JavaScript. This typically contains common functions and constants that can be reused from other JavaScript actions. See JavaScript actions for a more detailed discussion. The following code sample shows how to add a JavaScript function at document level:

JavaScript javaScript = new JavaScript("function foo() { return 10; }");
document.JavaScripts.Add( javaScript );

Code sample: Add a document-level JavaScript function in C#

The document level javascript will need to be run at least once before the definitions in it become available to other javascript code. Existing document level javascript will be run automatically when the document gets opened (if allowed by the ScriptBehavior property), so existing definitions will be available automatically. If you add new definitions however, and you want to use these immediately without saving and reopening the document, you will need to run the document level javascript code explicitly. In order to do so, please execute the following code before executing any other javascript code that relies on it.

foreach (JavaScript javaScript in document.JavaScripts)
{           
  javaScript.Run(document);
}

Code sample: Explicitly running document level javascript in C# in order to declare new functions.

LaunchAction

This action lets you launch an application. The path property of this class may point either to the application itself or to a document which is then opened by the associated application.

LaunchAction

Adobe has specified a number of named actions. You can specify these through this class by setting the NamedAction.Name property to any of the following values:  

  • NextPage: go to the next page
  • PrevPage: go to the previous page
  • FirstPage: go to the first page
  • LastPage: go to the last page

UriAction

The UriAction jumps to a given URI such as http://www.tallcomponents.com.