public class ClipData extends Object implements Parcelable
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.
A ClipData contains a ClipDescription
, which describes
important meta-data about the clip. In particular, its
getDescription().getMimeType(int)
must return correct MIME type(s) describing the data in the clip. For help
in correctly constructing a clip with the correct MIME type, use
newPlainText(CharSequence, CharSequence)
,
newUri(ContentResolver, CharSequence, Uri)
, and
newIntent(CharSequence, Intent)
.
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.
For more information about using the clipboard framework, read the Copy and Paste developer guide.
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 an 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.
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 ContentResolver.getStreamTypes(Uri, String)
and
ContentResolver.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:
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.
For applications that do not have intrinsic knowledge of the data structure,
the content provider holding it can make the data available as an arbitrary
number of types of data streams. This is done by implementing the
ContentProvider ContentProvider.getStreamTypes(Uri, String)
and
ContentProvider.openTypedAssetFile(Uri, String, android.os.Bundle)
methods.
Going back to our simple NotePad application, this is the implementation it may have to convert a single note URI (consisting of a title and the note text) into a stream of plain text data.
The copy operation in our NotePad application is now just a simple matter of making a clip containing the URI of the note being copied:
Note if a paste operation needs this clip as text (for example to paste
into an editor), then ClipData.Item.coerceToText(Context)
will ask the content
provider for the clip URI as text and successfully paste the entire note.
Modifier and Type | Class and Description |
---|---|
static class |
ClipData.Item
Description of a single item in a ClippedData.
|
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static Parcelable.Creator<ClipData> |
CREATOR |
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE
Constructor and Description |
---|
ClipData(CharSequence label,
String[] mimeTypes,
ClipData.Item item)
Create a new clip.
|
ClipData(ClipData other)
Create a new clip that is a copy of another clip.
|
ClipData(ClipDescription description,
ClipData.Item item)
Create a new clip.
|
Modifier and Type | Method and Description |
---|---|
void |
addItem(ClipData.Item item)
Add a new Item to the overall ClipData container.
|
int |
describeContents()
Describe the kinds of special objects contained in this Parcelable's
marshalled representation.
|
ClipDescription |
getDescription()
Return the
ClipDescription associated with this data, describing
what it contains. |
Bitmap |
getIcon() |
ClipData.Item |
getItemAt(int index)
Return a single item inside of the clip data.
|
int |
getItemCount()
Return the number of items in the clip data.
|
static ClipData |
newHtmlText(CharSequence label,
CharSequence text,
String htmlText)
Create a new ClipData holding data of the type
ClipDescription.MIMETYPE_TEXT_HTML . |
static ClipData |
newIntent(CharSequence label,
Intent intent)
Create a new ClipData holding an Intent with MIME type
ClipDescription.MIMETYPE_TEXT_INTENT . |
static ClipData |
newPlainText(CharSequence label,
CharSequence text)
Create a new ClipData holding data of the type
ClipDescription.MIMETYPE_TEXT_PLAIN . |
static ClipData |
newRawUri(CharSequence label,
Uri uri)
Create a new ClipData holding an URI with MIME type
ClipDescription.MIMETYPE_TEXT_URILIST . |
static ClipData |
newUri(ContentResolver resolver,
CharSequence label,
Uri uri)
Create a new ClipData holding a URI.
|
void |
toShortString(StringBuilder b) |
String |
toString()
Returns a string containing a concise, human-readable description of this
object.
|
void |
writeToParcel(Parcel dest,
int flags)
Flatten this object in to a Parcel.
|
public static final Parcelable.Creator<ClipData> CREATOR
public ClipData(CharSequence label, String[] mimeTypes, ClipData.Item item)
label
- Label to show to the user describing this clip.mimeTypes
- An array of MIME types this data is available as.item
- The contents of the first item in the clip.public ClipData(ClipDescription description, ClipData.Item item)
description
- The ClipDescription describing the clip contents.item
- The contents of the first item in the clip.public ClipData(ClipData other)
other
- The existing ClipData that is to be copied.public static ClipData newPlainText(CharSequence label, CharSequence text)
ClipDescription.MIMETYPE_TEXT_PLAIN
.label
- User-visible label for the clip data.text
- The actual text in the clip.public static ClipData newHtmlText(CharSequence label, CharSequence text, String htmlText)
ClipDescription.MIMETYPE_TEXT_HTML
.label
- User-visible label for the clip data.text
- The text of clip as plain text, for receivers that don't
handle HTML. This is required.htmlText
- The actual HTML text in the clip.public static ClipData newIntent(CharSequence label, Intent intent)
ClipDescription.MIMETYPE_TEXT_INTENT
.label
- User-visible label for the clip data.intent
- The actual Intent in the clip.public static ClipData newUri(ContentResolver resolver, CharSequence label, Uri uri)
ClipDescription.MIMETYPE_TEXT_URILIST
.resolver
- ContentResolver used to get information about the URI.label
- User-visible label for the clip data.uri
- The URI in the clip.public static ClipData newRawUri(CharSequence label, Uri uri)
ClipDescription.MIMETYPE_TEXT_URILIST
.
Unlike newUri(ContentResolver, CharSequence, Uri)
, nothing
is inferred about the URI -- if it is a content: URI holding a bitmap,
the reported type will still be uri-list. Use this with care!label
- User-visible label for the clip data.uri
- The URI in the clip.public ClipDescription getDescription()
ClipDescription
associated with this data, describing
what it contains.public void addItem(ClipData.Item item)
public Bitmap getIcon()
public int getItemCount()
public ClipData.Item getItemAt(int index)
getItemCount()
-1.public String toString()
Object
getClass().getName() + '@' + Integer.toHexString(hashCode())
See Writing a useful
toString
method
if you intend implementing your own toString
method.
public void toShortString(StringBuilder b)
public int describeContents()
Parcelable
describeContents
in interface Parcelable
public void writeToParcel(Parcel dest, int flags)
Parcelable
writeToParcel
in interface Parcelable
dest
- The Parcel in which the object should be written.flags
- Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE
.