Android provides a powerful clipboard-based framework for copying and pasting. It supports both simple and complex data types, including text strings, complex data structures, text and binary stream data, and even application assets. Simple text data is stored directly in the clipboard, while complex data is stored as a reference that the pasting application resolves with a content provider. Copying and pasting works both within an application and between applications that implement the framework.
Since a part of the framework uses content providers, this topic assumes some familiarity with the Android Content Provider API, which is described in the topic Content Providers.
When you use the clipboard framework, you put data into a clip object, and then put the clip object on the system-wide clipboard. The clip object can take one of three forms:
The clipboard holds only one clip object at a time. When an application puts a clip object on the clipboard, the previous clip object disappears.
If you want to allow users to paste data into your application, you don't have to handle all types of data. You can examine the data on the clipboard before you give users the option to paste it. Besides having a certain data form, the clip object also contains metadata that tells you what MIME type or types are available. This metadata helps you decide if your application can do something useful with the clipboard data. For example, if you have an application that primarily handles text you may want to ignore clip objects that contain a URI or Intent.
You may also want to allow users to paste text regardless of the form of data on the clipboard. To do this, you can force the clipboard data into a text representation, and then paste this text. This is described in the section Coercing the clipboard to text.
This section describes the classes used by the clipboard framework.
In the Android system, the system clipboard is represented by the global {@link android.content.ClipboardManager} class. You do not instantiate this class directly; instead, you get a reference to it by invoking {@link android.content.Context#getSystemService(String) getSystemService(CLIPBOARD_SERVICE)}.
To add data to the clipboard, you create a {@link android.content.ClipData} object that contains both a description of the data and the data itself. The clipboard holds only one {@link android.content.ClipData} at a time. A {@link android.content.ClipData} contains a {@link android.content.ClipDescription} object and one or more {@link android.content.ClipData.Item} objects.
A {@link android.content.ClipDescription} object contains metadata about the clip. In particular, it contains an array of available MIME types for the clip's data. When you put a clip on the clipboard, this array is available to pasting applications, which can examine it to see if they can handle any of available the MIME types.
A {@link android.content.ClipData.Item} object contains the text, URI, or Intent data:
You can add more than one {@link android.content.ClipData.Item} object to a clip. This allows users to copy and paste multiple selections as a single clip. For example, if you have a list widget that allows the user to select more than one item at a time, you can copy all the items to the clipboard at once. To do this, you create a separate {@link android.content.ClipData.Item} for each list item, and then you add the {@link android.content.ClipData.Item} objects to the {@link android.content.ClipData} object.
The {@link android.content.ClipData} class provides static convenience methods for creating a {@link android.content.ClipData} object with a single {@link android.content.ClipData.Item} object and a simple {@link android.content.ClipDescription} object:
label.
The single MIME type in {@link android.content.ClipDescription} is
{@link android.content.ClipDescription#MIMETYPE_TEXT_PLAIN}.
Use {@link android.content.ClipData#newPlainText(CharSequence,CharSequence) newPlainText()} to create a clip from a text string.
label.
If the URI is a content URI ({@link android.net.Uri#getScheme() Uri.getScheme()} returns
content:), the method uses the {@link android.content.ContentResolver} object
provided in resolver to retrieve the available MIME types from the
content provider and store them in {@link android.content.ClipDescription}. For a URI that
is not a content: URI, the method sets the MIME type to
{@link android.content.ClipDescription#MIMETYPE_TEXT_URILIST}.
Use
{@link android.content.ClipData#newUri(ContentResolver, CharSequence, Uri) newUri()}
to create a clip from a URI, particularly a content: URI.
label.
The MIME type is set to {@link android.content.ClipDescription#MIMETYPE_TEXT_INTENT}.
Use {@link android.content.ClipData#newIntent(CharSequence, Intent) newIntent()} to create a clip from an Intent object.
Even if your application only handles text, you can copy non-text data from the clipboard by converting it with the method {@link android.content.ClipData.Item#coerceToText(Context) ClipData.Item.coerceToText()}.
This method converts the data in {@link android.content.ClipData.Item} to text and returns a {@link java.lang.CharSequence}. The value that {@link android.content.ClipData.Item#coerceToText(Context) ClipData.Item.coerceToText()} returns is based on the form of data in {@link android.content.ClipData.Item}:
The clipboard framework is summarized in Figure 1. To copy data, an application puts a {@link android.content.ClipData} object on the {@link android.content.ClipboardManager} global clipboard. The {@link android.content.ClipData} contains one or more {@link android.content.ClipData.Item} objects and one {@link android.content.ClipDescription} object. To paste data, an application gets the {@link android.content.ClipData}, gets its MIME type from the {@link android.content.ClipDescription}, and gets the data either from the {@link android.content.ClipData.Item} or from the content provider referred to by {@link android.content.ClipData.Item}.
Figure 1. The Android clipboard framework
As described previously, to copy data to the clipboard you get a handle to the global {@link android.content.ClipboardManager} object, create a {@link android.content.ClipData} object, add a {@link android.content.ClipDescription} and one or more {@link android.content.ClipData.Item} objects to it, and add the finished {@link android.content.ClipData} object to the {@link android.content.ClipboardManager} object. This is described in detail in the following procedure:
The Note Pad sample application is an example of using a content provider for copying and pasting. The NotePadProvider class implements the content provider. The NotePad class defines a contract between the provider and other applications, including the supported MIME types.
...
// if the user selects copy
case R.id.menu_copy:
// Gets a handle to the clipboard service.
ClipboardManager clipboard = (ClipboardManager)
getSystemService(Context.CLIPBOARD_SERVICE);
Copy the data to a new {@link android.content.ClipData} object:
// Creates a new text clip to put on the clipboard
ClipData clip = ClipData.newPlainText("simple text","Hello, World!");
This snippet constructs a URI by encoding a record ID onto the content URI for the provider. This technique is covered in more detail in the section Encoding an identifier on the URI:
// Creates a Uri based on a base Uri and a record ID based on the contact's last name // Declares the base URI string private static final String CONTACTS = "content://com.example.contacts"; // Declares a path string for URIs that you use to copy data private static final String COPY_PATH = "/copy"; // Declares the Uri to paste to the clipboard Uri copyUri = Uri.parse(CONTACTS + COPY_PATH + "/" + lastName); ... // Creates a new URI clip object. The system uses the anonymous getContentResolver() object to // get MIME types from provider. The clip object's label is "URI", and its data is // the Uri previously created. ClipData clip = ClipData.newUri(getContentResolver(),"URI",copyUri);
This snippet constructs an Intent for an application and then puts it in the clip object:
// Creates the Intent
Intent appIntent = new Intent(this, com.example.demo.myapplication.class);
...
// Creates a clip object with the Intent in it. Its label is "Intent" and its data is
// the Intent object created previously
ClipData clip = ClipData.newIntent("Intent",appIntent);
// Set the clipboard's primary clip. clipboard.setPrimaryClip(clip);
As described previously, you paste data from the clipboard by getting the global clipboard object, getting the clip object, looking at its data, and if possible copying the data from the clip object to your own storage. This section describes in detail how to do this for the three forms of clipboard data.
To paste plain text, first get the global clipboard and verify that it can return plain text. Then get the clip object and copy its text to your own storage using {@link android.content.ClipData.Item#getText()}, as described in the following procedure:
ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE); String pasteData = "";
// Gets the ID of the "paste" menu item
MenuItem mPasteItem = menu.findItem(R.id.menu_paste);
// If the clipboard doesn't contain data, disable the paste menu item.
// If it does contain data, decide if you can handle the data.
if (!(clipboard.hasPrimaryClip())) {
mPasteItem.setEnabled(false);
} else if (!(clipboard.getPrimaryClipDescription().hasMimeType(MIMETYPE_TEXT_PLAIN))) {
// This disables the paste menu item, since the clipboard has data but it is not plain text
mPasteItem.setEnabled(false);
} else {
// This enables the paste menu item, since the clipboard contains plain text.
mPasteItem.setEnabled(true);
}
}
// Responds to the user selecting "paste"
case R.id.menu_paste:
// Examines the item on the clipboard. If getText() does not return null, the clip item contains the
// text. Assumes that this application can only handle one item at a time.
ClipData.Item item = clipboard.getPrimaryClip().getItemAt(0);
// Gets the clipboard as text.
pasteData = item.getText();
// If the string contains data, then the paste operation is done
if (pasteData != null) {
return;
// The clipboard does not contain text. If it contains a URI, attempts to get data from it
} else {
Uri pasteUri = item.getUri();
// If the URI contains something, try to get text from it
if (pasteUri != null) {
// calls a routine to resolve the URI and get data from it. This routine is not
// presented here.
pasteData = resolveUri(Uri);
return;
} else {
// Something is wrong. The MIME type was plain text, but the clipboard does not contain either
// text or a Uri. Report an error.
Log.e("Clipboard contains an invalid data type");
return;
}
}
If the {@link android.content.ClipData.Item} object contains a content URI and you have determined that you can handle one of its MIME types, create a {@link android.content.ContentResolver} and then call the appropriate content provider method to retrieve the data.
The following procedure describes how to get data from a content provider based on a content URI on the clipboard. It checks that a MIME type that the application can use is available from the provider:
// Declares a MIME type constant to match against the MIME types offered by the provider public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"
// Gets a handle to the Clipboard Manager ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE); // Gets a content resolver instance ContentResolver cr = getContentResolver();
// Gets the clipboard data from the clipboard
ClipData clip = clipboard.getPrimaryClip();
if (clip != null) {
// Gets the first item from the clipboard data
ClipData.Item item = clip.getItemAt(0);
// Tries to get the item's contents as a URI
Uri pasteUri = item.getUri();
Uri does not point to a valid content provider:
// If the clipboard contains a URI reference
if (pasteUri != null) {
// Is this a content URI?
String uriMimeType = cr.getType(pasteUri);
// If the return value is not null, the Uri is a content Uri
if (uriMimeType != null) {
// Does the content provider offer a MIME type that the current application can use?
if (uriMimeType.equals(MIME_TYPE_CONTACT)) {
// Get the data from the content provider.
Cursor pasteCursor = cr.query(uri, null, null, null, null);
// If the Cursor contains data, move to the first record
if (pasteCursor != null) {
if (pasteCursor.moveToFirst()) {
// get the data from the Cursor here. The code will vary according to the
// format of the data model.
}
}
// close the Cursor
pasteCursor.close();
}
}
}
}
To paste an Intent, first get the global clipboard. Examine the {@link android.content.ClipData.Item} object to see if it contains an Intent. Then call {@link android.content.ClipData.Item#getIntent()} to copy the Intent to your own storage. The following snippet demonstrates this:
// Gets a handle to the Clipboard Manager
ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
// Checks to see if the clip item contains an Intent, by testing to see if getIntent() returns null
Intent pasteIntent = clipboard.getPrimaryClip().getItemAt(0).getIntent();
if (pasteIntent != null) {
// handle the Intent
} else {
// ignore the clipboard, or issue an error if your application was expecting an Intent to be
// on the clipboard
}
Content providers support copying complex data such as database records or file streams. To copy the data, you put a content URI on the clipboard. Pasting applications then get this URI from the clipboard and use it to retrieve database data or file stream descriptors.
Since the pasting application only has the content URI for your data, it needs to know which piece of data to retrieve. You can provide this information by encoding an identifier for the data on the URI itself, or you can provide a unique URI that will return the data you want to copy. Which technique you choose depends on the organization of your data.
The following sections describe how to set up URIs, how to provide complex data, and how to provide file streams. The descriptions assume that you are familiar with the general principles of content provider design.
A useful technique for copying data to the clipboard with a URI is to encode an identifier for the data on the URI itself. Your content provider can then get the identifier from the URI and use it to retrieve the data. The pasting application doesn't have to know that the identifier exists; all it has to do is get your "reference" (the URI plus the identifier) from the clipboard, give it your content provider, and get back the data.
You usually encode an identifier onto a content URI by concatenating it to the end of the URI. For example, suppose you define your provider URI as the following string:
"content://com.example.contacts"
If you want to encode a name onto this URI, you would use the following snippet:
String uriString = "content://com.example.contacts" + "/" + "Smith" // uriString now contains content://com.example.contacts/Smith. // Generates a uri object from the string representation Uri copyUri = Uri.parse(uriString);
If you are already using a content provider, you may want to add a new URI path that indicates the URI is for copying. For example, suppose you already have the following URI paths:
"content://com.example.contacts"/people "content://com.example.contacts"/people/detail "content://com.example.contacts"/people/images
You could add another path that is specific to copy URIs:
"content://com.example.contacts/copying"
You could then detect a "copy" URI by pattern-matching and handle it with code that is specific for copying and pasting.
You normally use the encoding technique if you're already using a content provider, internal database, or internal table to organize your data. In these cases, you have multiple pieces of data you want to copy, and presumably a unique identifier for each piece. In response to a query from the pasting application, you can look up the data by its identifier and return it.
If you don't have multiple pieces of data, then you probably don't need to encode an identifier. You can simply use a URI that is unique to your provider. In response to a query, your provider would return the data it currently contains.
Getting a single record by ID is used in the
Note Pad sample application to
open a note from the notes list. The sample uses the _id field from an SQL
database, but you can have any numeric or character identifier you want.
You set up a content provider for copying and pasting complex data as a subclass of the {@link android.content.ContentProvider} component. You should also encode the URI you put on the clipboard so that it points to the exact record you want to provide. In addition, you have to consider the existing state of your application:
In the content provider, you will want to override at least the following methods:
MIME types for complex data are described in the topic Content Providers.
Notice that you don't have to have any of the other content provider methods such as {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} or {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) update()}. A pasting application only needs to get your supported MIME types and copy data from your provider. If you already have these methods, they won't interfere with copy operations.
The following snippets demonsrate how to set up your application to copy complex data:
In the global constants for your application, declare a base URI string and a path that identifies URI strings you are using to copy data. Also declare a MIME type for the copied data:
// Declares the base URI string private static final String CONTACTS = "content://com.example.contacts"; // Declares a path string for URIs that you use to copy data private static final String COPY_PATH = "/copy"; // Declares a MIME type for the copied data public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"
public class MyCopyActivity extends Activity {
...
// The user has selected a name and is requesting a copy.
case R.id.menu_copy:
// Appends the last name to the base URI
// The name is stored in "lastName"
uriString = CONTACTS + COPY_PATH + "/" + lastName;
// Parses the string into a URI
Uri copyUri = Uri.parse(uriString);
// Gets a handle to the clipboard service.
ClipboardManager clipboard = (ClipboardManager)
getSystemService(Context.CLIPBOARD_SERVICE);
ClipData clip = ClipData.newUri(getContentResolver(), "URI", copyUri);
// Set the clipboard's primary clip.
clipboard.setPrimaryClip(clip);
In the global scope of your content provider, create a URI matcher and add a URI pattern that will match URIs you put on the clipboard:
public class MyCopyProvider extends ContentProvider {
...
// A Uri Match object that simplifies matching content URIs to patterns.
private static final UriMatcher sURIMatcher = new UriMatcher(UriMatcher.NO_MATCH);
// An integer to use in switching based on the incoming URI pattern
private static final int GET_SINGLE_CONTACT = 0;
...
// Adds a matcher for the content URI. It matches
// "content://com.example.contacts/copy/*"
sUriMatcher.addURI(CONTACTS, "names/*", GET_SINGLE_CONTACT);
Set up the {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) query()} method. This method can handle different URI patterns, depending on how you code it, but only the pattern for the clipboard copying operation is shown:
// Sets up your provider's query() method.
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
String sortOrder) {
...
// Switch based on the incoming content URI
switch (sUriMatcher.match(uri)) {
case GET_SINGLE_CONTACT:
// query and return the contact for the requested name. Here you would decode
// the incoming URI, query the data model based on the last name, and return the result
// as a Cursor.
...
}
Set up the {@link android.content.ContentProvider#getType(Uri) getType()} method to return an appropriate MIME type for copied data:
// Sets up your provider's getType() method.
public String getType(Uri uri) {
...
switch (sUriMatcher.match(uri)) {
case GET_SINGLE_CONTACT:
return (MIME_TYPE_CONTACT);
The section Pasting data from a content URI describes how to get a content URI from the clipboard and use it to get and paste data.
You can copy and paste large amounts of text and binary data as streams. The data can have forms such as the following:
A content provider for data streams provides access to its data with a file descriptor object such as {@link android.content.res.AssetFileDescriptor} instead of a {@link android.database.Cursor} object. The pasting application reads the data stream using this file descriptor.
To set up your application to copy a data stream with a provider, follow these steps:
To paste a data stream, an application gets the clip from the clipboard, gets the URI, and uses it in a call to a {@link android.content.ContentResolver} file descriptor method that opens the stream. The {@link android.content.ContentResolver} method calls the corresponding {@link android.content.ContentProvider} method, passing it the content URI. Your provider returns the file descriptor to {@link android.content.ContentResolver} method. The pasting application then has the responsibility to read the data from the stream.
The following list shows the most important file descriptor methods for a content provider. Each of these has a corresponding {@link android.content.ContentResolver} method with the string "Descriptor" appended to the method name; for example, the {@link android.content.ContentResolver} analog of {@link android.content.ContentProvider#openAssetFile(Uri, String) openAssetFile()} is {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) openAssetFileDescriptor()}:
This method handles subsections of files. You can use it to read assets that the content provider has copied to the clipboard.
You can optionally use the
{@link android.content.ContentProvider#openPipeHelper(Uri, String, Bundle, T, ContentProvider.PipeDataWriter) openPipeHelper()}
method with your file descriptor method. This allows the pasting application to read the
stream data in a background thread using a pipe. To use this method, you need to implement the
{@link android.content.ContentProvider.PipeDataWriter} interface. An example of doing this is
given in the Note Pad sample
application, in the openTypedAssetFile() method of
NotePadProvider.java.
To design effective copy and paste functionality for your application, remember these points: