UIDocumentInteractionController Class Reference

Inherits from
NSObject
Conforms to
UIActionSheetDelegate
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.2 and later.
Companion guide
Document Interaction Programming Topics for iOS
Declared in
UIDocumentInteractionController.h
Related sample code

Overview

A document interaction controller, along with a delegate object, provides in-app support for managing user interactions with files in the local system. For example, an email program might use this class to allow the user to preview attachments and open them in other apps. Use this class to present an appropriate user interface for previewing, opening, copying, or printing a specified file.

After presenting its user interface, a document interaction controller handles all interactions needed to support file preview and menu display. In some cases the object employs a delegate to determine how to respond to specific commands. For example, to provide copying or printing, you must implement the documentInteractionController:canPerformAction: and documentInteractionController:performAction: delegate methods.

You can also use the delegate to participate with interactions occurring within the presented interface. For example, the delegate is notified when a file is about to be handed off to another application for opening. For a complete description of the methods you can implement in your delegate, see UIDocumentInteractionControllerDelegate Protocol Reference.

Tasks

Creating the Document Interaction Controller

Presenting and Dismissing a Document Preview

Presenting and Dismissing Menus

Accessing the Target Document’s Attributes

Accessing the Controller Attributes

Properties

annotation

Custom property list information for the target file.

@property(nonatomic,retain) id annotation
Discussion

Use this property to pass information about the document type to the app responsible for opening it. The type of this object should be one used to contain property list information, namely NSDictionary, NSArray, NSData, NSString, NSNumber, or NSDate.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

delegate

The delegate you want to receive document interaction notifications.

@property(nonatomic,assign) id<UIDocumentInteractionControllerDelegate> delegate
Discussion

You can implement a delegate object to track user interactions with menu items displayed by the document interaction controller. For more information, see UIDocumentInteractionControllerDelegate Protocol Reference.

The default value of this property is nil.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
UIDocumentInteractionController.h

gestureRecognizers

The system-supplied gesture recognizers for presenting a document interaction controller. (read-only)

@property(nonatomic,readonly) NSArray *gestureRecognizers
Discussion

The objects in the gestureRecognizers array each descend from the UIGestureRecognizer class. You can attach these gesture recognizers to the view you use to represent a document. For example, if you represent a document by name or icon in a table view cell , you can attach a document interaction controller’s gesture recognizers using code like this:

cell.contentView.gestureRecognizers = self.docInteractionController.gestureRecognizers;

(In this statement, the cell object is an instance of the UITableViewCell class and the docInteractionController instance variable points to the document interaction controller for the document named in the cell.)

With gesture recognizers so attached, a user gesture automatically initiates the appropriate action. A tap gestures initiates a preview of the associated document. A long press gesture displays the options menu relevant to the document.

The UIDocumentInteractionController class supports only the tap (UITapGestureRecognizer) and long press (UILongPressGestureRecognizer) gesture recognizers.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

icons

The images associated with the target file. (read-only)

@property(nonatomic,readonly) NSArray *icons
Discussion

This property contains an array of UIImage objects containing the available icons for the given file. The images in the array are sorted from smallest to largest, with the smallest image located at index 0. The returned array always contains at least one image.

The images themselves are provided by the system and determined by the UTI of the file. Apps can register custom icons for their associated files by including the appropriate meta information in their Info.plist file. If no custom icon exists, the images in this property represent the generic document icon.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

name

The name of the target file.

@property(nonatomic,copy) NSString *name
Discussion

This property contains the filename without any preceding path information. The default value of this property is derived from the path information in the URL property. You can change the value of this property as needed if you want to associate a different name with the file.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

URL

The URL identifying the target file on the local filesystem.

@property(nonatomic,retain) NSURL *URL
Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

UTI

The type of the target file.

@property(nonatomic,copy) NSString *UTI
Discussion

The value of this property is used to determine which apps are capable of opening the document. The default value is determined automatically whenever possible. However, if the document is a custom type that cannot be determined readily, the value of this property may be nil. If you know the type of the document, you can set the value of this property explicitly.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

Class Methods

interactionControllerWithURL:

Creates and returns a new UIDocumentationInteractionController object initialized with the specified URL.

+ (UIDocumentInteractionController *)interactionControllerWithURL:(NSURL *)url
Parameters
url

A URL that specifies the location of the desired document. This parameter is retained. It can be changed later by modifying the URL property.

Return Value

A new document interaction controller object.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
UIDocumentInteractionController.h

Instance Methods

dismissMenuAnimated:

Dismisses the currently active menu.

- (void)dismissMenuAnimated:(BOOL)animated
Parameters
animated

Specify YES to animate the dismissal of the currently active menu or NO to dismiss it immediately.

Discussion

Use this method to dismiss a menu programmatically. The document interaction controller can also dismiss the menu automatically in response to user actions.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

dismissPreviewAnimated:

Dismisses the currently active document preview.

- (void)dismissPreviewAnimated:(BOOL)animated
Parameters
animated

Specify YES to animate the dismissal of the document preview or NO to dismiss it immediately.

Discussion

Use this method to dismiss the document preview programmatically. The document interaction controller may also dismiss the document preview automatically in response to user actions.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h

presentOpenInMenuFromBarButtonItem:animated:

Displays a menu for opening the document and anchors that menu to the specified bar button item.

- (BOOL)presentOpenInMenuFromBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated
Parameters
item

The bar button item to which to anchor the menu.

animated

Specify YES to animate the appearance of the menu or NO to display it immediately.

Return Value

YES if this method was able to display the menu or NO if it was not.

Discussion

This method is similar to the presentOptionsMenuFromBarButtonItem:animated: method, but presents a menu restricted to a list of apps capable of opening the current document. This determination is made based on the document type (as indicated by the UTI property) and on the document types supported by the installed apps. To support one or more document types, an app must register those types in its Info.plist file using the CFBundleDocumentTypes key.

If there are no registered apps that support opening the document, the document interaction controller does not display a menu.

This method displays the menu asynchronously. The document interaction controller dismisses the menu automatically when the user selects an appropriate app. You can also dismiss it programmatically using the dismissMenuAnimated: method.

Availability
  • Available in iOS 3.2 and later.
See Also
Declared In
UIDocumentInteractionController.h

presentOpenInMenuFromRect:inView:animated:

Displays a menu for opening the document and anchors that menu to the specified view.

- (BOOL)presentOpenInMenuFromRect:(CGRect)rect inView:(UIView *)view animated:(BOOL)animated
Parameters
rect

The location (in the coordinate system of view) at which to anchor the menu.

view

The view from which to display the menu.

animated

Specify YES to animate the appearance of the menu or NO to display it immediately.

Return Value

YES if this method was able to display the menu or NO if it was not.

Discussion

This method is similar to the presentOptionsMenuFromRect:inView:animated: method, but presents a menu restricted to a list of apps capable of opening the current document. This determination is made based on the document type (as indicated by the UTI property) and on the document types supported by the installed apps. To support one or more document types, an app must register those types in its Info.plist file using the CFBundleDocumentTypes key.

If there are no registered apps that support opening the document, the document interaction controller does not display a menu.

This method displays the options menu asynchronously. The document interaction controller dismisses the menu automatically when the user selects an appropriate option. You can also dismiss it programmatically using the dismissMenuAnimated: method.

Availability
  • Available in iOS 3.2 and later.
See Also
Declared In
UIDocumentInteractionController.h

presentOptionsMenuFromBarButtonItem:animated:

Displays an options menu and anchors it to the specified bar button item.

- (BOOL)presentOptionsMenuFromBarButtonItem:(UIBarButtonItem *)item animated:(BOOL)animated
Parameters
item

The bar button item to which to anchor the menu.

animated

Specify YES to animate the appearance of the menu or NO to display it immediately.

Return Value

YES if the options menu was displayed or NO if it was not. The options menu may not be displayed in cases where there are no appropriate items to include in the menu.

Discussion

The contents of the options menu are built dynamically based on three things:

  • The type of the document (as specified by the UTI property)

  • The set of installed apps that have registered support for opening documents

  • The actions that you have indicated as supported in the document interaction controller delegate’s documentInteractionController:canPerformAction: method

Options that cannot be performed on the current document are not included in the menu. For example, if the document cannot be opened by any known apps, the menu does not include options for opening it.

This method displays the options menu asynchronously. The document interaction controller dismisses the menu automatically when the user selects an appropriate option. You can also dismiss it programmatically using the dismissMenuAnimated: method.

To instead present a menu that contains only a list of apps capable of opening the current document, the presentOpenInMenuFromBarButtonItem:animated: method instead.

Availability
  • Available in iOS 3.2 and later.
See Also
Declared In
UIDocumentInteractionController.h

presentOptionsMenuFromRect:inView:animated:

Displays an options menu and anchors it to the specified location in the view.

- (BOOL)presentOptionsMenuFromRect:(CGRect)rect inView:(UIView *)view animated:(BOOL)animated
Parameters
rect

The location (in the coordinate system of view) at which to anchor the menu.

view

The view from which to display the options menu.

animated

Specify YES to animate the appearance of the menu or NO to display it immediately.

Return Value

YES if the options menu was displayed or NO if it was not. The options menu may not be displayed in cases where there are no appropriate items to include in the menu.

Discussion

The contents of the options menu are built dynamically based on three things:

  • The type of the document (as specified by the UTI property)

  • The set of installed apps that have registered support for opening documents

  • The actions that you have indicated as supported in the document interaction controller delegate’s documentInteractionController:canPerformAction: method

Options that cannot be performed on the current document are not included in the menu. For example, if the document cannot be opened by any known apps, the menu does not include options for opening it.

This method displays the options menu asynchronously. The menu is dismissed automatically when the user selects one of the available options. You can also dismiss it programmatically using the dismissMenuAnimated: method.

To instead present a menu that contains only a list of apps capable of opening the current document, the presentOpenInMenuFromRect:inView:animated: method instead.

Availability
  • Available in iOS 3.2 and later.
See Also
Declared In
UIDocumentInteractionController.h

presentPreviewAnimated:

Displays a full-screen preview of the target document.

- (BOOL)presentPreviewAnimated:(BOOL)animated
Parameters
animated

Specify YES to animate the appearance of the document preview or NO to display it immediately.

Return Value

YES if this method was able to display the document preview or NO if it was not.

Discussion

To use this method, you must first provide a delegate object that implements the documentInteractionControllerViewControllerForPreview: method. The view controller returned by that method is used to present the document preview modally.

If your delegate implements the documentInteractionControllerViewForPreview: and documentInteractionControllerRectForPreview: methods, the view and rectangle returned by those methods is used as the starting point for the animation used to display the document preview. If the animated parameter is YES but your delegate does not implement the documentInteractionControllerViewForPreview: method (or that method returns nil), the document preview is animated into place using a crossfade transition.

This method displays the document preview asynchronously. The document interaction controller dismisses the document preview automatically in response to appropriate user interactions. You can also dismiss the preview programmatically using the dismissPreviewAnimated: method.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDocumentInteractionController.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-03-08)

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