iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIDocumentPickerViewController Class Reference

Options
Deployment Target:

On This Page
Language:

UIDocumentPickerViewController

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 8.0 and later.

A UIDocumentPickerViewController object lets the user select documents or destinations outside your app’s sandbox. You must enable iCloud document support before you can use the document picker. For more information, see iCloud Design Guide.

Document Picker Modes

The document picker supports four modes. Each mode provides a slightly different approach to sharing files between apps.

  • Import an external document. The user selects an external document. The document picker copies the document, leaving the original unchanged.

  • Export a local document. The user selects an external destination. The document picker copies the document, leaving the original unchanged.

  • Open an external document. The user selects an external document. The document picker provides access to the document, letting the user edit the document in place.

  • Move a local document. The user selects an external destination. The document picker moves the document; however, you can still access the document as an external document, letting the user edit the document in place.

Working with External Documents

Both the open and move operations grant access to documents outside your app’s sandbox. This gives users an unprecedented amount of flexibility when it comes to working with their documents. However, it also adds a layer of complexity to your file handling. External documents have the following additional requirements:

  • The open and move operations provide security-scoped URLs for all external documents. Call the startAccessingSecurityScopedResource method to access these documents and the stopAccessingSecurityScopedResource method to release them. If you are using a UIDocument subclass to manage your document, it automatically manages the security-scoped URL for you.

  • Always use file coordinators to read and write to external documents.

  • Always use a file presenter when displaying the contents of an external document.

  • Don’t save any URLs provided by the open and move operations. You can, however, save a bookmark to these URLs. Call the the bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: method and pass in the NSURLBookmarkCreationWithSecurityScope option. This creates a bookmark containing a security-scoped URL.

For more information on working with external documents, see Creating an Outstanding User Experience in App Extension Programming Guide.

  • Initializes and returns a document picker that can import or open the given file types.

    Declaration

    Swift

    init(documentTypes allowedUTIs: [AnyObject], inMode mode: UIDocumentPickerMode)

    Objective-C

    - (instancetype)initWithDocumentTypes:(NSArray *)allowedUTIs inMode:(UIDocumentPickerMode)mode

    Parameters

    allowedUTIs

    An array of uniform type identifiers. UTIs are strings that uniquely identify a file’s type. For more information, see Uniform Type Identifiers Overview.

    mode

    The type of file-transfer operation that the document picker performs. This argument accepts only the UIDocumentPickerModeImport or UIDocumentPickerModeOpen mode.

    Return Value

    Returns an initialized UIDocumentPickerViewController object, or nil if the object could not be successfully initialized.

    Discussion

    This method returns the document picker view controller from the most recently used Document Provider extension. It defaults back to iCloud Drive if no other valid Document Provider extension can be found.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • init(URL:inMode:) - initWithURL:inMode: Designated Initializer

    Initializes and returns a document picker that can export or move the given document.

    Declaration

    Swift

    init(URL url: NSURL, inMode mode: UIDocumentPickerMode)

    Objective-C

    - (instancetype)initWithURL:(NSURL *)url inMode:(UIDocumentPickerMode)mode

    Parameters

    url

    The document to be exported or moved.

    mode

    The type of file-transfer operation that the document picker performs. This argument accepts only the UIDocumentPickerModeExportToService or UIDocumentPickerModeMoveToService mode.

    Return Value

    Returns an initialized UIDocumentPickerViewController object, or nil if the object could not be successfully initialized.

    Discussion

    This method returns the document picker view controller from the most recently used Document Provider extension. It defaults back to iCloud Drive if no other valid Document Provider extension can be found.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • delegate delegate Property

    The document picker’s delegate.

    Declaration

    Swift

    weak var delegate: UIDocumentPickerDelegate?

    Objective-C

    @property(nonatomic, weak) id< UIDocumentPickerDelegate > delegate

    Discussion

    The delegate must adopt the UIDocumentPickerDelegate protocol.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The type of file-transfer operation that the document picker performs. (read-only)

    Declaration

    Swift

    var documentPickerMode: UIDocumentPickerMode { get }

    Objective-C

    @property(nonatomic, assign, readonly) UIDocumentPickerMode documentPickerMode

    Discussion

    For a list of available modes, see UIDocumentPickerMode.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Modes that define the type of file-transfer operation used by the document picker.

    Declaration

    Swift

    enum UIDocumentPickerMode : UInt { case Import case Open case ExportToService case MoveToService }

    Objective-C

    typedef NS_ENUM (NSUInteger, UIDocumentPickerMode ) { UIDocumentPickerModeImport, UIDocumentPickerModeOpen, UIDocumentPickerModeExportToService, UIDocumentPickerModeMoveToService }

    Constants

    • Import

      UIDocumentPickerModeImport

      The document picker imports a file from outside the app’s sandbox.

      Available in iOS 8.0 and later.

    • Open

      UIDocumentPickerModeOpen

      The document picker opens an external file located outside the app’s sandbox.

      Available in iOS 8.0 and later.

    • ExportToService

      UIDocumentPickerModeExportToService

      The document picker exports a local file to a destination outside the app’s sandbox.

      Available in iOS 8.0 and later.

    • MoveToService

      UIDocumentPickerModeMoveToService

      The document picker moves a local file outside the app’s sandbox and provides access to it as an external file.

      Available in iOS 8.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.