Most computer users today are familar with the Portable Document Format (PDF) that was created by Adobe, and which has been an integral part of Mac OS X from the start. What makes PDF so successful is that it is a proven technology, the specification is public and platform-independent, and PDF files can be both compact and secure. In short, PDF has become a de facto standard in the world because it makes it easy for users to create, distribute, and view documents.

And now making the PDF document format available in your Cocoa application is easy, with PDF Kit. Available in Mac OS X v10.4 Tiger, PDF Kit allows you to display and manipulate PDF documents in your application without writing a lot of custom file handling code. By implementing aspects of Adobe's PDF specification for you, PDF Kit minimizes development time on your part. Even Apple's own applications such as Safari and Preview use PDF Kit to display PDF content.

This article provides an overview of developing with PDF Kit and the benefits it provides, and helps you get started as quickly as possible.

What makes PDF Kit exciting is not only its ability to display a document in a window, but also the ease with which it lets your application support navigating, annotating, and searching a document. Your application can also display the document outline, if one exists in the PDF file. We will highlight several of these functions in this article, but be sure to investigate the references listed at the end of this article for full treatment of each subject.

What is PDF Kit?

PDF Kit is a Cocoa framework that provides a set of Objective-C classes that allow you to display and manipulate PDF documents. The display of a document relies on the class PDFView, which encapsulates the functionality of a corresponding Interface Builder widget. PDFDocument represents the document itself; it contains functionality for performing initialization, searching, and other basic operations on a document. Other classes encapsulate the functionality of pages, outlines, selections, and annotations. The PDF Kit Reference document, linked at the end of this article, discusses these classes in great detail.

Getting Started

Before you can work with PDF Kit, you need to prepare your toolset. Make sure you have installed latest version of the Xcode tools; they are included in the installation disks that come with Mac OS X v10.4 Tiger, and you can also download Xcode from the Tools Download page. This section walks you through the process of adding PDF Kit to an Xcode Cocoa project. There is also an Interface Builder widget that allows you to include a PDFView object in a container.

Xcode

You need to add PDF Kit to your Cocoa project in order to work with PDFView and other classes. PDF Kit is a sub-framework under the Quartz umbrella framework. Linking in the umbrella framework is easy to do in Xcode. Select the menu item Project > Add to Project..., then locate and select /System/Library/Frameworks/Quartz.framework, and finally, click Add to add the framework to your project. This is illustrated in Figure 1.

Figure 1: Add the Quartz Framework to Your Project

In your project, if you disclose the contents of Quartz.framework, you will find PDFKit.framework, as shown in Figure 2.

Figure 2: The Quartz Umbrella Framework Contains the PDF Kit Sub-Framework

Note: The sample code projects already include Quartz.framework. You should not need to add the framework to PDFKitViewer or PDFKitLinker2.

Interface Builder

The PDF View widget, which you can manipulate in Interface Builder, is contained in a special type of bundle file called a "palette." This section shows you how to easily add the PDF Kit palette to the set of palettes available in Interface Builder.

In Interface Builder, select the menu item Interface Builder > Preferences..., which opens the Interface Builder preferences dialog. Click on the Palettes tab at the top of the dialog, and you will see a list of palettes included or previously imported into Interface Builder, sorted alphabetically by framework and palette name. As you can see in Figure 3, the PDF Kit palette is not included by default under the Cocoa framework. You may have to scroll to view the entire list.

Figure 3: Hmm, No PDF Kit Palette

Still in the Palettes pane, click the Add... button in the lower-right corner. This brings up a file browser that allows you to select a palette. Navigate to /Developer/Extras/Palettes as shown in Figure 4, and select PDFKit.palette. Click the Open button.

Figure 4: Adding the PDF Kit Palette

PDFKit.palette should now be listed in the Interface Builder Palettes pane with the other palettes (see Figure 5). As before, you may need to scroll the list to locate PDFKit.palette.

Figure 5: The Palette List After Adding the PDF Kit Palette

The PDF View widget is now ready for use. And it remains available in Interface Builder for your subsequent projects.

Figure 6: The PDF View Widget Available in Interface Builder

Working With PDFKit

In this section we discuss several features of PDF Kit, with the help of two sample code projects. You may want to set these up first so you can follow along. We use the /Developer/Examples/Quartz/PDFKit/PDFKitViewer project to illustrate the display of a PDF document. If you have installed the Mac OS X v10.4 Developer Tools, this project should be on your system. After that discussion, we use the PDFKitLinker2 sample code project, available for download from ADC, to show how to annotate a document. We conclude with an overview of searching a PDF document.

Display

Display of a PDF document is handled by the PDFView class. The Sample Code project PDFKitViewer allows the user to select and open a PDF file, which is then displayed in a PDFView object. Figure 7 shows the running application.

Figure 7: A PDF document Displayed in PDFKit Viewer

