Paragraph 12.3 of the PDF specification describes available document-level navigation objects that can be used inside the PDF file to allow quick jumps between articles, paragraphs, or sections of the document. These objects may or may not be present in PDF file, and handling them requires a right tool.
The core object that handles all navigation tasks is DocumentNavigatorclass, it can be obtained by using the Navigatorproperty of the created Documentobject:
[C#]
Document pdfDocument = newDocument(inputStream);
DocumentNavigator navigator = pdfDocument.Navigator;
Using this navigator object you may navigate between pages of the document by passing page objects, bookmarks, links and search results - objects defined or found in PDF document. When navigation occurs, the navigator’s CurrentPageproperty contains the page that passed object refers to. So it’s becomes easier to track and render the “current page” instead of implementing own navigation mechanism.
It’s also possible to navigate back and forward using corresponding member functions, and because the navigator class also raises a Navigatedevent it’s easy to handle and reflect the current page change. It might be extremely useful for custom viewers, thus we used it a lot in our viewer app for Windows Phone as well as in our free Windows Forms PDF Viewer control.
The code below demonstrates simple navigation and corresponding event handling task for the PDF document:1
- We load a PDF document first into a class-level field
- Subscribe to navigator’s Navigated event
- Now we can call MoveForward member from anywhere and handle the navigation in our DocumentNavigationHandler
[C#]
publicvoid LoadDocument(string pathToPdfFile)
{
using (FileStream inputStream = newFileStream(pathToPdfFile, FileMode.Open))
{
// this object represents a PDF document
pdfDocument = newDocument(inputStream);
// subscribe to Navigator's events
pdfDocument.Navigator.Navigated += DocumentNavigationHandler;
}
}
privatevoidDocumentNavigationHandler(object sender, NavigatedEventArgs eventargs)
{
// get the navigator and print current page index
DocumentNavigator navigator = (DocumentNavigator)sender;
Console.WriteLine(string.Format("Navigated to page: {0}", navigator.CurrentIndex));
}
publicvoid MoveForward(Document pdfDocument)
{
// just move forward
if (pdfDocument != null)
{
pdfDocument.Navigator.MoveForward();
}
}
Handling PDF bookmarks
A nice wpf viewer sample post describes in details how to work with bookmarks in PDF file, but in short - if you want to enumerate document’s bookmarks just use its Bookmarksproperty. Every Bookmarkobject then can be navigated using document navigator by using its GoToBookmarkmethod.
[C#]
publicvoidGoToFirstBookmark()
{
// navigate to first bookmark in bookmarks collection
pdfDocument.Navigator.GoToBookmark(pdfDocument.Bookmarks.Children[0]);
}
Handling PDF search results
In our previous blogpost we showed how to use classes from Apitron.PDF.Rasterizer.Searchnamespace to perform search tasks for PDF documents. That sample just saved found pages to bitmaps, but what if you want to navigate within a document using the search results?
It’s dead simple. Just use the GoToSearchResultmember of the document navigator and pass the SearchResultItemthat you’ve got by doing the search. See the code below.
[C#]
privatevoid DoSearch(SearchIndex pdfSearchIndex)
{
// just invoke the search and pass our search handler
pdfSearchIndex.Search(MyPDFSearchHandler, "apitron");
}
privatevoidMyPDFSearchHandler(SearchHandlerArgshandlerArgs)
{
// navigate to first found item in our pdf document
if(handlerArgs.ResultItems.Count > 0)
{
pdfDocument.Navigator.GoToSearchResult(handlerArgs.ResultItems[0]);
// indicate that search should be stopped
handlerArgs.CancelSearch = true;
}
}
Supported platforms
The API described works on all supported platforms, including Android and iOS (using Xamarin), Windows Phone, WinRT. You can read more about the Apitron.PDF.Rasterizer for .NET component here.