Using the Library

Working with XpdfViewer

The XpdfViewer library uses an opaque handle (type PDFViewerHandle) to represent a viewer object. An application can use multiple XpdfViewer objects (multiple PDFViewerHandles), each attached to a different window.

Any program that uses the library must include the XpdfViewer header file:

#include "XpdfViewer.h"

Typical code to create an XpdfViewer object and attach it to a window looks like this:

HWND viewerWnd; PDFViewerHandle viewer; /* create a window */ viewerWnd = CreateWindow("static", ...); /* create an XpdfViewer object, attached to the window */ if (pdfCreateViewer(&viewer, viewerWnd) != pdfOk) { /* error ... */ }

Key bindings

The XpdfViewer library automatically handles a few simple key bindings (when the viewer's window has the keyboard focus):

the arrow keys scroll the document (16 pixels per click) in all four directions
the Page Up key scrolls the document up by one screenful, i.e., the current height of the window, which may be less than a whole PDF page
the Page Down key and space key both scroll down by one screenful

Using XpdfViewer in a multithreaded application

In a multithreaded application, the pdfInitLibrary function must be called before any other functions are called. Unlike in single-thread applications where this is optional, the pdfInitLibrary call is required in multithreaded applications. Each PDF viewer handle must be used by only one thread. Given that constraint, all XpdfViewer functions (other than pdfInitLibrary) are thread-safe.

Compiling & linking on Windows

The XpdfViewer library is supplied as a DLL (XpdfViewer.dll) and an import library (XpdfViewer.lib).

The following instructions are for Microsoft Visual C++ 6. Similar steps should work for other development environments.

Add the include file directory: in the "Project Settings" dialog, under the "C/C++" tab, in the "Preprocessor" category, add the library include file directory (....\XpdfViewer\include).
Add the import library: in the "Project Settings" dialog, under the "Link" tab, in the "General" category, add the library (....\XpdfViewer\lib\XpdfViewer.lib).
Either add the library directory (....\XpdfViewer\lib) to your executable search path, or copy XpdfViewer.dll into the same directory as your application's executable.

Static library

XpdfViewer includes a static library as well as the dynamic library. To use it, include XpdfViewerStatic.h in place of XpdfViewer.h, and link to XpdfViewerStatic.lib.

Example code

The XpdfViewer library distribution includes two sample programs, viewer and highlight, located in the examples directory. These programs demonstrate the use of the various XpdfViewer functions. To build them on Windows, follow the instructions above.

The viewer program (viewer.c) demonstrates attaching an XpdfViewer to a window. It provides a minimal user interface which can load a PDF file (test.pdf) in the current directory, move to the next and previous pages, extract text from the current selection, and print.

The highlight program (highlight.c) makes use of XpdfViewer's highlighted region feature. It allows the user to highlight a set of regions and then extract them all to one text file.