# Print output for @column tags ?>
Developers

- Design
- Develop
- Distribute

Developer Console

## Most visited

## Recently visited

## Results for

Summary: Nested Classes | Inherited Constants | Fields | Ctors | Methods | Inherited Methods

# ClipData

`public class ClipData`
`extends Object` `implements Parcelable`

java.lang.Object
↳ | android.content.ClipData

Representation of a clipped data on the clipboard.

ClipData is a complex type containing one or more 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.

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(java.lang.CharSequence, java.lang.CharSequence)`, `newUri(android.content.ContentResolver, java.lang.CharSequence, android.net.Uri)`, and `newIntent(java.lang.CharSequence, android.content.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 `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 ClipData object into an application, the application must correctly interpret the data for its use. If the `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 ClipData 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(android.content.ContentResolver, java.lang.CharSequence, android.net.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 = orig.getColumnIndex(NotePad.Notes.COLUMN_NAME_NOTE);
                        int colTitleIndex = orig.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 `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:

    public CharSequence coerceToText(Context context) {
        // If this Item has an explicit textual value, simply return that.
        CharSequence text = getText();
        if (text != null) {
            return text;
        }

        // If this Item has a URI value, try using that.
        Uri uri = getUri();
        if (uri != null) {
            // First see if the URI can be opened as a plain text stream
            // (of any sub-type).  If so, this is the best textual
            // representation for it.
            final ContentResolver resolver = context.getContentResolver();
            AssetFileDescriptor descr = null;
            FileInputStream stream = null;
            InputStreamReader reader = null;
            try {
                try {
                    // Ask for a stream of the desired type.
                    descr = resolver.openTypedAssetFileDescriptor(uri, "text/*", null);
                } catch (SecurityException e) {
                    Log.w("ClipData", "Failure opening stream", e);
                } catch (FileNotFoundException|RuntimeException e) {
                    // Unable to open content URI as text...  not really an
                    // error, just something to ignore.
                }
                if (descr != null) {
                    try {
                        stream = descr.createInputStream();
                        reader = new InputStreamReader(stream, "UTF-8");

                        // Got it...  copy the stream into a local string and return it.
                        final StringBuilder builder = new StringBuilder(128);
                        char[] buffer = new char[8192];
                        int len;
                        while ((len=reader.read(buffer)) > 0) {
                            builder.append(buffer, 0, len);
                        }
                        return builder.toString();
                    } catch (IOException e) {
                        // Something bad has happened.
                        Log.w("ClipData", "Failure loading text", e);
                        return e.toString();
                    }
                }
            } finally {
                IoUtils.closeQuietly(descr);
                IoUtils.closeQuietly(stream);
                IoUtils.closeQuietly(reader);
            }

            // If we couldn't open the URI as a stream, use the URI itself as a textual
            // representation (but not for "content", "android.resource" or "file" schemes).
            final String scheme = uri.getScheme();
            if (SCHEME_CONTENT.equals(scheme)
                    || SCHEME_ANDROID_RESOURCE.equals(scheme)
                    || SCHEME_FILE.equals(scheme)) {
                return "";
            }
            return uri.toString();
        }

        // Finally, if all we have is an Intent, then we can just turn that
        // into text.  Not the most user-friendly thing, but it's something.
        Intent intent = getIntent();
        if (intent != null) {
            return intent.toUri(Intent.URI_INTENT_SCHEME);
        }

        // Shouldn't get here, but just in case...
        return "";
    }

### Implementing Copy or Drag

To be the source of a clip, the application must construct a ClipData 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 `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.

    /**
     * This describes the MIME types that are supported for opening a note
     * URI as a stream.
     */
    static ClipDescription NOTE_STREAM_TYPES = new ClipDescription(null,
            new String[] { ClipDescription.MIMETYPE_TEXT_PLAIN });

    /**
     * Returns the types of available data streams.  URIs to specific notes are supported.
     * The application can convert such a note to a plain text stream.
     *
     * @param uri the URI to analyze
     * @param mimeTypeFilter The MIME type to check for. This method only returns a data stream
     * type for MIME types that match the filter. Currently, only text/plain MIME types match.
     * @return a data stream MIME type. Currently, only text/plan is returned.
     * @throws IllegalArgumentException if the URI pattern doesn't match any supported patterns.
     */
    @Override
    public String[] getStreamTypes(Uri uri, String mimeTypeFilter) {
        /**
         *  Chooses the data stream type based on the incoming URI pattern.
         */
        switch (sUriMatcher.match(uri)) {

            // If the pattern is for notes or live folders, return null. Data streams are not
            // supported for this type of URI.
            case NOTES:
                return null;

            // If the pattern is for note IDs and the MIME filter is text/plain, then return
            // text/plain
            case NOTE_ID:
                return NOTE_STREAM_TYPES.filterMimeTypes(mimeTypeFilter);

                // If the URI pattern doesn't match any permitted patterns, throws an exception.
            default:
                throw new IllegalArgumentException("Unknown URI " + uri);
            }
    }

    /**
     * Returns a stream of data for each supported stream type. This method does a query on the
     * incoming URI, then uses
     * {@link android.content.ContentProvider#openPipeHelper(Uri, String, Bundle, Object,
     * PipeDataWriter)} to start another thread in which to convert the data into a stream.
     *
     * @param uri The URI pattern that points to the data stream
     * @param mimeTypeFilter A String containing a MIME type. This method tries to get a stream of
     * data with this MIME type.
     * @param opts Additional options supplied by the caller.  Can be interpreted as
     * desired by the content provider.
     * @return AssetFileDescriptor A handle to the file.
     * @throws FileNotFoundException if there is no file associated with the incoming URI.
     */
    @Override
    public AssetFileDescriptor openTypedAssetFile(Uri uri, String mimeTypeFilter, Bundle opts)
            throws FileNotFoundException {

        // Checks to see if the MIME type filter matches a supported MIME type.
        String[] mimeTypes = getStreamTypes(uri, mimeTypeFilter);

        // If the MIME type is supported
        if (mimeTypes != null) {

            // Retrieves the note for this URI. Uses the query method defined for this provider,
            // rather than using the database query method.
            Cursor c = query(
                    uri,                    // The URI of a note
                    READ_NOTE_PROJECTION,   // Gets a projection containing the note's ID, title,
                                            // and contents
                    null,                   // No WHERE clause, get all matching records
                    null,                   // Since there is no WHERE clause, no selection criteria
                    null                    // Use the default sort order (modification date,
                                            // descending
            );

            // If the query fails or the cursor is empty, stop
            if (c == null || !c.moveToFirst()) {

                // If the cursor is empty, simply close the cursor and return
                if (c != null) {
                    c.close();
                }

                // If the cursor is null, throw an exception
                throw new FileNotFoundException("Unable to query " + uri);
            }

            // Start a new thread that pipes the stream data back to the caller.
            return new AssetFileDescriptor(
                    openPipeHelper(uri, mimeTypes[0], opts, c, this), 0,
                    AssetFileDescriptor.UNKNOWN_LENGTH);
        }

        // If the MIME type is not supported, return a read-only handle to the file.
        return super.openTypedAssetFile(uri, mimeTypeFilter, opts);
    }

    /**
     * Implementation of {@link android.content.ContentProvider.PipeDataWriter}
     * to perform the actual work of converting the data in one of cursors to a
     * stream of data for the client to read.
     */
    @Override
    public void writeDataToPipe(ParcelFileDescriptor output, Uri uri, String mimeType,
            Bundle opts, Cursor c) {
        // We currently only support conversion-to-text from a single note entry,
        // so no need for cursor data type checking here.
        FileOutputStream fout = new FileOutputStream(output.getFileDescriptor());
        PrintWriter pw = null;
        try {
            pw = new PrintWriter(new OutputStreamWriter(fout, "UTF-8"));
            pw.println(c.getString(READ_NOTE_TITLE_INDEX));
            pw.println("");
            pw.println(c.getString(READ_NOTE_NOTE_INDEX));
        } catch (UnsupportedEncodingException e) {
            Log.w(TAG, "Ooops", e);
        } finally {
            c.close();
            if (pw != null) {
                pw.flush();
            }
            try {
                fout.close();
            } catch (IOException e) {
            }
        }
    }

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:

    case R.id.context_copy:
        // Gets a handle to the clipboard service.
        ClipboardManager clipboard = (ClipboardManager)
                getSystemService(Context.CLIPBOARD_SERVICE);

        // Copies the notes URI to the clipboard. In effect, this copies the note itself
        clipboard.setPrimaryClip(ClipData.newUri(   // new clipboard item holding a URI
                getContentResolver(),               // resolver to retrieve URI info
                "Note",                             // label for the clip
                noteUri)                            // the URI
        );

        // Returns to the caller and skips further processing.
        return true;

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

## Summary

### Nested classes
`class` | `ClipData.Item` Description of a single item in a ClipData.

### Inherited constants
From interface `android.os.Parcelable`
`int` | `CONTENTS_FILE_DESCRIPTOR` Descriptor bit used with `describeContents()`: indicates that the Parcelable object's flattened representation includes a file descriptor.
`int` | `PARCELABLE_WRITE_RETURN_VALUE` 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)`".

### Fields
`public static final Creator<ClipData>` | `CREATOR`

### Public constructors
`ClipData(CharSequence label, String[] mimeTypes, ClipData.Item item)` Create a new clip.
`ClipData(ClipDescription description, ClipData.Item item)` Create a new clip.
`ClipData(ClipData other)` Create a new clip that is a copy of another clip.

### Public methods
`void` | `addItem(ContentResolver resolver, ClipData.Item item)` Add a new Item to the overall ClipData container.
`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 instance's marshaled representation.
`ClipDescription` | `getDescription()` Return the `ClipDescription` associated with this data, describing what it contains.
`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.
`String` | `toString()` Returns a string representation of the object.
`void` | `writeToParcel(Parcel dest, int flags)` Flatten this object in to a Parcel.

### Inherited methods
From class `java.lang.Object`
`Object` | `clone()` Creates and returns a copy of this object.
`boolean` | `equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void` | `finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>` | `getClass()` Returns the runtime class of this `Object`.
`int` | `hashCode()` Returns a hash code value for the object.
`final void` | `notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void` | `notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String` | `toString()` Returns a string representation of the object.
`final void` | `wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void` | `wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void` | `wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.
From interface `android.os.Parcelable`
`abstract int` | `describeContents()` Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
`abstract void` | `writeToParcel(Parcel dest, int flags)` Flatten this object in to a Parcel.

## Fields

### CREATOR

    public static final Creator<ClipData> CREATOR

## Public constructors

### ClipData

    public ClipData (CharSequence label,
                    String[] mimeTypes,
                    ClipData.Item item)

Create a new clip.

Parameters
`label` | `CharSequence`: Label to show to the user describing this clip.
`mimeTypes` | `String`: An array of MIME types this data is available as.
`item` | `ClipData.Item`: The contents of the first item in the clip.

### ClipData

    public ClipData (ClipDescription description,
                    ClipData.Item item)

Create a new clip.

Parameters
`description` | `ClipDescription`: The ClipDescription describing the clip contents.
`item` | `ClipData.Item`: The contents of the first item in the clip.

### ClipData

    public ClipData (ClipData other)

Create a new clip that is a copy of another clip. This does a deep-copy of all items in the clip.

Parameters
`other` | `ClipData`: The existing ClipData that is to be copied.

## Public methods

### addItem

    public void addItem (ContentResolver resolver,
                    ClipData.Item item)

Add a new Item to the overall ClipData container.

Unlike `addItem(android.content.ClipData.Item)`, this method will update the list of available MIME types in the `ClipDescription`.

Parameters
`resolver` | `ContentResolver`: ContentResolver used to get information about the URI possibly contained in the item.
`item` | `ClipData.Item`: Item to be added.

### addItem

    public void addItem (ClipData.Item item)

Add a new Item to the overall ClipData container.

This method will not update the list of available MIME types in the `ClipDescription`. It should be used only when adding items which do not add new MIME types to this clip. If this is not the case, use `addItem(android.content.ContentResolver, android.content.ClipData.Item)` or call `ClipData(java.lang.CharSequence, java.lang.String[], android.content.ClipData.Item)` with a complete list of MIME types.

Parameters
`item` | `ClipData.Item`: Item to be added.

### describeContents

    public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of `writeToParcel(android.os.Parcel, int)`, the return value of this method must include the `CONTENTS_FILE_DESCRIPTOR` bit.

Returns
`int` | a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either `0` or `CONTENTS_FILE_DESCRIPTOR`

### getDescription

    public ClipDescription getDescription ()

Return the `ClipDescription` associated with this data, describing what it contains.

Returns
`ClipDescription` |

### getItemAt

    public ClipData.Item getItemAt (int index)

Return a single item inside of the clip data. The index can range from 0 to `getItemCount()`-1.

Parameters
`index` | `int`

Returns
`ClipData.Item` |

### getItemCount

    public int getItemCount ()

Return the number of items in the clip data.

Returns
`int` |

### newHtmlText

    public static ClipData newHtmlText (CharSequence label,
                    CharSequence text,
                    String htmlText)

Create a new ClipData holding data of the type `ClipDescription#MIMETYPE_TEXT_HTML`.

Parameters
`label` | `CharSequence`: User-visible label for the clip data.
`text` | `CharSequence`: The text of clip as plain text, for receivers that don't handle HTML. This is required.
`htmlText` | `String`: The actual HTML text in the clip.

Returns
`ClipData` | Returns a new ClipData containing the specified data.

### newIntent

    public static ClipData newIntent (CharSequence label,
                    Intent intent)

Create a new ClipData holding an Intent with MIME type `ClipDescription#MIMETYPE_TEXT_INTENT`.

Parameters
`label` | `CharSequence`: User-visible label for the clip data.
`intent` | `Intent`: The actual Intent in the clip.

Returns
`ClipData` | Returns a new ClipData containing the specified data.

### newPlainText

    public static ClipData newPlainText (CharSequence label,
                    CharSequence text)

Create a new ClipData holding data of the type `ClipDescription#MIMETYPE_TEXT_PLAIN`.

Parameters
`label` | `CharSequence`: User-visible label for the clip data.
`text` | `CharSequence`: The actual text in the clip.

Returns
`ClipData` | Returns a new ClipData containing the specified data.

### newRawUri

    public static ClipData newRawUri (CharSequence label,
                    Uri uri)

Create a new ClipData holding an URI with MIME type `ClipDescription#MIMETYPE_TEXT_URILIST`. Unlike `newUri(android.content.ContentResolver, java.lang.CharSequence, android.net.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!

Parameters
`label` | `CharSequence`: User-visible label for the clip data.
`uri` | `Uri`: The URI in the clip.

Returns
`ClipData` | Returns a new ClipData containing the specified data.

### newUri

    public static ClipData newUri (ContentResolver resolver,
                    CharSequence label,
                    Uri uri)

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 `ClipDescription#MIMETYPE_TEXT_URILIST`.

Parameters
`resolver` | `ContentResolver`: ContentResolver used to get information about the URI.
`label` | `CharSequence`: User-visible label for the clip data.
`uri` | `Uri`: The URI in the clip.

Returns
`ClipData` | Returns a new ClipData containing the specified data.

### toString

    public String toString ()

Returns a string representation of the object. In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The `toString` method for class `Object` returns a string consisting of the name of the class of which the object is an instance, the at-sign character ``@`', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

>      getClass().getName() + '@' + Integer.toHexString(hashCode())

Returns
`String` | a string representation of the object.

### writeToParcel

    public void writeToParcel (Parcel dest,
                    int flags)

Flatten this object in to a Parcel.

Parameters
`dest` | `Parcel`: The Parcel in which the object should be written.
`flags` | `int`: Additional flags about how the object should be written. May be 0 or `Parcelable.PARCELABLE_WRITE_RETURN_VALUE`. Value is either `0` or a combination of `Parcelable.PARCELABLE_WRITE_RETURN_VALUE`, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES

Full name *
Email address *
Company / developer name
One of your Play Store app URLs *
Which best describes your business:*
Apps
Games
Apps & Games
*
*