DropHelper

public final class DropHelper

Helper class used to configure Views to receive data dropped by a drag and drop operation. Includes support for content insertion using an OnReceiveContentListener. Adds highlighting during the drag interaction to indicate to the user where the drop action can successfully take place.

To ensure that drop target highlighting and text data handling work correctly, all EditText elements in the drop target view's descendant tree (that is, any EditText elements contained within the drop target) must be provided as arguments to a call to addInnerEditTexts. Otherwise, an EditText within the target will steal the focus during the drag and drop operation, possibly causing undesired highlighting behavior.

Also, if the user is dragging text data and URI data in the drag and drop ClipData, one of the EditText elements in the drop target is automatically chosen to handle the text data. See addInnerEditTexts for the order of precedence in selecting the EditText that handles the text data.

This helper attaches an OnReceiveContentListener to drop targets and configures drop targets to listen for drag and drop events (see configureView). Do not attach an OnDragListener or additional OnReceiveContentLister to drop targets when using DropHelper.

Note: This class requires Android API level 24 or higher.

See also
<a href="https://developer.android.com/guide/topics/ui/drag-drop">Drag and drop</a>

Multi-window support

Summary

Nested types
public final class DropHelper.Options

Options for configuring drop targets specified by DropHelper.
public final class DropHelper.Options.Builder

Builder for constructing a DropHelper.Options instance.

Public methods
static void
configureView(
    @NonNull Activity activity,
    @NonNull View dropTarget,
    @NonNull String[] mimeTypes,
    @NonNull OnReceiveContentListener onReceiveContentListener
)

Configures a View for drag and drop operations, including the highlighting that indicates the view is a drop target.
static void
configureView(
    @NonNull Activity activity,
    @NonNull View dropTarget,
    @NonNull String[] mimeTypes,
    @NonNull DropHelper.Options options,
    @NonNull OnReceiveContentListener onReceiveContentListener
)

Configures a View for drag and drop operations, including the highlighting that indicates the view is a drop target.

Public methods

configureView

Added in 1.0.0
public static void configureView(
    @NonNull Activity activity,
    @NonNull View dropTarget,
    @NonNull String[] mimeTypes,
    @NonNull OnReceiveContentListener onReceiveContentListener
)

Configures a View for drag and drop operations, including the highlighting that indicates the view is a drop target. Sets a listener that enables the view to handle dropped data.

Same as configureView but with default configuration options.

Note: If the drop target contains EditText elements, you must use configureView. The Options argument enables you to specify a list of the EditText elements (see addInnerEditTexts).

Parameters
@NonNull Activity activity

The current Activity (used for URI permissions).
@NonNull View dropTarget

A View that accepts the drag and drop data.
@NonNull String[] mimeTypes

The MIME types the drop target can accept from the dropped data.
@NonNull OnReceiveContentListener onReceiveContentListener

A listener that handles the dropped data.

configureView

Added in 1.0.0
public static void configureView(
    @NonNull Activity activity,
    @NonNull View dropTarget,
    @NonNull String[] mimeTypes,
    @NonNull DropHelper.Options options,
    @NonNull OnReceiveContentListener onReceiveContentListener
)

Configures a View for drag and drop operations, including the highlighting that indicates the view is a drop target. Sets a listener that enables the view to handle dropped data.

If the drop target's view hierarchy contains any EditText elements, they all must be specified in options (see addInnerEditTexts).

View highlighting occurs for a drag action only if a MIME type in the ClipDescription matches a MIME type provided in mimeTypes; wildcards are allowed (for example, "image/*"). A drop can be executed and passed on to the OnReceiveContentListener even if the MIME type is not matched.

See DropHelper for more information.

Parameters
@NonNull Activity activity

The current Activity (used for URI permissions).
@NonNull View dropTarget

A View that accepts the drag and drop data.
@NonNull String[] mimeTypes

The MIME types the drop target can accept from the dropped data.
@NonNull DropHelper.Options options

Configuration options for the drop target (see DropHelper.Options).
@NonNull OnReceiveContentListener onReceiveContentListener

A listener that handles the dropped data.