Conceptos clave

En las siguientes secciones, se explican algunos conceptos clave para el proceso de arrastrar y soltar.

Proceso de arrastrar y soltar

Hay cuatro pasos o estados en el proceso de arrastrar y soltar: iniciado, continuo, soltado y finalizado.

Iniciado

En respuesta al gesto de arrastre de un usuario, tu aplicación llama a startDragAndDrop() para indicarle al sistema que inicie una operación de arrastrar y soltar. Los argumentos del método proporcionan lo siguiente:

• Los datos que se arrastrarán.
• Una devolución de llamada para dibujar la sombra de arrastre
• Metadatos que describen los datos arrastrados
• El sistema responde llamando a tu aplicación para obtener una sombra de arrastre. Luego, muestra la sombra de arrastre en el dispositivo.
• A continuación, el sistema envía un evento de arrastre con el tipo de acción ACTION_DRAG_STARTED al objeto de escucha de eventos de arrastre de todos los objetos View del diseño actual. Para seguir recibiendo eventos de arrastre, incluido un posible evento de soltar, el objeto de escucha de eventos de arrastre debe mostrar true. Esto registra el objeto de escucha en el sistema. Solo los objetos de escucha registrados continúan recibiendo eventos de arrastre. En este punto, los objetos de escucha también pueden cambiar el aspecto de su objeto View de destino para soltar a fin de mostrar que la vista puede aceptar un evento de acción de soltar.
• Si el objeto de escucha de eventos de arrastre muestra false, no recibirá eventos de arrastre para la operación actual hasta que el sistema envíe un evento de arrastre con el tipo de acción ACTION_DRAG_ENDED. Al mostrar false, el objeto de escucha le indica al sistema que no está interesado en la operación de arrastrar y soltar, y que no quiere aceptar los datos arrastrados.

Nota: Un valor que se muestra false de un View.OnDragListener activa el controlador onDragEvent() de la vista.

Continuando

El usuario continúa con el arrastre. A medida que la sombra de arrastre se cruza con el cuadro límite de un destino para soltar, el sistema envía uno o más eventos de arrastre al objeto de escucha de eventos de arrastre del destino. El objeto de escucha puede modificar el aspecto del destino para soltar View en respuesta al evento. Por ejemplo, si el evento indica que la sombra de arrastre ingresa en el cuadro de límite del destino para soltar (tipo de acción ACTION_DRAG_ENTERED), el objeto de escucha puede reaccionar destacando View.

Soltado

El usuario suelta la sombra de arrastre dentro del cuadro de límite de un destino para soltar. El sistema envía al objeto de escucha del destino para soltar un evento de arrastre con el tipo de acción ACTION_DROP. El objeto de evento de arrastre contiene los datos que pasan al sistema en la llamada a startDragAndDrop() que inicia la operación. Se espera que el objeto de escucha muestre un valor booleano true al sistema si procesa correctamente los datos descartados. : Este paso solo se produce si el usuario suelta la sombra de arrastre dentro del cuadro de límite de una View cuyo objeto de escucha está registrado para recibir eventos de arrastre (un destino para soltar). Si el usuario suelta la sombra de arrastre en cualquier otra situación, no se envía ningún evento de arrastre ACTION_DROP.

Finalizado

Después de que el usuario suelte la sombra de arrastre y después de que el sistema envíe

fuera un evento de arrastre con el tipo de acción ACTION_DROP; si es necesario, el sistema envía un evento de arrastre con el tipo de acción ACTION_DRAG_ENDED para indicar que la operación de arrastrar y soltar finalizó. Esto se lleva a cabo sin importar el lugar en que el usuario suelte la sombra de arrastre. El evento se envía a todos los objetos de escucha que están registrados para recibir eventos de arrastre, incluso si también reciben el evento ACTION_DROP.

Cada uno de estos pasos se describe con más detalle en la sección Una operación de arrastrar y soltar.

Nota: Si las apps se ejecutan en el modo multiventana, los usuarios pueden arrastrar datos de una app a otra. Para obtener más información, consulta Cómo arrastrar y soltar en Compatibilidad con el modo multiventana.

Eventos de arrastre

El sistema envía un evento de arrastre en forma de objeto DragEvent, que contiene un tipo de acción que describe lo que sucede en el proceso de arrastrar y soltar. Según el tipo de acción, el objeto también puede contener otros datos.

Los objetos de escucha de eventos de arrastre reciben el objeto DragEvent. Para obtener el tipo de acción, los objetos de escucha llaman a DragEvent.getAction(). Hay seis valores posibles definidos por constantes en la clase DragEvent, que se describen en la tabla 1:

Tabla 1: Tipos de acción DragEvent

Tipo de acción	Significado
ACTION_DRAG_STARTED	La aplicación llama a startDragAndDrop() y obtiene una sombra de arrastre. Si el objeto de escucha desea seguir recibiendo eventos de arrastre para esta operación, debe mostrar un valor booleano true al sistema.
ACTION_DRAG_ENTERED	La sombra de arrastre ingresa en el cuadro de límite del View del objeto de escucha de eventos de arrastre. Este es el primer tipo de acción de evento que recibe el objeto de escucha cuando la sombra de arrastre ingresa al cuadro de límite.
ACTION_DRAG_LOCATION	Luego de un evento ACTION_DRAG_ENTERED, la sombra de arrastre permanece dentro del cuadro de límite del View del objeto de escucha de eventos de arrastre.
ACTION_DRAG_EXITED	Después de un evento ACTION_DRAG_ENTERED y, al menos, un evento ACTION_DRAG_LOCATION, la sombra de arrastre se mueve fuera del cuadro de límite del View del objeto de escucha de eventos de arrastre.
ACTION_DROP	La sombra de arrastre se suelta sobre el View del objeto de escucha de eventos de arrastre. Este tipo de acción se envía al objeto de escucha de un objeto View solo si el objeto de escucha muestra un valor booleano true en respuesta al evento de arrastre ACTION_DRAG_STARTED. Este tipo de acción no se envía si el usuario suelta la sombra de arrastre sobre una View cuyo objeto de escucha no está registrado o si suelta la sombra de arrastre sobre cualquier elemento que no forme parte del diseño actual. El objeto de escucha muestra un valor booleano true si procesa con éxito la acción de soltar. De lo contrario, debe mostrar false.
ACTION_DRAG_ENDED	El sistema finalizará la operación de arrastrar y soltar. Este tipo de acción no necesariamente está precedido por un evento ACTION_DROP. Si el sistema envía un ACTION_DROP, recibir el tipo de acción ACTION_DRAG_ENDED no implica que la acción de soltar se haya realizado correctamente. El objeto de escucha debe llamar a getResult(), como se muestra en la tabla 2, para obtener el valor que se muestra en respuesta a ACTION_DROP. Si no se envía un evento ACTION_DROP, getResult() muestra false.

El objeto DragEvent también contiene los datos y metadatos que tu aplicación proporciona al sistema en la llamada a startDragAndDrop(). Algunos de los datos son válidos solo para ciertos tipos de acción, como se resume en la tabla 2. Para obtener más información sobre los eventos y sus datos asociados, consulta la sección Operación de arrastrar y soltar.

Tabla 2: Datos válidos de DragEvent por tipo de acción

getAction() valor	getClipDescription() valor	getLocalState() valor	getX() valor	getY() valor	getClipData() valor	getResult() valor
ACTION_DRAG_STARTED	✓	✓
ACTION_DRAG_ENTERED	✓	✓
ACTION_DRAG_LOCATION	✓	✓	✓	✓
ACTION_DRAG_EXITED	✓	✓
ACTION_DROP	✓	✓	✓	✓	✓
ACTION_DRAG_ENDED		✓				✓

Los métodos getAction(), describeContents(), writeToParcel() y toString() de DragEvent siempre muestran datos válidos.

Si un método no contiene datos válidos para un tipo de acción específico, muestra null o 0, según su tipo de resultado.

Sombra de arrastre

Durante una operación de arrastrar y soltar, el sistema muestra una imagen que el usuario arrastra. Para el movimiento de datos, esta imagen representa los datos que se arrastran. Para otras operaciones, la imagen representa algún aspecto de la operación de arrastre.

La imagen se denomina sombra de arrastre. Se crea con métodos que declaras para un objeto View.DragShadowBuilder. Debes pasar el compilador al sistema cuando inicies una operación de arrastrar y soltar con startDragAndDrop(). Como parte de la respuesta a startDragAndDrop(), el sistema invoca los métodos de devolución de llamada que defines en View.DragShadowBuilder para obtener una sombra de arrastre.

La clase View.DragShadowBuilder tiene dos constructores:

View.DragShadowBuilder(View)

Este constructor acepta cualquiera de los objetos View de la aplicación. El constructor almacena el objeto View en el objeto View.DragShadowBuilder, por lo que las devoluciones de llamada pueden acceder a él para construir la sombra de arrastre. No es necesario que la vista sea un View que el usuario seleccione para iniciar la operación de arrastre.

Si usas este constructor, no necesitas extender View.DragShadowBuilder ni anular sus métodos. De forma predeterminada, obtendrás una sombra de arrastre que tiene la misma apariencia que el View que pasas como argumento, centrada debajo de la ubicación en la que el usuario toca la pantalla.

View.DragShadowBuilder()

Si usas este constructor, no habrá ningún objeto View disponible en el objeto View.DragShadowBuilder. El campo se establece en null. Debes extender View.DragShadowBuilder y anular sus métodos. De lo contrario, obtendrás una sombra de arrastre invisible. El sistema no arroje un error.

La clase View.DragShadowBuilder tiene dos métodos que, en conjunto, crean la sombra de arrastre:

onProvideShadowMetrics()

El sistema llama a este método inmediatamente después de que llamas a startDragAndDrop(). Usa el método para enviar las dimensiones y el punto táctil de la sombra de arrastre al sistema. El método tiene dos parámetros:

outShadowSize: Es un objeto Point. El ancho de la sombra de arrastre va en x y su altura va en y.

outShadowTouchPoint: Es un objeto Point. El punto táctil es la ubicación dentro de la sombra de arrastre que debe estar debajo del dedo del usuario durante el arrastre. Su posición X va en x y su posición Y va en y.

onDrawShadow()

Inmediatamente después de la llamada a onProvideShadowMetrics(), el sistema llama a onDrawShadow() para crear la sombra de arrastre. El método tiene un solo argumento, un objeto Canvas que el sistema construye a partir de los parámetros que proporcionas en onProvideShadowMetrics(). El método dibuja la sombra de arrastre en el Canvas proporcionado.

Para mejorar el rendimiento, mantén pequeño el tamaño de la sombra de arrastre. Para un solo elemento, es posible que quieras usar un ícono. Para una selección de varios elementos, te recomendamos que uses íconos en una pila en lugar de imágenes completas distribuidas en la pantalla.

Objetos de escucha de eventos de arrastre y métodos de devolución de llamada

Un View recibe eventos de arrastre con un objeto de escucha de eventos de arrastre que implementa View.OnDragListener o con el método de devolución de llamada onDragEvent() de la vista. Cuando el sistema llama al método o al objeto de escucha, proporciona un argumento DragEvent.

En la mayoría de los casos, es preferible usar un objeto de escucha que usar el método de devolución de llamada. Cuando se diseñan IU, por lo general, no se crean subclases de clases View, pero el uso del método de devolución de llamada te obliga a crear subclases para anular el método. En comparación, puedes implementar una clase de objeto de escucha y, luego, usarla con varios objetos View diferentes. También puedes implementarlo como una clase intercalada anónima o una expresión lambda. Para configurar el objeto de escucha de un objeto View, llama a setOnDragListener().

Como alternativa, puedes modificar la implementación predeterminada de onDragEvent() sin anular el método. Configura un objeto OnReceiveContentListener en una vista. Para obtener más detalles, consulta setOnReceiveContentListener(). Luego, el método onDragEvent() hace lo siguiente de forma predeterminada:

• Muestra true en respuesta a la llamada a startDragAndDrop().

• Llama a performReceiveContent() si los datos de la función de arrastrar y soltar se sueltan en la vista. Los datos se pasan al método como un objeto ContentInfo. El método invoca el OnReceiveContentListener.

• El resultado es verdadero si los datos de la función de arrastrar y soltar se sueltan en la vista y el objeto OnReceiveContentListener consume el contenido.

Define el OnReceiveContentListener para controlar los datos específicos de tu app. Para ofrecer retrocompatibilidad hasta el nivel de API 24, usa la versión de Jetpack de OnReceiveContentListener.

Puedes tener un objeto de escucha de eventos de arrastre y un método de devolución de llamada para un objeto View, en cuyo caso el sistema primero llama al objeto de escucha. El sistema no llama al método de devolución de llamada, a menos que el objeto de escucha muestre false.

La combinación del método onDragEvent() y View.OnDragListener es análoga a la combinación de onTouchEvent() y View.OnTouchListener que se usan con los eventos táctiles.

Término clave: En las siguientes secciones, se hace referencia al método que recibe los eventos de arrastre como el objeto de escucha del evento de arrastre. Sin embargo, puede ser una devolución de llamada onDragEvent(), un método View.OnDragListener o ambos.