Good afternoon. Welcome to Understanding the Document Interaction Controller. My name is Jason Beaver. I'm an engineer on the iPhone Frameworks Team and I'll be joined in a little bit by Luke who is also on the team, to go through a few demos. So, what are we going to cover today? Well, there's 5 basic things.

We're going to talk a little bit about what documents are like on the iPhone OS or iOS now. We're going to talk about how you register your applications as owners or editors of a particular type of document. Once you've registered for a document, we're going to talk about what you need to do to actually open the document when you're asked about the operating system.

And if your application allows users to interact with documents, as an example of this, consider the mail application where attachments can get mailed to the user and the user can click on those and open them and preview and things like that. We're going to talk about a new class called the UIDocumentInteractionController that automates a lot of this behavior for you. And finally, we're going to spend a little time covering the QuickLook framework. The QuickLook framework has been around on the desktop for quite awhile.

It's new to iOS and DocumentInteractionController uses it to handle preview functionality, but it's public and you can use it yourself, if the way that the DocumentInteractionController exposes it is not appropriate in your application. Alright, so let's start with the basics of documents on iOS. So this is a sample of what a document might look like by default, and the frameworks provide a view for you that represent a document. This is left up to you to build in a way that's appropriate for your look and feel in your application.

To the operating system, know you specify documents by URL and these will be file URLs. Here it's going to be the file type and there'll be some path into the sandbox in your application and in this case, the last path component is Beach Party.pdf. And we'll extract that last path component as the name that's visible to the user, and then we'll also extract the path extension from that name, and from that we're going to derive a UTI. We use UTIs for a wide variety of purposes. In this case, for PDF, the UTI for that is com.adobe.pdf.

Now, maybe then in your application, the last path component of URL isn't appropriate to display to the user. For example, if you use some sort of unique identifier for a document, in this case, you can actually replace the name, in this case, Beach Party.pdf and we'll still derive the UTI from the extension of that name.

You can also specify the UTI separately if that can't be derived from the extension of the name. And finally, documents have icons associated with them. These icons are provided by the application that registers itself as the owner of this particular file type. And so for the Pages document for example, the Pages icon will come from the Pages applications.

OK, let's move on to registering for documents. Just like on the desktop, if you're familiar with Mac OS X development, you register for documents via your applications Info.plist. And there's a specific key in there called CFBundleDocumentTypes, and this is the exact same key we use on the desktop to register for documents types. And this is an array of dictionaries. Now, these dictionaries can have quite a number of keys.

The documentation goes over all of the possible keys, but there are four that we're going to sort of touch on briefly today. The first is CFBundleTypeExtensions, and this is an array of extensions that you know how to open, in this case, PDF. The second is LSItemContentTypes, and this is just an array of the UTIs that are associated with these extensions, and so in this example com.adobe.pdf.

The third is CFBundleTypeName, and this is just the user visible string for this type of document, not for the specific document but for the generic type, in this case, PDF document. And finally, LSHandlerRank, and this allows you to fine tune the document's association with your application. There should be one application on the system which is defined as the owner typically. In the pages example we talked about, that would be the page's application.

It is the only one that actually owns pages type documents. But if other apps on the system like yours can open pages of documents, you would specify yourself as default or alternate and the documentation goes into some specifics as to why you might choose one over the other. If you just leave that key out, you'll get the default behavior and that's typically the most useful.

So this is what it looks like in your Info.plist. You have the key CFBundleDocumentTypes and as you see, it's an array of dictionaries, so this whole bundle worth of key value pairs could get duplicated for other extensions that you might want to register for. First key CFBundleTypeExtensions, as I mention, that's an array of strings, in this case PDF. LSItemContentTypes is also an array of strings, in this case, com.abode.pdf. And CFBundleTypeName is just a simple string in that PDF document.

OK. So, now you've registered your application to open a certain document type. How do you actually open that? Well, you do that with a couple of methods on the UIApplicationDelegate Protocol. So your application's delegate will receive these methods when needed to open a document. The first is application didFinishLaunchingWithOptions.

So right after your application is launched, this is one of the first methods you'll receive. And that Options dictionary as the second argument there has a large number of parameters, but there are three that are specific to opening documents. The first is UIApplicationLaunchOptionsURLKey and this is just that URL for that document that you're asked to open.

The second is UIApplicationLaunchOptions SourceApplicationKey, and this is the bundle identifier of the application which has asked that this document be opened. So if users in mail and they click on a document to open it and your application launches, you'll be sent the bundle identifier of our mail application. And the final key is UIApplicationLaunchOptions AnnotationKey.

