PDFDocument Class Reference

Inherits from
Conforms to
Framework
Library/Frameworks/Quartz.framework/Frameworks/PDFKit.framework
Availability
Available in OS X v10.4 and later.
Declared in
PDFDocument.h
Related sample code

Overview

A PDFDocument object represents PDF data or a PDF file and defines methods for writing, searching, and selecting PDF data.

The other utility classes are either instantiated from methods in PDFDocument, as are PDFPage and PDFOutline; or support it, as do PDFSelection and PDFDestination.

You initialize a PDFDocument object with PDF data or with a URL to a PDF file. You can then ask for the page count, add or delete pages, perform a find, or parse selected content into an NSString object.

Tasks

Initializing Documents

Accessing Document Information

Managing Document Security

Writing Out the PDF Data

Working with Pages

Managing Find Operations

Working with Selections

Setting the Delegate

Searching Documents

Unlocking Documents

Determining the Page Class

Instance Methods

allowsCopying

Returns a Boolean value indicating whether the document allows copying of content to the Pasteboard.

- (BOOL)allowsCopying
Discussion

The ability to copy content from a PDF document is an attribute unrelated to whether the document is locked or unlocked. It depends on the PDF permissions set by the document’s author.

This method only determines the desired permissions setting in the PDF document; it is up to the application to enforce (or ignore) the permissions.

This method always returns YES if the document is not encrypted. Note that in many cases an encrypted document may still be readable by all users due to the standard empty string password. For more details about user and owner passwords, see the Adobe PDF specification.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

allowsPrinting

Returns a Boolean value indicating whether the document allows printing.

- (BOOL)allowsPrinting
Discussion

The ability to print a PDF document is an attribute unrelated to whether the document is locked or unlocked. It depends on the PDF permissions set by the document’s author.

This method only determines the desired permissions setting in the PDF document; it is up to the application to enforce (or ignore) the permissions.

This method always returns YES if the document is not encrypted. Note that in many cases an encrypted document may still be readable by all users due to the standard empty string password. For more details about user and owner passwords, see the Adobe PDF specification.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

beginFindString:withOptions:

Asynchronously finds all instances of the specified string in the document.

- (void)beginFindString:(NSString *)string withOptions:(int)options
Discussion

This method returns immediately. It causes notifications to be issued when searching begins and ends, on each search hit, and when the search proceeds to a new page. For options, refer to Searching and Comparing Strings.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

beginFindStrings:withOptions:

Asynchronously finds all instances of the specified array of strings in the document.

- (void)beginFindStrings:(NSArray *)strings withOptions:(int)options;
Discussion

This method returns immediately. It causes notifications to be issued when searching begins and ends, on each search hit, and when the search proceeds to a new page. For options, refer to Searching and Comparing Strings.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
PDFDocument.h

cancelFindString

Cancels a search initiated with beginFindString:withOptions:.

- (void)cancelFindString
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

dataRepresentation

Returns a representation of the document as an NSData object.

- (NSData *)dataRepresentation
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

delegate

Returns the object acting as the delegate for the PDFDocument object.

- (id)delegate
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

documentAttributes

Returns a dictionary of document metadata.

- (NSDictionary *)documentAttributes
Return Value

The dictionary of document metadata. The dictionary may be empty, or only some of the keys may have associated values. See “Constants” for a list of possible key words.

Discussion

Metadata is optional for PDF documents.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

documentURL

Returns the URL for the document.

- (NSURL *)documentURL
Return Value

The URL for the document; may return NULL if the document was created from an NSData object.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

exchangePageAtIndex:withPageAtIndex:

Swaps one page with another.

- (void)exchangePageAtIndex:(NSUInteger)indexA withPageAtIndex:(NSUInteger)indexB
Discussion

This method raises an exception if either index value is out of bounds.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

findString:fromSelection:withOptions:

Synchronously finds the next occurance of a string after the specified selection (or before the selection if you specified NSBackwardsSearch as a search option.

- (PDFSelection *)findString:(NSString *)string fromSelection:(PDFSelection *)selection withOptions:(int)options
Discussion

Matches are returned as a PDFSelection object. If the search reaches the end (or beginning) of the document without any hits, this method returns NULL.

If you pass NULL for the selection, this method begins searching from the beginning of the document (or the end, if you specified NSBackwardsSearch).

You can use this method to implement “Find Again” behavior. For options, refer to Searching and Comparing Strings.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

findString:withOptions:

Synchronously finds all instances of the specified string in the document.

- (NSArray *)findString:(NSString *)string withOptions:(int)options
Discussion

Each hit gets added to an NSArray object as a PDFSelection object. If there are no hits, this method returns an empty array.

Use this method when the complete search process will be brief and when you don’t need the flexibility or control offered by beginFindString:withOptions:. For options, refer to Searching and Comparing Strings.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

indexForPage:

Gets the index number for the specified page.

- (NSUInteger)indexForPage:(PDFPage *)page
Discussion

Indexes are zero-based. This method raises an exception and returns NSNotFound if page is not found.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
PDFDocument.h

initWithData:

Initializes a PDFDocument object with the passed-in data.

- (id)initWithData:(NSData *)data
Return Value

A PDFDocument instance initialized with the passed-in PDF data, or NULL if the object could not be initialized.

Discussion

The data must be PDF data encapsulated in an NSData object; otherwise this method returns NULL.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

initWithURL:

Initializes a PDFDocument object with the contents at the specified URL (if the URL is invalid, this method returns NULL).

- (id)initWithURL:(NSURL *)url
Return Value

A PDFDocument instance initialized with the data at the passed-in URL or NULL if the object could not be initialized or if the URL is invalid.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

insertPage:atIndex:

Inserts a page at the specified index point.

- (void)insertPage:(PDFPage *)page atIndex:(NSUInteger)index
Discussion

This method raises an exception if index is out of bounds.

Be aware that a PDF viewing application might use the size of the first page in the document as representative of all page sizes when reporting the size of a document. If you need to get the actual size of an individual page, you can use boundsForBox: (note that the size is returned in points, which are typically converted to inches or centimeters by PDF viewing applications).

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
PDFDocument.h

isEncrypted

Returns a Boolean value specifying whether the document is encrypted.

- (BOOL)isEncrypted
Return Value

YES if the document is encrypted, whether it is locked or unlocked; NO otherwise.

Discussion

If encrypted, reading the document requires a password.

Encrypted documents whose password is the empty string are unlocked automatically upon opening, because PDF Kit tries the empty string as a password if none is supplied. Use the unlockWithPassword: method to unlock a document using a password.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

isFinding

Returns a Boolean value indicating whether an asynchronous find operation is in progress.

- (BOOL)isFinding
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

isLocked

Returns a Boolean value indicating whether the document is locked.

- (BOOL)isLocked
Return Value

YES if the document is locked; NO otherwise.

Discussion

Only encrypted documents can be locked. Encrypted documents whose password is the empty string are unlocked automatically upon opening, because PDF Kit tries the empty string as a password if none is supplied. Use the unlockWithPassword: method to unlock a document using a password.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

majorVersion

Returns the major version of the document.

- (int)majorVersion
Return Value

The major version of the document.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

minorVersion

Returns the minor version of the document.

- (int)minorVersion
Return Value

The minor version of the document.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

outlineItemForSelection:

Returns the most likely parent PDF outline object for the selection.

- (PDFOutline *)outlineItemForSelection:(PDFSelection *)selection
Parameters
selection

The area of the document currently selected by the user. A selection can span multiple outline items, but only the point representing the first character is considered.

Return Value

The PDF outline object that is the most likely parent of the specified selection. Note that only the point representing the first character of the selection is considered in this method.

Discussion

Typically, outlines represent structural items such as chapters. You can use this method to identify the chapter that a selection falls within.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

outlineRoot

Returns the root PDF outline object for the document.

- (PDFOutline *)outlineRoot
Return Value

The root outline object or NULL if there is no root outline object. The root outline is the nonvisible top-level container for outline items.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.h

pageAtIndex:

Returns the page at the specified index number.

- (PDFPage *)pageAtIndex:(NSUInteger)index
Discussion

Indexes are zero based. This method raises an exception if index is out of bounds.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
PDFDocument.h

pageClass

Returns the class that is allocated and initialized when page objects are created for the document.

- (Class)pageClass
Discussion

If you want to supply a custom page class, subclass PDFDocument and implement this method to return your custom class. Note that your custom class must be a subclass of PDFPage; otherwise, the behavior is undefined.

The default implementation of pageClass returns [PDFPage class].

Availability
  • Available in OS X v10.5 and later.
Declared In
PDFDocument.h

pageCount

Returns the number of pages in the document.

- (NSUInteger)pageCount
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

removePageAtIndex:

Removes the page at the specified index point.

- (void)removePageAtIndex:(NSUInteger)index
Discussion

This method raises an exception if index is out of bounds.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

selectionForEntireDocument

Returns a selection representing the textual content of the entire document.

- (PDFSelection *)selectionForEntireDocument
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

selectionFromPage:atCharacterIndex:toPage:atCharacterIndex:

Returns the specified selection based on starting and ending character indexes.

- (PDFSelection *)selectionFromPage:(PDFPage *)startPage atCharacterIndex:(NSUInteger)startChar toPage:(PDFPage *)endPage atCharacterIndex:(NSUInteger)endChar
Discussion

The selection begins at startChar on startPage and ends at endChar on endPage. The starting and ending index values must be in the range of the number of characters (as returned by numberOfCharacters) within the respective PDFPage objects.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

selectionFromPage:atPoint:toPage:atPoint:

Returns the specified selection based on starting and ending points.

- (PDFSelection *)selectionFromPage:(PDFPage *)startPage atPoint:(NSPoint)startPt toPage:(PDFPage *)endPage atPoint:(NSPoint)endPt
Discussion

The selection begins at startPt on startPage and ends at endPt on endPage. The starting and ending points should be specified in page space, relative to their respective pages.

The starting and ending points can be on the same page. In this case, invoking this method is equivalent to sending the selectionFromPoint:toPoint: message to a PDFPage object.

Page space is a 72 dpi coordinate system with the origin at the lower-left corner of the current page.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

setDelegate:

Establishes the specified object as the delegate for the PDFDocument object.

- (void)setDelegate:(id)anObject
Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
PDFDocument.h

setDocumentAttributes:

Sets the document attributes.

- (void)setDocumentAttributes:(NSDictionary *)attributes
Parameters
attributes

A dictionary containing document attributes as key-value pairs. See “Constants” for a list of possible key words.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

setOutlineRoot:

Sets the document’s root outline to a PDF outline object.

- (void)setOutlineRoot:(PDFOutline *)outline
Parameters
outline

The outline to be used as the document’s root outline. Pass NULL to strip the outline from a document.

Discussion

When a PDF document is saved, the outline tree structure is written out to the destination PDF file.

Availability
  • Available in OS X v10.5 and later.
See Also
  • – outlineRoot
Declared In
PDFDocument.h

string

Returns a string representing the textual content for the entire document.

- (NSString *)string
Return Value

A string that represents the textual content of the entire document.

Discussion

Pages are delimited with linefeed characters.

This is a convenience method, equivalent to creating a selection object for the entire document and then invoking the PDFSelection class’s string method.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

unlockWithPassword:

Attempts to unlock an encrypted document.

- (BOOL)unlockWithPassword:(NSString *)password
Parameters
password

The password to unlock an encrypted document (you cannot lock an unlocked PDF document by using an incorrect password).

Return Value

YES if the specified password unlocks the document, NO otherwise.

Discussion

If the password is correct, this method returns YES, and a PDFDocumentDidUnlockNotification notification is sent. Once unlocked, you cannot use this function to relock the document.

If you attempt to unlock an already unlocked document, one of the following occurs:

  • If the document is unlocked with full owner permissions, unlockWithPassword does nothing and returns YES. The password string is ignored.

  • If the document is unlocked with only user permissions, unlockWithPassword attempts to obtain full owner permissions with the password string. If the string fails, the document maintains its user permissions. In either case, this method returns YES.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

writeToFile:

Writes the document to a file at the specified path.

- (BOOL)writeToFile:(NSString *)path
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

writeToFile:withOptions:

Writes the document to a file at the specified path with the specified options.

- (BOOL)writeToFile:(NSString *)path withOptions:(NSDictionary *)options
Discussion

The most commonly-used options are kCGPDFContextOwnerPassword, kCGPDFContextUserPassword, kCGPDFContextAllowsCopying and kCGPDFContextAllowsPrinting. For more details about these options, see the “Auxiliary Dictionary Keys” in CGPDFContext Reference, part of the Quartz 2D Reference.

Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

writeToURL:

Writes the document to a location specified by the passed-in URL.

- (BOOL)writeToURL:(NSURL *)url
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

writeToURL:withOptions:

Writes the document to the specified URL with the specified options.

- (BOOL)writeToURL:(NSURL *)url withOptions:(NSDictionary *)options
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

Delegate Methods

didMatchString:

Called for every match found during a find operation.

- (void)didMatchString:(PDFSelection *)instance
Availability
  • Available in OS X v10.4 and later.
Declared In
PDFDocument.h

documentDidBeginDocumentFind:

Called when the PDFDocumentDidBeginFindNotification notification is posted.

- (void)documentDidBeginDocumentFind:(NSNotification *)notification
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.h

documentDidBeginPageFind:

Called when the PDFDocumentDidBeginPageFindNotification notification is posted.

- (void)documentDidBeginPageFind:(NSNotification *)notification
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.h

documentDidEndDocumentFind:

Called when the PDFDocumentDidEndFindNotification notification is posted.

- (void)documentDidEndDocumentFind:(NSNotification *)notification
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.h

documentDidEndPageFind:

Called when the PDFDocumentDidEndPageFindNotification notification is posted.

- (void)documentDidEndPageFind:(NSNotification *)notification
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.h

documentDidFindMatch:

Called when the PDFDocumentDidFindMatchNotification notification is posted.

- (void)documentDidFindMatch:(NSNotification *)notification
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.h

documentDidUnlock:

Called when the PDFDocumentDidUnlockNotification notification is posted.

- (void)documentDidUnlock:(NSNotification *)notification
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.h

Constants

PDFPrintScalingMode

The type of scaling to be used when printing a page (see “PDF Page Scaling Modes for Printing”).

typedef NSInteger PDFPrintScalingMode;
Availability
  • Available in OS X v10.5 and later.
Declared In
PDFDocument.h

Document Attribute Keys

Keys for the document attributes dictionary. See documentAttributes and setDocumentAttributes:.

extern NSString *PDFDocumentTitleAttribute;
extern NSString *PDFDocumentAuthorAttribute;
extern NSString *PDFDocumentSubjectAttribute;
extern NSString *PDFDocumentCreatorAttribute;
extern NSString *PDFDocumentProducerAttribute;
extern NSString *PDFDocumentCreationDateAttribute;
extern NSString *PDFDocumentModificationDateAttribute;
extern NSString *PDFDocumentKeywordsAttribute;
Constants
PDFDocumentTitleAttribute

An optional text string (an NSString) containing the title of the document.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

PDFDocumentAuthorAttribute

An optional text string (an NSString) containing the name of the author of the document.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

PDFDocumentSubjectAttribute

An optional text string (an NSString) containing a description of the subject of the document.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

PDFDocumentCreatorAttribute

An optional text string (an NSString) containing the name of the application that created the document content.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

PDFDocumentProducerAttribute

An optional text string (an NSString) containing the name of the application that produced the PDF data for the document.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

PDFDocumentCreationDateAttribute

An optional text string (an NSDate) containing the document’s creation date.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

PDFDocumentModificationDateAttribute

An optional text string (an NSDate) containing the document’s last-modified date.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

PDFDocumentKeywordsAttribute

An optional array of text strings (an NSArray of NSString objects) containing keywords for the document.

Available in OS X v10.4 and later.

Declared in PDFDocument.h.

Declared In
PDFDocument.h

PDF Page Scaling Modes for Printing

Modes that specify how the page should be scaled when printing. See the PDFView method printWithInfo:autoRotate:pageScaling:.

enum { kPDFPrintPageScaleNone = 0,
   kPDFPrintPageScaleToFit = 1,
   kPDFPrintPageScaleDownToFit = 2 };
Constants
kPDFPrintPageScaleNone

Do not apply scaling to the page when printing.

Available in OS X v10.5 and later.

Declared in PDFDocument.h.

kPDFPrintPageScaleToFit

Scale each page up or down to best fit the paper size.

Available in OS X v10.5 and later.

Declared in PDFDocument.h.

kPDFPrintPageScaleDownToFit

Scale large pages down to fit the paper size (smaller pages do not get scaled up).

Available in OS X v10.5 and later.

Declared in PDFDocument.h.

Declared In
PDFDocument.h

Notifications

PDFDocument declares and posts the following notifications:

PDFDocumentDidUnlockNotification

Posted when a document unlocks after a unlockWithPassword: message.

The notification object is the PDFDocument object itself.

Availability
Declared In
PDFDocument.h

PDFDocumentDidBeginFindNotification

Posted when the beginFindString:withOptions: or findString:withOptions: method begins finding.

The notification object is the PDFDocument object itself.

Availability
Declared In
PDFDocument.h

PDFDocumentDidEndFindNotification

Posted when the beginFindString:withOptions: or findString:withOptions: method returns.

The beginFindString:withOptions: method returns immediately, so this notification is posted when the “find” operation is finished.

You can use this notification to know when to close or hide a progress bar.

The notification object is the PDFDocument object itself.

Availability
Declared In
PDFDocument.h

PDFDocumentDidBeginPageFindNotification

Posted each time a find operation begins working on a new page of a document.

You can use this notification to update a progress bar.

The notification object is the PDFDocument object itself. To determine the page, use the @"PDFDocumentPageIndex" key to obtain userinfo of type NSNumber.

Availability
Declared In
PDFDocument.h

PDFDocumentDidEndPageFindNotification

Posted each time a find operation finishes working on a page in a document.

You can use this notification to update a progress bar.

The notification object is the PDFDocument object itself. To determine the page, use the @"PDFDocumentPageIndex" key to obtain userinfo of type NSNumber.

Availability
Declared In
PDFDocument.h

PDFDocumentDidFindMatchNotification

Posted each time a string match is found in a document.

The notification object is the PDFDocument object itself. To determine the string selection found, use the @"PDFDocumentFoundSelection" key to obtain userinfo of type PDFSelection *

Availability
Declared In
PDFDocument.h

PDFDocumentDidBeginWriteNotification

Posted each time a write operation begins working on a document.

The notification object is the PDFDocument object itself.

Availability
Declared In
PDFDocument.h

PDFDocumentDidEndWriteNotification

Posted each time a write operation finishes working on a document.

The notification object is the PDFDocument object itself.

Availability
Declared In
PDFDocument.h

PDFDocumentDidBeginPageWriteNotification

Posted each time a write operation begins working on a page in a document.

The notification object is the PDFDocument object itself. To determine the page, use the @"PDFDocumentPageIndex" key to obtain userinfo of type NSNumber.

Availability
Declared In
PDFDocument.h

PDFDocumentDidEndPageWriteNotification

Posted each time a write operation finishes working on a page in a document.

The notification object is the PDFDocument object itself. To determine the page, use the @"PDFDocumentPageIndex" key to obtain userinfo of type NSNumber.

Availability
Declared In
PDFDocument.h