UIPrint​Interaction​Controller

Written by Nate Cook
This article has been translated into:
中文

With all the different means to comment, mark up, save, and share right at our fingertips, it’s easy to overlook the value of a printed sheet of paper.

UIKit makes it easy to print straight from a user’s device with custom designs that you can adapt to both your content and the paper size. This article will first walk through how to format your content for printing, then detail the different ways to present (or not!) the printing interface.

The “printed” images throughout this article are taken from Apple’s Printer Simulator. (The yellow edges represent the non-printable margins of the paper)

As of Xcode 6, the printer simulator must be downloaded as part of the Hardware IO Tools for Xcode.

Download Hardware I/O Tools from Apple Developer Website

PrintSimulator App Info

PrintSimulator App Load Paper

At the heart of the UIKit Printing APIs is UIPrintInteractionController. A shared instance of this class manages details of print jobs and configure any UI that will be presented to the user. It also provides three levels of control for the formatting of your content.

Printing is a Job

Before we look at formatting actual content for printing, let’s go through the options for configuring the print job and the print options presented to the user.

UIPrintInfo

Print job details are set in a UIPrintInfo instance. You can use the following properties:

  • jobName String: A name for this print job. The name will be displayed in the Print Center on the device and, for some printers, on the LCD display.
  • orientation UIPrintInfoOrientation: Either .Portrait (the default) or .Landscape—this is ignored if what you print has an intrinsic orientation, such as a PDF.
  • duplex UIPrintInfoDuplex: .None, .ShortEdge, or .LongEdge. The short- and long-edge settings indicate how double-sided pages could be bound, while .None suppresses double-sided printing (though not the UI toggle for duplexing, perplexingly).
  • outputType UIPrintInfoOutputType: Gives UIKit a hint about the type of content you’re printing. Can be any of:
    • .General (default): For mixed text and graphics; allows duplexing.
    • .Grayscale: Can be better than .General if your content includes black text only.
    • .Photo: For color or black and white images; disables duplexing and favors photo media for the paper type.
    • .PhotoGrayscale: Can be better than .Photo for grayscale-only images, depending on the printer.
  • printerID String?: An ID for a particular printer—you can retrieve this only after the user has selected a printer through the UI and save it to use as a preset for a future print job.

In addition, UIPrintInfo provides a dictionaryRepresentation property, which can be saved and used to create a new UIPrintInfo instance later.

UIPrintInteractionController Settings

There are a handful of settings on the UIPrintInteractionController that you can configure before displaying the printing UI. These include:

  • printInfo UIPrintInfo: The aforementioned print job configuration.
  • printPaper UIPrintPaper: A simple type that describes the physical and printable size of a paper type; except for specialized applications, this will be handled for you by UIKit.
  • showsNumberOfCopies Bool: When true, lets the user choose the number of copies.
  • showsPageRange Bool: When true, lets the user choose a sub-range from the printed material. This only makes sense with multi-page content—it’s turned off by default for images.
  • showsPaperSelectionForLoadedPapers Bool: When this is true and the selected printer has multiple paper options, the UI will let the user choose which paper to print on.

Formatting Your Content

Through four different properties of UIPrintInteractionController, you can select the level of control (and complexity) you want for your content.

  1. printingItem AnyObject! or printingItems [AnyObject]!: At the most basic level, the controller simply takes content that is already printable (images and PDFs) and sends them to the printer.
  2. printFormatter UIPrintFormatter: At the next level, you can use a UIPrintFormatter subclass to format content inside your application, then hand the formatter off to the UIPrintInteractionController. You have some control over the format, and the printing API largely takes care of the rest.
  3. printPageRenderer UIPrintPageRenderer: At the highest level, you can create a custom subclass of UIPrintPageRenderer, combining page formatters and your own drawing routines for headers, footers, and page content.

Since Thanksgiving (my favorite holiday) is around the corner, to illustrate these properties we’ll add printing to different screens of a hypothetical app for Thanksgiving recipes.

Printing With printItem(s)

You can print pre-existing printable content by setting either the printItem or printItems property of UIPrintInteractionController. Images and PDFs can be given either as image data (in a NSData, UIImage, or ALAsset instance) or via any NSURL referencing something that can be loaded into an NSData object. To be printable, images must be in a format that UIImage supports.

Let’s walk through a very simple case: showing the UI to print an image when the user taps a button. (We’ll look at alternate ways of initiating printing below.) The process will be largely the same, no matter what you’re printing—configure your print info, set up the print interaction controller, and provide your content before displaying the UI:

@IBAction func print(sender: UIBarButtonItem) {
    if UIPrintInteractionController.canPrintURL(imageURL) {
        let printInfo = UIPrintInfo(dictionary: nil)
        printInfo.jobName = imageURL.lastPathComponent
        printInfo.outputType = .Photo

        let printController = UIPrintInteractionController.sharedPrintController()!
        printController.printInfo = printInfo
        printController.showsNumberOfCopies = false

        printController.printingItem = imageURL

        printController.presentAnimated(true, completionHandler: nil)
    }
}

Easy as pie! (Or, in this case, sautéed Swiss chard.)

Print with .printingItem

The presentAnimated(:completionHandler:) method is for presenting the printing UI on the iPhone. If printing from the iPad, use one of the presentFromBarButtonItem(:animated:completionHandler:) or presentFromRect(:inView:animated:completionHandler:) methods instead.

UIPrintFormatter

The UIPrintFormatter class has two subclasses that can be used to format text (UISimpleTextPrintFormatter and UIMarkupTextPrintFormatter) plus another (UIViewPrintFormatter) that can format the content of three views: UITextView, UIWebView, and MKMapView. Print formatters have a few properties that allow you to define the printed area of the page in different ways; the final print area for the formatter will be the smallest rectangle that meets the following criteria:

  • contentInsets UIEdgeInsets: A set of insets from the edges of the page for the entire block of content. The left and right insets are applied on every page, but the top inset is only applied on the first page. The bottom inset is ignored.
  • perPageContentInsets UIEdgeInsets (iOS 8 only): A set of insets from the edges of the page for every page of formatted content.
  • maximumContentWidth and maximumContentHeight CGFloat: If specified, these can further constrain the width and height of the content area.

Though not clearly documented by Apple, all of these values are based on 72 points per inch.

The two text-based print formatters are initialized with the text they will be formatting. UISimpleTextPrintFormatter can handle plain or attributed text, while UIMarkupTextPrintFormatter takes and renders HTML text in its markupText property. Let’s try sending an HTML version of our Swiss chard recipe through the markup formatter:

let formatter = UIMarkupTextPrintFormatter(markupText: htmlString)
formatter.contentInsets = UIEdgeInsets(top: 72, left: 72, bottom: 72, right: 72) // 1" margins

printController.printFormatter = formatter

The result? A handsomely rendered HTML page:

Print with UIMarkupTextPrintFormatter

On the other hand, to use a UIViewPrintFormatter, you retrieve one from the view you want to print via its viewPrintFormatter property. Here’s a look at how the formatter does its job for each of the three supported views:

1) UITextView

Print with UITextView

2) UIWebView

Print with UIWebView

3) MKMapView

Print with MKMapView

UIPrintPageRenderer

The built-in formatters are fine, but for the most control over the printed page, you can implement a subclass of UIPrintPageRenderer. In your subclass you can combine the print formatters we saw above with your own custom drawing routines to create terrific layouts for your app’s content. Let’s look at one more way of printing a recipe, this time using a page renderer to add a header and to draw the images alongside the text of the recipe.

In the initializer, we save the data that we’ll need to print, then set the headerHeight (the header and footer drawing methods won’t even be called unless you set their respective heights) and create a markup text formatter for the text of the recipe.

Complete Objective-C and Swift source code for the following examples is available as a gist.

class RecipePrintPageRenderer: UIPrintPageRenderer {
    let authorName: String
    let recipe: Recipe

    init(authorName: String, recipe: Recipe) {
        self.authorName = authorName
        self.recipe = recipe
        super.init()

        self.headerHeight = 0.5 * POINTS_PER_INCH
        self.footerHeight = 0.0 // default

        let formatter = UIMarkupTextPrintFormatter(markupText: recipe.html)
        formatter.perPageContentInsets = UIEdgeInsets(top: POINTS_PER_INCH, left: POINTS_PER_INCH,
            bottom: POINTS_PER_INCH, right: POINTS_PER_INCH * 3.5)
        addPrintFormatter(formatter, startingAtPageAtIndex: 0)
    }

    …
}

When you use one or more print formatters as part of your custom renderer (as we’re doing here), UIKit queries them for the number of pages to print. If you’re doing truly custom page layout, implement the numberOfPages() method to provide the correct value.

Next, we override drawHeaderForPageAtIndex(:inRect:) to draw our custom header. Unfortunately, those handy per-page content insets on print formatters are gone here, so we first need to inset the headerRect parameter to match my margins, then simply draw into the current graphics context. There’s a similar drawFooterForPageAtIndex(:inRect:) method for drawing the footer.

