| Inherits from | |
| Conforms to | |
| Framework | Library/Frameworks/Quartz.framework/Frameworks/PDFKit.framework |
| Availability | Available in Mac OS X v10.4 and later. |
| Declared in | PDFPage.h |
| Related sample code |
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.
– annotations
– displaysAnnotations
– setDisplaysAnnotations:
– addAnnotation:
– removeAnnotation:
– annotationAtPoint:
– selectionForRect:
– selectionForWordAtPoint:
– selectionForLineAtPoint:
– selectionFromPoint:toPoint:
– selectionForRange:
Adds the specified annotation object to the page.
- (void)addAnnotation:(PDFAnnotation *)annotation
– annotations– displaysAnnotations– setDisplaysAnnotations:– removeAnnotation:– annotationAtPoint:PDFPage.hReturns the annotation, if there is one, at the specified point.
- (PDFAnnotation *)annotationAtPoint:(NSPoint)point
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.
PDFPage.hReturns an array containing the page’s annotations.
- (NSArray *)annotations
The elements of the array will most likely be typed to subclasses of the PDFAnnotation class.
– displaysAnnotations– setDisplaysAnnotations:– addAnnotation:– removeAnnotation:– annotationAtPoint:PDFPage.hReturns an NSAttributedString object representing the text on the page.
- (NSAttributedString *)attributedString
PDFPage.hReturns the bounds for the specified PDF display box.
- (NSRect)boundsForBox:(PDFDisplayBox)box
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.
– setBounds:forBox:PDFPage.hReturns the bounds, in page space, of the character at the specified index.
- (NSRect)characterBoundsAtIndex:(NSInteger)index
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.
PDFPage.hReturns the character index value for the specified point in page space.
- (NSInteger)characterIndexAtPoint:(NSPoint)point
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.
PDFPage.hReturns the PDF data (that is, a PDF document) representing this page. This method does not preserve external page links.
- (NSData *)dataRepresentation
PDFPage.hReturns a Boolean value indicating whether annotations are displayed for the page.
- (BOOL)displaysAnnotations
If YES, the page will draw annotations when a drawing method is called.
– annotations– setDisplaysAnnotations:– addAnnotation:– removeAnnotation:– annotationAtPoint:– drawWithBox:PDFPage.hReturns the PDFDocument object with which the page is associated.
- (PDFDocument *)document
PDFPage.hDraws the page within the specified box.
- (void)drawWithBox:(PDFDisplayBox)box
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.
PDFPage.hInitializer for subclasses of PDFPage. (Deprecated. Use [PDFPage init] or initWithImage: instead.)
- (id)initWithDocument:(PDFDocument *)document
Subclasses of PDFPage must handle several methods that are transparently handled when using the PDFPage class directly, including boundsForBox and drawInRect:withBox:.
PDFPage.hCreates a new PDFPage object and initializes it with the specified NSImage object.
- (id)initWithImage:(NSImage *)image
PDFPage.hReturns the label for the page.
- (NSString *)label
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).
PDFPage.hReturns the number of characters on the page, including whitespace characters.
- (NSUInteger)numberOfCharacters
PDFPage.hRemoves the specified annotation from the page.
- (void)removeAnnotation:(PDFAnnotation *)annotation
PDFPage.hReturns the page rotation angle in degrees.
- (int)rotation
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.
PDFPage.hReturns the whole line of text that includes the specified point.
- (PDFSelection *)selectionForLineAtPoint:(NSPoint)point
Returns NULL if no line of text contains point.
Use this method to respond to a triple-click.
PDFPage.hReturns the text contained within the specified range.
- (PDFSelection *)selectionForRange:(NSRange)range
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.
– selectionForRect:– selectionForWordAtPoint:– selectionForLineAtPoint:– selectionFromPoint:toPoint:PDFPage.hReturns the text enclosed within the specified rectangle, expressed in page (user) coordinates.
- (PDFSelection *)selectionForRect:(NSRect)rect
– selectionForWordAtPoint:– selectionForLineAtPoint:– selectionFromPoint:toPoint:– selectionForRange:PDFPage.hReturns the whole word that includes the specified point.
- (PDFSelection *)selectionForWordAtPoint:(NSPoint)point
Returns NULL if no word contains point.
Use this method to respond to a double-click.
PDFPage.hReturns the text between the two specified points in page space.
- (PDFSelection *)selectionFromPoint:(NSPoint)startPoint toPoint:(NSPoint)endPoint
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.
PDFPage.hSets the bounds for the specified box.
- (void)setBounds:(NSRect)bounds forBox:(PDFDisplayBox)box
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.
PDFPage.hSpecifies whether or not to display annotations for the page.
- (void)setDisplaysAnnotations:(BOOL)display
If display is YES, the page will draw annotations when a drawing method is called.
PDFPage.hSets the rotation angle for the page in degrees.
- (void)setRotation:(int)angle
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.
PDFPage.hReturns an NSString object representing the text on the page.
- (NSString *)string
PDFPage.hTransforms the current context, given the specified box.
- (void)transformContextForBox:(PDFDisplayBox)box
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.
– drawWithBox:PDFPage.hThe 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.
Last updated: 2007-12-11
