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 DocumentNavigator
class, it can be obtained by using the Navigator
property of the created Document
object:
[C#]
Document pdfDocument = new Document(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 CurrentPage
property 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 Navigated
event 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#]
public void LoadDocument(string pathToPdfFile)
{
using (FileStream inputStream
= new FileStream(pathToPdfFile,
FileMode.Open))
{
// this object represents a PDF document
pdfDocument = new Document(inputStream);
// subscribe to Navigator's events
pdfDocument.Navigator.Navigated += DocumentNavigationHandler;
}
}
private void
DocumentNavigationHandler(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));
}
public void 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 Bookmarks
property. Every Bookmark
object then can be navigated using document navigator by using its GoToBookmark
method.
[C#]
public void
GoToFirstBookmark()
{
// 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.Search
namespace 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 GoToSearchResult
member of the document navigator and pass the SearchResultItem
that you’ve got by doing the search. See the code below.
[C#]
private void DoSearch(SearchIndex pdfSearchIndex)
{
// just invoke the search and pass our search handler
pdfSearchIndex.Search(MyPDFSearchHandler, "apitron");
}
private void
MyPDFSearchHandler(SearchHandlerArgs
handlerArgs)
{
// 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.
