iOS Reference Library Apple Developer
Search

Previewing and Opening Items

Your application can provide previews of items that you otherwise could not open—iWork documents, PDF files, images, and others. To do this, use an instance of the UIDocumentInteractionController class, which also lets you open a previewed item in an appropriate application, if one is available.

If your application can display specific file types, you can register that capability in your Xcode project’s Info.plist file. When another application asks the system for help opening a previewed item of those types, your application will be included in the options menu presented to the user.

Previewing and Opening Items

When your application needs to interact with certain types of items that it cannot open on its own, you can use a UIDocumentInteractionController object to manage those interactions. A document interaction controller works with the Quick Look framework to determine whether files can be previewed in place or opened by another application. Your application, in turn, works with the document interaction controller to present the available options to the user at appropriate times.

To use a document interaction controller in your application, do the following:

  1. Create an instance of the UIDocumentInteractionController class for each file you want to manage.

  2. Present the file in your application’s user interface. (Typically, you would do this by displaying the file name or icon somewhere in your interface.)

  3. When the user interacts with the file, ask the document interaction controller to present one of the following interfaces:

    • A file preview view that displays the contents of the file

    • A menu containing options to preview the file, copy its contents, or open it using another application

    • A menu prompting the user to open it with another application

Any application that interacts with files can use a document interaction controller. Programs that download files from the network are the most likely candidates to need these capabilities. For example, an email program might use document interaction controllers to preview or open files attached to an email. Of course, you do not need to download files from the network to use this feature. If your application supports file sharing, you might need to use a document interaction controller to process files of unknown types discovered in your application’s Documents/Shared directory.

Creating and Configuring a Document Interaction Controller

To create a new document interaction controller, initialize a new instance of the UIDocumentInteractionController class with the file you want it to manage and assign a delegate object. The delegate is responsible for providing the document interaction controller with information it needs to present its views. You can also use the delegate to perform additional actions when those views are displayed. The following code creates a new document interaction controller and sets the delegate to the current object. Note that the caller of this method needs to retain the returned object.

- (UIDocumentInteractionController*)docControllerForFile:(NSURL)fileURL
{
   UIDocumentInteractionController* docController =
       [UIDocumentInteractionController interactionControllerWithURL:fileURL];
   docController.delegate = self;
 
   return docController;
}

Once you have a document interaction controller, you can use its properties to get information about the file, including its name, type information, and path information. The controller also has an icons property that contains UIImage objects representing the document’s icon in various sizes. You can use all of this information when presenting the document in your user interface.

If you plan to let the user open the file in another application, you can use the annotation property of the document interaction controller to pass custom information to the opening application. It is up to you to provide information in a format that the other application will recognize. For example, this property is typically used by application suites that want to communicate additional information about a file to other applications in the suite. The opening application sees the annotation data in the UIApplicationLaunchOptionsAnnotationKey key of the options dictionary that is passed to it at launch time.

Presenting a Document Interaction Controller

When the user interacts with a file, you use the document interaction controller to display the appropriate user interface. You have the choice of displaying a document preview or of prompting the user to choose an appropriate action for the file using one of the following methods:

Each of the preceding methods attempts to display a custom view with the appropriate content. When calling these methods, you should always check the return value to see if the attempt was actually successful. These methods may return NO if the resulting interface would have contained no content. For example, the presentOpenInMenuFromRect:inView:animated: method returns NO if there are no applications capable of opening the file.

If you choose a method that might display a preview of the file, your delegate object must implement the documentInteractionControllerViewControllerForPreview: method. Document previews are displayed using a modal view, so the view controller you return becomes the parent of the modal document preview. If you do not implement this method, if your implementation returns nil, or if the specified view controller is unable to present another modal view controller, a document preview is not displayed.

Normally, the document interaction controller automatically handles the dismissal of the view it presents. However, you can dismiss the view programmatically as needed by calling the dismissMenuAnimated: or dismissPreviewAnimated: methods.

Registering the File Types Your Application Supports