Now, this is just an extra bag of information which is of a plist type that you can use if you want to pass information from one application to another. So let's say you have a suite of applications and you want to transfer a document from one to another and pass on a little bit of extra information so that resulting application can, let's say, open to the same spot in a document or something like that.

This is a good way to do that by default from nearby applications, this key won't be present. So, when you're sent this message, you're not expected to actually open the document inside this method. This is just an indictor of whether you can open it or should open it.

The return value for this is a Boolean. And if you return yes from that, you'll be sent a second method which is application handleOpenURL, and this is where you actually need to open the document. In fact, if your application is already running, you'll only receive the second method there to open a second document. With that, I'd like to bring Luke up on stage and he can run to a demo of what we covered at this point.

OK, thank you, Jason. So what I want to show you guys today is a practical example of how do we actually register to open some documents and then how do we actually go about opening those documents. So, as Jason talked about before, registering for documents is as simple as putting some keys into your Info.plist.

So, I'm going to show you what that actually looks like in Xcode. You got to see the XML before, so let's zoom in on this. Hopefully, I'd see a little better. OK. So this document is called PDF viewer, and it registers for two types of applications or two types of documents that is, text and PDF.

So here we have CFBundleDocumentTypes which as Jason said is an array of dictionaries. The first dictionary here is going to register for a text document, and so we have CFBundleTypeExtensions, so it's text. And we have CFBundleTypeName, that's the text document. And I'm also going to provide an icon file which uses CFBundleTypeIconFile. And we set the UTI using LSItemContentTypes which for this public all text.

And then we do the same thing for PDF documents. I have CFBundleTypeExtension PDF, CFBundleTypeName PDF document. Again, I defined an icon file which is using CFBundleType icon file, and the UTI for this is comwww.pdf. And really that's all I need to do to register to open PDF and text documents. It's simple entries in the Info.plist and I'm done.

So, let's see what that actually does for me in the context of other applications that might use UIDocumentInteractionController to open documents. I've installed PDF viewer along with another application called plain text viewer into my iPhone simulator, and plain text viewer is the same as PDF viewer except it only registers for the text file types.

And I have also put in this application called doc interaction which is a very simple implementation that is going to use UIDocumentInteractionController gto show us what happens when we actually register for these types. OK. So this application is a representation of a few documents that holds the text document image, PDF and HTML document.

And simply by having registered for those document types, namely PDF and text in those two applications, PDF viewer and text viewer, we'll see what happens when in this application I press and hold on this image, DocumentInteractionController gives me an option to open in PDF viewer and that comes simply from the Info.plist keys that I put in the Info.plist. It knows-- the PDF viewer knows how to handle that document type. And similarly, if we over the text document and do the same, I get Open In PDF viewer.

This also, this Open In button that we get here, if we click on, we see both PDF viewer and plain text viewer are registered for this document type. So, all that sort of external visibility that other applications get the opportunity to show the user that our application opens these documents come simply from these Info.plist keys.

OK, so we've learned how to register an application for document. But probably what we're more interested in doing is opening the document, when we actually are asked to by another application. So, as Jason talked about, we need to use some methods on the application delegate. So this application delegate already has application, did Finish Launching With Options, and now it returns Yes. This code is going to be very familiar to you. But what is going to be interesting for us to open a document is to use application: handleOpenURL.

Now this application, PDF viewer, is going to have a very simple implementation. It's just going to use a web view and load any URL that comes into it. We're going to take advantage of the fact that web views know how to handle text content and they know how to handle PDF content. So any text or PDF document that comes through us, we can just load into our Web View. So, let's implement application handleOpenURL.

The first time we run it, we just need to create our web view and add it into the window. That's very simple. The actual work is going to be done simply by loading the URL that is sent to us as the argument to handleOpenURL. So that's simply WebView loadrequest using an NSURLRequest with the URL that's handed to us. And application: handleOpenURL takes a Boolean argument, so we're just going to return "yes" that we successfully open the document, and that's really all the code we need to write to handle opening a document in this case.

Obviously, your application is likely to have unique things that you do to a document. But the important thing to remember is that application handleOpenURL is the place that you need to implement your special code that does what you do best to use the documents. So, let's go back to our simulator and just see this working.

We'll see that we actually can. Now, open a text document in PDF viewer, and there it is. Very simple text document but our viewer is able to open it by running the code in application handleOpenURL. So, that's how simple it is to register for an application-- or to register for a document type and then to open it.

