iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIDocumentPickerExtensionViewController Class Reference

Options
Deployment Target:

On This Page
Language:

UIDocumentPickerExtensionViewController

The UIDocumentPickerExtensionViewController class is the principal class for the Document Picker View Controller extension. When creating a Document Picker extension, you must subclass UIDocumentPickerExtensionViewController to provide the document picker’s user interface. Your subclass presents a list of available documents and destinations to the user. When the user makes a selection, you trigger the file transfer and pass the selected URL back to the host app. More...

Inheritance


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 8.0 and later.
  • Dismisses the document picker.

    Declaration

    Swift

    func dismissGrantingAccessToURL(_ url: NSURL!)

    Objective-C

    - (void)dismissGrantingAccessToURL:(NSURL *)url

    Parameters

    url

    The URL that the extension returns to the host app.

    Discussion

    Call this method when the user selects a document or destination. This method dismisses the document picker view controller in the host app and triggers the appropriate file transfer. After the transfer is complete, the method passes the provided URL to the host app’s documentPicker:didPickDocumentAtURL: delegate method.

    The URL must meet all of the following conditions:

    • Import Document Picker mode. Provide a URL for the selected file. The URL only needs to be accessible by the Document Picker View Controller extension.

    • Open Document Picker mode. Provide a URL for the selected file. The URL must point to a location inside the directory hierarchy referred to by your documentStorageURL property.

    • Export Document Picker mode. Before calling this method, copy the file to the selected destination. Your extensions also need to track the file and make sure it is synced to your server.

      After the copy is complete, call this method and provide the URL to the new copy. This URL needs to be accessible only by the Document Picker View Controller extension. The system returns the URL to the host app to indicate success; however, the host app cannot access the document at this URL.

    • Move Document Picker mode. Before calling this method, copy the file to the selected destination. Your extensions also need to track the file and make sure it is synced to your server.

      After the copy is complete, call this method and provide the URL to the new copy. The URL needs to be contained inside the hierarchy referred to by your documentStorageURL property. The system returns this URL to the host app, and the host app can continue to access the document at this URL.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The document picker’s file-transfer operation. (read-only)

    Declaration

    Swift

    var documentPickerMode: UIDocumentPickerMode { get }

    Objective-C

    @property(nonatomic, readonly, assign) UIDocumentPickerMode documentPickerMode

    Discussion

    For a list of available modes, see Document Picker Modes in UIDocumentPickerViewController Class Reference.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The root URL for documents provided by the corresponding File Provider extension. (read-only)

    Declaration

    Swift

    @NSCopying var documentStorageURL: NSURL! { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSURL *documentStorageURL

    Discussion

    This property returns a subdirectory of the app group container shared by the Document Picker extension and its corresponding File Provider extension. By default, this property holds the value returned by calling the File Provider extension’s documentStorageURL method.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The URL of the file to be exported. (read-only)

    Declaration

    Swift

    @NSCopying var originalURL: NSURL? { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSURL *originalURL

    Discussion

    While in UIDocumentPickerModeExportToService mode, this property contains the original URL of the file to be copied. Otherwise it is nil.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Performs any custom configuration of the document picker view controller.

    Declaration

    Swift

    func prepareForPresentationInMode(_ mode: UIDocumentPickerMode)

    Objective-C

    - (void)prepareForPresentationInMode:(UIDocumentPickerMode)mode

    Parameters

    mode

    The type of file-transfer operation that the document picker performs. For a list of valid modes, see Document Picker Modes in UIDocumentPickerViewController Class Reference.

    Discussion

    The system calls this method when a host app presents a document picker view controller for your Document Picker extension. Override this method to provide a custom user interface based on the provided mode.

    Different modes may require different user interfaces. For example, the UIDocumentPickerModeImport and UIDocumentPickerModeOpen modes should let the user explore the available documents, whereas the UIDocumentPickerModeExportToService and UIDocumentPickerModeMoveToService modes let the user select the destination.

    When overriding this method, examine the mode and present an appropriate user interface for the task at hand. If the differences between the modes are significant, consider creating separate child view controllers for each mode and then present the appropriate child in this method.

    If your extension can manage multiple file types, check the validTypes property and make sure you are presenting only files that match one or more of the specified types.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • An identifier shared by this Document Picker extension and its corresponding File Provider extension. (read-only)

    Declaration

    Swift

    var providerIdentifier: String { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSString *providerIdentifier

    Discussion

    Both the Document Picker View Controller extension and the File Provider extension should pass this identifier to their file coordinator’s setPurposeIdentifier: method. This approach helps coordinate the read and write operations between the two extensions, preventing possible deadlocks.

    This property holds the value returned by calling the File Provider extension’s providerIdentifier method.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • An array of valid uniform type identifiers. (read-only)

    Declaration

    Swift

    var validTypes: [AnyObject]? { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSArray *validTypes

    Discussion

    While in the UIDocumentPickerModeImport or UIDocumentPickerModeOpen modes, this property holds an array of valid UTIs; otherwise, it is nil.

    Check the value of this property before your Document Picker extension displays any files to the user. You should let the user select only files that match at least one of the given UTIs.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.