UIDocumentInteractionControllerDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.2 and later.
Declared in
UIDocumentInteractionController.h
Related sample code

Overview

The UIDocumentInteractionControllerDelegate protocol includes methods you can implement to respond to messages from a document interaction controller. Use this protocol to participate when document previews are displayed and when a document is about to be opened by another application. You can also use this protocol to respond to commands (such as “copy” and “print”) from a document interaction controller’s options menu.

If you use a document interaction controller to display a document preview, your delegate must implement the documentInteractionControllerViewControllerForPreview: method. All other methods of this protocol are optional.

For more information about using a document interaction controller, see UIDocumentInteractionController Class Reference.

Tasks

Configuring the Parent View Controller

Presenting the User Interface

Opening Files

Managing Actions

Instance Methods

documentInteractionController:didEndSendingToApplication:

Called when a document interaction controller’s document has been handed off to the specified application.

- (void) documentInteractionController: (UIDocumentInteractionController *) controller didEndSendingToApplication: (NSString *) application
Parameters
controller

The document interaction controller whose document is about to be opened.

application

The bundle identifier of the application that is about to open the document. This value corresponds to the value in the CFBundleIdentifier key of the application’s Info.plist file.

Discussion

This method is called after the document information has been saved for the specified application.

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

documentInteractionController:willBeginSendingToApplication:

Called when a document interaction controller’s document is about to be opened by the specified application.

- (void) documentInteractionController: (UIDocumentInteractionController *) controller willBeginSendingToApplication: (NSString *) application
Parameters
controller

The document interaction controller whose document is about to be opened.

application

The bundle identifier of the application that is about to open the document. This value corresponds to the value in the CFBundleIdentifier key of the application’s Info.plist file.

Discussion

This method is called when the user chooses to open a document, which could occur from within a document preview. When a document is passed to another application, the contents of the document interaction controller’s annotation property are passed with it. You can use this method to configure the contents of that property or prepare your own application for handing off the document.

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

documentInteractionControllerDidDismissOpenInMenu:

Called when a document interaction controller has dismissed its Open In menu.

- (void) documentInteractionControllerDidDismissOpenInMenu: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller that dismissed its menu.

Discussion

You can use this method to remove any additional views or content you placed underneath the Open In menu in your documentInteractionControllerWillPresentOpenInMenu: method.

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

documentInteractionControllerDidDismissOptionsMenu:

Called when a document interaction controller has dismissed its options menu.

- (void) documentInteractionControllerDidDismissOptionsMenu: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller that dismissed its options menu.

Discussion

You can use this method to remove any additional views or content you placed underneath the options menu in your documentInteractionControllerWillPresentOptionsMenu: method.

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

documentInteractionControllerDidEndPreview:

Called when a document interaction controller has dismissed its document preview.

- (void)documentInteractionControllerDidEndPreview:(UIDocumentInteractionController *)controller
Parameters
controller

The document interaction controller that dismissed its document preview.

Discussion

This method is called after the view containing the document preview has been removed from the application’s key window. You can use this notification to remove any interface elements you set up behind the preview elements.

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

documentInteractionControllerRectForPreview:

Called when a document interaction controller needs the rectangle to use as the starting point for animating the display of a document preview.

- (CGRect) documentInteractionControllerRectForPreview: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller requesting the starting rectangle.

Return Value

A rectangle in the coordinate system of the view returned by the documentInteractionControllerViewForPreview: method.

Discussion

If you do not implement the documentInteractionControllerViewForPreview: method, or if you do implement it but return a nil value, this method is not called. If you do not implement this method, the starting rectangle is assumed to be the bounds of the view returned by the documentInteractionControllerViewForPreview: method.

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

documentInteractionControllerViewControllerForPreview:

Called when a document interaction controller needs a view controller for presenting a document preview.

- (UIViewController *) documentInteractionControllerViewControllerForPreview: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller requesting the parent view controller.

Return Value

The view controller to use when presenting the document preview. The return value must not be nil.

Discussion

Although technically optional, this method is required if your application attempts to display a preview for a document. The view controller returned by this method is used as the parent for the document preview.

If you return a navigation controller from this method, the document interaction controller is pushed onto the navigation stack using the standard navigation controller animations. If you return any other type of view controller, the document interaction controller is displayed modally, in which case, the view controller you return must be capable of presenting a modal view controller.

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

documentInteractionControllerViewForPreview:

Called when a document interaction controller needs the starting point for animating the display of a document preview.

- (UIView *) documentInteractionControllerViewForPreview: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller requesting the starting view.

Return Value

The view to use as the starting point for the animation or nil if you want the document preview to fade into place.

Discussion

By default, the starting rectangle for the animation is set to the bounds of the returned view. To specify a different starting rectangle, you must also override the documentInteractionControllerRectForPreview: method.

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

documentInteractionControllerWillBeginPreview:

Called when a document interaction controller is about to display a preview for its document.

- (void) documentInteractionControllerWillBeginPreview: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller that is about to preview its document.

Discussion

This method is called shortly before the view containing the document preview is presented modally. You can use this notification to set up any additional interface elements behind the preview elements.

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

documentInteractionControllerWillPresentOpenInMenu:

Called when a document interaction controller is about to display an Open In menu.

- (void) documentInteractionControllerWillPresentOpenInMenu: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller that is about to display a menu.

Discussion

The Open In menu is used to select an application for opening the current file. You can use this method to update your user interface in response to displaying the menu.

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

documentInteractionControllerWillPresentOptionsMenu:

Called when a document interaction controller is about to display an options menu.

- (void) documentInteractionControllerWillPresentOptionsMenu: (UIDocumentInteractionController *) controller
Parameters
controller

The document interaction controller that is about to display an options menu.

Discussion

The options menu is used to present the user with options for previewing the document, opening it in an application, or copying its contents. You can use this method to update your user interface in response to displaying the menu.

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