The Printing User Interface

The first thing a user sees related to printing is a print button. The print button is often a bar-button item on a navigation bar or a toolbar. The print button should logically apply to the content the app is presenting; if the user taps the button, the app should print that content. Although the print button can be any custom button, it is recommended that you use the system item-action button shown in Figure 5-1. This is a UIBarButtonItem object, specified with the UIBarButtonSystemItemAction constant, that you create either in Interface Builder or by calling initWithBarButtonSystemItem:target:action:.

When a user taps the print button, a controller object of the app receives the action message. The controller responds by preparing for printing and displaying the printer-options view. The options always include the destination printer (selected from a list of discoverable printers), the number of copies, and sometimes the range of pages to print. If the selected printer is capable of duplex printing, users can choose single-sided or double-sided output. If users decide not to print, they tap outside the options view (on iPad) or tap the Cancel button (on iPhone and iPod touch) to dismiss the printer-options view.

The kind of user interface shown depends on the device. On iPad, the UIKit framework displays a popover view containing the options, as shown in Figure 5-2. An app can animate this view to appear from the print button or from an arbitrary area of the app’s user interface.

On iPhone and iPod touch devices, UIKit displays a sheet of printing options that an app can animate to slide up from the bottom of the screen, as shown in Figure 5-3.

Once a print job has been submitted and is either printing or waiting in the print queue, users can check on its status by double-tapping the Home button to access the Print Center in the multitasking UI. The Print Center (shown in Figure 5-4) is a background system app that shows the order of jobs in the print queue, including those that are currently printing. It is only available while a print job is in progress.

Users can tap a print job in the Print Center to get detailed information about it (Figure 5-5) and cancel jobs that are printing or waiting in the queue.

How Printing Works in iOS

An app uses the UIKit printing API to assemble the elements of a print job, including the content to print and information related to the print job. It then presents the printer-options view described in The Printing User Interface. The user makes his or her choices and then taps Print. In some cases, the UIKit framework then asks the app to draw the content to be printed; UIKit records what the app draws as PDF data. UIKit then hands off the printing data to the printing subsystem.

The printing system does a few things. As UIKit passes the print data to the printing subsystem, it writes this data to storage (that is, it spools the data). It also captures information about the print job. The printing system manages the combined print data and metadata for each print job in a first-in-first-out print queue. Multiple apps on a device can submit multiple print jobs to the printing subsystem, and all of these are placed in the print queue. Each device has one queue for all print jobs regardless of originating app or destination printer.

When a print job rises to the top of the queue, the system printing daemon (printd) considers the destination printer's requirements and, if necessary, converts the print data to a form that is usable by the printer. The printing system reports error conditions such as "Out of Paper" to the user as alerts. It also reports the progress of print jobs programmatically to the Print Center, which displays information such as “page 2 of 5” for a print job.

This overall architecture is shown in Figure 5-6.

Printing Support Overview

At a high level, there are two ways to add printing to your app. If you are using a UIActivityViewController, and if you do not need the ability to control whether the user can choose a page range or override the paper selection process, you can add a printing activity.

Otherwise, to add printing to your app, you must work with the UIPrintInteractionController class. A shared instance of the UIPrintInteractionController class provides your app with the ability to specify what should happen when the user tells your app to print. It contains information about the print job (UIPrintInfo) and the size of the paper and the area for the printed content (UIPrintPaper). It can also have a reference to a delegate object that adopts the UIPrintInteractionControllerDelegate protocol for further configuring behavior.

More importantly, the print interaction controller lets your app provide the content to be printed. The UIPrintInteractionController class provides three distinct ways to print content:

• Static images or PDFs. For simple content, you can use the print interaction controller’s printingItem or printingItems properties to provide an image (in various formats), a PDF file, or an array of images and PDF files.

• Print formatters. If you need to print text and HTML content with automatic reflow, you can assign an instance of any of the built-in print formatter classes to the print interaction controller’s printFormatter property.

• Page renderers. Page renderers let you provide your own drawing routines for custom content, and give you complete control over the page layout, including headers and footers. To use a page renderer, you must first write a page renderer subclass, then assign an instance of it to the print interaction controller’s printPageRenderer property.

