Conceptos clave

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

Proceso de arrastrar y soltar

El proceso de arrastrar y soltar tiene cuatro pasos o estados: iniciado, continuando, descartada y finalizada.

Iniciado

En respuesta al gesto de arrastre de un usuario, tu aplicación llama startDragAndDrop() para indicar al sistema que inicie una operación de arrastrar y soltar El 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 volviendo a llamar a tu aplicación para arrastrarla sombra. 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 hasta el evento de arrastre objeto de escucha de todos los objetos View del diseño actual. Para seguirán recibiendo eventos de arrastre, incluida una posible evento: el objeto de escucha de eventos de arrastre debe mostrar true. Esto registra el objeto de escucha con el sistema. Solo los objetos de escucha registrados continúan recibir eventos de arrastre. En este punto, los objetos de escucha también pueden cambiar aspecto del objeto View del destino para soltar para mostrar que la vista puede aceptar un evento de soltar.
• Si el objeto de escucha de eventos de arrastre muestra false, no recibe el elemento 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. Cuando muestra false, el objeto de escucha le indica al sistema que no está interesado. en la operación de arrastrar y soltar y no quiere aceptar los datos arrastrados.

Continuando

El usuario continúa con el arrastre. Como la sombra de arrastre se cruza con la cuadro delimitador de un destino para soltar, el sistema envía uno o más eventos de arrastre a el objeto de escucha de eventos de arrastre del objetivo. El oyente puede alterar la apariencia de el destino para soltar View en respuesta al evento Por ejemplo, si el evento indica que la sombra de arrastre ingresa al cuadro delimitador de la acción de soltar objetivo: 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 delimitador de una acción de soltar objetivo. El sistema envía al objeto de escucha del destino para soltar un evento de arrastre con acción. escribe 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. El oyente es Se espera que muestre un valor booleano true al sistema si el objeto de escucha se ejecuta correctamente. procesa los datos descartados. : Este paso solo se produce si el usuario suelta la sombra de arrastre dentro del cuadro de límite de un objeto View cuyo objeto de escucha está registrado para recibir eventos de arrastre (un objetivo de soltar). Si el usuario suelta la sombra de arrastre en cualquier otro no se envía ningún evento de arrastre ACTION_DROP.

Finalizado

Después de que el usuario suelta la sombra de arrastre y después de que el sistema envía

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 el elemento la operación de arrastrar y soltar. Esto se hace independientemente del lugar donde el usuario libera la sombra de arrastre. El evento se envía a todos los objetos de escucha para recibir eventos de arrastre, incluso si el objeto de escucha también recibe el elemento ACTION_DROP evento.

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

Eventos de arrastre

El sistema envía un evento de arrastre en forma de un objeto DragEvent, que contiene un tipo de acción que describe lo que sucede al momento de arrastrar y soltar el proceso de administración de recursos. 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 quiere seguir recibiendo eventos de arrastre para esta operación, debe mostrar un valor booleano true al en un sistema de archivos.
ACTION_DRAG_ENTERED	La sombra de arrastre ingresa al cuadro delimitador del objeto de escucha de eventos de arrastre View Este es el primer tipo de acción de evento que el objeto de escucha recibe cuando la sombra de arrastre ingresa en el cuadro delimitador.
ACTION_DRAG_LOCATION	Luego de un ACTION_DRAG_ENTERED, la sombra de arrastre permanece dentro del cuadro delimitador del objeto de escucha de eventos de arrastre View
ACTION_DRAG_EXITED	Después de una ACTION_DRAG_ENTERED y, al menos, una ACTION_DRAG_LOCATION, la sombra de arrastre se mueve fuera del cuadro delimitador del objeto de escucha de eventos de arrastre View
ACTION_DROP	La sombra de arrastre se suelta sobre el objeto de escucha de eventos de arrastre View Este tipo de acción se envía a un View el objeto de escucha del objeto solo si este devuelve un valor booleano true en respuesta al ACTION_DRAG_STARTED evento de arrastre. Este tipo de acción no es que se envía si el usuario suelta la sombra de arrastre sobre un elemento View cuyo objeto de escucha no está registrado o si el usuario suelta el elemento sombrea sobre todo lo que no sea parte del diseño actual. El objeto de escucha muestra un valor booleano true si procesa correctamente la bajada. De lo contrario, debe mostrarse false
ACTION_DRAG_ENDED	El sistema está finalizando la operación de arrastrar y soltar. Este tipo de acción no está necesariamente precedida por un evento ACTION_DROP. Si el sistema envía un ACTION_DROP, que recibe el El tipo de acción ACTION_DRAG_ENDED no implica que el elemento se realizó correctamente. El objeto de escucha debe llamar getResult(), como se muestra en la tabla 2, para obtener el valor que que se muestra en respuesta a ACTION_DROP. Si un No se envía el evento ACTION_DROP. Luego, 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álido solo para ciertos tipos de acciones, como se resume en la tabla 2. Para ver más información sobre eventos y sus datos asociados, consulte la sección A de arrastrar y soltar.

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

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

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

Si un método no contiene datos válidos para un tipo de acción en particular, 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 llama sombra de arrastre. Se crea con métodos que declaras para pañal View.DragShadowBuilder . El compilador se pasa al sistema cuando comienzas a arrastrar y soltar con startDragAndDrop(). Como parte de su 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 View que el usuario selecciona para iniciar la operación de arrastre.

Si usas este constructor, no necesitas extender View.DragShadowBuilder ni anular sus métodos. De forma predeterminada, se muestra un arrastre que tiene la misma apariencia que la View que pasas como argumento, centrado debajo de la ubicación donde el usuario toca la pantalla.

View.DragShadowBuilder()

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

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

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: 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 de contacto 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 un objeto Canvas que que el sistema construye a partir de los parámetros que proporcionas en onProvideShadowMetrics() El método dibuja la sombra de arrastre en el espacio Canvas

Para mejorar el rendimiento, mantén pequeño el tamaño de la sombra de arrastre. Para una sola elemento, puedes usar un ícono. Para una selección de varios elementos, puedes queremos usar iconos 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 elemento 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. Cuándo el sistema llama al método o al objeto de escucha, proporciona 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 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. Establece un OnReceiveContentListener en una vista; para obtener más información, consulta setOnReceiveContentListener() Luego, el método onDragEvent() hará lo siguiente de forma predeterminada:

• El resultado es verdadero en respuesta a la llamada a startDragAndDrop().

• Llamadas performReceiveContent() si los datos de arrastrar y soltar aparecen en la vista. Los datos se pasan al como un objeto ContentInfo. El invoca el método OnReceiveContentListener.

• El resultado es verdadero si los datos de arrastrar y soltar se sueltan en la vista y el ícono OnReceiveContentListener consume todo el contenido.

Define el OnReceiveContentListener para manejar los datos específicamente para tu . Para ofrecer retrocompatibilidad hasta el nivel de API 24, usa la versión 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 en cuyo caso el sistema primero llama al receptor. El sistema no llama al a menos que el objeto de escucha muestre false.

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