Merge "Improve javadocs for OnReceiveContentListener" into sc-dev

core/java/android/view/OnReceiveContentListener.java

@@ -92,21 +92,25 @@ public interface OnReceiveContentListener {
      * {@link android.content.ContentResolver#SCHEME_CONTENT content URIs} in the payload passed
      * to this listener. Permissions are transient and will be released automatically by the
      * platform.
-     * <ul>
-     *     <li>If the {@link ContentInfo#getSource() source} is the
-     *     {@link ContentInfo#SOURCE_CLIPBOARD clipboard}, permissions are released whenever the
-     *     next copy action is performed by the user.
-     *     <li>If the source is {@link ContentInfo#SOURCE_AUTOFILL autofill}, permissions are tied
-     *     to the target {@link android.app.Activity} lifecycle (released when the activity
-     *     finishes).
-     *     <li>For other sources, permissions are tied to the passed-in {@code payload} object
-     *     (released automatically when there are no more references to it). To ensure that
-     *     permissions are not released prematurely, implementations of this listener should pass
-     *     along the {@code payload} object if processing is done on a background thread.
-     * </ul>
+     * <p>Processing of content should normally be done in a service or activity.
+     * For long-running processing, using {@code androidx.work.WorkManager} is recommended.
+     * When implementing this, permissions should be extended to the target service or activity
+     * by passing the content using {@link android.content.Intent#setClipData Intent.setClipData}
+     * and {@link android.content.Intent#addFlags(int) setting} the flag
+     * {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION FLAG_GRANT_READ_URI_PERMISSION}.
+     * <p>Alternatively, if using a background thread within the current context to process the
+     * content, a reference to the {@code payload} object should be maintained to ensure that
+     * permissions are not revoked prematurely.
      *
      * @param view The view where the content insertion was requested.
-     * @param payload The content to insert and related metadata.
+     * @param payload The content to insert and related metadata. The payload may contain multiple
+     *                items and their MIME types may be different (e.g. an image item and a text
+     *                item). The payload may also contain items whose MIME type is not in the list
+     *                of MIME types specified when
+     *                {@link View#setOnReceiveContentListener setting} the listener. For
+     *                those items, the listener may reject the content (defer to the default
+     *                platform behavior) or execute some other fallback logic (e.g. show an
+     *                appropriate message to the user).
      *
      * @return The portion of the passed-in content whose processing should be delegated to
      * the platform. Return null if all content was handled in some way. Actual insertion of

core/java/android/view/View.java

@@ -9046,22 +9046,27 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * content into this view.
      *
      * <p>Depending on the type of view, this listener may be invoked for different scenarios. For
-     * example, for editable TextViews, this listener will be invoked for the following scenarios:
+     * example, for an editable {@link android.widget.TextView}, this listener will be invoked for
+     * the following scenarios:
      * <ol>
      *     <li>Paste from the clipboard (e.g. "Paste" or "Paste as plain text" action in the
      *     insertion/selection menu)
      *     <li>Content insertion from the keyboard (from {@link InputConnection#commitContent})
-     *     <li>Drag and drop (drop events from {@link #onDragEvent(DragEvent)})
+     *     <li>Drag and drop (drop events from {@link #onDragEvent})
      *     <li>Autofill
      *     <li>Selection replacement via {@link Intent#ACTION_PROCESS_TEXT}
      * </ol>
      *
-     * <p>When setting a listener, clients should also declare the MIME types accepted by it.
-     * When invoked with other types of content, the listener may reject the content (defer to
-     * the default platform behavior) or execute some other fallback logic. The MIME types
-     * declared here allow different features to optionally alter their behavior. For example,
-     * the soft keyboard may choose to hide its UI for inserting GIFs for a particular input
-     * field if the MIME types set here for that field don't include "image/gif" or "image/*".
+     * <p>When setting a listener, clients must also declare the accepted MIME types.
+     * The listener will still be invoked even if the MIME type of the content is not one of the
+     * declared MIME types (e.g. if the user pastes content whose type is not one of the declared
+     * MIME types).
+     * In that case, the listener may reject the content (defer to the default platform behavior)
+     * or execute some other fallback logic (e.g. show an appropriate message to the user).
+     * The declared MIME types serve as a hint to allow different features to optionally alter
+     * their behavior. For example, a soft keyboard may optionally choose to hide its UI for
+     * inserting GIFs for a particular input field if the MIME types set here for that field
+     * don't include "image/gif" or "image/*".
      *
      * <p>Note: MIME type matching in the Android framework is case-sensitive, unlike formal RFC
      * MIME types. As a result, you should always write your MIME types with lowercase letters,