If your application is capable of opening specific types of files, you should register that support with the system. To declare its support for file types, your application must include the CFBundleDocumentTypes key in its Info.plistfile. The system gathers this information from your application and maintains a registry that other applications can access through a document interaction controller.

The CFBundleDocumentTypes key contains an array of dictionaries, each of which identifies information about a specific document type. A document type usually has a one-to-one correspondence with a particular document type. However, if your application treats more than one file type the same way, you can group those types together as a single document type. For example, if you have two different file formats for your application’s native document type, you could group both the old type and new type together in a single document type entry. By doing so, both the new and old files would appear to be the same type of file and would be treated in the same way.

Each dictionary in the CFBundleDocumentTypes array can include the following keys:

From the perspective of your application, a document is a file type (or file types) that the application supports and treats as a single entity. For example, an image processing application might treat different image file formats as different document types so that it can fine tune the behavior associated with each one. Conversely, a word processing application might not care about the underlying image formats and just manage all image formats using a single document type.

Listing 3-1 shows a sample XML snippet from the Info.plist of an application that is capable of opening a custom file type. The LSItemContentTypes key identifies the UTI associated with the file format and the CFBundleTypeIconFiles key points to the icon resources to use when displaying it.

Listing 3-1  Document type information for a custom file format

<dict>
   <key>CFBundleTypeName</key>
   <string>My File Format</string>
   <key>CFBundleTypeIconFiles</key>
       <array>
           <string>MySmallIcon.png</string>
           <string>MyLargeIcon.png</string>
       </array>
   <key>LSItemContentTypes</key>
       <array>
           <string>com.example.myformat</string>
       </array>
   <key>LSHandlerRank</key>
   <string>Owner</string>
</dict>

For more information about the contents of the CFBundleDocumentTypes key, see the description of that key in Information Property List Key Reference.

Opening Supported File Types

At launch time, the system may ask your application to open a specific file and present it to the user. This typically occurs because another application encountered the file and used a document interaction controller to handle it. You receive information about the file to be opened in the application:didFinishLaunchingWithOptions: method of your application delegate. If your application handles custom file types, you must implement this delegate method (instead of the applicationDidFinishLaunching: method) and use it to initialize your application.

The options dictionary passed to the application:didFinishLaunchingWithOptions: method contains information about the file to be opened. Specifically, your application should look in this dictionary for the following keys:

If the UIApplicationLaunchOptionsURLKey key is present, your application must open the file referenced by that key and present its contents immediately. You can use the other keys in the dictionary to gather information about the circumstances surrounding the opening of the file.

Using the Quick Look Framework

To gain even more control over your previews, you can use the Quick Look framework directly. The framework’s primary class is QLPreviewController. It relies on a delegate for responding to preview actions, and a data source for providing the preview items.

An instance of the QLPreviewController class, or Quick Look preview controller, provides a specialized view for previewing an item. To display a Quick Look preview controller you have two options: You can push it into view using a UINavigationController object, or can present it modally, full screen, using the presentModalViewController:animated: method of its parent class, UIViewController.

Choose the display option that best fits the visual and navigation style of your application. Modal, full-screen display might work best if your app doesn’t use a navigation bar. If your app uses iPhone-style navigation, you might want to opt for pushing your preview into view.

A displayed preview includes a title taken from the last path component of the item URL. You can override this by implementing a previewItemTitle accessor for the preview item.

A Quick Look preview controller can display previews for the following items:

To use a Quick Look preview controller, you must provide a data source object using the methods described in QLPreviewControllerDataSource Protocol Reference. The data source provides preview items to the controller and tells it how many items to include in a preview navigation list. If there is more than one item in the list, a modally-presented (that is, full-screen) controller displays navigation arrows to let the user switch among the items. For a Quick Look preview controller pushed using a navigation controller, you can provide buttons in the navigation bar for moving through the preview-item list.

For a complete description of the Quick Look framework, see Quick Look Framework Reference.



Last updated: 2010-04-30

Did this document help you? Yes It's good, but... Not helpful...