Bookmarks and Destinations in the PDF Viewer for WPF

• Apr 29, 2022
• 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), external URI or action. The PDF Viewer displays document bookmarks in the Bookmarks panel of the Navigation pane.

Navigate to a Bookmark

Code

Call the PdfViewerControl.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. Call the Dispatcher.BeginInvoke method to use the GoToBookmark method in the PdfViewerControl.DocumentLoaded event handler.

C#

private void PdfViewer_DocumentLoaded(object sender, RoutedEventArgs e) {
    foreach (var bookmarkItem in pdfViewer.Bookmarks) {
        if (bookmarkItem.Title == "Annotations")
            Dispatcher.BeginInvoke(new Action(() => pdfViewer.GoToBookmark(bookmarkItem)), DispatcherPriority.ApplicationIdle);
    }
}

VB.NET

Private Sub PdfViewer_DocumentLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    For Each bookmarkItem In pdfViewer.Bookmarks
        If bookmarkItem.Title = "Annotations" Then
            Dispatcher.BeginInvoke(New Action(Sub() pdfViewer.GoToBookmark(bookmarkItem)), DispatcherPriority.ApplicationIdle)
        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#

using DevExpress.Pdf;

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

}

VB.NET

Imports DevExpress.Pdf

Private Sub PdfViewer_DocumentLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    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 PdfViewerControl.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#

using DevExpress.Xpf.Core;
using System.Linq;
//...
pdfViewer.DocumentLoaded += pdfViewer_DocumentLoaded;

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

VB.NET

Imports DevExpress.Xpf.Core
Imports System.Linq
'...
Private pdfViewer.DocumentLoaded += AddressOf pdfViewer_DocumentLoaded

Private Sub pdfViewer_DocumentLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    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 PdfOutlinesViewerSettings class properties to change display settings for the Bookmarks panel. The following settings are available:

HideOutlinesViewer

Gets or sets whether to hide the Bookmarks panel. This is a dependency property.

NavigationPanelsLayout

Gets or sets the layout of the navigation panels. This is a dependency property.

HideAfterUse

Gets or sets a value that specifies whether the Document Map should be hidden after using it for navigation purposes. This is a dependency property.

WrapLongLines

Gets or sets a value that specifies whether long lines should be wrapped in the Document Map. This is a dependency property.

ApplyOutlinesForeground

Specifies whether to use document foreground colors for the outline node text in the Bookmarks panel.

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

XAML

<dxpdf:PdfViewerControl x:Name="pdfViewer" NavigationPanelsLayout="DockPanel">
    <dxpdf:PdfViewerControl.OutlinesViewerSettings>
        <dxpdf:PdfOutlinesViewerSettings ApplyOutlinesForeground="True" 
                                         HideAfterUse="True" 
                                         WrapLongLines="True"/>
    </dxpdf:PdfViewerControl.OutlinesViewerSettings>
</dxpdf:PdfViewerControl>     

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

You can change the outlines viewer visible state for the PDF Viewer using the OutlinesViewerState (specifies the current visible state of the panel) and OutlinesViewerInitialState (specifies the panel visibility behavior after loading new PDF document) properties. These properties can be set to one of the following values.

• Expanded – the panel is expanded
• Collapsed – the panel is collapsed
• Visible – the panel is visible

Note

If a PDF document does not have bookmarks, the outlines viewer is hidden (the PdfOutlinesViewerSettings.HideOutlinesViewer property is set to true).

The OutlinesViewerInitialState property also has the additional Null value (the Default mode). In this mode, the OutlinesViewerState property is set either to Visible (if a PDF document contains bookmarks) or Collapsed (if a PDF document does contain them).