Extending the photo edit picker for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic describes how your photo editing app can appear in the photo edit picker, a page that lets the user pick an app for editing the photo they are viewing. Learn about how your app can access that photo without asking the user to select it. For more info about other ways you can extend the photos experience, see Photo extensibility for Windows Phone 8.

This feature is for Windows Phone 8 photo editing apps only. To help make sure your app can be certified for the Store, see Additional requirements for specific app types for Windows Phone.

This topic contains the following sections.

• Extending the photo edit picker
• Step 1: Specify capabilities
• Step 2: Register extensions
• Step 3: Map the launch URI
• Step 4: Handle the URI Parameters
• Testing photo edit picker extensibility

Extending the photo edit picker

The photo edit picker appears in the built-in photo viewer. You launch it from the app bar, by tapping on the edit link. The following image shows the photo viewer edit link and the name of the photo edit picker extension (which is described later in this topic).

The following steps describe how to integrate your app into the photo edit picker.

Step 1: Specify capabilities

Windows Phone 8 apps need to specify the ID_CAP_MEDIALIB_PHOTO capability to access photos in the media library. Capabilities are specified in the app manifest file, WMAppManifest.xml.

<!-- For accessing photos in the media library. -->
<Capability Name="ID_CAP_MEDIALIB_PHOTO" />

Step 2: Register extensions

To appear in the photo edit picker, register for the Photos_Extra_Image_Editor extension. Extensions are specified in WMAppManifest.xml. Just after the Tokens element, inside the Extensions element, the photo edit picker extension is specified with the following Extension element.

<Extension ExtensionName="Photos_Extra_Image_Editor" 
           ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5632}" 
           TaskID="_default" />

The Windows Phone Manifest Designer does not support extensions; use the XML (Text) Editor to edit them. For more info, see How to modify the app manifest file for Windows Phone 8.

Step 3: Map the launch URI

When the user taps your app in the photo edit picker, a deep link URI is launched to open your app and send a token to the photo that the user was viewing. Your app can detect a photo edit picker launch when the URI contains the strings: EditPhotoContent and FileId. The following example is a launch URI from the photo edit picker (as seen from a URI mapper when the default navigation page is MainPage.xaml).

/MainPage.xaml?Action=EditPhotoContent&FileId=%7Bea74a960-3829-4007-8859-cd065654fbbc%7D

In this example, the FileId parameter value is the token. That string can be used to retrieve the photo from the media library. This is described later in the topic.

Because the photo edit picker targets the default navigation page (in this case, MainPage.xaml), that page will be launched if you don’t implement any URI mapping. If your app’s default navigation page can edit the photo referenced by the token, URI mapping may not be necessary.

However, if you want to launch a different page for editing a photo, you’ll need to map the URI to that page. The following example shows how this is done with a custom URI mapper class.

using System;
using System.Windows.Navigation;

namespace CustomMapping
{
    class CustomUriMapper : UriMapperBase
    {
        public override Uri MapUri(Uri uri)
        {
            string tempUri = uri.ToString();
            string mappedUri;

            // Launch from the photo edit picker.
            // Incoming URI example: /MainPage.xaml?Action=EditPhotoContent&FileId=%7Bea74a960-3829-4007-8859-cd065654fbbc%7D
            if ((tempUri.Contains("EditPhotoContent")) && (tempUri.Contains("FileId")))
            {
                // Redirect to PhotoEdit.xaml.
                mappedUri = tempUri.Replace("MainPage", "PhotoEdit");
                return new Uri(mappedUri, UriKind.Relative);
            }

            // Otherwise perform normal launch.
            return uri;
        }
    }
}

In this example, the URI mapper maps the incoming URI to a page named PhotoEdit.xaml by replacing the page name within the URI. The URI returned by that method is then used by the root frame of the app to launch the first page when the app starts. The root frame uses the custom URI mapper because it is assigned as the app initializes. The following code shows how the URI mapper is assigned in the InitializePhoneApplication method of the App.xaml.cs file.

private void InitializePhoneApplication()
{
    if (phoneApplicationInitialized)
        return;

    // Create the frame but don't set it as RootVisual yet; this allows the splash
    // screen to remain active until the application is ready to render.
    RootFrame = new PhoneApplicationFrame();
    RootFrame.Navigated += CompleteInitializePhoneApplication;

    // Handle navigation failures
    RootFrame.NavigationFailed += RootFrame_NavigationFailed;

    // Assign the custom URI mapper class to the application frame.
    RootFrame.UriMapper = new CustomMapping.CustomUriMapper();

    // Ensure we don't initialize again
    phoneApplicationInitialized = true;
}

Step 4: Handle the URI Parameters

When the page is launched, the page can access all of the parameters in the URI (that launched the page) using the QueryString property of the page’s NavigationContext object. The following example shows how the value of the FileId parameter is used with the MediaLibraryGetPictureFromToken(String) method to extract the photo from the media library. This code is from the PhotoEdit.xaml.cs file of the Photo Extensibility Sample.

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    // Get a dictionary of query string keys and values.
    IDictionary<string, string> queryStrings = this.NavigationContext.QueryString;

    // Ensure that there is at least one key in the query string, and check whether the "FileId" key is present.
    if (queryStrings.ContainsKey("FileId"))
    {
        // Retrieve the photo from the media library using the FileID passed to the app.
        MediaLibrary library = new MediaLibrary();
        Picture photoFromLibrary = library.GetPictureFromToken(queryStrings["FileId"]);

        // Create a BitmapImage object and add set it as the image control source.
        // To retrieve a full-resolution image, use the GetImage() method instead.
        BitmapImage bitmapFromPhoto = new BitmapImage();
        bitmapFromPhoto.SetSource(photoFromLibrary.GetPreviewImage());
        image1.Source = bitmapFromPhoto;
    }
}

Testing photo edit picker extensibility

This procedure describes how you can launch the Photo Extensibility Sample from the edit link.

To test photo edit picker extensibility

1. Download the Photo Extensibility Sample and open it in the Windows Phone SDK.

2. Select Debug from the menu, and select Start Debugging.

3. After the main page of the app appears, tap Start to navigate to the Start screen.

4. On the Start screen, tap the Photos app, and then select a photo and view it in the photo viewer.

5. Tap the three dots at the bottom of the page on the app bar. When the app bar expands, tap the edit link.

6. On the edit page, tap the name of your app. This will launch a URI containing a token to the photo you were just viewing. That URI will ultimately launch the PhotoEdit.xaml page and display the photo you were just looking at.