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 |
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
-
– documentURL -
– majorVersion -
– minorVersion -
– string -
– outlineItemForSelection: -
– outlineRoot -
– documentAttributes -
– setDocumentAttributes: -
– setOutlineRoot:
Managing Document Security
Writing Out the PDF Data
-
– dataRepresentation -
– writeToFile: -
– writeToFile:withOptions: -
– writeToURL: -
– writeToURL:withOptions:
Working with Pages
-
– pageCount -
– pageAtIndex: -
– indexForPage: -
– insertPage:atIndex: -
– removePageAtIndex: -
– exchangePageAtIndex:withPageAtIndex:
Managing Find Operations
-
– findString:withOptions: -
– beginFindString:withOptions: -
– beginFindStrings:withOptions: -
– findString:fromSelection:withOptions: -
– isFinding -
– cancelFindString
Working with Selections
-
– selectionFromPage:atCharacterIndex:toPage:atCharacterIndex: -
– selectionFromPage:atPoint:toPage:atPoint: -
– selectionForEntireDocument
Setting the Delegate
Searching Documents
-
– didMatchString:delegate method -
– documentDidBeginDocumentFind:delegate method -
– documentDidBeginPageFind:delegate method -
– documentDidEndDocumentFind:delegate method -
– documentDidEndPageFind:delegate method -
– documentDidFindMatch:delegate method
Unlocking Documents
-
– documentDidUnlock:delegate method
Determining the Page Class
Instance Methods
allowsCopying
Returns a Boolean value indicating whether the document allows copying of content to the Pasteboard.
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.hallowsPrinting
Returns a Boolean value indicating whether the document allows printing.
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.hbeginFindString:withOptions:
Asynchronously finds all instances of the specified string in the document.
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.hbeginFindStrings:withOptions:
Asynchronously finds all instances of the specified array of strings in the document.
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
-
– beginFindString:withOptions: -
– findString:withOptions: -
– isFinding -
– cancelFindString
Declared In
PDFDocument.hcancelFindString
Cancels a search initiated with beginFindString:withOptions:.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hdataRepresentation
Returns a representation of the document as an NSData object.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.hdelegate
Returns the object acting as the delegate for the PDFDocument object.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.hdocumentAttributes
Returns a dictionary of document metadata.
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.
See Also
Declared In
PDFDocument.hdocumentURL
Returns the URL for the document.
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.hexchangePageAtIndex:withPageAtIndex:
Swaps one page with another.
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.hfindString: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.
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.
See Also
Declared In
PDFDocument.hfindString:withOptions:
Synchronously finds all instances of the specified string in the document.
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.hindexForPage:
Gets the index number for the specified 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.
See Also
Declared In
PDFDocument.hinitWithData:
Initializes a PDFDocument object with the passed-in 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.
See Also
Declared In
PDFDocument.hinitWithURL:
Initializes a PDFDocument object with the contents at the specified URL (if the URL is invalid, this method returns NULL).
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.
See Also
Declared In
PDFDocument.hinsertPage:atIndex:
Inserts a page at the specified index point.
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.
See Also
Declared In
PDFDocument.hisEncrypted
Returns a Boolean value specifying whether the document is encrypted.
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.hisFinding
Returns a Boolean value indicating whether an asynchronous find operation is in progress.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hisLocked
Returns a Boolean value indicating whether the document is locked.
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.hmajorVersion
Returns the major version of the document.
Return Value
The major version of the document.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.hminorVersion
Returns the minor version of the document.
Return Value
The minor version of the document.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.houtlineItemForSelection:
Returns the most likely parent PDF outline object for the 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.
See Also
Declared In
PDFDocument.houtlineRoot
Returns the root PDF outline object for the document.
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
-
– outlineItemForSelection: -
– setOutlineRoot:
Declared In
PDFDocument.hpageAtIndex:
Returns the page at the specified index number.
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.
See Also
Declared In
PDFDocument.hpageClass
Returns the class that is allocated and initialized when page objects are created for the document.
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.hpageCount
Returns the number of pages in the document.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.hremovePageAtIndex:
Removes the page at the specified index point.
Discussion
This method raises an exception if index is out of bounds.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.hselectionForEntireDocument
Returns a selection representing the textual content of the entire document.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hselectionFromPage:atCharacterIndex:toPage:atCharacterIndex:
Returns the specified selection based on starting and ending character indexes.
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.hselectionFromPage:atPoint:toPage:atPoint:
Returns the specified selection based on starting and ending points.
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.hsetDelegate:
Establishes the specified object as the delegate for the PDFDocument object.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.hsetDocumentAttributes:
Sets the document 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.
See Also
Declared In
PDFDocument.hsetOutlineRoot:
Sets the document’s root outline to a PDF outline object.
Parameters
- outline
The outline to be used as the document’s root outline. Pass
NULLto 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.hstring
Returns a string representing the textual content for the entire document.
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.hunlockWithPassword:
Attempts to unlock an encrypted document.
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,
unlockWithPassworddoes nothing and returnsYES. The password string is ignored.If the document is unlocked with only user permissions,
unlockWithPasswordattempts to obtain full owner permissions with the password string. If the string fails, the document maintains its user permissions. In either case, this method returnsYES.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hwriteToFile:
Writes the document to a file at the specified path.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hwriteToFile:withOptions:
Writes the document to a file at the specified path with the specified 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.hwriteToURL:
Writes the document to a location specified by the passed-in URL.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hwriteToURL:withOptions:
Writes the document to the specified URL with the specified options.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hDelegate Methods
didMatchString:
Called for every match found during a find operation.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
PDFDocument.hdocumentDidBeginDocumentFind:
Called when the PDFDocumentDidBeginFindNotification notification is posted.
Availability
- Available in OS X v10.4 and later.
See Also
-
PDFDocumentDidBeginFindNotification -
– setDelegate:
Declared In
PDFDocument.hdocumentDidBeginPageFind:
Called when the PDFDocumentDidBeginPageFindNotification notification is posted.
Availability
- Available in OS X v10.4 and later.
See Also
-
PDFDocumentDidBeginPageFindNotification -
– setDelegate:
Declared In
PDFDocument.hdocumentDidEndDocumentFind:
Called when the PDFDocumentDidEndFindNotification notification is posted.
Availability
- Available in OS X v10.4 and later.
See Also
-
PDFDocumentDidEndFindNotification -
– setDelegate:
Declared In
PDFDocument.hdocumentDidEndPageFind:
Called when the PDFDocumentDidEndPageFindNotification notification is posted.
Availability
- Available in OS X v10.4 and later.
See Also
-
PDFDocumentDidEndPageFindNotification -
– setDelegate:
Declared In
PDFDocument.hdocumentDidFindMatch:
Called when the PDFDocumentDidFindMatchNotification notification is posted.
Availability
- Available in OS X v10.4 and later.
See Also
-
PDFDocumentDidFindMatchNotification -
– setDelegate:
Declared In
PDFDocument.hdocumentDidUnlock:
Called when the PDFDocumentDidUnlockNotification notification is posted.
Availability
- Available in OS X v10.4 and later.
See Also
-
PDFDocumentDidUnlockNotification -
– setDelegate:
Declared In
PDFDocument.hConstants
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.hDocument 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
PDFDocumentTitleAttributeAn optional text string (an
NSString) containing the title of the document.Available in OS X v10.4 and later.
Declared in
PDFDocument.h.PDFDocumentAuthorAttributeAn 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.PDFDocumentSubjectAttributeAn 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.PDFDocumentCreatorAttributeAn 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.PDFDocumentProducerAttributeAn 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.PDFDocumentCreationDateAttributeAn optional text string (an
NSDate) containing the document’s creation date.Available in OS X v10.4 and later.
Declared in
PDFDocument.h.PDFDocumentModificationDateAttributeAn optional text string (an
NSDate) containing the document’s last-modified date.Available in OS X v10.4 and later.
Declared in
PDFDocument.h.PDFDocumentKeywordsAttributeAn optional array of text strings (an
NSArrayofNSStringobjects) containing keywords for the document.Available in OS X v10.4 and later.
Declared in
PDFDocument.h.
Declared In
PDFDocument.hPDF 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
kPDFPrintPageScaleNoneDo not apply scaling to the page when printing.
Available in OS X v10.5 and later.
Declared in
PDFDocument.h.kPDFPrintPageScaleToFitScale each page up or down to best fit the paper size.
Available in OS X v10.5 and later.
Declared in
PDFDocument.h.kPDFPrintPageScaleDownToFitScale 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.hNotifications
PDFDocument declares and posts the following notifications:
PDFDocumentDidUnlockNotification
unlockWithPassword: message. The notification object is the PDFDocument object itself.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidBeginFindNotification
beginFindString:withOptions: or findString:withOptions: method begins finding. The notification object is the PDFDocument object itself.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidEndFindNotification
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
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidBeginPageFindNotification
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
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidEndPageFindNotification
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
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidFindMatchNotification
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
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidBeginWriteNotification
The notification object is the PDFDocument object itself.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidEndWriteNotification
The notification object is the PDFDocument object itself.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidBeginPageWriteNotification
The notification object is the PDFDocument object itself. To determine the page, use the @"PDFDocumentPageIndex" key to obtain userinfo of type NSNumber.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.hPDFDocumentDidEndPageWriteNotification
The notification object is the PDFDocument object itself. To determine the page, use the @"PDFDocumentPageIndex" key to obtain userinfo of type NSNumber.
Availability
- Available in OS X v10.4 and later.
Declared In
PDFDocument.h© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)