Monday, February 21, 2011

Quick Look for iOS

Many apps work directly with files. Quick Look is the perfect framework for previewing those files. Right out of the box, it supports all the common file formats. Like many of Apple’s other frameworks, it takes very few lines of code to add. Quick Look has been in Mac OS X for a while now and has recently been made available for iOS in 4.0.

Adding Quick Look is a few easy steps:
  1. Import QuickLook.framework.
  2. Create a QLPreviewItem (or NSURL).
  3. Create a QLPreviewControllerDataSource.
  4. Create a QLPreviewControllerDelegate.
  5. Present a QLPreviewController.
Any item can be previewed. It simply needs to conform to the QLPreviewItem protocol. This protocol only has two methods. The first, previewItemURL, returns the URL to locate the file to preview. The second, previewItemTitle, returns the title to show for the document. If this method is not defined, then the document name will be the title. One important item to note is that NSURL conforms to the QLPreviewItem protocol. You may use NSURLs instead of making a class that conforms to the protocol. Another important gotcha, any URLs returned from previewItemURL must use the file protocol (ex. file://some/file/path.txt). This is easily done with [NSURL fileURLWithPath:someFilePath]. If you don’t use the file scheme, then you will get an error message like this: “UIDocumentInteractionController: invalid scheme (null). Only the file scheme is supported.”

Next, setup a QLPreviewControllerDataSource and QLPreviewControllerDelegate. QLPreviewControllerDataSource needs to know how many QLPreviewItems you want to show (numberOfPreviewItemsInPreviewController:) and which QLPreviewItem is at each index (previewController:previewItemAtIndex:). These are often one line if you already have your documents in an array. Once the delegate and data source are set up, all you need to do is present the view however you like. The most convenient way on iPhone is [self presentModalViewController:previewController animated:YES];. QLPreviewControllerDelegate adds some extra callbacks that may be helpful, but it may be unnecessary depending on your needs.

Quick Look also comes with other features for free. First, it presents the option to open the file in another app that accepts that file format. For example, CSV files can be opened in Numbers and PDFs can be opened in iBooks. Second, files can be printed. If you don’t have a printer to test it on, Apple provides Printer Simulator in the developer tools.

Simple table views works well for managing file previews; however, you may want a more custom UI and more control. UIDocumentInteractionController is the class to use for that. I won’t go into details on document interaction. Session 106 of WWDC 2010 goes into great detail about UIDocumentInteractionController. The sample code is also available in the developer docs.

EDIT:
Since writing this post I have written a subclass of QLPreviewController that includes many conveniences, and have removed the old sample code. If you are using my old Quick Look sample, you should switch over to RBFilePreviewer. You can find it here on Github. You can also find a demo of RBFilePreviewer in my demo repository.