UIPrintPageRenderer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 4.2 and later.
Companion guide
Declared in
UIPrintPageRenderer.h
Related sample code

Overview

A UIPrintPageRenderer object draws pages of content that are to be printed, with or without the assistance of print formatters.

A page renderer is an instance of a custom subclass of UIPrintPageRenderer. When you compose a print job using the shared instance of UIPrintInteractionController, you assign the page renderer to the printPageRenderer property of that instance. The subclass typically overrides one or more of the five draw... methods:

UIPrintPageRenderer usually requires you to specify the number of pages of printable content by overriding numberOfPages. It also allows you to specify the heights of page headers and footers.

You may assign one or more print formatters—that is, UIPrintFormatter objects that can lay out printable content of a certain kind—to specific page ranges of the content. For example, if your printable content is partially HTML, you may assign an instance of the UIMarkupTextPrintFormatter object to the starting page of HTML content. You assign a print formatter using the addPrintFormatter:startingAtPageAtIndex: method and you can get the print formatters for a given page by calling printFormattersForPageAtIndex:.

Tasks

Accessing Information About the Print Job

Specifying Header and Footer Heights

Managing Print Formatters

Preparing for Drawing

Drawing a Page

Properties

footerHeight

The height of the page footer.

@property CGFloat footerHeight
Discussion

The footer is measured in points from the bottom of printableRect and is below the content area. The default footer height is 0.0

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

headerHeight

The height of the page header.

@property CGFloat headerHeight
Discussion

The header is measured in points from the top of printableRect and is above the content area. The default header height is 0.0.

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

paperRect

The size of the paper used for printing. (read-only)

@property(readonly) CGRect paperRect
Discussion

The value of this property is a rectangle that defines the size of paper chosen for the print job. The origin is always (0,0).

Availability
  • Available in iOS 4.2 and later.
See Also
Declared In
UIPrintPageRenderer.h

printableRect

The area in which printing can occur. (read-only)

@property(readonly) CGRect printableRect
Discussion

The value of this property is a rectangle that defines the area in which the printer can print content. Sometimes this is referred to as the imageable area of the paper.

Availability
  • Available in iOS 4.2 and later.
See Also
Declared In
UIPrintPageRenderer.h

printFormatters

The print formatters associated with the page renderer.

@property(copy) NSArray *printFormatters
Discussion

The elements of the array are UIPrintFormatter objects. A print formatter can be an instance of UISimpleTextPrintFormatter, UIMarkupTextPrintFormatter, or UIViewPrintFormatter. Print formatters added this way to a page renderer are associated with page ranges through each print formatter’s startPage and pageCount properties.

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

Instance Methods

addPrintFormatter:startingAtPageAtIndex:

Adds a print formatter to the page renderer starting at the specified page.

- (void)addPrintFormatter:(UIPrintFormatter *)formatter startingAtPageAtIndex:(NSInteger)pageIndex
Parameters
formatter

The UIPrintFormatter object to add to the page renderer. A print formatter can be an instance of UISimpleTextPrintFormatter, UIMarkupTextPrintFormatter, or UIViewPrintFormatter.

pageIndex

The index identifying the first page with which the print formatter should be associated with. This value overrides the startPage property of the print formatter.

Discussion

You can dissociate a print formatter from its page renderer by calling the removeFromPrintPageRenderer method on the print formatter.

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

drawContentForPageAtIndex:inRect:

Overridden to draw the content of the given page.

- (void)drawContentForPageAtIndex:(NSInteger)index inRect:(CGRect)contentRect
Parameters
index

The index of the page in which to draw content.

contentRect

The area in which content is to be drawn, specified in the coordinate system of the printable rectangle. This is the area defined by printableRect minus headerHeight and footerHeight.

Discussion

The default implementation of this method does nothing. The method is set up for drawing to the current graphics context (as returned by UIGraphicsGetCurrentContext).

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

drawFooterForPageAtIndex:inRect:

Overridden to draw the footer of the given page.

- (void)drawFooterForPageAtIndex:(NSInteger)index inRect:(CGRect)footerRect
Parameters
index

The index of the page in which to draw the footer content.

footerRect

The rectangle in which the footer content should be drawn. It is specified in the coordinate system of the paper rectangle (paperRect); that is, the origin of coordinates is at the top-left corner of the sheet.

