Documents

The fundamental building block for a PDF is the document itself. The document is typically stored on disk as a file.

Documents support versioning and can be tagged with metadata such as the author, creation date, and so on.

A document can be encrypted, requiring a password to view it. Two levels of encryption exist:

• User level encryption: If the user successfully obtains user-level permissions, they can view the document but may be restricted from printing or copying the document.

• Owner-level encryption: A user who obtains owner-level permissions can view the document and has full usage permissions.

Many encrypted PDF documents have a “dummy” user password which is the empty string. Most PDF document parsers (including PDF Kit) automatically try the empty string password on encrypted documents, and if successful, simply display the document. Therefore, a document that is technically encrypted may not necessarily prompt the user for a password.

Pages

A PDF document consists of a number of pages. These are the metaphorical equivalent of pages in a physical book, and they are what the user sees onscreen. However, unlike a physical page, PDF pages can contain hyperlinks and annotations. Pages can support cropping as well, which can be useful if you want to hide extraneous portions (such as registration marks) during display.

Note that most objects on a page are specified in page space, rather than view space. That is, the coordinate system is in points (72 points per inch), with the origin at the bottom left of the page, not the view. Page space doesn’t care about zooming, display mode, and so on. An item that has bounds of, say 32 points square, retains those bounds regardless of display size. Figure 1-1 compares the two coordinate systems:

The PDFView class contains a number of conversion methods to translate coordinates from view space to page space and vice versa.

Outlines

An outline is like an interactive table of contents, showing the chapter or structure hierarchy of the document. Outlines make it easy for users to see the structure of a document and to jump to a particular location.

Not all PDF documents contain an outline.

Annotations

Annotations are “extra” elements that can appear on a PDF page in addition to the standard text and images. Some annotations merely add visual features, such as lines, circles, and such, while others can have some interactive behavior.

Some examples of annotations include:

• “Sticky notes” displaying text.

• Note icons that can display text when clicked upon.

• Editable text fields that can accept user text.

• Buttons, such as checkboxes. Such annotations, along with editable text fields, may be useful in forms to be filled out by the user.

• Circles, arbitrary lines, and boxes.

• Links to other documents, or to other sections within a document.

• Highlighting, strike-throughs, and other text markups.

Figure 1-3 shows some annotation types available in PDF Kit.

These are the annotations that PDF Kit supports and can display in documents. However, PDF Kit can also support additional annotation types if they are specified using appearance streams. Appearance streams let you draw based on a drawing sequence rather than a specification based on a particular annotation type. For example, rather than specify “a circle annotation with a 20 point radius,” an appearance stream would simply contain instructions for drawing a circle of that size.

Annotations often have content associated with them that your application can display. For example, text annotations typically appear as an icon in the PDF; when the user clicks on it, a window can open displaying its text.

Note that PDF Kit does not supply a mechanism for displaying the annotation content; your application must create a window to display the content when the user clicks on an annotation.

Selections

PDF documents let the user select blocks of text, much like word processing applications. However, they offer greater flexibility in that text selections do not have to be linearly contiguous. For example, using PDF Kit, you could select a block of text within a page that doesn’t have to be sequential, as shown in Figure 1-4 Such selections can be useful if the document contains multicolumn pages, tables, or other unusual formatting.

You can experiment with block selection by holding down the Option key while selecting text in Preview (in OS X v10.4 and later).

Selections are stored as selection objects, which also store additional data such as the page or pages containing the selection. This information is useful when presenting multiple selections to the user (for example, a list of search results).

The PDFView Class

The PDFView class, like the Web Kit WebView class, derives from the Application Kit NSView class. You can use a PDFView object directly in your application simply by placing it in a window using Interface Builder. Get the palette from /Developer/Extras/Palettes/PDFKit.palette.

PDFView may be the only PDF Kit class that you need to deal with. It lets you display PDF data in your application and allows users to select content and navigate through a document, set the zoom level, and copy textual content to the Pasteboard. Users can also drag-and-drop documents into PDFView.

PDFView calls upon the PDF utility classes to implement much of its functionality. If you want to add special features, you need to use or subclass from the utility classes.

PDF Kit Utility Classes

The PDF Kit utility classes offer a mix of Foundation-like and Application Kit-like behavior. They are analogous to the NSString class, and its NSString Additions methods, in that many of them support drawing. These classes are subclasses of NSObject, as shown in Figure 1-5.