With such a range of options available to you, what is the best option for your app? Table 5-1 clarifies the factors involved in making this decision.

Printing Workflow

The general workflow for printing an image, document, or other printable content of an app is as follows:

1. Obtain the shared instance of UIPrintInteractionController.

2. (Optional, but strongly recommended) Create a UIPrintInfo object, set attributes such as output type, job name, and print orientation; then assign the object to the printInfo property of the UIPrintInteractionController instance. (Setting the output type and job name are strongly recommended.)

   If you don’t assign a print-info object, UIKit assumes default attributes for the print job (for example, the job name is the app name).

3. (Optional) Assign a custom controller object to the delegate property. This object must adopt the UIPrintInteractionControllerDelegate protocol. The delegate can do a range of tasks. It can respond appropriately when printing options are presented and dismissed, and when the print job starts and ends. It can return a parent view controller for the print interaction controller.

   Also, by default, UIKit chooses a default paper size and printable area based on the output type, which indicates the kind of content your app is printing. If your app needs more control over paper size, you can override this standard behavior. See Specifying Paper Size, Orientation, and Duplexing Options for more details.

4. Assign one of the following to a property of the UIPrintInteractionController instance:

   • A single NSData, NSURL, UIImage, or ALAsset object containing or referencing PDF data or image data to the printingItem property.

   • An array of directly printable images or PDF documents to the printingItems property. Array elements must be NSData, NSURL, UIImage, or ALAsset objects containing, referencing, or representing PDF data or images in supported formats.

   • A UIPrintFormatter object to the printFormatter property. Print formatters perform custom layout of printable content.

   • A UIPrintPageRenderer object to the printPageRenderer property.

   Only one of these properties can be non-nil for any print job. See Printing Support Overview for descriptions of these properties.

5. If you assigned a page renderer in the previous step, that object is typically an instance of a custom subclass of UIPrintPageRenderer. This object draws pages of content for printing when requested by the UIKit framework. It can also draw content in headers and footers of printed pages. A custom page renderer must override one or more of the “draw” methods and, if it is drawing at least part of the content (excluding headers and footers), it must compute and return the number of pages for the print job. (Note that you can use an instance of UIPrintPageRenderer “as-is” to connect a series of print formatters.)

6. (Optional) If you are using a page renderer, you can create one or more UIPrintFormatter objects using concrete subclasses of this class; then add the print formatters for specific pages (or page ranges) to the UIPrintPageRenderer instance either by calling the addPrintFormatter:startingAtPageAtIndex: method of UIPrintPageRenderer or by creating an array of one or more print formatters (each with its own starting page) and assigning that array to the printFormatters property of UIPrintPageRenderer.

7. If the current user-interface idiom is iPad, present the printing interface to the user by calling presentFromBarButtonItem:animated:completionHandler: or presentFromRect:inView:animated:completionHandler:; if the idiom is iPhone or iPod touch, call presentAnimated:completionHandler:. Alternatively, you can embed the printing UI into your existing UI by implementing a printInteractionControllerParentViewController: delegate method. If your app uses an activity sheet (in iOS 6.0 and later), you can also add a printing activity item.

From here, the process varies depending on whether you are printing using static content, a print formatter, or a page renderer.

Setting the Layout Properties for the Print Job

To define the areas on pages for printable content, the UIPrintFormatter class declares four key properties for its concrete subclasses. These properties, along with the footerHeight and headerHeight properties of UIPrintPageRenderer and the paperSize and printableRect properties of UIPrintPaper, define the layout of a multi-page print job. Figure 5-8 depicts this layout.

UIPrintFormatter uses all the properties depicted in the diagram in Figure 5-8 to compute the number of pages needed for the print job; it stores this value in the read-only pageCount property.

Using a Print Formatter

UIKit allows you to assign a single print formatter for a print job. This can be a useful capability if you have plain-text or HTML documents, because UIKit has concrete print-formatter classes for these types of textual content. The framework also implements a concrete print-formatter subclass that enables you to print the content of certain UIKit views in a printer-friendly way.

The UIPrintFormatter class is the abstract base class for the system-provided print formatters. Currently, iOS provides the following built-in print formatters:

