iOS Developer Library

Developer

UIKit Framework Reference UIPrintFormatter Class Reference

Options
Deployment Target:

On This Page
Language:

UIPrintFormatter

Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 4.2 and later

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 1Layout of printed content image: ../Art/print_formatter_attrs.jpg

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

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

    Declaration

    Swift

    var contentInsets: UIEdgeInsets

    Objective-C

    @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.

    The default value of this property is UIEdgeInsetsZero.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

  • The margins for each printed page.

    Declaration

    Swift

    var perPageContentInsets: UIEdgeInsets

    Objective-C

    @property(nonatomic) UIEdgeInsets perPageContentInsets

    Discussion

    This property specifies the margins to apply to each printed page. All margins are respected, so the top inset value represents the top margin of every page, the left inset value represents the left margin of every page, and so on. If the per-page insets are smaller than the printable area of the page, or smaller than the printable area after the values in the contentInsets property are applied, the value in this property is effectively ignored.

    The default value of this property is UIEdgeInsetsZero.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later

  • The maximum height of the content area.

    Declaration

    Swift

    var maximumContentHeight: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

  • The maximum width of the content area.

    Declaration

    Swift

    var maximumContentWidth: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

  • startPage startPage Property

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

    Declaration

    Swift

    var startPage: Int

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

    See Also

    pageCount

  • pageCount pageCount Property

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

    Declaration

    Swift

    var pageCount: Int { get }

    Objective-C

    @property(nonatomic, readonly) NSInteger pageCount

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

    See Also

    startPage

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

    Declaration

    Swift

    func drawInRect(_ rect: CGRect, forPageAtIndex pageIndex: Int)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

  • Returns the area enclosing a specified page of content.

    Declaration

    Swift

    func rectForPageAtIndex(_ pageIndex: Int) -> CGRect

    Objective-C

    - (CGRect)rectForPageAtIndex:(NSInteger)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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

  • Removes the print formatter from the page renderer.

    Declaration

    Swift

    func removeFromPrintPageRenderer()

    Objective-C

    - (void)removeFromPrintPageRenderer

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later

  • Returns the page renderer with which the receiver is associated.

    Declaration

    Swift

    unowned(unsafe) var printPageRenderer: UIPrintPageRenderer! { get }

    Objective-C

    @property(nonatomic, readonly, assign) 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later