Bookmarks and Destinations in the PDF Viewer

Aug 23, 2024
4 minutes to read

Bookmarks (outlines) are used to quickly navigate from one part of a document to another. Bookmarks can be anchored to a document page with specific view parameters (a destination), an external URI, or an action. The PDF Viewer displays document bookmarks in the Bookmarks panel of the Navigation pane.

Note

The PDF Viewer shows bookmarks within its navigation pane for a document that contains them.

Navigate to a Bookmark

Code

Call the PdfViewer.GoToBookmark method to navigate to a specific bookmark. Use the PdfViewer.Bookmarks property to obtain a list of document bookmarks.

The code sample below navigates to a bookmark node with a specific title when the document is loaded:

C#
VB.NET

csharp

using DevExpress.Pdf;
using DevExpress.XtraPdfViewer;
using System.Collections.Generic;
//...
pdfViewer.DocumentChanged += pdfViewer_DocumentChanged;

// Navigate to the "Annotations" bookmark
private void pdfViewer_DocumentChanged(object sender, PdfDocumentChangedEventArgs e) {
    foreach (var bookmarkItem in pdfViewer.Bookmarks) {
        if (bookmarkItem.Title == "Annotations") 
            pdfViewer.GoToBookmark(bookmarkItem);
    }
}

Imports DevExpress.Pdf
Imports DevExpress.XtraPdfViewer
Imports System.Collections.Generic
'...
Private pdfViewer.DocumentChanged += AddressOf pdfViewer_DocumentChanged

' Navigate to the "Annotations" bookmark
Private Sub pdfViewer_DocumentChanged(ByVal sender As Object, ByVal e As PdfDocumentChangedEventArgs)
    For Each bookmarkItem In pdfViewer.Bookmarks
        If bookmarkItem.Title = "Annotations" Then
            pdfViewer.GoToBookmark(bookmarkItem)
        End If
    Next bookmarkItem
End Sub

The PdfViewerBookmarkExtensions.FindBookmark method allows you to find a bookmark that meets specified criteria. This method can be useful if you need to find a bookmark in a document with a complex bookmark tree.

The code sample below finds a bookmark with the specified title and navigates to this bookmark when the document is loaded:

C#
VB.NET

csharp

using DevExpress.Pdf;
using DevExpress.XtraPdfViewer;
//...
pdfViewer.DocumentChanged += pdfViewer_DocumentChanged;

private void pdfViewer_DocumentChanged(object sender, PdfDocumentChangedEventArgs e) {
    var bookmark = pdfViewer.Bookmarks.FindBookmark(x => x.Title == "4 Notation");
    if (bookmark != null) { 
        pdfViewer.GoToBookmark(bookmark); 
    }
}

Imports DevExpress.Pdf
Imports DevExpress.XtraPdfViewer
'...
Private pdfViewer.DocumentChanged += AddressOf pdfViewer_DocumentChanged

Private Sub pdfViewer_DocumentChanged(ByVal sender As Object, ByVal e As PdfDocumentChangedEventArgs)
    Dim bookmark = pdfViewer.Bookmarks.FindBookmark(Function(x) x.Title = "4 Notation")
    If bookmark IsNot Nothing Then
        pdfViewer.GoToBookmark(bookmark)
    End If
End Sub

User Interface

The Bookmarks panel allows you to navigate to a bookmark. The panel displays bookmarks in a hierarchical tree. When an outline node is opened, you can see its children in the pane.

Navigate to a Destination

A destination is a reference to a page with specific view parameters. A destination includes the following view parameters:

The displayed document page
The location of the document window on this page
The magnification (zoom factor)

A PDF file may contain a list of named destinations. Call the PdfViewer.GoToDestination method to navigate to the specified destination. The DestinationNames property retrieves a list of available destination names.

The code sample below shows how to navigate to a destination when the document is loaded:

C#
VB.NET

csharp

using DevExpress.XtraPdfViewer;
using System.Linq;
//...
pdfViewer.DocumentChanged += pdfViewer_DocumentChanged;

private void pdfViewer_DocumentChanged(object sender, PdfDocumentChangedEventArgs e) {
    var destNames = pdfViewer.DestinationNames;
    var dest = destNames.Where(x => x.Contains("Page 6")).First();
    pdfViewer.GoToDestination(dest);
}

Imports DevExpress.XtraPdfViewer
Imports System.Linq
'...

Private Sub pdfViewer_DocumentChanged(ByVal sender As Object, ByVal e As PdfDocumentChangedEventArgs)
    Dim destNames = pdfViewer.DestinationNames
    Dim dest = destNames.Where(Function(x) x.Contains("Page 6")).First()
    pdfViewer.GoToDestination(dest)
End Sub

Note

The PDF viewer does not display destinations in the Navigation pane.

Specify Outline Display Settings

Use the PdfOutlineViewerSettings class properties to change display settings for the Bookmarks panel. The following settings are available:

HideAfterUseGets or sets whether to hide the Bookmarks panel after a bookmark is clicked.WrapLongLinesGets or sets whether to wrap outline titles in the Bookmarks panel.UseOutlinesForeColorSpecifies whether to use document foreground colors for the outline node text in the Bookmarks panel.TextSizeGets or sets text size for outline nodes in the Bookmarks panel.

The code sample below shows how to specify these options in code:

C#
VB.NET

csharp

var outlineViewerSettings = pdfViewer.OutlineViewerSettings;
outlineViewerSettings.WrapLongLines = false;
outlineViewerSettings.UseOutlinesForeColor = true;
outlineViewerSettings.HideAfterUse = true;
outlineViewerSettings.TextSize = PdfOutlineNodeTextSize.Medium;

Dim outlineViewerSettings As PdfOutlineViewerSettings = pdfViewer.OutlineViewerSettings
outlineViewerSettings.WrapLongLines = False
outlineViewerSettings.UseOutlinesForeColor = True
outlineViewerSettings.HideAfterUse = True
outlineViewerSettings.TextSize = PdfOutlineNodeTextSize.Medium

These options are also available in the Options drop-down list in the Bookmarks panel.