UIPrintInteractionController Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 4.2 and later.
Companion guide
Drawing and Printing Guide for iOS
Declared in
UIPrintError.h
UIPrintInteractionController.h
Related sample code

Overview

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:

If the showsPageRange property is set to YES, 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.

Tasks

Getting the Shared Controller Instance

Determining Printability

Providing the Source of Printable Content

Presenting the Printing User Interface

Accessing Print-Job Information

Assigning the Delegate

Properties

delegate

The delegate of the print interaction controller.

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

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

printFormatter

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

@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 YES—and if the formatter represents content of more than one page—the printing options include the control for selecting a page range.

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

printInfo

An object encapsulating information about the print job.

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

Availability
  • Available in iOS 4.2 and later.
See Also
Related Sample Code
Declared In
UIPrintInteractionController.h

printingItem

A single ready-to-print object.

@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 YES—and the printing item is a PDF document of more than one page—the printing options include the control for selecting a page range.

Availability
  • Available in iOS 4.2 and later.
Related Sample Code
Declared In
UIPrintInteractionController.h

printingItems

An array of ready-to-print objects.

@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 YES. If you want page-range selection, you should use the printingItem property instead.

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

printPageRenderer

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

@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 YES—and the rendered content is greater than one page—the printing options include the control for selecting a page range.

Availability
  • Available in iOS 4.2 and later.
Related Sample Code
Declared In
UIPrintInteractionController.h

printPaper

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

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

Availability
  • Available in iOS 4.2 and later.
See Also
Declared In
UIPrintInteractionController.h

showsPageRange

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

@property(nonatomic) BOOL showsPageRange
Discussion

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

Availability
  • Available in iOS 4.2 and later.
Related Sample Code
Declared In
UIPrintInteractionController.h

Class Methods

canPrintData:

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

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

YES if UIKit can print the contents of the data object, otherwise NO. The method returns NO 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.

Availability
  • Available in iOS 4.2 and later.
See Also
Declared In
UIPrintInteractionController.h

canPrintURL:

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

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

YES if UIKit can print the contents of the referenced file, otherwise NO. The method returns NO 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.

Availability
  • Available in iOS 4.2 and later.
See Also
Declared In
UIPrintInteractionController.h

isPrintingAvailable

Returns a Boolean indicating whether the device supports printing.

+ (BOOL)isPrintingAvailable
Return Value

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

Availability
  • Available in iOS 4.2 and later.
See Also
Declared In
UIPrintInteractionController.h

printableUTIs

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

+ (NSSet *)printableUTIs
Return Value

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

Availability
  • Available in iOS 4.2 and later.
See Also
Declared In
UIPrintInteractionController.h

sharedPrintController

Returns the shared print-interaction controller object.

+ (UIPrintInteractionController *)sharedPrintController
Return Value

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

Availability
  • Available in iOS 4.2 and later.
Related Sample Code
Declared In
UIPrintInteractionController.h

Instance Methods

dismissAnimated:

Dismisses the printing-options sheet or popover.

- (void)dismissAnimated:(BOOL)animated
Parameters
animated

YES to animate the dismissal, otherwise NO.

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.

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

presentAnimated:completionHandler:

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

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

YES to animate the display of the sheet, NO 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 YES 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.

Availability
  • Available in iOS 4.2 and later.
Related Sample Code
Declared In
UIPrintInteractionController.h

presentFromBarButtonItem:animated:completionHandler:

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

- (void)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

YES to animate the printing popover view from item, NO 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 YES 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.

Availability
  • Available in iOS 4.2 and later.
Related Sample Code
Declared In
UIPrintInteractionController.h

presentFromRect:inView:animated:completionHandler:

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

- (void)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

YES to animate the printing popover view from item, NO 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 YES 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.

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

Constants

UIPrintInteractionCompletionHandler

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

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.

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

UIKit Printing Error Domain

The error domain for printer errors

UIKIT_EXTERN NSString *const UIPrintErrorDomain;
Constants
UIPrintErrorDomain

The string constant defining the UIKit printing error domain.

Available in iOS 4.2 and later.

Declared in UIPrintError.h.

Declared In
UIPrintError.h

UIKit Printing Error Codes

Error codes for UIKit printing errors.

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

The device does not support printing.

Available in iOS 4.2 and later.

Declared in UIPrintError.h.

UIPrintNoContentError

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

Available in iOS 4.2 and later.

Declared in UIPrintError.h.

UIPrintUnknownImageFormatError

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

Available in iOS 4.2 and later.

Declared in UIPrintError.h.

UIPrintJobFailedError

An internal error occurred with the print job.

Available in iOS 4.2 and later.

Declared in UIPrintError.h.

Declared In
UIPrintError.h


© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-10-12)

Did this document help you? Yes It's good, but... Not helpful...