UIPrintFormatter Class Reference

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

Overview

UIPrintFormatter is an abstract base class for print formatters: objects that lay out custom printable content that can cross page boundaries. Given a print formatter, the printing system can automate the printing of the type of content associated with the print formatter.

Examples of such content could be a web view, a mix of images and text, or a long text document. The UIKit framework provides several concrete subclasses of UIPrintFormatter: UISimpleTextPrintFormatter, UIMarkupTextPrintFormatter, and UIViewPrintFormatter.

You can assign a single print formatter for a print job via the printFormatter property of the UIPrintInteractionController shared instance; or you can specify one or more print formatters that are associated with specific pages of a page renderer through the addPrintFormatter:startingAtPageAtIndex:method of UIPrintPageRenderer. A page renderer is an instance of a custom subclass of UIPrintPageRenderer that draws content for printing.

UIPrintFormatter publishes an interface that allows you to specify the starting page for a print job and the margins around the printed content; given that information plus the content, a print formatter computes the number of pages for the print job. Figure 1 depicts the print-formatter properties, along with certain UIPrintPaper and UIPrintPageRenderer properties, that define the layout of a multi-page print job.

Figure 1  Layout of printed content

Third-party subclasses of UIPrintFormatter are not recommended. If you have custom content to print, use a custom UIPrintPageRenderer object.

Tasks

Laying Out the Content

Managing Pagination

Drawing the Content

Communicating with the Page Renderer

Properties

contentInsets

The distances the edges of content are inset from the printing rectangle.

@property(nonatomic) UIEdgeInsets contentInsets
Discussion

This property adjusts the margins for content printed by the formatter. The printing rectangle defines the area the printer is capable of printing in; each inset is an inward distance, in points, from a side of the printing area. The top inset is used only on the first page that the formatter draws. The bottom inset is not used. You can use the UIEdgeInsetsMake macro to create a UIEdgeInsets structure.

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

maximumContentHeight

The maximum height of the content area.

@property(nonatomic) CGFloat maximumContentHeight
Discussion

UIPrintFormatter uses this value to determine where the content rectangle begins on the first page. It compares the value of this property with the printing rectangle’s height minus the header and footer heights and the top inset value (of contentInsets); it uses the lower of the two values. The default value of this property is the maximum float value.

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

maximumContentWidth

The maximum width of the content area.

@property(nonatomic) CGFloat maximumContentWidth
Discussion

UIPrintFormatter uses this value to determine the maximum width of the content rectangle. It compares the value of this property with the printing rectangle’s width minus the left and right inset values and uses the lower of the two. The default value of this property is the maximum float value.

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

pageCount

The number of pages to be printed. (read-only)

@property(nonatomic, readonly) NSInteger pageCount
Discussion

UIPrintFormatter calculates this value based on the layout metrics and content.

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

printPageRenderer

Returns the page renderer with which the receiver is associated.

@property(readonly) UIPrintPageRenderer *printPageRenderer
Discussion

If the receiving print formatter was not added to a page renderer—that is, it was assigned to the printFormatter property of the UIPrintInteractionController class—the value returned is nil.

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

startPage

The index of the first page that the print formatter lays out.

@property(nonatomic) NSInteger startPage
Discussion

The value is a zero-based index. You can set the starting page of a print formatter by assigning an index to this property or by passing one as the second argument of the addPrintFormatter:startingAtPageAtIndex: method of UIPrintPageRenderer.

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

Instance Methods

drawInRect:forPageAtIndex:

Draws the portion of a print formatter’s content that goes in the given area for the specified page

- (void)drawInRect:(CGRect)rect forPageAtIndex:(NSInteger)pageIndex
Parameters
rect

The area in which to draw the content.

pageIndex

The number of the page of content to draw.

Discussion

This method is called by the default implementation of drawPrintFormatter:forPageAtIndex: of the UIPrintPageRenderer class for each print formatter associated with a page.

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

rectForPageAtIndex:

Returns the area enclosing a specified page of content.

- (CGRect)rectForPageAtIndex:(NSIndex)pageIndex
Parameters
pageIndex

The index number of a page.

Return Value

A rectangle enclosing the content area for page pageIndex.

Discussion

Returns CGRectZero if the print formatter draws no content on the specified page.

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

removeFromPrintPageRenderer

Removes the print formatter from the page renderer.

- (void)removeFromPrintPageRenderer
Discussion

A print formatter is typically associated with a pages of a UIPrintPageRenderer object through the addPrintFormatter:startingAtPageAtIndex: method.

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