iOS Developer Library

Developer

UIKit Framework Reference UIPrintInteractionController Class Reference

Options
Deployment Target:

On This Page
Language:

UIPrintInteractionController

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 4.2 and later.

The shared instance of the UIPrintInteractionController class presents a printing user interface and manages the printing of documents, images, and other printable content in iOS.

UIPrintInteractionController is the central class for printing in iOS. The shared instance of it represents a print job. A print job includes the content to be printed and information and options related to its printing, such as output type, job name, paper size, and orientation.

UIPrintInteractionController has four mutually exclusive properties for giving it the content to be printed:

  • printingItem takes a single print-ready object.

  • printingItems takes an array of print-ready objects.

  • printFormatter takes a print formatter, an object that knows how to lay out content of a certain type.

  • printPageRenderer takes a page renderer, a custom object that draws the content for printing.

If the showsPageRange property is set to YEStrue, the number of pages is more than 1, and you assign an object to any of these properties except for the printingItems property, the printing options include a control that allows users to select a page range.

When users tap a print button on the application’s user interface, a controller object of the application should respond to the action message by obtaining the shared instance of UIPrintInteractionController and preparing it for the print job. When the application calls one of the present... methods (for example, presentAnimated:completionHandler:), UIPrintInteractionController displays a view containing printing options. This interface is simple, allowing users to select a printer, specify the number of copies and possibly a range of pages, and choose single-sided or double-sided printing (if the printer supports duplex printing). When users make their selections and tap Print, the print job begins.

  • Returns the shared print-interaction controller object.

    Declaration

    Swift

    class func sharedPrintController() -> UIPrintInteractionController?

    Objective-C

    + (UIPrintInteractionController *)sharedPrintController

    Return Value

    The singleton instance of the UIPrintInteractionController class or nil if the object could not be created.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Returns a Boolean indicating whether the device supports printing.

    Declaration

    Swift

    class func isPrintingAvailable() -> Bool

    Objective-C

    + (BOOL)isPrintingAvailable

    Return Value

    YEStrue if the device supports printing, otherwise NOfalse. An application can show or hide any print buttons based on this value.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Returns whether UIKit can print the contents of a data object.

    Declaration

    Swift

    class func canPrintData(_ data: NSData) -> Bool

    Objective-C

    + (BOOL)canPrintData:(NSData *)data

    Parameters

    data

    An instance of the NSData class that contains PDF data or an image in a format supported by the Image I/O framework. See Supported Image Formats in View Programming Guide for iOS for a list of the supported image formats.

    Return Value

    YEStrue if UIKit can print the contents of the data object, otherwise NOfalse. The method returns NOfalse if data is PDF data that specifies that printing is not allowed.

    Discussion

    You should call this method to test a data object prior to assigning it to printingItem or printingItems.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Returns whether UIKit can print the file referenced by a URL.

    Declaration

    Swift

    class func canPrintURL(_ url: NSURL) -> Bool

    Objective-C

    + (BOOL)canPrintURL:(NSURL *)url

    Parameters

    url

    An object representing a URL. Valid NSURL objects must use the file: or assets-library: scheme or any scheme that can return an NSData object with a registered protocol. The file referenced by the URL must contain PDF data or an image in a format supported by the Image I/O framework. See Supported Image Formats in View Programming Guide for iOS for a list of the supported image formats.

    Return Value

    YEStrue if UIKit can print the contents of the referenced file, otherwise NOfalse. The method returns NOfalse if url references PDF data that specifies that printing is not allowed.

    Discussion

    You should call this method to test the data referenced by a URL prior to assigning that URL to printingItem or printingItems.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Returns a set of the Uniform Type Identifiers for the types of data that UIKit can print.

    Declaration

    Swift

    class func printableUTIs() -> Set<NSObject>

    Objective-C

    + (NSSet *)printableUTIs

    Return Value

    A set object that contains, as strings, the UTIs identifying data types that UIKit knows how to print natively.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • A single ready-to-print object.

    Declaration

    Swift

    @NSCopying var printingItem: AnyObject!

    Objective-C

    @property(nonatomic, copy) id printingItem

    Discussion

    The object must be an instance of the NSURL, NSData, UIImage, or ALAsset class. An object of the first two types must reference or contain image data or PDF data. NSURL objects must use the file: or assets-library: scheme or any scheme that can return an NSData object with a registered protocol. Image data (including that encapsulated by UIImage an ALAsset objects) must be in a format supported by the Image I/O framework; see Supported Image Formats in UIImage Class Reference for more information. An ALAsset object must be of type ALAssetTypePhoto. The object is released at the end of the print job. The default value is nil.

    If you set this property, UIPrintInteractionController sets the printingItems, printPageRenderer, and printFormatter properties to nil. (Only one of these properties can be set for a print job.)

    If this property is set and the showsPageRange property is set to YEStrue—and the printing item is a PDF document of more than one page—the printing options include the control for selecting a page range.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • An array of ready-to-print objects.

    Declaration

    Swift

    var printingItems: [AnyObject]!

    Objective-C

    @property(nonatomic, copy) NSArray *printingItems

    Discussion

    The array must contain NSURL, NSData, UIImage, or ALAsset objects in any combination. Objects of the first two types must reference or contain image data or PDF data. NSURL objects must use the file: or assets-library: scheme or any scheme that can return an NSData object with a registered protocol. Image data (including that encapsulated by UIImage and ALAsset objects) must be in a format supported by the Image I/O framework; see Supported Image Formats in UIImage Class Reference for more information. An ALAsset object must be of type ALAssetTypePhoto. Items are printed in array-index order. The array is released at the end of the print job. The default value is nil.

    If you set this property, UIPrintInteractionController sets the printingItem, printPageRenderer, and printFormatter properties to nil. (Only one of these properties can be set for a print job.)

    If this property is set, the printing options do not include the control for selecting a page range, even if the showsPageRange property is set to YEStrue. If you want page-range selection, you should use the printingItem property instead.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • An object that draws pages of printable content when requested by UIKit.

    Declaration

    Swift

    var printPageRenderer: UIPrintPageRenderer!

    Objective-C

    @property(nonatomic, retain) UIPrintPageRenderer *printPageRenderer

    Discussion

    The object assigned to this property must be an instance of a custom subclass of UIPrintPageRenderer. The UIPrintInteractionController class retains the page-renderer object and releases it at the end of the print job. The default value is nil.

    If you set this property, UIPrintInteractionController sets the printingItems, printingItem, printFormatter properties to nil. (Only one of these properties can be set for a print job.)

    If this property is set and the showsPageRange property is set to YEStrue—and the rendered content is greater than one page—the printing options include the control for selecting a page range.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • An object that lays out the content of pages based on the kind of content.

    Declaration

    Swift

    var printFormatter: UIPrintFormatter!

    Objective-C

    @property(nonatomic, retain) UIPrintFormatter *printFormatter

    Discussion

    Assign to this property an instance of one of the concrete subclasses of UIPrintFormatter: UISimpleTextPrintFormatter, UIMarkupTextPrintFormatter, and UIViewPrintFormatter. This object is released at the end of the print job.

    If you set this property, UIPrintInteractionController sets the printingItems, printingItem, and printPageRenderer properties to nil. (Only one of these properties can be set for a print job.)

    If this property is set and the showsPageRange property is set to YEStrue—and if the formatter represents content of more than one page—the printing options include the control for selecting a page range.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Presents the iPhone printing user interface in a sheet that can be animated to slide up from the bottom of the screen.

    Declaration

    Swift

    func presentAnimated(_ animated: Bool, completionHandler completion: UIPrintInteractionCompletionHandler?) -> Bool

    Objective-C

    - (BOOL)presentAnimated:(BOOL)animated completionHandler:(UIPrintInteractionCompletionHandler)completion

    Parameters

    animated

    YEStrue to animate the display of the sheet, NOfalse to display the sheet immediately.

    completion

    A block of type UIPrintInteractionCompletionHandler that you implement to handle the conclusion of the print job (for instance, to reset state) and to handle any errors encountered in printing.

    Discussion

    It is valid to call this method for applications on iPhone and iPod touch devices. Calling this method on an iPad with animated set to YEStrue causes the printing options view to animate from the window frame.

    If you call this method when the printing options are already displayed, UIPrintInteractionController hides the printing-options sheet. You must call the method again to display the options.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Presents the iPad printing user interface in a popover view that can be animated from a bar-button item.

    Declaration

    Swift

    func presentFromBarButtonItem(_ item: UIBarButtonItem, animated animated: Bool, completionHandler completion: UIPrintInteractionCompletionHandler?) -> Bool

    Objective-C

    - (BOOL)presentFromBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated completionHandler:(UIPrintInteractionCompletionHandler)completion

    Parameters

    item

    The UIBarButtonItem object that the user tapped for printing. You are encouraged to use the constant UIBarButtonSystemItemAction when creating a bar-button item for this purpose.

    animated

    YEStrue to animate the printing popover view from item, NOfalse to display it immediately.

    completion

    A block of type UIPrintInteractionCompletionHandler that you implement to handle the conclusion of the print job (for instance, to reset state) and to handle any errors encountered in printing.

    Discussion

    It is valid to call this method for applications on iPad devices. Calling this method on an iPhone or iPod touch with animated set to YEStrue causes the printing options view to animate upward from the bottom of the screen.

    If you call this method when the printing options are already displayed, UIPrintInteractionController hides the printing-options popover view. You must call the method again to display the options.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Presents the iPad printing user interface in a popover view that can be animated from any area in a view.

    Declaration

    Swift

    func presentFromRect(_ rect: CGRect, inView view: UIView, animated animated: Bool, completionHandler completion: UIPrintInteractionCompletionHandler?) -> Bool

    Objective-C

    - (BOOL)presentFromRect:(CGRect)rect inView:(UIView *)view animated:(BOOL)animated completionHandler:(UIPrintInteractionCompletionHandler)completion

    Parameters

    rect

    A rectangle that defines the area from which the printing popover view is animated.

    view

    The view providing the coordinate system for rect.

    animated

    YEStrue to animate the printing popover view from item, NOfalse to display it immediately.

    completion

    A block of type UIPrintInteractionCompletionHandler that you implement to handle the conclusion of the print job (for instance, to reset state) and to handle any errors encountered in printing.

    Discussion

    It is valid to call this method for applications on iPad devices. Calling this method on an iPhone or iPod touch with animated set to YEStrue causes the printing options view to animate upward from the bottom of the screen.

    If you call this method when the printing options are already displayed, UIPrintInteractionController hides the printing-options popover view. You must call the method again to display the options.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Dismisses the printing-options sheet or popover.

    Declaration

    Swift

    func dismissAnimated(_ animated: Bool)

    Objective-C

    - (void)dismissAnimated:(BOOL)animated

    Parameters

    animated

    YEStrue to animate the dismissal, otherwise NOfalse.

    Discussion

    You should dismiss the printing options when they are presented in a sheet or animated from a rectangle and the user changes the orientation of the device. (This, of course, assumes your application responds to orientation changes.) You should then present the printing options again once the new orientation takes effect. You can observe the UIApplicationWillChangeStatusBarOrientationNotification notification to find out when the device orientation is about to change.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • Print directly to the specified printer.

    Declaration

    Swift

    func printToPrinter(_ printer: UIPrinter, completionHandler completion: UIPrintInteractionCompletionHandler?) -> Bool

    Objective-C

    - (BOOL)printToPrinter:(UIPrinter *)printer completionHandler:(UIPrintInteractionCompletionHandler)completion

    Parameters

    printer

    The printer to use for printing. You can obtain a list of available printers using a UIPrinterPickerController object.

    completion

    The block to execute when the print operation finishes.

    Return Value

    YEStrue if printing was successful or NOfalse if there was a problem.

    Discussion

    This method starts the print job and displays the printing progress indicator to the user. This method associates the current printing information (available in the printInfo property) with the job but disables duplex printing. Upon completion of the print job, the print interaction controller executes the block in the completion parameter.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • printInfo printInfo Property

    An object encapsulating information about the print job.

    Declaration

    Swift

    var printInfo: UIPrintInfo!

    Objective-C

    @property(nonatomic, retain) UIPrintInfo *printInfo

    Discussion

    An instance of UIPrintInfo includes properties such as the print-job name, the printer identifier, the orientation of the printed content, the duplex mode, and the kind of content (general, photo, or grayscale). If you do not assign an instance of UIPrintInfo to this property, the UIKit printing system assumes defaults for many of these properties. Users can modify the selected printer and the duplex mode (if available on the printer). Once the printing options are presented, any changes to the UIPrintInfo object referenced by this property are ignored. The object is released when printing completes.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

    See Also

    printPaper

  • An object representing the paper size and printing area for the print job. (read-only)

    Declaration

    Swift

    var printPaper: UIPrintPaper! { get }

    Objective-C

    @property(nonatomic, readonly) UIPrintPaper *printPaper

    Discussion

    UIPrintInteractionController sets this property immediately after the user selects a printer and before it calls the delegate’s printInteractionControllerWillStartJob: method. If its delegate implements the printInteractionController:choosePaper: method of the UIPrintInteractionControllerDelegate protocol, it can return the UIPrintPaper object to assign to this property. Otherwise, UIKit assigns an object with a default paper size and printing rectangle that is based on the output type and the capabilities of the destination printer. This object is released when the print job finishes.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

    See Also

    printInfo

  • A Boolean value that determines whether the printing options include the number of copies.

    Declaration

    Swift

    var showsNumberOfCopies: Bool

    Objective-C

    @property(nonatomic) BOOL showsNumberOfCopies

    Discussion

    The default value is YEStrue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • A Boolean value that determines whether the printing options include a page-range control.

    Declaration

    Swift

    var showsPageRange: Bool

    Objective-C

    @property(nonatomic) BOOL showsPageRange

    Discussion

    The default value is NOfalse. If you assign printable content to the printingItems property, the page-range control is not shown, even if showPageRange is YEStrue. In other cases, the number of pages to print must be greater than 1 form the page-range control to appear.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • A Boolean value for enabling the paper selection menu.

    Declaration

    Swift

    var showsPaperSelectionForLoadedPapers: Bool

    Objective-C

    @property(nonatomic) BOOL showsPaperSelectionForLoadedPapers

    Discussion

    The default value of this property is NOfalse. Setting the value to YEStrue enables a paper selection menu on printers that support different types of paper and have more than one paper type loaded. On printers where only one paper type is available, no paper selection menu is displayed, regardless of the value of this property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • delegate delegate Property

    The delegate of the print interaction controller.

    Declaration

    Swift

    unowned(unsafe) var delegate: UIPrintInteractionControllerDelegate?

    Objective-C

    @property(nonatomic, assign) id< UIPrintInteractionControllerDelegate > delegate

    Discussion

    The delegate must adopt the UIPrintInteractionControllerDelegate protocol and implement one or more of its methods. It is not retained.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

