Bookmarks and Destinations in the PDF Viewer for WPF
- 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.
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);
}
}
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:
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);
}
}
#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:
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);
}
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:
<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 Pdf
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).