Discussion

The default implementation of this method does nothing. It is not called if footerHeight is not a positive value. The method is set up for drawing to the current graphics context (as returned by UIGraphicsGetCurrentContext).

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

drawHeaderForPageAtIndex:inRect:

Overridden to draw the header of the given page.

- (void)drawHeaderForPageAtIndex:(NSInteger)index inRect:(CGRect)headerRect
Parameters
index

The index of the page in which to draw the header.

headerRect

The rectangle in which the header content should be drawn. It is specified in the coordinate system of the paper rectangle (paperRect); that is, the origin of coordinates is at the top-left corner of the sheet.

Discussion

The default implementation of this method does nothing. It is not called if headerHeight is not a positive value. The method is set up for drawing to the current graphics context (as returned by UIGraphicsGetCurrentContext).

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

drawPageAtIndex:inRect:

Overridden to draw a given page of content for the printer.

- (void)drawPageAtIndex:(NSInteger)index inRect:(CGRect)pageRect
Parameters
index

The index of the page to draw.

pageRect

The rectangle in which printable content can be drawn.

Discussion

The default implementation of this method calls, in sequence, drawHeaderForPageAtIndex:inRect:, drawContentForPageAtIndex:inRect:, drawPrintFormatter:forPageAtIndex:, and drawFooterForPageAtIndex:inRect:. The method is set up for drawing to the current graphics context (as returned by UIGraphicsGetCurrentContext).

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

drawPrintFormatter:forPageAtIndex:

Overridden to add custom drawing to the drawing provided by a given print formatter for a page.

- (void)drawPrintFormatter:(UIPrintFormatter *)printFormatter forPageAtIndex:(NSInteger)index
Parameters
printFormatter

A UIPrintFormatter object associated with page index.

index

The index of the page in which printFormatter is to draw.

Discussion

This method is invoked for each print formatter assigned to the specified page. The default implementation invokes the drawInRect:forPageAtIndex: method of the UIPrintFormatter object that is passed in. You can override this method to intermix custom drawing with the formatter drawing—for example, by adding an overlay or underlay graphic. Call drawInRect:forPageAtIndex: to have the print formatter draw its portion of the page. The method is set up for drawing to the current graphics context (as returned by UIGraphicsGetCurrentContext).

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

numberOfPages

The number of pages to render.

- (NSInteger)numberOfPages
Discussion

By default, returns the number of pages as calculated by UIKit if the receiver uses print formatters. If the page renderer uses no print formatters, the returned value is zero. If your page renderer is doing any custom drawing except for headers and footers, it must override this method.

This method is called at any point when UIKit needs the number of pages. If an application requests the page range control, it's called early on. It can also be called when the selected printer or duplex mode changes. Otherwise, it is called when the print job starts.

If print formatters aren’t used to compute the page count, the page renderer can override this method to calculate and return the number of pages. The computation can take into account the current printableRect value for each page, any implicit margins, and the content to be drawn when laid out within these boundaries.

Availability
  • Available in iOS 4.2 and later.
See Also
Related Sample Code
Declared In
UIPrintPageRenderer.h

prepareForDrawingPages:

Overridden by the page renderer to prepare for drawing a range of pages.

- (void)prepareForDrawingPages:(NSRange)range
Parameters
range

A range of pages.

Discussion

UIKit calls this method before it requests drawing for a range of pages. You can optionally override this method to perform setup tasks. The default implementation does nothing.

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h

printFormattersForPageAtIndex:

Returns the print formatters associated with a specified page.

- (NSArray *)printFormattersForPageAtIndex:(NSInteger)pageIndex
Parameters
pageIndex

The index of a page of printable content.

Return Value

An array of UIPrintFormatter objects. A print formatter can be an instance of UISimpleTextPrintFormatter, UIMarkupTextPrintFormatter, or UIViewPrintFormatter.

Discussion

A print formatter is associated with a starting page of printable content through the addPrintFormatter:startingAtPageAtIndex: method or the startPage property of UIPrintFormatter. The number of pages from that page is determined by the pageCount property, which UIPrintFormatter computes based on layout metrics and content.

Availability
  • Available in iOS 4.2 and later.
Declared In
UIPrintPageRenderer.h