iOS Developer Library

Developer

UIKit Framework Reference UIDocumentInteractionControllerDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

UIDocumentInteractionControllerDelegate

Inherits From


Not Applicable

Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 3.2 and later

The UIDocumentInteractionControllerDelegate protocol includes methods you can implement to respond to messages from a document interaction controller. Use this protocol to participate when document previews are displayed and when a document is about to be opened by another application. You can also use this protocol to respond to commands (such as “copy” and “print”) from a document interaction controller’s options menu.

If you use a document interaction controller to display a document preview, your delegate must implement the documentInteractionControllerViewControllerForPreview: method. All other methods of this protocol are optional.

For more information about using a document interaction controller, see UIDocumentInteractionController Class Reference.

  • Called when a document interaction controller needs a view controller for presenting a document preview.

    Declaration

    Swift

    optional func documentInteractionControllerViewControllerForPreview(_ controller: UIDocumentInteractionController) -> UIViewController

    Objective-C

    - (UIViewController *)documentInteractionControllerViewControllerForPreview:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller requesting the parent view controller.

    Return Value

    The view controller to use when presenting the document preview. The return value must not be nil.

    Discussion

    Although technically optional, this method is required if your application attempts to display a preview for a document. The view controller returned by this method is used as the parent for the document preview.

    If you return a navigation controller from this method, the document interaction controller is pushed onto the navigation stack using the standard navigation controller animations. If you return any other type of view controller, the document interaction controller is displayed modally, in which case, the view controller you return must be capable of presenting a modal view controller.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller needs the starting point for animating the display of a document preview.

    Declaration

    Swift

    optional func documentInteractionControllerViewForPreview(_ controller: UIDocumentInteractionController) -> UIView?

    Objective-C

    - (UIView *)documentInteractionControllerViewForPreview:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller requesting the starting view.

    Return Value

    The view to use as the starting point for the animation or nil if you want the document preview to fade into place.

    Discussion

    By default, the starting rectangle for the animation is set to the bounds of the returned view. To specify a different starting rectangle, you must also override the documentInteractionControllerRectForPreview: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller needs the rectangle to use as the starting point for animating the display of a document preview.

    Declaration

    Swift

    optional func documentInteractionControllerRectForPreview(_ controller: UIDocumentInteractionController) -> CGRect

    Objective-C

    - (CGRect)documentInteractionControllerRectForPreview:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller requesting the starting rectangle.

    Return Value

    A rectangle in the coordinate system of the view returned by the documentInteractionControllerViewForPreview: method.

    Discussion

    If you do not implement the documentInteractionControllerViewForPreview: method, or if you do implement it but return a nil value, this method is not called. If you do not implement this method, the starting rectangle is assumed to be the bounds of the view returned by the documentInteractionControllerViewForPreview: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller is about to display a preview for its document.

    Declaration

    Swift

    optional func documentInteractionControllerWillBeginPreview(_ controller: UIDocumentInteractionController)

    Objective-C

    - (void)documentInteractionControllerWillBeginPreview:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller that is about to preview its document.

    Discussion

    This method is called shortly before the view containing the document preview is presented modally. You can use this notification to set up any additional interface elements behind the preview elements.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller has dismissed its document preview.

    Declaration

    Swift

    optional func documentInteractionControllerDidEndPreview(_ controller: UIDocumentInteractionController)

    Objective-C

    - (void)documentInteractionControllerDidEndPreview:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller that dismissed its document preview.

    Discussion

    This method is called after the view containing the document preview has been removed from the application’s key window. You can use this notification to remove any interface elements you set up behind the preview elements.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller is about to display an options menu.

    Declaration

    Swift

    optional func documentInteractionControllerWillPresentOptionsMenu(_ controller: UIDocumentInteractionController)

    Objective-C

    - (void)documentInteractionControllerWillPresentOptionsMenu:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller that is about to display an options menu.

    Discussion

    The options menu is used to present the user with options for previewing the document, opening it in an application, or copying its contents. You can use this method to update your user interface in response to displaying the menu.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller has dismissed its options menu.

    Declaration

    Swift

    optional func documentInteractionControllerDidDismissOptionsMenu(_ controller: UIDocumentInteractionController)

    Objective-C

    - (void)documentInteractionControllerDidDismissOptionsMenu:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller that dismissed its options menu.

    Discussion

    You can use this method to remove any additional views or content you placed underneath the options menu in your documentInteractionControllerWillPresentOptionsMenu: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller is about to display an Open In menu.

    Declaration

    Swift

    optional func documentInteractionControllerWillPresentOpenInMenu(_ controller: UIDocumentInteractionController)

    Objective-C

    - (void)documentInteractionControllerWillPresentOpenInMenu:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller that is about to display a menu.

    Discussion

    The Open In menu is used to select an application for opening the current file. You can use this method to update your user interface in response to displaying the menu.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller has dismissed its Open In menu.

    Declaration

    Swift

    optional func documentInteractionControllerDidDismissOpenInMenu(_ controller: UIDocumentInteractionController)

    Objective-C

    - (void)documentInteractionControllerDidDismissOpenInMenu:(UIDocumentInteractionController *)controller

    Parameters

    controller

    The document interaction controller that dismissed its menu.

    Discussion

    You can use this method to remove any additional views or content you placed underneath the Open In menu in your documentInteractionControllerWillPresentOpenInMenu: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller’s document is about to be opened by the specified application.

    Declaration

    Swift

    optional func documentInteractionController(_ controller: UIDocumentInteractionController, willBeginSendingToApplication application: String)

    Objective-C

    - (void)documentInteractionController:(UIDocumentInteractionController *)controller willBeginSendingToApplication:(NSString *)application

    Parameters

    controller

    The document interaction controller whose document is about to be opened.

    application

    The bundle identifier of the application that is about to open the document. This value corresponds to the value in the CFBundleIdentifier key of the application’s Info.plist file.

    Discussion

    This method is called when the user chooses to open a document, which could occur from within a document preview. When a document is passed to another application, the contents of the document interaction controller’s annotation property are passed with it. You can use this method to configure the contents of that property or prepare your own application for handing off the document.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller’s document has been handed off to the specified application.

    Declaration

    Swift

    optional func documentInteractionController(_ controller: UIDocumentInteractionController, didEndSendingToApplication application: String)

    Objective-C

    - (void)documentInteractionController:(UIDocumentInteractionController *)controller didEndSendingToApplication:(NSString *)application

    Parameters

    controller

    The document interaction controller whose document is about to be opened.

    application

    The bundle identifier of the application that is about to open the document. This value corresponds to the value in the CFBundleIdentifier key of the application’s Info.plist file.

    Discussion

    This method is called after the document information has been saved for the specified application.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later

  • Called when a document interaction controller needs to know whether the specified action can be performed on the associated document.

    Deprecation Statement

    Apps should use UIActivityViewController for actions.

    Declaration

    Objective-C

    - (BOOL)documentInteractionController:(UIDocumentInteractionController *)controller canPerformAction:(SEL)action

    Parameters

    controller

    The document interaction controller managing an associated document.

    action

    The selector representing the action in question.

    Return Value

    YEStrue if the specified action is supported for the associated document or NOfalse if it is not. If you do not implement this method, the return value is assumed to be NOfalse.

    Discussion

    When building the options menu (invoked, for example, by the user performing a long press gesture), a document interaction controller calls this method to find out if your app can perform various actions. If you implement this method for a given action, you must also implement the documentInteractionController:performAction: method for that action.

    The supported action selectors for this method are copy: and print:. (The print: selector is available in iOS 4.2 and later. Printing is supported only on devices that support multitasking.)

    For each action that you implement in the documentInteractionController:performAction: delegate method, return YEStrue from this method if that action is available for the document.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 3.2 and later

    Deprecated in iOS 6.0

  • Called when a document interaction controller wants its delegate to perform a specified action with the associated document.

    Deprecation Statement

    Apps should use UIActivityViewController for actions.

    Declaration

    Objective-C

    - (BOOL)documentInteractionController:(UIDocumentInteractionController *)controller performAction:(SEL)action

    Parameters

    controller

    The document interaction controller managing an associated document.

    action

    The selector representing the action to perform. You can invoke this selector directly on the object responsible for performing the action or use it to call the appropriate method.

    Return Value

    YEStrue if the action was performed successfully or NOfalse if it was not.

    Discussion

    The supported action selectors for this method are copy: and print:. (The print: selector is available in iOS 4.2 and later. Printing is supported only on devices that support multitasking.)

    To implement a copy: action, write the contents of the document—directly, or modified according to the intent of your app—to the pasteboard.

    To implement a print: action, use the shared print interaction controller object. Assign the URL property of the document interaction controller to the print interaction controller’s printingItem property. Then present the printing user interface. For details, refer to UIPrintInteractionController Class Reference and to Printing in Drawing and Printing Guide for iOS.

    Instead of implementing printing code in this method, you can rely on the built-in printing support of the Quick Look framework. For document types that can be previewed, the options menu of a document interaction controller always contains a Quick Look item. If the user chooses that item, the resulting Quick Look view includes an action button in the navigation bar that, when tapped, offers a Print button. In this case, the system automatically handles printing. For details, refer to QLPreviewController Class Reference and to Using the Quick Look Framework in Document Interaction Programming Topics for iOS.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 3.2 and later

    Deprecated in iOS 6.0