override func drawHeaderForPageAtIndex(pageIndex: Int, var inRect headerRect: CGRect) {
    var headerInsets = UIEdgeInsets(top: CGRectGetMinY(headerRect), left: POINTS_PER_INCH, bottom: CGRectGetMaxY(paperRect) - CGRectGetMaxY(headerRect), right: POINTS_PER_INCH)
    headerRect = UIEdgeInsetsInsetRect(paperRect, headerInsets)

    // author name on left
    authorName.drawAtPointInRect(headerRect, withAttributes: nameAttributes, andAlignment: .LeftCenter)

    // page number on right
    let pageNumberString: NSString = "\(pageIndex + 1)"
    pageNumberString.drawAtPointInRect(headerRect, withAttributes: pageNumberAttributes, andAlignment: .RightCenter)
}

Lastly, let’s provide an implementation of drawContentForPageAtIndex(:inRect:):

override func drawContentForPageAtIndex(pageIndex: Int, inRect contentRect: CGRect) {
    if pageIndex == 0 {
        // only use rightmost two inches of contentRect
        let imagesRectWidth = POINTS_PER_INCH * 2
        let imagesRectHeight = paperRect.height - POINTS_PER_INCH - (CGRectGetMaxY(paperRect) - CGRectGetMaxY(contentRect))
        let imagesRect = CGRect(x: CGRectGetMaxX(paperRect) - imagesRectWidth - POINTS_PER_INCH, y: paperRect.origin.y + POINTS_PER_INCH, width: imagesRectWidth, height: imagesRectHeight)

        drawImages(recipe.images, inRect: imagesRect)
    }
}

With the implementation of our custom page renderer complete, we can set an instance as the pageRenderer property on the print interaction controller and we’re ready to print.

let renderer = RecipePrintPageRenderer(authorName: "Nate Cook", recipe: selectedRecipe)
printController.printPageRenderer = renderer

The final result is much nicer than any of the built-in formatters.

Note that the text of the recipe is being formatted by a UIMarkupTextPrintFormatter, while the header and images are drawn via custom code.

Print with UIPrintPageRenderer subclass

Printing via a Share Sheet

With the tools we’ve learned above, adding printing capability in a share sheet is simple. Instead of using UIPrintInteractionController to present the printing UI, we pass off our configured UIPrintInfo and printing item(s), formatter, or renderer to a UIActivityViewController. If the user selects the Print button in the share sheet, the printing UI will be displayed with all our configurations intact.

@IBAction func openShareSheet() {
    let printInfo = ...
    let formatter = ...

    let activityItems = [printInfo, formatter, textView.attributedText]
    let activityController = UIActivityViewController(activityItems: activityItems, applicationActivities: nil)
    presentViewController(activityController, animated: true, completion: nil)
}

While UIPrintInfo and subclasses of UIPrintFormatter and UIPrintPageRenderer can be passed to a UIActivityViewController as activities, none of them seem to conform to the UIActivityItemSource protocol, so you’ll see a (harmless) warning in your console about “Unknown activity items.”

Skipping the Printing UI

New in iOS 8 is a way to print without any presentation of the printing UI. Instead of presenting the UI each time the user presses a print button, you can provide a way for your users to select a printer somewhere in your app with the easy-to-use UIPrinterPickerController. It accepts an optional UIPrinter instance in its constructor for a pre-selection, uses the same presentation options as explained above, and has a completion handler for when the user has selected her printer:

let printerPicker = UIPrinterPickerController(initiallySelectedPrinter: savedPrinter)
printerPicker.presentAnimated(true) {
    (printerPicker, userDidSelect, error) in

    if userDidSelect {
        self.savedPrinter = printerPicker.selectedPrinter
    }
}

Now you can tell your UIPrintInteractionController to print directly by calling printToPrinter(:completionHandler:) with the saved printer instead of using one of the present... methods.

As one final recommendation, consider the printed page as you would any other way of interacting with your content. In the same way you scrutinize font size and weight or the contrast between elements on screen, make sure to test your print layouts on paper—the contrast, size, and margins should all be appropriate to the medium.

NSMutableHipster

Questions? Corrections? Issues and pull requests are always welcome.

This article uses Swift version 1.0. Find status information for all articles on the status page.

Written by Nate Cook
Nate Cook

Nate Cook (@nnnnnnnn) is an independent web and application developer who writes frequently about topics in Swift, and the creator of SwiftDoc.org.

Next Article

After taking a look at WatchKit, there were a few things that jumped out coming from UIKit. They’re the kind of subjective, opinionated things that don’t make for good documentation, but might be interesting or useful to anyone else as they’re getting started.