iOS Developer Library

Developer

UIKit Framework Reference UIDocumentInteractionController Class Reference

Options
Deployment Target:

On This Page
Language:

UIDocumentInteractionController

Inheritance


  • NSObject
  • UIDocumentInteractionController
  • NSObject
  • UIDocumentInteractionController

Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 3.2 and later.

A document interaction controller, along with a delegate object, provides in-app support for managing user interactions with files in the local system. For example, an email program might use this class to allow the user to preview attachments and open them in other apps. Use this class to present an appropriate user interface for previewing, opening, copying, or printing a specified file.

After presenting its user interface, a document interaction controller handles all interactions needed to support file preview and menu display.

You can also use the delegate to participate in interactions occurring within the presented interface. For example, the delegate is notified when a file is about to be handed off to another application for opening. For a complete description of the methods you can implement in your delegate, see UIDocumentInteractionControllerDelegate Protocol Reference.

  • Creates and returns a new UIDocumentationInteractionController object initialized with the specified URL.

    Declaration

    Swift

    init(URL url: NSURL) -> UIDocumentInteractionController

    Objective-C

    + (UIDocumentInteractionController *)interactionControllerWithURL:(NSURL *)url

    Parameters

    url

    A URL that specifies the location of the desired document. This parameter is retained. It can be changed later by modifying the URL property.

    Return Value

    A new document interaction controller object.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Displays a full-screen preview of the target document.

    Declaration

    Swift

    func presentPreviewAnimated(_ animated: Bool) -> Bool

    Objective-C

    - (BOOL)presentPreviewAnimated:(BOOL)animated

    Parameters

    animated

    Specify YEStrue to animate the appearance of the document preview or NOfalse to display it immediately.

    Return Value

    YEStrue if this method was able to display the document preview or NOfalse if it was not.

    Discussion

    To use this method, you must first provide a delegate object that implements the documentInteractionControllerViewControllerForPreview: method. The view controller returned by that method is used to present the document preview modally.

    If your delegate implements the documentInteractionControllerViewForPreview: and documentInteractionControllerRectForPreview: methods, the view and rectangle returned by those methods is used as the starting point for the animation used to display the document preview. If the animated parameter is YEStrue but your delegate does not implement the documentInteractionControllerViewForPreview: method (or that method returns nil), the document preview is animated into place using a crossfade transition.

    This method displays the document preview asynchronously. The document interaction controller dismisses the document preview automatically in response to appropriate user interactions. You can also dismiss the preview programmatically using the dismissPreviewAnimated: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Dismisses the currently active document preview.

    Declaration

    Swift

    func dismissPreviewAnimated(_ animated: Bool)

    Objective-C

    - (void)dismissPreviewAnimated:(BOOL)animated

    Parameters

    animated

    Specify YEStrue to animate the dismissal of the document preview or NOfalse to dismiss it immediately.

    Discussion

    Use this method to dismiss the document preview programmatically. The document interaction controller may also dismiss the document preview automatically in response to user actions.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Displays an options menu and anchors it to the specified location in the view.

    Declaration

    Swift

    func presentOptionsMenuFromRect(_ rect: CGRect, inView view: UIView, animated animated: Bool) -> Bool

    Objective-C

    - (BOOL)presentOptionsMenuFromRect:(CGRect)rect inView:(UIView *)view animated:(BOOL)animated

    Parameters

    rect

    The location (in the coordinate system of view) at which to anchor the menu.

    view

    The view from which to display the options menu.

    animated

    Specify YEStrue to animate the appearance of the menu or NOfalse to display it immediately.

    Return Value

    YEStrue if the options menu was displayed or NOfalse if it was not. The options menu may not be displayed in cases where there are no appropriate items to include in the menu.

    Discussion

    The contents of the options menu are built dynamically based on three things:

    • The type of the document (as specified by the UTI property)

    • The set of installed apps that have registered support for opening documents

    • The actions that you have indicated as supported in the document interaction controller delegate’s documentInteractionController:canPerformAction: method

    Options that cannot be performed on the current document are not included in the menu. For example, if the document cannot be opened by any known apps, the menu does not include options for opening it.

    This method displays the options menu asynchronously. The menu is dismissed automatically when the user selects one of the available options. You can also dismiss it programmatically using the dismissMenuAnimated: method.

    To instead present a menu that contains only a list of apps capable of opening the current document, the presentOpenInMenuFromRect:inView:animated: method instead.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Displays an options menu and anchors it to the specified bar button item.

    Declaration

    Swift

    func presentOptionsMenuFromBarButtonItem(_ item: UIBarButtonItem, animated animated: Bool) -> Bool

    Objective-C

    - (BOOL)presentOptionsMenuFromBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated

    Parameters

    item

    The bar button item to which to anchor the menu.

    animated

    Specify YEStrue to animate the appearance of the menu or NOfalse to display it immediately.

    Return Value

    YEStrue if the options menu was displayed or NOfalse if it was not. The options menu may not be displayed in cases where there are no appropriate items to include in the menu.

    Discussion

    The contents of the options menu are built dynamically based on three things:

    • The type of the document (as specified by the UTI property)

    • The set of installed apps that have registered support for opening documents

    • The actions that you have indicated as supported in the document interaction controller delegate’s documentInteractionController:canPerformAction: method

    Options that cannot be performed on the current document are not included in the menu. For example, if the document cannot be opened by any known apps, the menu does not include options for opening it.

    This method displays the options menu asynchronously. The document interaction controller dismisses the menu automatically when the user selects an appropriate option. You can also dismiss it programmatically using the dismissMenuAnimated: method.

    To instead present a menu that contains only a list of apps capable of opening the current document, the presentOpenInMenuFromBarButtonItem:animated: method instead.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Displays a menu for opening the document and anchors that menu to the specified view.

    Declaration

    Swift

    func presentOpenInMenuFromRect(_ rect: CGRect, inView view: UIView, animated animated: Bool) -> Bool

    Objective-C

    - (BOOL)presentOpenInMenuFromRect:(CGRect)rect inView:(UIView *)view animated:(BOOL)animated

    Parameters

    rect

    The location (in the coordinate system of view) at which to anchor the menu.

    view

    The view from which to display the menu.

    animated

    Specify YEStrue to animate the appearance of the menu or NOfalse to display it immediately.

    Return Value

    YEStrue if this method was able to display the menu or NOfalse if it was not.

    Discussion

    This method is similar to the presentOptionsMenuFromRect:inView:animated: method, but presents a menu restricted to a list of apps capable of opening the current document. This determination is made based on the document type (as indicated by the UTI property) and on the document types supported by the installed apps. To support one or more document types, an app must register those types in its Info.plist file using the CFBundleDocumentTypes key.

    If there are no registered apps that support opening the document, the document interaction controller does not display a menu.

    This method displays the options menu asynchronously. The document interaction controller dismisses the menu automatically when the user selects an appropriate option. You can also dismiss it programmatically using the dismissMenuAnimated: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Displays a menu for opening the document and anchors that menu to the specified bar button item.

    Declaration

    Swift

    func presentOpenInMenuFromBarButtonItem(_ item: UIBarButtonItem, animated animated: Bool) -> Bool

    Objective-C

    - (BOOL)presentOpenInMenuFromBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated

    Parameters

    item

    The bar button item to which to anchor the menu.

    animated

    Specify YEStrue to animate the appearance of the menu or NOfalse to display it immediately.

    Return Value

    YEStrue if this method was able to display the menu or NOfalse if it was not.

    Discussion

    This method is similar to the presentOptionsMenuFromBarButtonItem:animated: method, but presents a menu restricted to a list of apps capable of opening the current document. This determination is made based on the document type (as indicated by the UTI property) and on the document types supported by the installed apps. To support one or more document types, an app must register those types in its Info.plist file using the CFBundleDocumentTypes key.

    If there are no registered apps that support opening the document, the document interaction controller does not display a menu.

    This method displays the menu asynchronously. The document interaction controller dismisses the menu automatically when the user selects an appropriate app. You can also dismiss it programmatically using the dismissMenuAnimated: method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Dismisses the currently active menu.

    Declaration

    Swift

    func dismissMenuAnimated(_ animated: Bool)

    Objective-C

    - (void)dismissMenuAnimated:(BOOL)animated

    Parameters

    animated

    Specify YEStrue to animate the dismissal of the currently active menu or NOfalse to dismiss it immediately.

    Discussion

    Use this method to dismiss a menu programmatically. The document interaction controller can also dismiss the menu automatically in response to user actions.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • URL URL Property

    The URL identifying the target file on the local filesystem.

    Declaration

    Swift

    var URL: NSURL

    Objective-C

    @property(retain) NSURL *URL

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • UTI UTI Property

    The type of the target file.

    Declaration

    Swift

    var UTI: String?

    Objective-C

    @property(nonatomic, copy) NSString *UTI

    Discussion

    The value of this property is used to determine which apps are capable of opening the document. The default value is determined automatically whenever possible. However, if the document is a custom type that cannot be determined readily, the value of this property may be nil. If you know the type of the document, you can set the value of this property explicitly.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • name name Property

    The name of the target file.

    Declaration

    Swift

    var name: String!

    Objective-C

    @property(copy) NSString *name

    Discussion

    This property contains the filename without any preceding path information. The default value of this property is derived from the path information in the URL property. You can change the value of this property as needed if you want to associate a different name with the file.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • icons icons Property

    The images associated with the target file. (read-only)

    Declaration

    Swift

    var icons: [AnyObject] { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *icons

    Discussion

    This property contains an array of UIImage objects containing the available icons for the given file. The images in the array are sorted from smallest to largest, with the smallest image located at index 0. The returned array always contains at least one image.

    The images themselves are provided by the system and determined by the UTI of the file. Apps can register custom icons for their associated files by including the appropriate meta information in their Info.plist file. If no custom icon exists, the images in this property represent the generic document icon.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Custom property list information for the target file.

    Declaration

    Swift

    var annotation: AnyObject?

    Objective-C

    @property(nonatomic, retain) id annotation

    Discussion

    Use this property to pass information about the document type to the app responsible for opening it. The type of this object should be one used to contain property list information, namely NSDictionary, NSArray, NSData, NSString, NSNumber, or NSDate.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • The system-supplied gesture recognizers for presenting a document interaction controller. (read-only)

    Declaration

    Swift

    var gestureRecognizers: [AnyObject] { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *gestureRecognizers

    Discussion

    The objects in the gestureRecognizers array each descend from the UIGestureRecognizer class. You can attach these gesture recognizers to the view you use to represent a document. For example, if you represent a document by name or icon in a table view cell , you can attach a document interaction controller’s gesture recognizers using code like this:

    Swift

    • cell.contentView.gestureRecognizers = docInteractionController.gestureRecognizers

    Objective-C

    • cell.contentView.gestureRecognizers = self.docInteractionController.gestureRecognizers;

    (In this statement, the cell object is an instance of the UITableViewCell class and the docInteractionController instance variable points to the document interaction controller for the document named in the cell.)

    With gesture recognizers so attached, a user gesture automatically initiates the appropriate action. A tap gestures initiates a preview of the associated document. A long press gesture displays the options menu relevant to the document.

    The UIDocumentInteractionController class supports only the tap (UITapGestureRecognizer) and long press (UILongPressGestureRecognizer) gesture recognizers.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • delegate delegate Property

    The delegate you want to receive document interaction notifications.

    Declaration

    Swift

    unowned(unsafe) var delegate: UIDocumentInteractionControllerDelegate?

    Objective-C

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

    Discussion

    You can implement a delegate object to track user interactions with menu items displayed by the document interaction controller. For more information, see UIDocumentInteractionControllerDelegate Protocol Reference.

    The default value of this property is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.