Remember, we register using the Info.plist keys, and then we open the document by implementing handleOpenURL, which can be called any point in the application lifecycle at launch or later. Perhaps if your application is backgrounded, they might be brought back to the foreground to open a URL. So that's registering for and opening documents using UIDocumentInteractionController. So, I'll hand you back to Jason. Thank you, Jason.

Thanks, Luke. OK, let's move on to interacting with documents and specifically using the new UIDocumentInteractionController class to provide a lot of the same functionality that we just saw with demo. So, as we mentioned, we don't provide a-- of a view by default to attach or to represent the document and to attach these to do a-- to a DocumentInteractionController, but this is what it might look like. This is mail with a couple of different documents. And what does the DocumentInteractionController actually do for us? Well, the first thing it can do is actually present a full screen preview of these documents. This is what it looks like on iPhone and iPad.

The DocumentInteractionController can also present an Options menu. This gives the user a few high level choices, whether they want to Quick Look it, which is that preview functionality we just saw, or open it in whatever the default application for that document type is. Or if there are multiple applications, you can even open the-- choose Open In and pick one of the other ones.

If they do pick Open In, the DocumentInteractionController can automatically take care of presenting the user interface to show all of the applications which register for that document type on the system, and it takes care of the differences between iPhone or iPad just like we're seeing here. So, the first thing we need to do is create a UIDocumentInteractionController, and we do that with the class method interactionControllerWithURL.

Next, there are a few different properties we can use to configure the DocumentInteractionController, the first is that the URL, so even after you create it, you can change the document that the DocumentInteractionController refers to by just replacing the URL. And like I said before, you can override the name in UTI if they can't be derived from the URL that you give us.

So, that's almost all the information that you need to draw your view. There's one more piece that you need, and that is the icons. So there's an additional property on UIDocumentInteractionController called icons, and that just returns an array of UIImages that the owning application has defined for this document type.

And these UIImages are sorted from smallest to largest so you can look through there and find the one that makes the most sense for you in whichever, whatever way you're presenting it. So with that, we have all the information that you need to define your view and present it to the user.

But we still need to tie the view that you've provided to the DocumentInteractionController that you created on the backend so that you can get some of this automatic behavior. Fortunately, it is really easy to do that. There's an additional property on the DocumentInteractionController called rs. Now, Gesture Recognizers were introduced in iOS 3.2. And if you haven't had a chance to take a look at them, I strongly encourage you to. Gesture Recognizers allow you to decouple gesture recognition from your view's implementation.

And so, all you need to do to get the default set of Gesture Recognizers that we provide so that your views feel like every other view on the system that represents documents is to assign your view's Gesture Recognizer property to the Gesture Recognizer property returned by the DocumentInteractionController. So what does that actually get you? So again, we're-- here is our example with a couple of document views.

And what I get you right off the box is if a user taps on your view, full screen preview will get presented. If instead of tapping on your view, they press and hold on your view for a moment, they'll automatically get the Options menu. And if they click on the Open In button there, they'll automatically get the Open In menu.

So there's one more bit of work that we need to do to actually support the Quick Look behavior so that you can get that full screen preview. You need to assign the delegate of the DocumentInteractionController to some object in your application, and then there's a few methods that you need to implement. The first one to support Quick Look as required and that is documentInteractionController ViewControllerForPreview.

Basically, what happens under the cover is that the Quick Look framework provides a view controller to display that preview. But it needs to get presented somewhere in your application, and it's going to be presented modally on top of a view controller that you provide. This is the way you return that view controller so that we know where to present that full screen preview.

Now on iPad, there are a couple of more methods that you can implement to control that scale animation that comes up. If you've actually played with attachments in mail on iPad, you'll know that the full screen preview zooms up from that document icon, and you can do that by the methods documentInteractionController ViewForPreview and documentInteractionControllerRectForPreview, and we'll talk about those here in a second.

So, in this sample, this is mail, the view controller's view is that entire message view, so the entire size of the screen. But we don't want the preview to scale up from the full screen so we need to implement that method documentInteractionController ViewForPreview to return the specific view that we want to scale up from, in this case, the one that the user clicked on.

But we really don't even want to scale up from that full view, we really want to scale up from that icon inside the view, and maybe there isn't a view associated with that. If the view that you've provided simply uses a drawRect to draw all the pieces, that's where that last method documentInteractionController RectForPreview, that lets you specify the subRect within that view where the preview should start scaling from.

Alright, there's a bunch of delegate notifications that the DocumentInteractionController sends to you that you can use to change your UI in response to various actions happening automatically by the DocumentInteractionController. The first pair we're going to look at is documentInteractionControllerWillBeginPreview and DidEndPreview. So if the user taps on your view and that preview appears, you'll get these notifications when the preview ends or begins. And then when the user clicks the Close or Done button, you'll get the second notification that the preview ended.

There are similar pairs of methods to be notified when the Options menu first appears or is dismissed, and there's a similar set for the Open In... menu. So when that pops up, you'll get that first notification. When the user dismisses it either by clicking the Cancel button on the iPhone case or just anywhere outside the popover in the iPad case, you'll get the DidDismiss. Now, if the user actually clicks on one of those applications to open it in another application, your application will receive the documentInteractionController willBeginSendingToApplication.

And once the copy has made it over to the other application sandbox, you're sent documentInteractionController didEndSendingToApplication. And this is a really good time for you to clean up any temporary state that you had that was associated with that document. So again, the user clicks on one of these, you'll receive these methods in sequence as that icon-- or as the document is copied over the other applications sandbox.

Now, you can also control that Options menu, and what appears in there with this method or this pair of methods here, documentInteractionController canPerformAction. Now, right now in UIDocumentInteractionController, there is one additional action that you can associate with that Options menu, and that's the Copy action. You'll be sent documentInteractionController canPerformAction and the actual will be the copy action. And if you return Yes from that, will automatically insert a Copy menu item in that Options menu.

And if the user clicks on that Copy menu item, you'll be sent the second method, documentInteractionController performAction. And although right now, the only methods we send or the only actions we send are the copy actions, you shouldn't assume that will always be the case. We may add other actions overtime, so be sure and sort of code defensively make sure you're checking for the action that you want. With that, let's bring Luke up again and take you to all of these.

OK, thank you again, Jason. Alright, so in the last demo, we saw how to register for the document type and then how to implement handleOpenURL in your application delegate to actually open a document. Now, to build on what Jason just talked about, I want to show you how to actually create a UIDocumentInteractionController in your application so that you can provide the user things like preview and ability to send a document to other applications. And then also, we're going to show you a few examples of using the properties and the delegate methods of UIDocumentInteractionController to customize it a little bit.

So, let's start by going into these applications, this doc interaction, and I'll show you-- I'll begin just by showing you what it looks like. OK, so this is similar to what you saw before, sort of an unfinished version and it represents the four documents, text, image, PDF, and HTML.

But it really doesn't do much else other than display some text and, you know, tell us what the document is. There is no icon there. I can't do anything by clicking on it. It really just is text. So, we want to enhance that by using our document interaction controller to give the users some interactivity with the documents, and also to enhance the look a little bit.

So, let's go into my custom UITableViewCell code, and it has this method, set document name, the extension, index, and table view controller. And it's simply a method on the table view cell to associate a document with the table view cell, and we're going to compose that with the document and its extension and the index in the table view controller give us some back preferences that we'll be able to support interaction with the controller in preview. So, in order to set up UIDocumentInteractionController, we're going to need a URL. So we're going to build that URL from the file path which we've gotten from NSBundle using a document and extension.

So we get doc URL simply by alloc initing with the file URL path. No one used that URL to actually build UIDocumentInteractionController. So let's create one with alloc init and then we set the DocumentInteractionController's URL property to the URL that we built. We also need to set the delegate of the UIDocumentInteractionController. We'll set that to self and then we can go ahead and release the document URL.

So, now we've created a document interaction controller. We want to use it to enhance the look of our cell a little bit, so we're going to take advantage of the icons property on the document interaction controller to actually be able to put an icon in the cell that represents the document. The icons property is an array of icons ordered from smallest to largest and we're going to get the count of the icons from the DocumentInteractionController.

As long as that's greater than zero, we will just take the last one, which will be the largest, and set that as the image of the cells image view. So using just that, we can run our application. And now, simply by creating a UIDocumentInteractionController and using the icon from it, you see that we've improved the look of our application a little bit. We now have icons associated with the various document types.

The thing that we don't have is interaction. So, DocumentInteractionController, as Jason talked about before, comes with a great way to add canned, consistent interaction that the user will recognize across all applications in the system, and we do that via the gesture Recognizer's property. The gestureRecognizer property, as Jason said before, gives us two gesture Recognizers. One that if you-- user taps on the view, it will provide a preview, and two, if the user presses and hold, that's UILongPressGestureRecognizer. It will present the Options menu from the DocumentInteractionController.

