ClipData

Class Overview

Representation of a clipped data on the clipboard.

ClippedData is a complex type containing one or Item instances,
each of which can hold one or more representations of an item of data.
For display to the user, it also has a label and iconic representation.

Each Item instance can be one of three main classes of data: a simple
CharSequence of text, a single Intent object, or a Uri. See ClipData.Item
for more details.

Developer Guides

For more information about using the clipboard framework, read the
Copy and Paste
developer guide.

Implementing Paste or Drop

To implement a paste or drop of a ClippedData object into an application,
the application must correctly interpret the data for its use. If the ClipData.Item
it contains is simple text or an Intent, there is little to be done: text
can only be interpreted as text, and an Intent will typically be used for
creating shortcuts (such as placing icons on the home screen) or other
actions.

If all you want is the textual representation of the clipped data, you
can use the convenience method Item.coerceToText.
In this case there is generally no need to worry about the MIME types
reported by getDescription().getMimeType(int),
since any clip item can always be converted to a string.

More complicated exchanges will be done through URIs, in particular
"content:" URIs. A content URI allows the recipient of a ClippedData item
to interact closely with the ContentProvider holding the data in order to
negotiate the transfer of that data. The clip must also be filled in with
the available MIME types; newUri(ContentResolver, CharSequence, Uri)
will take care of correctly doing this.

For example, here is the paste function of a simple NotePad application.
When retrieving the data from the clipboard, it can do either two things:
if the clipboard contains a URI reference to an existing note, it copies
the entire structure of the note into a new note; otherwise, it simply
coerces the clip into text and uses that as the new note's contents.

/**
* A helper method that replaces the note's data with the contents of the clipboard.
*/
private final void performPaste() {
// 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) {
String text=null;
String title=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 pointing to a note
Uri uri = item.getUri();
// Tests to see that the item actually is an URI, and that the URI
// is a content URI pointing to a provider whose MIME type is the same
// as the MIME type supported by the Note pad provider.
if (uri != null && NotePad.Notes.CONTENT_ITEM_TYPE.equals(cr.getType(uri))) {
// The clipboard holds a reference to data with a note MIME type. This copies it.
Cursor orig = cr.query(
uri, // URI for the content provider
PROJECTION, // Get the columns referred to in the projection
null, // No selection variables
null, // No selection variables, so no criteria are needed
null // Use the default sort order
);
// If the Cursor is not null, and it contains at least one record
// (moveToFirst() returns true), then this gets the note data from it.
if (orig != null) {
if (orig.moveToFirst()) {
int colNoteIndex = mCursor.getColumnIndex(NotePad.Notes.COLUMN_NAME_NOTE);
int colTitleIndex = mCursor.getColumnIndex(NotePad.Notes.COLUMN_NAME_TITLE);
text = orig.getString(colNoteIndex);
title = orig.getString(colTitleIndex);
}
// Closes the cursor.
orig.close();
}
}
// If the contents of the clipboard wasn't a reference to a note, then
// this converts whatever it is to text.
if (text == null) {
text = item.coerceToText(this).toString();
}
// Updates the current note with the retrieved title and text.
updateNote(text, title);
}
}

In many cases an application can paste various types of streams of data. For
example, an e-mail application may want to allow the user to paste an image
or other binary data as an attachment. This is accomplished through the
ContentResolver getStreamTypes(Uri, String) and
openTypedAssetFileDescriptor(Uri, String, android.os.Bundle)
methods. These allow a client to discover the type(s) of data that a particular
content URI can make available as a stream and retrieve the stream of data.

For example, the implementation of Item.coerceToText
itself uses this to try to retrieve a URI clip as a stream of text:

Implementing Copy or Drag

To be the source of a clip, the application must construct a ClippedData
object that any recipient can interpret best for their context. If the clip
is to contain a simple text, Intent, or URI, this is easy: an ClipData.Item
containing the appropriate data type can be constructed and used.

More complicated data types require the implementation of support in
a ContentProvider for describing and generating the data for the recipient.
A common scenario is one where an application places on the clipboard the
content: URI of an object that the user has copied, with the data at that
URI consisting of a complicated structure that only other applications with
direct knowledge of the structure can use.

Note if a paste operation needs this clip as text (for example to paste
into an editor), then coerceToText(Context) will ask the content
provider for the clip URI as text and successfully paste the entire note.

Flag for use with writeToParcel(Parcel, int): the object being written
is a return value, that is the result of a function such as
"Parcelable someFunction()",
"void someFunction(out Parcelable)", or
"void someFunction(inout Parcelable)".

Returns

Create a new ClipData holding a URI. If the URI is a content: URI,
this will query the content provider for the MIME type of its data and
use that as the MIME type. Otherwise, it will use the MIME type
MIMETYPE_TEXT_URILIST.

Parameters

resolver

ContentResolver used to get information about the URI.

label

User-visible label for the clip data.

uri

The URI in the clip.

Returns

Returns a string containing a concise, human-readable description of this
object. Subclasses are encouraged to override this method and provide an
implementation that takes into account the object's type and data. The
default implementation is equivalent to the following expression: