iOS Developer Library — Prerelease


App Extension Programming Guide

On This Page

Photo Editing

In iOS, a Photo Editing extension lets users edit a photo or video within the Photos app. After users confirm the changes they make in a Photo Editing extension, the adjusted content is available in Photos. Photos always keeps the original version of the content, too, so that users can revert the changes they make in an extension.

Understand How a Photo Editing Extension Works with Photos

To support a consistent editing experience, Photos keeps multiple versions of each media asset’s image or video data, in addition to adjustment data, which describes past edits made to the asset. For each asset, Photos stores the original version, the current version (which includes the most recent adjustments), and the set of adjustments that were applied to the original version to create the current version.

When a user chooses a Photo Editing extension, Photos asks the extension if it can read the adjustment data. If the app extension supports the adjustment data, Photos provides the original version of the asset as input to the editing session. After the extension reads the adjustment data and reconstructs the past edits, it can allow users to alter or revert past edits or add new edits. For example, if the adjustment data describes filters applied to a photo, the extension reapplies those filters to the original asset and can let users change filter parameters, add new filters, or remove filters.

If the extension doesn’t support an asset’s adjustment data, Photos provides the current version of the asset as input to the editing session. Because the current version contains the rendered output of all past edits, the extension can let users apply new edits to the asset but not alter or revert past edits.

When a user finishes using a Photo Editing extension, the extension returns the edited asset and the adjustment data.

iOS users get access to Photo Editing extensions in the Photos app. When a user chooses your extension, display a view that provides a custom editing interface. To present this view, use a view controller that adopts the PHContentEditingController protocol.

Use the Xcode Photo Editing Template

The Xcode Photo Editing template provides default header and implementation files for the principal view controller class (called PhotoEditingViewController), an Info.plist file, and an interface file (that is, a storyboard file).

By default, the Photo Editing template supplies the following Info.plist keys and values:

  1. <key>NSExtension</key>
  2. <dict>
  3. <key>NSExtensionAttributes</key>
  4. <dict>
  5. <key>PHSupportedMediaTypes</key>
  6. <array>
  7. <string>Image</string>
  8. </array>
  9. </dict>
  10. <key>NSExtensionMainStoryboard</key>
  11. <string>MainInterface</string>
  12. <key>NSExtensionPointIdentifier</key>
  13. <string></string>
  14. </dict>

In particular, make sure that the PHSupportedMediaTypes array specifies the types of media assets your app extension can edit. The default value is Image, but you can also use Video.

Design the UI

The Photos app displays a Photo Editing extension within a navigation bar, so you should avoid designing a navigation bar–based UI for your extension.

Photos automatically displays your extension’s view so that it occupies the full height of the screen, including the area behind the navigation bar. If you want your content view to appear below the bar, and not underneath it, be sure to use the view’s top layout guide appropriately.

It’s best when a Photo Editing extension lets users preview the results of their edits. Giving users a preview while they’re still using your extension means that they can get the effect they want without repeatedly exiting and reentering the extension.

Because users are likely to spend time editing a photo or movie in your app extension, you don’t want them to lose their work if they accidentally choose Cancel. To improve the user experience, be sure to implement the shouldShowCancelConfirmation method in your view controller, returning YEStrue if there are unsaved changes. When this method returns YEStrue, Photos displays confirmation UI so that users can confirm if they really want to cancel their changes.

Handling Memory Constraints

Because a Photo Editing extension often needs to work with large high-resolution images and videos, the extension is likely to experience memory pressures when running on a device. It’s recommended that you examine your existing image-processing code and make sure that it performs to a high standard before you use it in your app extension.

Testing a Photo Editing Extension

Avoid making assumptions about the media formats that your app extension may receive. Be sure to test your filtering and other image-processing code with a wide range of media formats; don’t just test with content from the device camera.

To learn about debugging app extensions in general, see Debug, Profile, and Test Your App Extension.