Mac Developer Library

Developer

PDFKit Reference Collection PDFPage Class Reference

Options
Deployment Target:

On This Page
Language:

PDFPage

PDFPage, a subclass of NSObject, defines methods used to render PDF pages and work with annotations, text, and selections.

PDFPage objects are flexible and powerful. With them you can render PDF content onscreen or to a printer, add annotations, count characters, define selections, and get the textual content of a page as an NSString object.

Your application instantiates a PDFPage object by asking for one from a PDFDocument object.

For simple display and navigation of PDF documents within your application, you don’t need to use PDFPage. You need only use PDFView.

  • Initializer for subclasses of PDFPage.

    Use [PDFPage init] or initWithImage: instead.

    Declaration

    - (id)initWithDocument:(PDFDocument *)document

    Discussion

    Subclasses of PDFPage must handle several methods that are transparently handled when using the PDFPage class directly, including boundsForBox and drawInRect:withBox:.

    Availability

    Available in OS X v10.4 and later.

  • Creates a new PDFPage object and initializes it with the specified NSImage object.

    Declaration

    - (id)initWithImage:(NSImage *)image

    Availability

    Available in OS X v10.5 and later.

  • Returns the PDFDocument object with which the page is associated.

    Declaration

    - (PDFDocument *)document

    Availability

    Available in OS X v10.4 and later.

  • Returns the label for the page.

    Declaration

    - (NSString *)label

    Discussion

    Typically, the label is “1” for the first page, “2” for the second page, and so on, but nonnumerical labels are also possible (such as “xxi”, “4-1” and so on).

    Availability

    Available in OS X v10.4 and later.

    See Also

    – document

  • Returns the bounds for the specified PDF display box.

    Declaration

    - (NSRect)boundsForBox:(PDFDisplayBox)box

    Discussion

    The PDFDisplayBox enumeration defines the various box types (see Constants for additional information about box types).

    Note that only the media box is required for a PDF. If you request the bounds for the crop box, but the PDF does not include a crop box, the bounds for the media box are returned instead. If you request the bounds for other box types, and the PDF does not includes these types, the bounds for the crop box are returned instead.

    The coordinates for the box are in page space, so you might need to transform the points if the page has a rotation on it. Also, note that the bounds boundsForBox returns are intersected with the page’s media box.

    boundsForBox throws a range exception if box is not in range.

    Availability

    Available in OS X v10.4 and later.

  • Sets the bounds for the specified box.

    Declaration

    - (void)setBounds:(NSRect)bounds forBox:(PDFDisplayBox)box

    Discussion

    If the box does not exist, this method creates it for you.

    To remove a box, pass NSZeroRect for the bounds (note that you cannot remove the media box). If the box bounds are not in range, this method throws a range exception.

    Availability

    Available in OS X v10.4 and later.

  • Returns the page rotation angle in degrees.

    Declaration

    - (int)rotation

    Discussion

    The rotation is a positive multiple of 90: 0, 90, 180, or 270. The rotation of pages with negative rotation is converted to a corresponding positive rotation.

    If you are subclassing PDFView and displaying pages yourself, don’t assume a rotation of 0. Pages with an inherent rotation display rotated when opened unless you set their rotation to zero. Regardless of the inherent rotation angle, it is up to the author of a page whether zero rotation corresponds to upright text when displayed on a monitor.

    Availability

    Available in OS X v10.4 and later.

  • Sets the rotation angle for the page in degrees.

    Declaration

    - (void)setRotation:(int)angle

    Discussion

    The rotation must be a positive or negative multiple of 90 (negative angles are converted to their positive equivalents; for example, -90 is changed to 270); otherwise this method throws an exception.

    Availability

    Available in OS X v10.4 and later.

    See Also

    – rotation

  • Draws the page within the specified box.

    Declaration

    - (void)drawWithBox:(PDFDisplayBox)box

    Discussion

    This method takes into account the page rotation and draws clipped to the specified box. If the page is set to display annotations, this method also draws them. This method does not clear the background. To clear the background before drawing, use NSRectFill with NSColor set (typically) to white.

    Availability

    Available in OS X v10.4 and later.

  • Transforms the current context, given the specified box.

    Declaration

    - (void)transformContextForBox:(PDFDisplayBox)box

    Discussion

    When transforming the current context, this method takes into account the rotation of the page, as well as the origin of the box with respect to the page’s base coordinate system. This is a convenient method to call within the PDFView drawPage: method or from within a draw method of a PDFAnnotation subclass.

    Availability

    Available in OS X v10.5 and later.

  • Returns the number of characters on the page, including whitespace characters.

    Declaration

    - (NSUInteger)numberOfCharacters

    Availability

    Available in OS X v10.4 and later.

    See Also

    – string

  • Returns an NSString object representing the text on the page.

    Declaration

    - (NSString *)string

    Availability

    Available in OS X v10.4 and later.

  • Returns an NSAttributedString object representing the text on the page.

    Declaration

    - (NSAttributedString *)attributedString

    Availability

    Available in OS X v10.4 and later.

  • Returns the bounds, in page space, of the character at the specified index.

    Declaration

    - (NSRect)characterBoundsAtIndex:(NSInteger)index

    Discussion

    In the unlikely event that there is more than one character at the specified index point, only the bounds of the first character is returned.

    Page space is a 72 dpi coordinate system with the origin at the lower-left corner of the current page. Note that the bounds returned are not guaranteed to have integer coordinates.

    Availability

    Available in OS X v10.4 and later.

  • Returns the character index value for the specified point in page space.

    Declaration

    - (NSInteger)characterIndexAtPoint:(NSPoint)point

    Discussion

    If there is no character at the specified point, the method returns -1.

    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.

  • Returns the PDF data (that is, a PDF document) representing this page. This method does not preserve external page links.

    Declaration

    - (NSData *)dataRepresentation

    Availability

    Available in OS X v10.4 and later.