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

Overview

UIPrintInteractionController クラスの共有インスタンスは、プリントするユーザインタフェースを表示し、ドキュメントやイメージやその他の印刷可能なiOSオブジェクトの印刷を管理する。

UIPrintInteractionController は、iOSの印刷のための中心となるクラスとなる。この共有インスタンスは、プリントジョブを代表する。プリントジョブは、プリントすべき内容と情報とプリントに関係するオプション（アウトプットタイプ、ジョブ名、ペーパサイズ、方向）を包含する。

UIPrintInteractionController は、プリントすべき内容に応じて与えられた４つの相互に排他的なプロパティを持つ。

• printingItem は、単一のプリント可能なオブジェクトを取得する。
• printingItems プリント可能な配列オブジェクトを取得する。
• printFormatter ある種の内容をどのようにレイアウトするかを知るオブジェクトであるプリントフォーマッタを取得する。
• printPageRenderer プリントする内容を描画するためのカスタムオブジェクトであるページレンダラを取得する。

もし showsPageRange プロパティがYESにセットされていれば, ページ数が１以上で,  printingItems プロパティ（ユーザにページ範囲を指定することを許す制御を含むプリンタオプション）の場合をのぞいて、これらの任意のオブジェクトを割り当てる。 

ユーザがアプリケーションのユーザインタフェース上にあるプリントボタンをタップしたとき、アプリケーションのコントローラオブジェクトは、UIPrintInteractionController の共有インスタンスとプリントジョブのために準備を含むアクションメッセージを返すべきである。

present... メソッド (例えば、presentAnimated:completionHandler:)のうちの一つをアプリケーションが呼ぶとき、 UIPrintInteractionController は、プリントオプションを含むビューを表示する。このインタフェースは、簡単に、コピー数とページ範囲を指定し、片面印刷か両面印刷かの選択（もし、プリンタが両面印刷をサポートしていたら）のユーザによるプリンタの選択を許す。ユーザがそれらの選択をし、プリントをタップするとプインとは開始する。

Tasks

共有コントローラインスタンスを取得する

• + sharedPrintController

プリント可否を決定する

• + isPrintingAvailable
• + canPrintData:
• + canPrintURL:
• + printableUTIs

プリント可能なコンテンツのソースを提供する

•   printingItem  property
•   printingItems  property
•   printPageRenderer  property
•   printFormatter  property

プリントのユーザインタフェースを表示する

• – presentAnimated:completionHandler:
• – presentFromBarButtonItem:animated:completionHandler:
• – presentFromRect:inView:animated:completionHandler:
• – dismissAnimated:

プリントジョブの情報にアクセスする

•   printInfo  property
•   printPaper  property
•   showsPageRange  property

デリゲートを割りあてる

•   delegate  property

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

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, andprintPageRenderer 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

•   @property printPaper

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 byUIImage 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, andprintFormatter 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.

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 typeALAssetTypePhoto. 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, andprintFormatter 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 theshowsPageRange 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. TheUIPrintInteractionController 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.

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 theprintInteractionController: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

•   @property printInfo

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.

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

• + canPrintURL:
• + printableUTIs

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

Availability

• Available in iOS 4.2 and later.

See Also

• + canPrintData:
• + printableUTIs

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

• + canPrintData:
• + canPrintURL:
• + printableUTIs

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

• + canPrintData:
• + canPrintURL:

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.

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 theUIApplicationWillChangeStatusBarOrientationNotification 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)animatedcompletionHandler:(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 withanimated 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.

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)animatedcompletionHandler:(UIPrintInteractionCompletionHandler)completion

Parameters

item

The UIBarButtonItem object that the user tapped for printing. You are encouraged to use the constantUIBarButtonSystemItemAction 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 withanimated 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

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)animatedcompletionHandler:(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 withanimated 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:, orpresentFromRect: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 isUIPrintErrorDomain. 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