So actually, adding the gestureRecognizer to your view is as simple as this line, self.gestureRecognizers = documentInteractionController. gestureRecognizers. Now, if I had other Gesture Recognizers on my view, I could have gone through a loop and added the Gesture Recognizers from the DocumentInteractionController to my view one at a time. But in this case, I don't have any other Gesture Recognizers so it's very simple, I can just do self.gestureRecognizers equals the ones from the DocumentInteractionController.

So, now that I've done that, I need to do one more thing to actually support Quick Look and preview in my application. And that's to implement the delegate method documentInteractionControllerViewControllerForPreview as Jason said before. Now, I've saved a way, the table view controller in my setDocumentName method. So for me, this is as simple as returning that table view controller. So now we have documentInteractionControllerViewControllerForPreview, that simply return the table view controller.

Now that DocumentInteractionController has a view controller to provide the preview on, we should have all we need to support both preview and opening the Options menu on our cell. So let's take a look at that. OK, everything looks the same as before. Now, let's see what happens when I tap on a cell: Preview pops up; that's exactly what we wanted. We got that simply from setting the Gesture Recognizers on our view, which is the cell.

Furthermore, if I tap and hold on say text document, I get the ability to-- I get the Options menu which gives the user a Quick Look option and also the ability to open in any other documents that are registered for that document type. Both of those actions came simply from setting the gesture recognizers on the view. And of course implementing ViewControllerForPreview Support Preview. OK, so that's good. Now I'd like to customize a little bit.

If you look at this view, we see we have the document name is Text Document, dub text actually. And that has survived form the URL that we provided to the document interaction controller. Now Jason said before, we divide the name from the URL unless you derive the UTI from the name.

So I want to give it a custom name, say I just want to call it "my doc" or whatever makes sense for my application. I can do that by going back to my code where I create the document interaction controller. And I'll simply change the name, DocumentInteractionController.name = mydoc. Let's give that a shot.

OK, so now I QuickLook my doc, or rather text document, when actually it's called "my doc". But something weird happened, our icons went away. Why did that happen? Well, as I said and as Jason said, the UTI is derived form the name and I change the name to an obviously ambiguous one "my doc," how could we possibly know what kind of document that is? So if I'm going to override the name to something ambiguous like my doc then I need to also override the UTI so that the document interaction controller knows what kind of document I'm talking about.

Now in this case, all I ever really wanted to do was change the name so rather than trying to calculate the UTI myself from the URL, I'm going to let the document interaction controller do that. So the point that I change the name, the DocumentInteractionController already knew the UTI. So I'm just going to store that away before I change the name.

Create a variable called UTI and store the DocumentInteractionController.UTI which is an NSString. Then after I set the name, I simply restore that value by doing DocumentInteractionController.UTI = UTI. I'd set the UTI right back after I change the name. So now doing that, I can run again. I got my icons back and I still have my custom name "my doc." So that's how I can use the name property and the UTI property to customize the name that you'll see in the preview a little bit.

OK, so now, let's look at this one more time. You see I have these checkmarks on the UITableView cells. Right now I'm not doing anything. But my intention is that this checkmarks indicate a document that is not read. And I want to respond to the user actually sort of opening or looking at the document by removing that checkmark and indicating that this is a read document.

I can do that by using a couple of delegate methods from the document interaction controller. Namely, I'm going to use documentInteractionControllerDidEndPreview. And it's also possible that the user instead of previewing looked at the document by sending into another application. So I'm also going to implement documentInteractionControllerDidEndSendingToApplication. So this code is going to be very simple. We'll start by implementing documentInteractionControllerDidEndPreview.

So my cell knows how to display itself by the document read property. Namely, if the document is read, don't show the checkmark and if it is not read do show the check mark. So all I need to do in my didEndPreview method is change the value of document read so do that setting to "yes". And the second things I'm going to do is simply notify my table view control of the read state. And that's all I need to do.

My cell will update its view based on the document read state and I'll be done. Now let's go ahead and see that running. You see now that I can preview the image. And when I let it go, a check mark goes away indicating to the user that I've read the document, or in this case, viewed it.

So the other case is if the user actually opens the document in another application. For that, we're going to use documentInteractionControllerDidEndSendingToApplication. The code is going to be exactly the same because I'll again all I need to do is update the document read state of my table view cell.

So, we set document read again. And again, notify the table view controller. And with this very simple code implemented in Interaction Controller didEndSendingToApplication, I'll be able to use the same document as read feature when I sent the document to another application. So let's try sending this document to the PDF Viewer which we looked for.

OK. PDF viewer displays the text. And now, since this is iOS 40, our application is suspended in the background and when we go back to that application it will continue running and we've gotten our documentInteractionController: didEndSendingToApplication, so the viewer when they return to the application see that our text document is now read.

So using those simple delegate callbacks we're able to add a little bit more polish and custom behavior to our application. And in that, we've seen just how simple it is to add a UIDocumentInteractionController to your applications so that you can begin to allow the user to Quick Look documents as well as send them to other applications and we've also seen how we can customize that a little bit using the name and the UTI properties and using the delegate callbacks to add more polish to our application. So let's getting started building a UIDocumentInterActionController and I'll hand you back to Jason again for some more sights.

Thanks again, Luke. So that shows you how easy it is to use the built-in Gesture Recognizers to provide a bunch of automatic interaction with your view. But it may not be appropriate in your application for tap to bring up the preview or press and hold to bring up those options menus. Say for example you've-- that the view that represents a document in your application is a cell in a table view and you want tap to be able to select that row.

You don't have to look up those gesture recognizers. All that same functionality is exposed in methods on document interaction controller and so you can drive all those interface elements directly. Start with Present Preview. There are two methods that you want to know about. The first is presentPreviewAnimated and dismissPreviewAnimated.

When you call that, a full screen preview will be shown just like it would if the user had tapped on it and you have the Gesture Recognizers hooked up and we'll use all the same machinery under the covers, the view controller that you return to us direct the view, all those sort of things are used to present the preview.

You can also directly present the options menu. There are two ways you can do this. The first is presentOptionsMenuFromRect inView. That will give you that for scale up that we talked about. The other is presentOptionsMenuFromBarButtonItem. And if you want to dismiss the Options Menu you do that with dismissMenuAnimated and you'll get the option menu.

Similarly, there are cool set of method to present the Open In Menu, presentOpenInMenuFromRect: inView: animated: and presentOpenInMenuFromBarButtonItem: animated: and use the exact same dismissMenuAnimated method to tear down the Open In Menu. If you do that again, that forces the Open In Menu on screen. So let's now look at a demo where we use an alternate way to present some of this UI from the Document Interaction Controller.

So in the last application, we saw basic usage of creating a UIDocumentInteractionController, when using the Can Gesture Recognizers to add some interactivity to our view. But as Jason just walked through, you know, sometimes we want to explicitly show the preview in code-- via code-- or show the options menu via code or even the Open In Menu.

So I'm going to go back to your code here and we're going to implement basically the same thing we had before but we're just going to modify to show you an example of how we might do this if we wanted to handle the showing of the preview and the options menu ourselves. So the first thing I did, there you see as I commented out self to adjust to recognizers equals documentInteractionContoller.gestureRecognizers. That was the thing that did all that work for us before. We want to make life a little more difficult this time.

And so what we're going to do is we're going to allow the table views, didSelectRowAtIndexPath method, that's going to be what we're going to use to display the preview and the user selects a row. We're going to display the preview. And then we're going to move our sort of long press gesture to the actual image view in the table view cell. So let's start with that long press gesture.

If you're not familiar with gesture recognizers they, you know, go on a specific view and they calculate the gestures that happened on that view that did the touch handling for you and hopefully you'll go to the gesture recognizer session tomorrow. So this is going to be as simple as creating a UI long press gesture recognizer, just like that, we alloc init. Gesture Recognizers use a target action pattern.

So we use self as a target and the action is "handle long press," which is a method that we'll write in a second and then we just need to add that Gesture Recognizer to the image view. Since we're going to use a long press now, only on the image view not the entire cell itself. So, we have image view adjust Recognizer. Now, we can release our gesture.

And maybe one more thing because image views have user interaction disabled by default, we're going to enable user interaction on our image view. So we used the action "handle long press" for our Gesture Recognizer. So, it's something that we need to implement and this is why we're going to actually tell the document interaction controller to present the Options menu.

OK. So handle long press-- it's going to look sort of like this in the shell. Gestures Recognizers use a series of states from possible begun, ended, cancel, change, things like that in their action. So all we're interested for a long press the begun state, because that's when the user has pressed and held long enough for a long press to begin.

So in that begun state, now all we need to do is tell our document interaction controller to present the Options menu. That looks like this, documentInteractionController: presentOptionsMenuFromRect: inView: animated. Now, as Jason touched on before, the rect and the view don't mean anything on an iPhone because we just display an action sheet.

