Interactive Features

Revision as of 15:55, 18 May 2018 by Adminko (talk | contribs)
Jump to: navigation, search

Interactive Features

This article describes the API related to the PDF features that allow a user to interact with a document when viewing it using the mouse and keyboard e.g. links, annotations, actions, events, various form controls etc.

Viewer Preferences

The preferrred viewing parameters can be set using the document-level API described in details here.

Document-Level Navigation

The PDF standard describes several approaches for implementing a document-level navigation. For these purposes a few PDF objects were defined, namely Destinations and Document Outlines (sometimes referred as “Bookmarks”).


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 factor (zoom)

Destinations may be associated with outline items (see the section 12.3.3 “Document Outline” of the specification), annotations or actions. In each case, the destination specifies the view of the document that shall be presented when the outline item or annotation is being opened or the action is being performed. A destination may be specified either explicitly, by creating an instance of the Destination class and defining its properties or indirectly, using its name.

Explicit destinations

Explicit destinations in PDF documents, as the name suggests, are defined in place, explicitly, with all the parameters needed for the navigation provided at the moment of creation.

Named destinations

Named destinations are in fact references to the destination objects present in the document's internal registry and describing the actual navigation. These destination objects should be registered in the PDF document with names, and in case of Fixed layout API, it's the FixedDocument.Destinations collection they should be added into to become usable.

The code below demonstrates how to add two link annotations onto the page of the PDF document and set their targets using explicit and named Destination objects.

// create output PDF file
using (FileStream outputStream = new FileStream("navigation.pdf", FileMode.Create, FileAccess.Write))
    // create new PDF document
    FixedDocument document = new FixedDocument();
    document.Pages.Add(new Page());
    // second page we are going to add a link to
    Page page2 = new Page();
    // create and register the named destination object
    document.Destinations.Add("myDestination",new Destination(page2, new DestinationTypeFit()));
    // add and place text object containing the text for our links
    TextObject textObject = new TextObject(StandardFonts.Helvetica, 14);
    textObject.AppendText("Navigate to page 2 using explicit destination");
    textObject.AppendText("Navigate to page 2 using named destination");
    // create link annotation using explicit destination
    LinkAnnotation linkAnnotation1 = new LinkAnnotation(new Boundary(10, 810, 300, 830));
    linkAnnotation1.BorderStyle = new AnnotationBorderStyle(1);
    linkAnnotation1.Color = new double[] { 0, 0, 0.9 };
    linkAnnotation1.Destination = new Destination(page2, new DestinationTypeFit());
    // create link annotation using named destination
    LinkAnnotation linkAnnotation2 = new LinkAnnotation(new Boundary(10, 780, 300, 800));
    linkAnnotation2.BorderStyle = new AnnotationBorderStyle(1);
    linkAnnotation2.Color = new double[] { 0, 0, 0.9 };
    linkAnnotation2.Destination = new Destination("myDestination");
    // add annotations to the PDF page

Usage of explicit destinations is pretty straightforward, while named destinations require registration in their parent document. Using named destination it becomes possible to separate references generation from actual content generation. You may generate a list of links using destinations names first and later register these destination objects pointing to the correct locations.

Resulting PDF file is shown on the image below:

Links added using explicit and named destinations

Document outline (bookmarks)

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 opened or closed, selectively showing or hiding further parts of the document hierarchy. When an item is closed, all of its descendants in the hierarchy should become hidden. Clicking the text of any visible item shall activate the item, causing the conforming reader to jump to a destination or trigger an action associated with the item.

Document bookmarks or outlines, as they are named in PDF specification, can be enumerated, added or edited using the Bookmark class provided by the Apitron PDF Kit. The Bookmarks property of the FixedDocument class is designed for this purpose. Each bookmark element in its turn has Bookmarks property holding its children and so on. A bookmark can have either a destination or action assigned.

Consider the code below demonstrating the creation of bookmarks:

// create output PDF file
using (FileStream outputStream = new FileStream("navigation.pdf", FileMode.Create, FileAccess.Write))
    // create new PDF document
    FixedDocument document = new FixedDocument();
    // add three pages
    document.Pages.Add(new Page());
    document.Pages.Add(new Page());
    document.Pages.Add(new Page());
    // add root bookmark and set it open by default
    Bookmark rootBookmark = new Bookmark(document.Pages[0], "Table of contents");
    rootBookmark.IsOpen = true;
    // add nested bookmarks
    rootBookmark.AddLast(new Bookmark(new Destination(document.Pages[1]), "Page 2"));
    rootBookmark.AddLast(new Bookmark(new GoToAction(document.Pages[2]), "Page 3"));
    rootBookmark.AddLast(new Bookmark(new JavaScriptAction("app.alert('Hello World!');"), "JavaScript Bookmark"));

The image below shows the resulting document produced by the sample code with the TOC containing three bookmarks of different nature - first uses explicit destination, second uses GoTo action, and the last uses JavaScript action invoking the alert window:

Creating bookmarks in PDF document