• UIViewPrintFormatter—automatically lays out the content of a view over multiple pages.

  To obtain a print formatter for a view, call the view’s viewPrintFormatter method.

  Not all built-in UIKit classes support printing. Currently, only the view classes UIWebView, UITextView, and MKMapView know how to draw their contents for printing.

  View formatters should not be used for printing your own custom views. To print the contents of a custom view, use a UIPrintPageRenderer instead.

• UISimpleTextPrintFormatter—automatically draws and lays out plain-text documents. This formatter allows you to set global properties for the text, such a font, color, alignment, and line-break mode.

• UIMarkupTextPrintFormatter—automatically draws and lays out HTML documents.

Although the following discussion pertains to the use of a single formatter (and no page renderer), much of the information about print formatters applies to print formatters used in conjunction with page renderers, which is described in Using One or More Formatters with a Page Renderer.

- (IBAction)printContent:(id)sender {

    UIPrintInteractionController *pic = [UIPrintInteractionController sharedPrintController];

    pic.delegate = self;

    UIPrintInfo *printInfo = [UIPrintInfo printInfo];

    printInfo.outputType = UIPrintInfoOutputGeneral;

    printInfo.jobName = self.documentName;

    pic.printInfo = printInfo;

    UIMarkupTextPrintFormatter *htmlFormatter = [[UIMarkupTextPrintFormatter alloc]

        initWithMarkupText:self.htmlString];

    htmlFormatter.startPage = 0;

    htmlFormatter.contentInsets = UIEdgeInsetsMake(72.0, 72.0, 72.0, 72.0); // 1 inch margins

    pic.printFormatter = htmlFormatter;

    pic.showsPageRange = YES;

    void (^completionHandler)(UIPrintInteractionController *, BOOL, NSError *) =

         ^(UIPrintInteractionController *printController, BOOL completed, NSError *error) {

             if (!completed && error) {

                 NSLog(@"Printing could not complete because of error: %@", error);

             }

         };

    if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) {

        [pic presentFromBarButtonItem:sender animated:YES completionHandler:completionHandler];

    } else {

        [pic presentAnimated:YES completionHandler:completionHandler];

    }

}

- (void)printWebPage:(id)sender {

    UIPrintInteractionController *controller = [UIPrintInteractionController sharedPrintController];

    void (^completionHandler)(UIPrintInteractionController *, BOOL, NSError *) =

        ^(UIPrintInteractionController *printController, BOOL completed, NSError *error) {

        if(!completed && error){

            NSLog(@"FAILED! due to error in domain %@ with error code %u",

            error.domain, error.code);

        }

    };

    UIPrintInfo *printInfo = [UIPrintInfo printInfo];

    printInfo.outputType = UIPrintInfoOutputGeneral;

    printInfo.jobName = [urlField text];

    printInfo.duplex = UIPrintInfoDuplexLongEdge;

    controller.printInfo = printInfo;

    controller.showsPageRange = YES;

    UIViewPrintFormatter *viewFormatter = [self.myWebView viewPrintFormatter];

    viewFormatter.startPage = 0;

    controller.printFormatter = viewFormatter;

    if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) {

        [controller presentFromBarButtonItem:printButton animated:YES completionHandler:completionHandler];

    }else

        [controller presentAnimated:YES completionHandler:completionHandler];

}

Using a Page Renderer

A page renderer is an instance of a custom subclass of UIPrintPageRenderer that draws the full or partial content of a print job. To use one, you must create the subclass, add it to your project, and instantiate it when you prepare a UIPrintInteractionController instance for a print job. Then assign the page renderer to the printPageRenderer property of the UIPrintInteractionController instance. A page renderer can have one or more print formatters associated with it; if it does, it mixes its drawing with the drawing of the print formatters.

A page renderer can draw and lay out printable content on its own or it can use print formatters to handle some or all of the rendering of specific ranges of pages. Thus, for relatively straightforward formatting needs, you can use an instance of UIPrintPageRenderer “as-is” to connect multiple print formatters. However, most page renderers are typically instances of custom subclasses of UIPrintPageRenderer.

The UIPrintPageRenderer base class includes properties for the page count and for heights of headers and footers of pages. It also declares several methods that you can override to draw specific portions of a page: the header, the footer, the content itself, or to integrate page renderer and print formatter drawing.

