Copy and Paste

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.

The Clipboard Framework

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:

Text

A text string. You put the string directly into the clip object, which you then put onto
the clipboard. To paste the string, you get the clip object from the clipboard and copy
the string to into your application's storage.

URI

A Uri object representing any form of URI. This is primarily for
copying complex data from a content provider. To copy data, you put a
Uri object into a clip object and put the clip object onto
the clipboard. To paste the data, you get the clip object, get the
Uri object, resolve it to a data source such as a content provider,
and copy the data from the source into your application's storage.

Intent

An Intent. This supports copying application shortcuts. To copy
data, you create an Intent, put it into a clip object, and put the clip object onto the
clipboard. To paste the data, you get the clip object and then copy the Intent object
into your application's memory area.

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.

A 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 Uri. This usually contains a content provider URI, although any
URI is allowed. The application that provides the data puts the URI on the clipboard.
Applications that want to paste the data get the URI from the clipboard and use it to
access the content provider (or other data source) and retrieve the data.

Intent

An Intent. This data type allows you to copy an application shortcut
to the clipboard. Users can then paste the shortcut into their applications for later use.

You can add more than one 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
ClipData.Item for each list item, and then you add the
ClipData.Item objects to the ClipData object.

If you are copying data using a content URI, set up a content
provider.

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.

Java

For a URI

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:

Kotlin

// Creates a Uri based on a base Uri and a record ID based on the contact's last name
// Declares the base URI string
const val CONTACTS = "content://com.example.contacts"
// Declares a path string for URIs that you use to copy data
const val COPY_PATH = "/copy"
// Declares the Uri to paste to the clipboard
val copyUri: Uri = 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.
val clip: ClipData = ClipData.newUri(contentResolver, "URI", copyUri)

Java

// 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);

For an Intent

This snippet constructs an Intent for an application
and then puts it in the clip object:

Kotlin

// Creates the Intent
val appIntent = Intent(this, com.example.demo.myapplication::class.java)
...
// Creates a clip object with the Intent in it. Its label is "Intent" and its data is
// the Intent object created previously
val clip: ClipData = ClipData.newIntent("Intent", appIntent)

Java

// 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);

Put the new clip object on the clipboard:

Kotlin

// Set the clipboard's primary clip.
clipboard.primaryClip = clip

Java

// Set the clipboard's primary clip.
clipboard.setPrimaryClip(clip);

Pasting from the Clipboard

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.

Pasting plain text

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
getText(), as described in the following procedure:

Java

Next, determine if you should enable or disable the "paste" option in the
current Activity. You should verify that the clipboard contains a clip and that you
can handle the type of data represented by the clip:

Kotlin

// Gets the ID of the "paste" menu item
val pasteItem: MenuItem = 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.
pasteItem.isEnabled = when {
!clipboard.hasPrimaryClip() -> {
false
}
!(clipboard.primaryClipDescription.hasMimeType(MIMETYPE_TEXT_PLAIN)) -> {
// This disables the paste menu item, since the clipboard has data but it is not plain text
false
}
else -> {
// This enables the paste menu item, since the clipboard contains plain text.
true
}
}

Java

// Gets the ID of the "paste" menu item
MenuItem pasteItem = 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())) {
pasteItem.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
pasteItem.setEnabled(false);
} else {
// This enables the paste menu item, since the clipboard contains plain text.
pasteItem.setEnabled(true);
}

Copy the data from the clipboard. This point in the program is only reachable if the
"paste" menu item is enabled, so you can assume that the clipboard contains
plain text. You do not yet know if it contains a text string or a URI that points to plain
text. The following snippet tests this, but it only shows the code for handling plain text:

Kotlin

when (menuItem.itemId) {
...
R.id.menu_paste -> { // Responds to the user selecting "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.
val item = clipboard.primaryClip.getItemAt(0)
// Gets the clipboard as text.
pasteData = item.text
return if (pasteData != null) {
// If the string contains data, then the paste operation is done
true
} else {
// The clipboard does not contain text.
// If it contains a URI, attempts to get data from it
val pasteUri: Uri? = item.uri
if (pasteUri != null) {
// If the URI contains something, try to get text from it
// calls a routine to resolve the URI and get data from it. This routine is not
// presented here.
pasteData = resolveUri(pasteUri)
true
} 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(TAG,"Clipboard contains an invalid data type")
false
}
}
}
}

Java

// 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 true;
// 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 true;
} 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(TAG, "Clipboard contains an invalid data type");
return false;
}
}

Pasting data from a content URI

If the ClipData.Item object contains a content URI and you
have determined that you can handle one of its MIME types, create a
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:

Kotlin

Java

// If the clipboard contains a URI reference
if (pasteUri != null) {
// Is this a content URI?
String uriMimeType = cr.getType(pasteUri);

Test to see if the content provider supports a MIME type that the current application
understands. If it does, call
ContentResolver.query() to get the data. The return value is a
Cursor:

Kotlin

// If the return value is not null, the Uri is a content Uri
uriMimeType?.takeIf {
// Does the content provider offer a MIME type that the current application can use?
it == MIME_TYPE_CONTACT
}?.apply {
// Get the data from the content provider.
cr.query(pasteUri, null, null, null, null)?.use { pasteCursor ->
// If the Cursor contains data, move to the first record
if (pasteCursor.moveToFirst()) {
// get the data from the Cursor here. The code will vary according to the
// format of the data model.
}
// Kotlin `use` will automatically close the Cursor
}
}
}
}

