Quickstart: Clipboard basics (HTML)
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
The best apps give users as much control over their data as possible. One method of control that users expect is clipboard operations. These operations enable users to cut, copy, and paste data. Clipboard operations can occur within the same app or between two different apps on the same computer. With the clipboard, users can easily put the information they need where they need it.
More than one way to share data
Before we discuss how to add clipboard operations to your app, you should remember that Windows 8 supports several different ways of moving data. We provide an overview of these methods in Sharing and exchanging data. One of these ways, sharing, has a lot in common with the clipboard. From a developer perspective, both sharing and clipboard operations use the same Windows namespace, Windows.ApplicationModel.DataTransfer. Both also require that your app collect the data that a user selects. (We often refer to this as packaging, because you use the DataPackage class to accomplish this.) From a user's perspective, the clipboard represents the "classic" way of moving data around.
As a developer, remember that while sharing and clipboard operations are very similar, they do have key differences. With sharing, the focus is on the destination: the app or service that the user selects. With the clipboard, the focus is more on the data. Most importantly, clipboard operations are the only way to exchange data between a desktop app and a Windows Store app.
For more information about the differences between sharing and clipboard operations, see Sharing and exchanging data.
Built-in clipboard support
In many cases, you might not need to write any code at all to support clipboard operations. Many of the controls that you can use to create your Windows Store app already support clipboard operations. For more information about what controls are available, see Adding controls and content.
Before you begin
Adding support for clipboard operations to your app is pretty straightforward. First, you should take a look at Guidelines and checklist for clipboard commands. There, you'll find a lot of information that can help you create the best user experience for clipboard operations, as well as a few thoughts that can help you make the most of your code.
Next, you need to consider what types of data formats you want to support. In Windows 8, there are two categories of formats: standard and custom. Currently, standard formats include:
- Text
- HTML
- URI
- Bitmaps
- StorageItems
- RTF
To see an example of clipboard operations that use these data formats, see our code sample. You might also want to look at the reference topic, StandardDataFormats, which you use to specify the types of formats that your app supports.
Custom data formats, as the name implies, refers to formats for data that doesn't fit into one of the standard formats. Often, these formats represent logical collections of data—such as an address or an event. To support custom formats, we strongly encourage you to use one of the many schemas specified at http://schema.org/docs/full.htm. Using commonly known data formats, such as these schemas, helps to ensure that the app that receives the clipboard data knows what to do with it.
Getting started
Supporting clipboard operations usually has two parts: copy (or cut), and paste. Let's look at how to handle copy and cut operations first. First, make sure your app has the appropriate references. If you're using a Microsoft Visual Studio template, these references are added as soon as you create a new project. If you're not using Visual Studio, make sure your app has access to the Windows.ApplicationModel.DataTransfer namespace.
After your project is set up, you need an instance of the DataPackage object. This object is what contains both the data the user wants to copy and any properties (such as a description) that you want to include.
var dataPackage = new Windows.ApplicationModel.DataTransfer.DataPackage();
Copy and cut
At this point, you are ready to specify the clipboard operation that you want to perform. These operations are available using the DataPackageOperation enumeration. Here's what to do for copy operations:
var dataPackage = new Windows.ApplicationModel.DataTransfer.DataPackage();
dataPackage.requestedOperation = Windows.ApplicationModel.DataTransfer.DataPackageOperation.copy;
And here's what you do for cut operations (also referred to as move operations):
var dataPackage = new Windows.ApplicationModel.DataTransfer.DataPackage();
dataPackage.requestedOperation = Windows.ApplicationModel.DataTransfer.DataPackageOperation.move;
At this point, you can add the data that a user has selected to the DataPackage object. If this data is supported by the DataPackage class, you can use one of the corresponding methods in the DataPackage object.
To add text:
dataPackage.setText("Hello World!");
To see examples of how to add other formats to a DataPackage, see the clipboard sample in the code gallery. And remember, you can add more than one format to a DataPackage.
The last thing you need to do is add the DataPackage to the clipboard. You can do this by calling the static Clipboard.setContent method.
Windows.ApplicationModel.DataTransfer.Clipboard.setContent(dataPackage);
Paste
To get the contents of the clipboard, call the static Clipboard.getContent method. This method returns a DataPackageView that contains the content. This object is almost identical to a DataPackage object, except that its contents are read-only. With that object, you can use either the AvailableFormats or the contains method to identify what formats are available. Then, you can call the corresponding DataPackageView method to get the data. For example, here's how you can get the text stored in the clipboard:
var dataPackageView = Windows.ApplicationModel.DataTransfer.Clipboard.getContent();
if (dataPackageView.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
dataPackageView.getTextAsync().then(function (text) {
// To output the text from this example, you need an HTML element
// with an id of "output".
document.getElementById("output").innerText = "Clipboard now contains: " + text;
});
}
Tracking changes to the clipboard
In addition to copy and paste commands, you might also find it helpful to add an event handler so that your app knows when the content of the clipboard changes. You can do this by handling the clipboard's ContentChanged event.
Windows.ApplicationModel.DataTransfer.Clipboard.addEventListener("contentchanged", function (event) {
var dataPackageView = Windows.ApplicationModel.DataTransfer.Clipboard.getContent();
if (dataPackageView.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
dataPackageView.getTextAsync().then(function (text) {
// To output the text from this example, you need an HTML element
// with an id of "output".
document.getElementById("output").innerText = "Clipboard now contains: " + text;
});
}
});
With this handler in place, your app is notified any time the content of the clipboard changes.
Next steps
By now, you should have a basic understanding of how to add clipboard support to your app. If you haven't done so already, we recommend that you review our Guidelines and checklist for clipboard commands, so you can create the best user experience possible. Also, download our sample from the code gallery to see a variety of examples of how to use the clipboard.
Related topics
Guidelines and checklist for clipboard commands