Mac Developer Library

Developer

PDFKit Reference Collection PDFDocument Class Reference

Options
Deployment Target:

On This Page
Language:

PDFDocument

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.

  • Initializes a PDFDocument object with the passed-in data.

    Declaration

    - (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.

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

    Declaration

    - (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.

  • Returns the URL for the document.

    Declaration

    - (NSURL *)documentURL

    Return Value

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

  • Returns the major version of the document.

    Declaration

    - (int)majorVersion

    Return Value

    The major version of the document.

  • Returns the minor version of the document.

    Declaration

    - (int)minorVersion

    Return Value

    The minor version of the document.

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

    Declaration

    - (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.

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

    Declaration

    - (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.

    See Also

    – outlineRoot

  • Returns the root PDF outline object for the document.

    Declaration

    - (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.

  • Returns a dictionary of document metadata.

    Declaration

    - (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.

  • Sets the document attributes.

    Declaration

    - (void)setDocumentAttributes:(NSDictionary *)attributes

    Parameters

    attributes

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

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

    Declaration

    - (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.

    See Also

    – outlineRoot

  • Returns a Boolean value specifying whether the document is encrypted.

    Declaration

    - (BOOL)isEncrypted

    Return Value

    YEStrue if the document is encrypted, whether it is locked or unlocked; NOfalse 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.

  • Returns a Boolean value indicating whether the document is locked.

    Declaration

    - (BOOL)isLocked

    Return Value

    YEStrue if the document is locked; NOfalse 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.

  • Attempts to unlock an encrypted document.

    Declaration

    - (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

    YEStrue if the specified password unlocks the document, NOfalse otherwise.

    Discussion

    If the password is correct, this method returns YEStrue, 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 YEStrue. 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 YEStrue.

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

    Declaration

    - (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 YEStrue 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.

  • Returns a Boolean value indicating whether the document allows printing.

    Declaration

    - (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 YEStrue 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.

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

    Declaration

    - (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].

Data Types

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

    Declaration

    typedef NSInteger PDFPrintScalingMode;

    Import Statement

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

    Declaration

    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.

    • PDFDocumentAuthorAttribute

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

    • PDFDocumentSubjectAttribute

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

    • PDFDocumentCreatorAttribute

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

    • PDFDocumentProducerAttribute

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

    • PDFDocumentCreationDateAttribute

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

    • PDFDocumentModificationDateAttribute

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

    • PDFDocumentKeywordsAttribute

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

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

    Declaration

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

    Constants

    • kPDFPrintPageScaleNone

      Do not apply scaling to the page when printing.

    • kPDFPrintPageScaleToFit

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

    • kPDFPrintPageScaleDownToFit

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

  • Posted when a document unlocks after a unlockWithPassword: message.

    The notification object is the PDFDocument object itself.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

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

    The notification object is the PDFDocument object itself.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • 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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • 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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • 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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • 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 *

    Import Statement

    Availability

    Available in OS X v10.4 and later.

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

    The notification object is the PDFDocument object itself.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

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

    The notification object is the PDFDocument object itself.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • 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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • 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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.