On iPad this would be the view interacts that the animation for the preview comes from. So that's the long press. Now, we're going to go to the table viewController. Now we need to do is implement table view didSelectRowAtIndexPath and tell the DocumentInteractionController to present a preview since we want to do this manually now.

So in didSelectRowAtIndexPath, first thing we need to do is actually get the Document Interaction Controller. Each one of our cells has a Document Interaction Controller associated with it. So we need to get the cell from the table view. Table view cell for RowAtIndexPath and then query that cell for its Document Interaction Controller, that's what we do here.

So now we have the Document Interaction Controller, we just need to tell it to present its preview. DocumentInteractionController: presentPreviewAnimated: yes. So we've eliminated the self to adjust to recognizers equals documentInteractionController.gestureRecognizers and we've used actual explicit calls to the display the Options Menu and the preview. And we'll see that work now.

When I select the cell, the preview is displayed for us just as before. And similarly, when I go and if I long press on the cell, we'll see it doesn't do anything anymore since we're no longer using the gesture recognizers on the cell itself. But if I go over here and I long press on the image view which is the icon I get my Options Menu again which I am manually displaying with the code.

So obviously, it's very easy and in general we're going to recommend that you use the canned gesture recognizers that come with UIDocumentInteractionController. But if it makes sense for your application to manually present the Options Menu, the opening menu or the preview in code that's exactly how you do that and you see of course it's very easy. So that's all I need to show you there and I'll hand you back to Jason once again for some more sights.

Thanks again, Luke. Alright, finally, let's talk a little bit about the Quick Look Framework. As I mentioned before the Quick Look framework sits below the Document Interaction Controller and provides that full screen preview but you can control that more directly if that makes sense in your application. So what does it provide to you? Well it provides a dedicated view controller that's used to preview documents. Here's a simple example of the preview print and preview in a numbers document but the QLPreviewController supports a wide variety of document types.

We support PDF, HTML, and a wide variety of rich formats-- rich text formats as well as a wide variety of plain text formats, a large number of image types are supported, contacts, and events can be previewed directly as well as all of the Apple iWork document types and Microsoft Office document types.

And if you were, like I said before, familiar with Quick Look on the desktop, the API is very similar on the device. So to get started, all we need to do is create a QLPreviewController and we do that by importing the Quick Look header out of the Quick Look framework and then simply allocating and initializing the QLPreviewController.

Now this is just a subclass of UIViewController so you present it like you would in any other view controller. You can either use UIViewControllers presentModalViewController: animated: method which will present the preview controller in a modal fashion on top of your view controller and that's what the Document Interaction Controller typically does or you can push a view controller onto a navigation stack.

Now the Document Interaction Controller actually will also do this one too if the view controller that you happen to returned to us is a navigation controller. So that gets the view controller on screen but we haven't given it any content yet. The QLPreviewController uses a data source model to get its content and there are two methods you need to implement to provide data to the QLPreviewController. The first is numberOfPreviewItemsInPreviewController: and the second one is previewController: previewItemAtIndex. So here's a simple sort of graphical example. In your model, you have some number of items that you want to preview.

And using these two methods, you tell the preview controller how many you have and when asked by the preview controller you return the appropriate one at that index. Now in order to actually display these, these items need to implement the QLPreviewItem protocol. So what's that? Well first I should mention that there is one class in our system that already implements the QLPreviewItem protocol and that's NSURL. So if the URL for your document expresses everything you want to display the last path component has the name that you would like to display visually, you can just return the URL to the QLPreview Controller. Your document will be previewed.

But if you want to change that name that appears at the top like we did in the Document Interaction Controller, you'll want to provide some alternate object and this can be a really simple little object. There are only two methods that you need to implement in the QLPreviewItem protocol. The first is that URL. You obviously already had that so just return it.

And the second is the title which is the thing you want to display at the top. So again, this is a really tiny little class. It's trivial to implement if you do need to change the behavior. There are a few delegate methods that are interesting that the QLPreviewController offers.

The first two are notifications on dismissal of the preview. When the dismissal is about to happen and after it did dismiss, you're sent these delegate messages. The third preview controller should open URL for preview item-- is called if the document that's being previewed has a clickable link in it and the user clicks on it, you're sent this message and there's a Boolean return here and you can indicate whether the user is allowed to open that link. With that, let's bring Luke up one last time and take a look at how to use QLPreviewController directly.

OK, thanks Jason. Alright. So up to this point, we've seen how to use a UIDocumentInteractionController and the various things that we can do with that. And that's great for interacting with one document in time but sometimes we want to go down and actually use the QLPreviewController and one of the main advantages that we get from that is we can allow the user to Quick Look a set of documents sort of as a set rather than one document at a time as we saw before. So let's go back to our application and we're going to change the implementation to use QLPreviewController.

So we're here back in our table view controller and this is the table view didSelectRowAtIndexPath that we just implemented to present the preview. Well, we're going to go ahead and get rid of that because we're going to now do Quick Look via QLPreviewController. And let's see just how easy that is. So obviously, first thing we need to do is create a QLPreviewController. Do that with alloc init. We want to delegate in the data source to be our self. So we'll do that.

We need to tell the preview controller what index to start at in the set of documents that we're getting that and we get that easily from the index path that was sent in to table viewed didSelectRowAtIndexPath. So we set the current preview item index to the-- to the section because each document gets its own section in our application. And then we simply need to display the preview controller. So we do that with presentModalViewController, animate the preview controller. Then we can go ahead and release the preview controller.

So we need to implement to the data source methods, the two data source methods, so that our preview controller will work. We need to tell it how many preview items are in the QLPreviewController. So we do that with numberOfPreviewItemsInPreviewController. For us, it's very simple. We return a macro num docs which represents the four documents that our application uses. So that's just four, very simple. And then we need to return a QLPreview item for each item that the user might Quick Look.

As Jason talked about before, NSURL already implements the QLPreview item protocol. So it is a fully qualified preview item. And we'll take advantage of that in our app to just return NSURLs for each preview item. So previewController: previewItemAtIndex:, we're going to get the file path from NSBundle the same way we did in the cell before when we used that file patch to create a URL, same as we did before. Set the URL to null and then we have a valid file path. We can just create it using NSURL-- URLWithPath and then all we need to do is return that URL.

OK. So we've implemented the two data source methods, numberOfPreviewItemsInPreviewController: and PreviewController preview Item At Index And that would be enough to get started using the preview-- QLPreviewController in our application. So now, when the user taps on the document, we get a preview, a Quick Look, just the same as before except there's one little difference and you'll see down here, there's a little bar and that actually allows the user to interact with the documents as a set. We have a set of four that the user can now arrow through and Quick Look each one of them in turn.

Now, something else has changed. You'll see that our check marks no longer disappear when we view the documents. If we're going to be using QLPreviewController, this is something that we need to re-implement for the QLPreviewController since that was set up UIDocumentInteractionController before. Fortunately for us, this is going to be a trivial task as we simply need to mark each document as read as we hit it in previewController: previewItemAtIndex.

So as soon as we create the URL, we can simply use the index that's given to us as an argument and set the document read based on that index and now when we run it, see, I can quickly click text document. I can arrow over to image document and when that's done, both of those document types are marked as read. So I was able to re-implement that using the QLPreview Controller.

As Jason talked about before, I could also re-implement the custom naming if I wanted to create my own QLPreview item compliant object, but in this case, I'll leave it at that and I encourage any of you who are interested to explore writing that yourself. So that's another option that we can use, QLPreviewController. We have both UIDocumentInteractionController and QLPreviewController.

Document Interaction Controller allows us to interact as one document at a time and the QLPreviewController allows us to use-- allows us to present them to the user as a set, so these are couple of options that we have at our behesty as programmers and I hope you enjoy using them. So thank you very much and I'll hand you back once more to Jason.

Alright, thanks again Luke. If you wanted more information, the application frameworks evangelist is Bill Dudney and his contact info is here. There's also Documentation for the UIDocumentInteractionController up on developer.apple.com. So the URL is a little long here but you can search for that. And of course the Developer Forums are a great place to get your questions answered. There's a bunch of the engineers who hang out there as well as a lot of you guys and you don't have to go through this alone. There're a lot of people out there that can help.

There are a couple of related sessions. We talked about Gesture Recognizers and their use briefly. But Gesture Recognizers are really powerful and allow you to add a lot of really rich interaction to your applications. There are two sessions tomorrow. The first one talks about how to use all the built-in Gesture Recognizers. The second one talks about how to write your own Gesture Recognizers. So quickly in summary, adding support for documents in your application is really simple.

Hopefully, I've shown it's-- not much work for you to do that. And so, I encourage you to do that. And secondly, if you're going to allow interaction with documents, please use UIDocumentInteractionController. It'll not only automate a lot of work for you, it'll provide a level of consistency in your application with all of the built-in application and other applications provided by third party developers.