Simply open the Xcode project /Developer/Examples/Quartz/PDFKit/PDFKitViewer/PDFKitViewer.xcode, build the application, then run it. All the functionality to instantiate the PDFView, as well as the menu handling, is included.

As you can see from the screenshot, PDFKitViewer includes several useful features:

• single page or side-by-side page display
• display of a document outline
• a search tool in the drawer

Best of all, the sample code shows you how all this works, so you can include these features in your own application. Figure 8 shows the interface declaration for MyPDFDocument, which does most of the work in PDFKitViewer. Note that MyPDFDocument inherits from NSDocument. Subclassing in this manner is a standard Cocoa paradigm.

Figure 8: MyPDFDocument Functions

As an example of how easy it can be, Listing 1 shows the code that scrolls the document to the selected search result item.

Listing 1: Scrolling the Document to Match the Selected Search Item

- (void) tableViewSelectionDidChange: (NSNotification *) notification
{
	int			rowIndex;
	
	// What was selected.  Skip out if the row has not changed.
	rowIndex = [(NSTableView *)[notification object] selectedRow];
	if (rowIndex >= 0)
	{
		[_pdfView setCurrentSelection: [_searchResults objectAtIndex: rowIndex]];
		[_pdfView centerSelectionInVisibleArea: self];
	}
}

Annotation

Another neat feature of PDF Kit is the ability to annotate documents. To explore this feature, we use PDFKitLinker2. This application allows the user to annotate a PDF document by embedding links. The destination of a link may be another page in the document, or an external URL, as shown in Figure 9.

Figure 9: Annotating with Links

Here are the steps you can follow to try out this feature:

1. Use the popup menu to set the link mode to "Edit Links"; this allows you to change or add a link. We will do the latter. The menu item equivalent is Tools > Edit Links. Later, you will change the mode to "Test Links" to verify your handiwork.
2. Select the text to be linked. In Figure 9, this is the string "Apple Computer, Inc."
3. Select Tools > New Link, or Command-N. This identifies the selected text as the source of a link.
4. Specify the destination of the link. If you select the "URL Link" radio button at the bottom of the window, you can enter a URL to which to link. In Figure 9, this is http://www.apple.com.
5. Change the link mode to "Test Links". Use the mouse to hover the cursor over the text "Apple Computer, Inc."; the cursor should change to a hand, signifying a hyperlink. Clicking on the text should open a browser window that connects to the Apple home page.

The Destination Link radio button allows you to link text to a specific page within the document. You can use this feature to build, for instance, a navigable table of contents within a PDF document. Briefly, the steps are:

1. Use the popup menu to set the link mode to "Edit Links".
2. Select the text to be linked.
3. Select Tools > New Link, or Command-N.
4. Scroll to the desired destination within the document. Don't select any text or anything, just position the page in the window. The part of the document at the top-left of the window will serve as the destination.
5. Click the Set Destination... button at the bottom of the window.
6. Change the link mode to "Test Links". Click the text you specified in step 2 for the link, and the document should jump to the page you selected in step 5.

You will find the implementation of the link handling methods in the class MyWindowController.m. Listing 2 shows the declarations for these methods from MyWindowController.h.

Listing 2: Link Management Method Declarations From MyWindowController.h

// -------- link methods
- (void) newActiveAnnotation: (NSNotification *) notification;
- (void) updateLinkTools;
- (void) linkTypeMatrixHit: (id) sender;
- (void) linkURLEntered: (id) sender;
- (void) linkSetDestinationHit: (id) sender;

Search

In the PDFKitView example we saw how to navigate within a document from a selected search result. But how do you perform the search?

PDF Kit supports two methods of searching within a document. The first is string-by-string searching, which follows the Find/Find Again model. Call PDFDocument:findString:fromSelection:withOptions to perform the search. The options include case-sensitivity, direction, and so on. To display the selection returned, you can call the PDFView method setCurrentSelection, which highlights the selection, followed by scrollSelectionToVisible.

The second type of search creates a list of all occurrences of the string within the document. For an asynchronous search, your application receives notifications during the search, allowing you to update a progress indicator, show partial results, and so on.

Both of these search methods are treated in-depth in the PDF Kit Programming Guide, which is linked at the end of this article. The sample code projects also contain methods that implement search functionality.

For More Information

Using the techniques discussed in this article, you can add PDF support to your Cocoa application. The ADC Reference Library documents below will help you find more specific information.

• PDF Kit Programming Guide
• PDF Kit Reference
• PDFKitLinker2 sample code

In addition to the reference documents, check out WWDC 2005 Conference Session 213, "Harnessing the Power of PDF" (available to registered ADC members). You will need to log in to your online ADC account, and then navigate to the section labelled WWDC Sessions to view the session movie and download the slides.

Posted: 2006-2-20