Bookmarks

• Nov 13, 2018
• 4 minutes to read

The PDF Document Processor provides properties and methods to generate new bookmarks or edit the bookmarks for an existing document in code.

Overview

A bookmark is represented by an instance of the PdfBookmark class. It can be accessed as an item of the PdfBookmark objects list returned by the PdfDocument.Bookmarks property. The PdfBookmark class contains the following properties to customize bookmarks.

Member	Description
PdfBookmark.Action	Provides access to the bookmark action being executed.
PdfBookmark.Children	Gets or sets the collection of bookmark children for a document with a tree-structured hierarchy.
PdfBookmark.Destination	Gets or sets a destination (a particular view of a document) to which a bookmark is referred to.
PdfBookmark.IsBold	Gets or sets the value indicating whether the bookmark text is formatted as bold.
PdfBookmark.IsItalic	Gets or sets the value indicating whether the bookmark text is formatted as italic.
PdfBookmark.IsInitiallyClosed	Gets or sets a value that indicates whether bookmarks are initially closed (bookmark children are hidden) in the navigation panel after a document is loaded.
PdfBookmark.TextColor	Gets or sets the color for a bookmark’s text in the navigation pane.
PdfBookmark.Title	Gets or sets the text that is displayed for a bookmark on the navigation pane.

Creating a Bookmark Destination

To create a destination to which a bookmark should be linked, call one of the overloaded PdfDocumentProcessor.CreateDestination methods. The PDF Document Processor can create the destination of the following types:

• PdfFitBBoxDestination
• PdfFitBBoxHorizontallyDestination
• PdfFitBBoxVerticallyDestination
• PdfFitHorizontallyDestination
• PdfFitRectangleDestination
• PdfFitVerticallyDestination
• PdfXYZDestination

The created destination is assigned to the PdfBookmark.Destination property.

The overloaded PdfDocumentProcessor.CreateDestination methods use the world coordinate system. The world coordinate system’s origin (0,0) is at the top left of the page. A positive x increases towards the right and a positive y towards the bottom. So, if you want to pass the page coordinates for a destination to one of the PdfDocumentProcessor.CreateDestination methods as arguments, you need to convert these page coordinates to the world coordinates. See Coordinate Systems to learn more about this transformation.

When the overloaded PdfDocumentProcessor.CreateDestination methods create a destination represented by the PdfDestination object, the world coordinates are converted to page coordinates (see Coordinate Systems for details). To convert the world coordinates (units) into a physical value such as inches, these methods need a resolution’s value (dpi) to be passed as dpiX and dpiY parameters. If the dpi is not passed to the methods, the default resolution in these methods is 96 dpi.

Since the measurement unit in the page coordinate system is a point (1/72 of an inch), pass 72 as dpiX and dpiY values to one of the PdfDocumentProcessor.CreateDestination methods.

Example

This example shows how to create bookmarks in code and add them to a document.

To do this:

• Create a PdfBookmark object;
• Specify the bookmark title and destination using the PdfBookmark.Title and PdfBookmark.Destination properties. To create a destination, call one of the PdfDocumentProcessor.CreateDestination overloaded methods.
• Add the bookmark to the bookmarks collection, which is accessed from the PdfDocument.Bookmarks property.

Note

The measurement unit in the destination is equal to 1/72 of an inch.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-add-bookmarks-to-a-document-t495077

Program.cs

using DevExpress.Pdf;

namespace AddBookmarks {
    class Program {
        static void Main(string[] args) {

            using (PdfDocumentProcessor processor = new PdfDocumentProcessor()) {

                // Load a document.
                processor.LoadDocument("..\\..\\Document.pdf");

                // Create bookmarks and add them to the PDF document.
                PdfDestination destination1 = processor.CreateDestination(1, 180, 150);
                PdfDestination destination2 = processor.CreateDestination(1, 168, 230);
                PdfDestination destination3 = processor.CreateDestination(1, 20, 350);
                processor.Document.Bookmarks.Add(new PdfBookmark() { Title = "PDF Document Processor", Destination = destination1 });
                processor.Document.Bookmarks.Add(new PdfBookmark() { Title = "Display, Print and Export PDF Documents", Destination = destination2 });
                processor.Document.Bookmarks.Add(new PdfBookmark() { Title = "Learn More", Destination = destination3 });

                // Save the result document.
                processor.SaveDocument("..\\..\\Result.pdf");
            }
        }
    }
}

Program.vb

Imports DevExpress.Pdf

Namespace AddBookmarks
    Friend Class Program
        Shared Sub Main(ByVal args() As String)

            Using processor As New PdfDocumentProcessor()

                ' Load a document.
                processor.LoadDocument("..\..\Document.pdf")

                ' Create bookmarks and add them to the PDF document.
                Dim destination1 As PdfDestination = processor.CreateDestination(1, 180, 150)
                Dim destination2 As PdfDestination = processor.CreateDestination(1, 168, 230)
                Dim destination3 As PdfDestination = processor.CreateDestination(1, 20, 350)
                processor.Document.Bookmarks.Add(New PdfBookmark() With {.Title = "PDF Document Processor", .Destination = destination1})
                processor.Document.Bookmarks.Add(New PdfBookmark() With {.Title = "Display, Print and Export PDF Documents", .Destination = destination2})
                processor.Document.Bookmarks.Add(New PdfBookmark() With {.Title = "Learn More", .Destination = destination3})

                ' Save the result document.
                processor.SaveDocument("..\..\Result.pdf")
            End Using
        End Sub
    End Class
End Namespace