Data Types

  • The type of block callback for responding to the completion of a print job or handing printing errors.

    Declaration

    Swift

    typealias UIPrintInteractionCompletionHandler = (UIPrintInteractionController!, Bool, NSError!) -> Void

    Objective-C

    typedef void (^UIPrintInteractionCompletionHandler) (UIPrintInteractionController *printInteractionController,BOOL completed, NSError *error);

    Discussion

    You implement this block as the final argument of presentAnimated:completionHandler:, presentFromBarButtonItem:animated:completionHandler:, or presentFromRect:inView:animated:completionHandler:. When a print job concludes, you can reset any state set up for printing and do related housekeeping tasks. If the print job encountered an error, it is likely to be a programming error, so you might want to log the error for debugging purposes.

    printInteractionController

    The shared instance of UIPrintInteractionController that is managing the print job.

    completed

    A Boolean value that indicates whether the print job completed successfully.

    error

    An instance of the NSError that contains information about the printing error. The printing domain is UIPrintErrorDomain. The printing error codes are described in UIKit Printing Error Codes. If the print job completes successfully, this parameter is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 4.2 and later.

  • The error domain for printer errors

    Declaration

    Swift

    let UIPrintErrorDomain: String

    Objective-C

    UIKIT_EXTERN NSString *const UIPrintErrorDomain;

    Constants

    • UIPrintErrorDomain

      UIPrintErrorDomain

      The string constant defining the UIKit printing error domain.

      Available in iOS 4.2 and later.

  • Error codes for UIKit printing errors.

    Declaration

    Swift

    var UIPrintingNotAvailableError: Int { get } var UIPrintNoContentError: Int { get } var UIPrintUnknownImageFormatError: Int { get } var UIPrintJobFailedError: Int { get }

    Objective-C

    enum { UIPrintingNotAvailableError = 1, UIPrintNoContentError, UIPrintUnknownImageFormatError, UIPrintJobFailedError, };

    Constants

    • UIPrintingNotAvailableError

      UIPrintingNotAvailableError

      The device does not support printing.

      Available in iOS 4.2 and later.

    • UIPrintNoContentError

      UIPrintNoContentError

      No print formatter, page renderer, printing item or printing items was assigned for printing.

      Available in iOS 4.2 and later.

    • UIPrintUnknownImageFormatError

      UIPrintUnknownImageFormatError

      An image is in a format not recognized by UIKit for printing.

      Available in iOS 4.2 and later.

    • UIPrintJobFailedError

      UIPrintJobFailedError

      An internal error occurred with the print job.

      Available in iOS 4.2 and later.