How to share an image (HTML) (Windows)

Article
04/29/2014

Applies to Windows and Windows Phone

Perhaps the most common kind of content that users want to share is images and photos. Here, we'll show you how to share a single image from your app.

The code in this section focuses on using setBitmap to share a bitmap image. Often, users share images that are represented by files. As a result, we recommend that your app also support StorageItems, which can be a collection of files. We describe how to support StorageItems in How to share files.

What you need to know

Technologies

Windows.ApplicationModel.DataTransfer

Prerequisites

You should be familiar with Visual Studio and its associated templates.
You should be familiar with JavaScript.
You should understand how to get files and other data, such as by using FileOpenPicker. You can learn more in Quickstart: Accessing files with file pickers.

Instructions

Step 1: Create a button handler function to let the user choose an image file

The following button handler code lets the user to pick an image file. This file is used in the remaining steps of this quickstart.

Note

The following code uses pickSingleFileAsync. On Windows Phone 8.1, pickSingleFileAndContinue should be used instead.

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

The DataTransferManager object is the main starting point for any share operation. Add a DataRequested event handler to fire when the user wants to invoke Share. In a Windows Store app, this occurs automatically when the user invokes the Share charm. If you're developing for Windows Phone, there is no built-in Share charm, so you'll need to add a control for the user to tap and trigger the handler.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareImageHandler);

The remaining steps implement the shareImageHandler function.

Step 3: Get a DataRequest object

When a datarequested event occurs, your app receives a DataRequest object. This object contains a DataPackage that you can use to provide the content that the user wants to share.

var request = e.request;

Step 4: Set the title and description properties

request.data.properties.title = "Share Image Example";
request.data.properties.description = "Demonstrates how to share an image.";

Step 5: Add a thumbnail to the DataPackage

We recommend that you always add a thumbnail image any time you're sharing an image.

request.data.properties.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile);

Check out the Thumbnail reference topic to learn about our recommended file sizes for thumbnail images.

Step 6: Add the image as a bitmap to the DataPackage

To share an image, use the setBitmap method. This method expects the image to be of the RandomAccessStreamReference type. To share multiple images, share them as storageItems instead. We describe how to support storageItems in How to share files. This helps to ensure that the user can choose from the largest number of apps when they share the image.

request.data.setBitmap(Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile));

Remarks

If your app needs to use an asynchronous operation to prepare the image or the thumbnail, you’ll need to use the deferral pattern. We show how to do this in How to make asynchronous calls in your datarequested handler.

If your app takes more than 200 milliseconds to get the image ready, you need to use a delegate function to share it. We show you how to do this in How to support pull operations.

Complete example

Here's an example that sets an image for a user to share. For a more complete example, check out our code gallery sample.

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

function shareImageHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Image Example";
    request.data.properties.description = "Demonstrates how to share an image.";

    // In this example, we use the imageFile for the thumbnail as well.
    request.data.properties.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile);
    request.data.setBitmap(Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile));
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // This app was newly launched; register it as share source.
            var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
            dataTransferManager.addEventListener("datarequested", shareImageHandler);
            // Set up the button handler to pick an image file.
            document.getElementById("chooseImageButton").addEventListener("click", pickImageFile, false);
        } else {
            // TODO: This application has been reactivated from suspension.
            // Restore application state here.
        }
        args.setPromise(WinJS.UI.processAll());
    }
};

How to share an image (HTML)