- (void)drawHeaderForPageAtIndex:(NSInteger)pageIndex  inRect:(CGRect)headerRect {

    UIFont *font = [UIFont fontWithName:@"Helvetica" size:12.0];

    CGSize titleSize = [self.jobTitle sizeWithFont:font];

    //center title in header

    CGFloat drawX = CGRectGetMaxX(headerRect)/2 - titleSize.width/2;

    CGFloat drawY = CGRectGetMaxY(headerRect) - titleSize.height;

    CGPoint drawPoint = CGPointMake(drawX, drawY);

    [self.jobTitle drawAtPoint:drawPoint withFont: font];

}

- (void)drawFooterForPageAtIndex:(NSInteger)pageIndex  inRect:(CGRect)footerRect {

    UIFont *font = [UIFont fontWithName:@"Helvetica" size:12.0];

    NSString *pageNumber = [NSString stringWithFormat:@"%d.", pageIndex+1];

    // page number at right edge of footer rect

    CGSize pageNumSize = [pageNumber sizeWithFont:font];

    CGFloat drawX = CGRectGetMaxX(footerRect) - pageNumSize.width - 1.0;

    CGFloat drawY = CGRectGetMaxY(footerRect) - pageNumSize.height;

    CGPoint drawPoint = CGPointMake(drawX, drawY);

    [pageNumber drawAtPoint:drawPoint withFont: font];

}

Testing for Printing Availability

Some iOS devices do not support printing. You should immediately determine this fact once your view loads. If printing is not available for the device, you should either not programmatically add any printing user-interface element (button, bar button item, and so on), or you should remove any printing element loaded from a nib file. To determine if printing is available, call the isPrintingAvailable class method of UIPrintInteractionController. Listing 5-5 illustrates how you might do this; it assumes an outlet to a print button (myPrintButton) loaded from a nib file.

Listing 5-5  Enabling or disabling a print button based on availability of printing

- (void)viewDidLoad {

    if (![UIPrintInteractionController isPrintingAvailable])

        [myPrintButton removeFromSuperView];

    // other tasks...

}

Specifying Print-Job Information

An instance of the UIPrintInfo class encapsulates information about a print job, specifically:

• The output type (indicating the type of content)

• The print-job name

• The printing orientation

• The duplex mode

• The identifier of the selected printer

You do not need to assign values to all UIPrintInfo properties; users choose some of these values and UIKit assumes default values for others. (Indeed, you don’t even have to explicitly create an instance of UIPrintInfo.)

However, in most cases you’ll want to specify some aspects of a print job, such as output type. Get an instance of UIPrintInfo by calling the printInfo class method. Assign values to the object’s properties you want to configure. Then assign the UIPrintInfo object to the printInfo property of the shared UIPrintInteractionController instance. Listing 5-6 gives an example of this procedure.

Listing 5-6  Setting properties of a UIPrintInfo object and assigning it to the printInfo property

UIPrintInteractionController *controller = [UIPrintInteractionController sharedPrintController];

UIPrintInfo *printInfo = [UIPrintInfo printInfo];

printInfo.outputType = UIPrintInfoOutputGeneral;

printInfo.jobName = [self.path lastPathComponent];

printInfo.duplex = UIPrintInfoDuplexLongEdge;

controller.printInfo = printInfo;

One of the UIPrintInfo properties is the printing orientation: portrait or landscape. You might want the printing orientation to suit the dimensions of the object being printed. In other words, if the object is large, and its width is greater than its height, landscape would be a suitable printing orientation for it. Listing 5-7 illustrates this with an image.

Listing 5-7  Setting the printing orientation to match image dimension

  UIPrintInteractionController *controller = [UIPrintInteractionController sharedPrintController];

// other code here...

  UIPrintInfo *printInfo = [UIPrintInfo printInfo];

  UIImage *image = ((UIImageView *)self.view).image;

  printInfo.outputType = UIPrintInfoOutputPhoto;

  printInfo.jobName = @"Image from PrintPhoto";

  printInfo.duplex = UIPrintInfoDuplexNone;

  // only if drawing...

  if (!controller.printingItem && image.size.width > image.size.height)

    printInfo.orientation = UIPrintInfoOrientationLandscape;