Java

// 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();
}
}
}
}

Pasting an Intent

To paste an Intent, first get the global clipboard. Examine the
ClipData.Item object to see if it contains an Intent. Then call
getIntent() to copy the Intent to your own storage.
The following snippet demonstrates this:

Kotlin

// Gets a handle to the Clipboard Manager
val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
// Checks to see if the clip item contains an Intent, by testing to see if getIntent() returns null
val pasteIntent: Intent? = clipboard.primaryClip?.getItemAt(0)?.intent
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
}

Java

// 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
}

Using Content Providers to Copy Complex Data

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.

Encoding an identifier on the URI

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:

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.

Copying data structures

You set up a content provider for copying and pasting complex data as a subclass of the
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:

If you already have a content provider, you can add to its functionality. You may only
need to modify its
query()
method to handle URIs coming from applications that want to paste data. You will
probably want to modify the method to handle a "copy" URI pattern.

If your application maintains an internal database, you may
want to move this database into a content provider to facilitate copying from it.

If you are not currently using a database, you can implement a simple content provider
whose sole purpose is to offer data to applications that are pasting from the
clipboard.

In the content provider, you will want to override at least the following methods:

Pasting applications will assume that they can get your data by using this method with
the URI you put on the clipboard. To support copying, you should have this method
detect URIs that contain a special "copy" path. Your application can then
create a "copy" URI to put on the clipboard, containing the copy path and
a pointer to the exact record you want to copy.

Notice that you don't have to have any of the other content provider methods such as
insert() or
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:

Copying data streams

You can copy and paste large amounts of text and binary data as streams. The data can have
forms such as the following:

Files stored on the actual device.

Streams from sockets.

Large amounts of data stored in a provider's underlying database system.

A content provider for data streams provides access to its data with a file descriptor object
such as AssetFileDescriptor instead of a
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:

Set up a content URI for the data stream you are putting on the clipboard. Options
for doing this include the following:

Encode an identifier for the data stream onto the URI,
as described in the section
Encoding an identifier on the URI, and then maintain a
table in your provider that contains identifiers and the corresponding stream name.

Encode the stream name directly on the URI.

Use a unique URI that always returns the current stream from the provider. If you
use this option, you have to remember to update your provider to point to a
different stream whenever you copy the stream to the clipboard via the URI.

Provide a MIME type for each type of data stream you plan to offer. Pasting applications
need this information to determine if they can paste the data on the clipboard.

Implement one of the ContentProvider methods that returns
a file descriptor for a stream. If you encode identifiers on the content URI, use this
method to determine which stream to open.

To copy the data stream to the clipboard, construct the content URI and place it
on the clipboard.

To paste a data stream, an application gets the clip from the clipboard, gets the URI, and
uses it in a call to a ContentResolver file descriptor method that
opens the stream. The ContentResolver method calls the corresponding
ContentProvider method, passing it the content URI. Your provider
returns the file descriptor to ContentResolver method. The pasting
application then has the responsibility to read the data from the stream.

This method should return an asset file descriptor, but only if the provided MIME type is
supported by the provider. The caller (the application doing the pasting) provides a MIME
type pattern. The content provider (of the application that has copied a URI to the
clipboard) returns an AssetFileDescriptor file handle if it
can provide that MIME type, or throws an exception if it can not.

This method handles subsections of files. You can use it to read assets that the
content provider has copied to the clipboard.

This is a more general form of
openAssetFile(). It can't
read subsections of files.

You can optionally use the
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
ContentProvider.PipeDataWriter interface. An example of doing this is
given in the Note Pad sample
application, in the openTypedAssetFile() method of
NotePadProvider.java.

Designing Effective Copy/Paste Functionality

To design effective copy and paste functionality for your application, remember these
points:

At any time, there is only one clip on the clipboard. A new copy operation by
any application in the system overwrites the previous clip. Since the user may
navigate away from your application and do a copy before returning, you can't assume
that the clipboard contains the clip that the user previously copied in your
application.

The intended purpose of multiple ClipData.Item
objects per clip is to support copying and pasting of multiple selections rather than
different forms of reference to a single selection. You usually want all of the
ClipData.Item objects in a clip to have the same form, that is,
they should all be simple text, content URI, or Intent, but not
a mixture.

When you provide data, you can offer different MIME representations. Add the MIME types
you support to the ClipDescription, and then
implement the MIME types in your content provider.

When you get data from the clipboard, your application is responsible for checking the
available MIME types and then deciding which one, if any, to use. Even if there is a
clip on the clipboard and the user requests a paste, your application is not required
to do the paste. You should do the paste if the MIME type is compatible. You
may choose to coerce the data on the clipboard to text using
coerceToText() if you
choose. If your application supports more than one of the available MIME types, you can
allow the user to choose which one to use.

Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.