IOS document Interaction Programming Guide

Original article: http://developer.apple.com/library/ios/#documentation/FileManagement/Conceptual/DocumentInteraction_TopicsForIOS/Introduction/Introduction.html

About documentinteraction

 

IOS supports previewing and displaying documents with other apps in your app. IOS also supports file association, allowing other apps to open files through your program. These technologies include the uidocumentinteractioncontroller class (Uidocumentinteractioncontroller class reference), And the quick look framework (Quick look framework reference).

 

Since ios4.2, the quick look framework provides built-in file printing support. If you want to customize your own printing and copying behaviors, You can implement the documentinteraction controller delegate method to provide support. For sample code of the uidocumentinteractioncontroller and qlpreviewcontroller classes, seeDocinteractionSample project.

Preview document and present option menu

If your app needs to open files that it does not support, use uidocumentinteractioncontroller. A documentinteraction controller uses the quick look framework to determine whether a document can be opened and previewed by another app. That is to say, your app provides users with optional operations through documentinteraction controller.

To use a document interaction controller, follow these steps:

1. Create a uidocumentinteractioncontroller instance for each file you want to open.

2. Provide an image representation of the file in the app UI (generally, you should display the file name or icon ).

3. If the user interacts with this object, for example, by touching this control, the document interaction controller is called to display the following interface:

O preview the content of the file.

O A menu containing preview and open operations. You can add other operations to the menu by implementing some delegate methods, such as copying and printing.

O a menu that only contains the "open in other ways" operation.

Documentinteraction controller has built-in gestures that you can directly implement their actions.

Document interaction controller can be used for apps that need to interact with files. Most of these programs need to download files from the network. For example, the email program needs to open and preview the email attachment.

Document interaction controller is required even for apps that never download files. For example, your app needs to support file sharing (refer to "file-sharing support" inIOS technology OverviewAndDocinteractionExample project), you can use documentinteraction controller to synchronize files to the app documents/shared directory.

Create documentinteraction Controller

Create a document interaction controller instance, instantiate it with the file you want to open, and set its delegate attribute. The delegate object informs the document interaction controller of the information required to present the view and the actions to be executed when the view is displayed and interacted with the user.

See the following code. Note that the caller of the method must retain the returned object.

 

- (UIDocumentInteractionController *) setupControllerWithURL: (NSURL) fileURL

usingDelegate: (id <UIDocumentInteractionControllerDelegate>) interactionDelegate {

UIDocumentInteractionController *interactionController =

[UIDocumentInteractionController interactionControllerWithURL: fileURL];

interactionController.delegate = interactionDelegate;

return interactionController;

}

 

After creating the document interaction controller, you can use its attributes to read the information of the associated file, including the file name, type, and URL. The controllery also has an icons attribute, which contains multiple uiimage objects. This attribute is used to indicate multiple icons of the document size. This information can be used in the UI.

If you want users to open this file in other programs, you can use the annotation attribute of controller to put the additional information required by the program. Of course, the information format must be recognized by the application. For example, this property will be used by a single program in an application suite. The annotation attribute can be used when the program wants to interact with other programs in the suite. When an application is called to open a file, the option dictionary contains the annotation value. You can use uiapplicationlaunchoptionsannotationkey as the key to retrieve it in the option dictionary.

Render document interactioncontroller

With documentinteraction controller, You can preview the file or use the pop-up menu to select the corresponding action.

· In the mode display file preview window, call presentpreviewanimated: method.

· The pop-up menu prompts you to select the action and call presentoptionsmenufromrect: inview: animated: Or presentoptionsmenufrombarbuttonitem: animated: method.

· Prompt the user to open the file with another program and call presentopeninmenufromrect: inview: animated: method or presentopeninmenufrombarbuttonitem: animated: method.

These methods will display a view-either a preview window or a pop-up menu. The return value must be checked for any method call. The returned value is no, indicating that the view does not have any content and cannot be displayed. For example, the presentopeninmenufromrect: inview: animated: method returns no, indicating that no program in the installed program can open this document.

To display the preview window, the delegate object must implement documentinteractioncontrollerviewcontrollerforpreview: method. The preview window is displayed as a mode window. Therefore, you need to return a View Controller in this method as the parent window of the preview window. If you do not implement this method, or return nil in this method, or the View Controller you return cannot render the mode window, the preview window will not be displayed.

Document interactioncontroller will automatically disband the window it presents. Of course, you can also call dismissmenuanimated: Or dismisspreviewanimated: to manually disband it.

In the example projectDocinteractionDemonstrate how to present a document interaction controller (using Gesture Recognition ).

 

Types of documents supported by registered applications

If your program can open a specific file type, you can use the info. pllist file registration program to open the file type. When other programs ask the system which programs can recognize this type of files, your programs will be listed in the Options menu for users to choose from.

Related chapters:"Register the file types supported by the application"

File Types supported by Application Registration

If your program can open a file, you can register it with the system. This will run other programs using the document Interaction Technology of IOS to provide users with a choice, and thus call your program to process these files.

This requires that the cfbundledocumenttypes key be included in the info. plist file of the Program (see "corefoundation keys "). The system registers the content contained in this key so that other programs can access this information through document interaction controller.

CFBundleDocumentTypesA key is a dictionary array, and a dictionary represents a specified document type. A document type usually corresponds to a certain file type. However, if your program uses the same processing method for multiple file types, you can also divide these types into one group and treat them as one document type. For example, one of the local document types used in your program is in the old format, and the other is in the new format (It seems to be an image of Microsoft Office documents ), you can divide the two into one group and put them in the same document type. In this way, files in the old and new formats are displayed as the same document type and opened in the same way.

CFBundleDocumentTypesEach dictionary in the array may contain the following keys:

·CFBundleTypeNameSpecify the document type name.

·CFBundleTypeIconFilesIs an array containing multiple image file names, used as the document icon.

·LSItemContentTypesIs an array that contains multiple string of the uti type. The UTI type is the file type included in this document type (group.

·LSHandlerRankIndicates whether an application is "owned" or "opened.

From an application perspective, a document type is actually a file type (or multiple file types), which treats all files of the same document type as the same. For example, an image processing program may regard various image files as different document types, which facilitates Optimization Based on each type. However, for a word processing program, it does not care about the real image format. It treats all the image formats as a document type.

The following table lists a cfbundletypename example in info. plist.

LSItemContentTypesIndicates the uti corresponding to the file format,CFBundleTypeIconFilesSpecifies the icon resource used for this type.

Table 1Document Type in 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>

AboutCFBundleDocumentTypesFor more information about the key, seeInfoplist key reference.

 

Open files in other applications

The system may request a program to open a file and display the open option menu to the user. The most common case is that an application has registered a supported file type. In this way, the system will pass the File URL to your application and put it in the foreground.

Related chapters:"Open supported file types"

Open supported file types

The system may request a program to open a certain file and present it to the user. This usually occurs when an application calls document interaction controller to process a file. You can delegate

 application:didFinishLaunchingWithOptions:Method. If your program needs to process some custom file types, you must implement this delegate method (insteadapplicationDidFinishLaunching:Method) and use this method to start the application.

 

application:didFinishLaunchingWithOptions:The option parameter of the method contains information about the file to be opened. In particular, you need to care about the following keys in the program:

·UIApplicationLaunchOptionsURLKeyTheNSURL.

·UIApplicationLaunchOptionsSourceApplicationKeyContains the bundle ID of the application sending the request.

·UIApplicationLaunchOptionsSourceApplicationKeyContains the attribute list objects related to the file passed by the source program to the target program.

IfUIApplicationLaunchOptionsURLKeyKey exists. Your program should immediately use this URL to open the file and present the content to the user. Other keys can be used to collect parameters and information related to opened files.

 

Preview and print in quick look Previews

To get more file preview functions, you can directly use the quick look framework. You can select the animation style when the preview window is displayed, and you can preview multiple files as you want to preview a single file. Quicklook preview controller also has built-in support for airprint printing of file types.

Related chapters:"Using quick look framework"

Use Quick look framework

 

The quick look framework provides enhanced preview functions. This framework mainly providesQLPreviewControllerClass. This class depends on the delegate object to respond to the preview action and a data source used to provide the preview file.

Starting from IOS 4.2, quicklook preview Controller provides a preview view containing an action button (that is, a print button. For files that can be previewed by the Controller, the action button can print this document. You do not need to write any printed code.

You can use the following method to display a quick look preview controller:

· Use the navigation controller to display the preview window in Push mode.

· Display in a modal window using the presentmodalviewcontroller: animated: Method of uiviewcontroller.

· Display a document interaction controller (as described in "preview and open a file ). You can select "quick look" from the Options menu of document interaction controller to open a quicklook preview controller.

When displaying quick lookpreview controller, select the appropriate appearance and navigation method for your application. If your program does not use a navigation bar, it is appropriate to use a full screen mode quick lookpreview controller. If your program uses an iPhone-style navigation, it is appropriate to display the preview window in Push mode.

The preview window contains a title that displays the last path of the File URL. To overload the title, you can customize the previewitem class and implement the previewitemtitle method in the qlpreviewitem protocol.

Quick look previewcontroller can preview the following files:

· Iwork document

· Microsoft Office documentation (for Versions later than office '97)

· Rich Text Format (RTF) Document

· PDF document

· Images

· Text file, whose uniform type identifier (UTI) is inpublic.textFile definition (ViewUniformtype identifiers reference)

· Comma-separated value (CSV) File

To use quicklook preview controller, you must specify the data source object (that is, implement the qlpreviewcontrollerdatasource Protocol). Please referQlpreviewcontrollerdatasource Protocol Reference). The data source provides preivew items for quick look preview controller and specifies their quantity to include them in a preview navigation list. The list contains multiple objects and a navigation arrow is displayed in the modal preview window (full screen) to switch between multiple preview objects. For quicklook preview controller displayed in the push mode of the navigation controller, You can provide buttons on the navigation bar to see the switch in the preview Object List.

For details about the quick look framework, seeIosquick look framework Manual.