Specifying Paper Size, Orientation, and Duplexing Options

By default, UIKit presents a set of default paper sizes for printable content based on the destination printer and the output type of the print job, as specified by the outputType property of the UIPrintInfo object.

For example, if the output type is UIPrintInfoOutputPhoto, the default paper size is 4 x 6 inches, A6, or some other standard size, depending on locale; if the output type is UIPrintInfoOutputGeneral or UIPrintInfoOutputGrayscale, the default paper size is US Letter (8 1/2 x 11 inches), A4, or some other standard size, depending on locale.

For most apps, these default paper sizes are acceptable. However, some apps might need a special paper size. A page-based app might need to show the user how content will actually appear on paper of a given size, an app that produces brochures or greeting cards might have its own preferred size, and so on.

In this case, the delegate of the print interaction controller can implement the UIPrintInteractionControllerDelegate protocol method printInteractionController:choosePaper: to return a UIPrintPaper object representing the optimal combination of available paper size and printable rectangle for a given content size.

The delegate has two approaches it can take. It can examine the passed-in array of UIPrintPaper objects and identify the one that is most suitable. Or it can let the system pick the most suitable object by calling the UIPrintPaper class method bestPaperForPageSize:withPapersFromArray:. Listing 5-8 shows an implementation of the method for an app that supports multiple document types, each with its own page size.

Listing 5-8  Implementing the printInteractionController:choosePaper: method

- (UIPrintPaper *)printInteractionController:(UIPrintInteractionController *)pic

    choosePaper:(NSArray *)paperList {

    // custom method & properties...

    CGSize pageSize = [self pageSizeForDocumentType:self.document.type];

    return [UIPrintPaper bestPaperForPageSize:pageSize

        withPapersFromArray:paperList];

}

Typically, apps that use custom page renderers factor the paper size into their calculations of the number of pages for a print job (numberOfPages).

If your app needs to present the user with a choice of page size (for a word processing app, for example), you must implement that UI yourself, and you must then use that paper size in your printInteractionController:choosePaper: implementation. For example:

// Create a custom CGSize for 8.5" x 11" paper.

CGSize custompapersize = CGSizeMake(8.5 * 72.0, 11.0 * 72.0);

The UIPrintInfo class also lets you provide additional settings, such as the printing orientation, selected printer, and the duplexing mode (if the printer supports duplex printing). Users can change the selected printer and duplex settings from the values you provide

Integrating Printing Into Your User Interface

There are two ways to integrate printing into your user interface:

• Using a print interaction controller.

• From the activity sheet (in iOS 6.0 and later).

The way you integrate printing depends on which of these techniques you choose.

if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) {

    [controller presentFromBarButtonItem:self.printButton animated:YES

        completionHandler:completionHandler];

} else {

    [controller presentAnimated:YES completionHandler:completionHandler];

}

Responding to Print-Job Completion and Errors

The final parameter of the presentation methods declared by UIPrintInteractionController and described in Presenting Printing Options Using a Print Interaction Controller is a completion handler. The completion handler is a block of type UIPrintInteractionCompletionHandler that is invoked when a print job completes successfully or when it is terminated because of an error. You can provide a block implementation that cleans up state that you have set up for the print job. The completion handler can also log error messages.

The example in Listing 5-10 clears an internal property upon completion or error; if there is an error, it logs information about it.

Listing 5-10  Implementing a completion-handler block

void (^completionHandler)(UIPrintInteractionController *, BOOL, NSError *) =

        ^(UIPrintInteractionController *pic, BOOL completed, NSError *error) {

    self.content = nil;

    if (!completed && error)

        NSLog(@"FAILED! due to error in domain %@ with error code %u",

            error.domain, error.code);

  };

UIKit automatically releases all objects assigned to the UIPrintInteractionController instance at the end of a print job (except for the delegate), so you do not have to do this yourself in a completion handler.

A printing error is represented by an NSError object having a domain of UIPrintErrorDomain and an error code declared in UIPrintError.h. In almost all cases, these codes indicate programming errors, so usually there is no need to inform the user about them. However, some errors can result from an attempt to print a file (located by a file-scheme NSURL object) that results in an error.