- iOS 11.0+
- Xcode 10.0+
The Document Browser sample code uses a
UIDocument as the app’s root view controller. The browser defines the structure of the app, and the app displays the browser view when it launches. Users can then use the browser to:
Browse all the text files on the user’s device, in their iCloud drive, or in any supported third-party file providers.
Create new text files.
Open text files.
When the user opens a file, the app transitions to an editor view. There, the user can edit and save the text file. When they are done editing, the app returns to the browser, letting the user open or create another file.
This sample code project demonstrates all the required steps to set up the document browser, to work with the user’s files, and to enable system animations. The following sections describe these steps in more detail.
Setting Up the Document Browser
The Document Browser app performs the following setup and configuration steps:
UIDocumentsubclass as the window’s
Browser View Controller
Specifies the supported document types.
Customizes the document browser’s behavior.
Document browser-based apps must assign a
UIDocument instance as the app’s
root, ensuring that the browser remains in memory throughout the app’s lifetime.
The sample code defines a
UIDocument subclass named
Document. It then marks the subclass as the app’s initial view controller in the
Main storyboard, and displays the browser view when launched.
All document browser-based apps must also declare the document types that they can open. The sample code app declares support for text files in the project editor’s Info pane. For more information on setting the document type, see Setting Up a Document Browser App.
Finally, the sample code configures the document browser in the
view method. Specifically, it enables document creation, and disables multiple document selection. This lets users create new documents from the browser, while also preventing them from opening more than one document at a time.
For more information on configuring a document browser, see Customizing the Browser
Creating New Documents
When the user creates a new document, the system calls the document browser delegate’s
In this method, the app creates, saves, and then closes a new text document. If successful, the app passes the URL to the method’s import handler, requesting that the system move the document to its final location. Otherwise, it passes
nil to the import handler, canceling document creation.
Opening and Importing Documents.
Users can open documents in multiple ways. The sample code handles the following situations:
If the app imports a document (including successfully creating a new document), the system calls the
Browser: did Import Document At URL: to Destination URL:
If the user selects a document from the browser, the system calls the
Browser: did Pick Document URLs:
If the user shares a document with the app, or drags a document into the app, the system calls the app delegate’s
open URL: options:
In the first two cases, the app calls the custom
present method. In the third case, the app calls the browser’s
reveal method to import the document (if needed). It then calls the
present method instantiates a
Text, sets up the document’s animation, opens the document, and then presents the view controller by calling the browser’s
The document browser provides two built-in animations: one for loading a file, another for transitioning to and from the document view.
To enable either of the system-provided document browser animations, first you need to request a transition controller for the document by calling the
To enable the loading animation, assign a
NSProgress object to the transition controller when you begin to load the document.
Increment the progress as the document loads, making sure to mark it as complete as soon as loading finishes. To simulate slow, incremental loading in the sample code project, uncomment the
To enable the transition animation, set the transition controller’s target view and pass it to the
The text document view controller wraps the transition controller in a
Document, and assigns the resulting delegate to its
The system then uses the transition animation when modally presenting the text view.