PDFPage Class Reference

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

Overview

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.

Tasks

Initializing a Page

Getting Information About a Page

Working with Annotations

Rendering Pages

Working with Textual Content

Working with Selections

Miscellaneous

Instance Methods

addAnnotation:

Adds the specified annotation object to the page.

- (void)addAnnotation:(PDFAnnotation *)annotation
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFPage.h

annotationAtPoint:

Returns the annotation, if there is one, at the specified point.

- (PDFAnnotation *)annotationAtPoint:(NSPoint)point
Discussion

Use this method for hit-testing based on the current cursor position. If more than one annotation shares the specified point, the frontmost (or topmost) one is returned (the annotations are searched in reverse order of their appearance in the PDF data file). Returns NULL if there is no annotation at point.

Specify the point in page space. 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.
See Also
Declared In
PDFPage.h

annotations

Returns an array containing the page’s annotations.

- (NSArray *)annotations
Discussion

The elements of the array will most likely be typed to subclasses of the PDFAnnotation class.

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

attributedString

Returns an NSAttributedString object representing the text on the page.

- (NSAttributedString *)attributedString
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFPage.h

boundsForBox:

Returns the bounds for the specified PDF display box.

- (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.
See Also
  • – setBounds:forBox:
Related Sample Code
Declared In
PDFPage.h

characterBoundsAtIndex:

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

- (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.
See Also
Declared In
PDFPage.h

characterIndexAtPoint:

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

- (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.
See Also
Declared In
PDFPage.h

dataRepresentation

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

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

displaysAnnotations

Returns a Boolean value indicating whether annotations are displayed for the page.

- (BOOL)displaysAnnotations
Discussion

If YES, the page will draw annotations when a drawing method is called.

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

document

Returns the PDFDocument object with which the page is associated.

- (PDFDocument *)document
Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
PDFPage.h

drawWithBox:

Draws the page within the specified box.

- (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.
See Also
Declared In
PDFPage.h

initWithDocument:

Initializer for subclasses of PDFPage. (Deprecated. Use [PDFPage init] or initWithImage: instead.)

- (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.
Declared In
PDFPage.h

initWithImage:

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

- (id)initWithImage:(NSImage *)image
Availability
  • Available in OS X v10.5 and later.
Declared In
PDFPage.h

label

Returns the label for the page.

- (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
Declared In
PDFPage.h

numberOfCharacters

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

- (NSUInteger)numberOfCharacters
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFPage.h

removeAnnotation:

Removes the specified annotation from the page.

- (void)removeAnnotation:(PDFAnnotation *)annotation
Availability
  • Available in OS X v10.4 and later.
See Also
Related Sample Code
Declared In
PDFPage.h

rotation

Returns the page rotation angle in degrees.

- (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.
See Also
Related Sample Code
Declared In
PDFPage.h

selectionForLineAtPoint:

Returns the whole line of text that includes the specified point.

- (PDFSelection *)selectionForLineAtPoint:(NSPoint)point
Discussion

Returns NULL if no line of text contains point.

Use this method to respond to a triple-click.

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

selectionForRange:

Returns the text contained within the specified range.

- (PDFSelection *)selectionForRange:(NSRange)range
Discussion

This method raises an exception if the range length is 0 or if either end of the range is outside the range of characters on the page.

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

selectionForRect:

Returns the text enclosed within the specified rectangle, expressed in page (user) coordinates.

- (PDFSelection *)selectionForRect:(NSRect)rect
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFPage.h

selectionForWordAtPoint:

Returns the whole word that includes the specified point.

- (PDFSelection *)selectionForWordAtPoint:(NSPoint)point
Discussion

Returns NULL if no word contains point.

Use this method to respond to a double-click.

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

selectionFromPoint:toPoint:

Returns the text between the two specified points in page space.

- (PDFSelection *)selectionFromPoint:(NSPoint)startPoint toPoint:(NSPoint)endPoint
Discussion

Either point may be the one closer to the start of the page. In determining the selection, the points are sorted first top to bottom and then left to right.

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

To visualize the selection, picture the rectangle defined by startPoint and endPoint. The selection begins at the first character fully within the defined rectangle and closest to its upper-left corner. The selection ends at the last character fully within the defined rectangle and closest to its lower-right corner.

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

setBounds:forBox:

Sets the bounds for the specified box.

- (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.
See Also
Declared In
PDFPage.h

setDisplaysAnnotations:

Specifies whether or not to display annotations for the page.

- (void)setDisplaysAnnotations:(BOOL)display
Discussion

If display is YES, the page will draw annotations when a drawing method is called.

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

setRotation:

Sets the rotation angle for the page in degrees.

- (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
Declared In
PDFPage.h

string

Returns an NSString object representing the text on the page.

- (NSString *)string
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
PDFPage.h

transformContextForBox:

Transforms the current context, given the specified box.

- (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.
See Also
  • – drawWithBox:
Declared In
PDFPage.h

Constants

The following box types may be used with PDFPage drawing and bounds-setting methods. See the Adobe PDF Specification for more information on box types, units, and coordinate systems.

Constant

Description

kPDFDisplayBoxMediaBox

A rectangle defining the boundaries of the physical medium for display or printing, expressed in default user-space units.

Available in OS X v10.4 and later.

Declared in PDFPage.h.

kPDFDisplayBoxCropBox

A rectangle defining the boundaries of the visible region , expressed in default user-space units. Default value equal to kPDFDisplayBoxMediaBox.

Available in OS X v10.4 and later.

Declared in PDFPage.h.

kPDFDisplayBoxBleedBox

A rectangle defining the boundaries of the clip region for the page contents in a production environment. Default value equal to kPDFDisplayBoxCropBox.

Available in OS X v10.4 and later.

Declared in PDFPage.h.

kPDFDisplayBoxTrimBox

A rectangle defining the intended boundaries of the finished page. Default value equal to kPDFDisplayBoxCropBox.

Available in OS X v10.4 and later.

Declared in PDFPage.h.

kPDFDisplayBoxArtBox

A rectangle defining the boundaries of the page’s meaningful content including surrounding white space intended for display. Default value equal to kPDFDisplayBoxCropBox.

Available in OS X v10.4 and later.

Declared in PDFPage.h.



© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)

Did this document help you? Yes It's good, but... Not helpful...