Principais conceitos

Testar o Compose

O Jetpack Compose é o kit de ferramentas de interface recomendado para Android. Aprenda a usar o recurso de arrastar e soltar no Compose.

Arrastar e soltar →

As seções a seguir explicam alguns conceitos importantes para o processo de arrastar e soltar.

Processo de arrastar e soltar

Existem quatro etapas ou estados no processo de arrastar e soltar: iniciado, em andamento, descartado e encerrado.

Iniciado

Em resposta ao gesto de arrastar de um usuário, o app chama startDragAndDrop() para instruir o sistema a iniciar uma operação de arrastar e soltar. Os argumentos do método fornecem o seguinte:

• Os dados a serem arrastados.
• Um callback para mostrar a ação de arrastar
• Metadados que descrevem os dados arrastados
• O sistema responde chamando o aplicativo para extrair uma ação de arrastar. Em seguida, o sistema mostra a ação de arrastar no dispositivo.
• Em seguida, o sistema envia um evento de arrastar com o tipo de ação ACTION_DRAG_STARTED para o listener de eventos de arrastar de todos os objetos View no layout atual. Para continuar recebendo eventos de arrastar, incluindo um possível evento de soltar, o listener de eventos de arrastar precisa retornar true. Isso registra o listener com o sistema. Somente listeners registrados continuam a receber eventos de arrastar. Neste ponto, os listeners também podem mudar a aparência do objeto View do destino de soltar para mostrar que a visualização pode aceitar um evento de soltar.
• Se o listener de evento de arrastar retornar false, ele não vai receber eventos de arrastar para a operação atual até que o sistema envie um evento de arrastar com o tipo de ação ACTION_DRAG_ENDED. Ao retornar false, o listener informa ao sistema que ele não tem interesse na operação de arrastar e soltar e não quer aceitar os dados arrastados.

Observação: um valor de retorno false de um View.OnDragListener aciona o gerenciador onDragEvent() da visualização.

Em andamento

O usuário continua a arrastar. Conforme a sombra de arrastar cruza a caixa delimitadora de um destino de soltar, o sistema envia um ou mais eventos de arrastar ao listener de eventos de arrastar do destino. O listener pode mudar a aparência do destino de soltar View em resposta ao evento. Por exemplo, se o evento indicar que a sombra de arrastar entrou na caixa delimitadora do destino de soltar (tipo de ação ACTION_DRAG_ENTERED), o listener pode reagir destacando a View.

Solto

O usuário solta a sombra de arraste dentro da caixa delimitadora de um destino de soltar. O sistema envia ao listener do destino de soltar um evento de arrastar com o tipo de ação ACTION_DROP. O objeto de evento de arrastar contém os dados que são transmitidos ao sistema na chamada para startDragAndDrop() que inicia a operação. Espera-se que o listener retorne o valor booleano true ao sistema se o processamento dos dados descartados for concluído pelo listener. Essa etapa só ocorre se o usuário soltar a sombra de arraste dentro da caixa delimitadora de uma View cujo listener está registrado para receber eventos de arrastar (um destino de soltar). Se o usuário soltar a sombra de arrastar em qualquer outra situação, nenhum evento de arrastar ACTION_DROP será enviado.

Encerrado

Depois que o usuário solta a sombra de arrastar e após o sistema enviar

um evento de arrastar com o tipo de ação ACTION_DROP, se necessário, o sistema envia um evento de arrastar com o tipo de ação ACTION_DRAG_ENDED para indicar que a operação de arrastar e soltar acabou. Isso é feito independente de onde o usuário solta a sombra de arraste. O evento é enviado a todos os listeners registrados para receber eventos de arrastar, mesmo que o listener também receba o evento ACTION_DROP.

Cada uma dessas etapas é descrita em mais detalhes na seção Uma operação de arrastar e soltar.

Observação: se os apps estiverem sendo executados no modo de várias janelas, os usuários poderão arrastar dados de um app para outro. Para mais informações, consulte Arrastar e soltar em Suporte ao modo de várias janelas.

Eventos de arrastar

O sistema envia um evento de arrastar na forma de um objeto DragEvent, que contém um tipo de ação que descreve o que está acontecendo no processo de arrastar e soltar. Dependendo do tipo de ação, o objeto também pode conter outros dados.

Os listeners de eventos de arrastar recebem o objeto DragEvent. Para ver o tipo de ação, os listeners chamam DragEvent.getAction(). Há seis valores possíveis, definidos por constantes na classe DragEvent, que são descritos na tabela 1:

Tabela 1. Tipos de ação de DragEvent.

Tipo de ação	Significado
ACTION_DRAG_STARTED	O aplicativo chama startDragAndDrop() e recebe uma ação de arrastar. Se o listener quiser continuar recebendo eventos de arrastar para a operação, ele precisa retornar o valor booleano true ao sistema.
ACTION_DRAG_ENTERED	A sombra de arrastar entra na caixa delimitadora da View do listener de eventos de arrastar. Esse é o primeiro tipo de ação de evento que o listener recebe quando a sombra de arraste entra na caixa delimitadora.
ACTION_DRAG_LOCATION	Depois de um evento ACTION_DRAG_ENTERED, a ação de arrastar ainda está dentro da caixa delimitadora da View do listener de eventos de arrastar.
ACTION_DRAG_EXITED	Após um evento ACTION_DRAG_ENTERED e pelo menos um ACTION_DRAG_LOCATION, a sombra de arrastar é movida para fora da caixa delimitadora da View do listener de eventos de arrastar.
ACTION_DROP	A sombra de arrastar é solta na View do listener de eventos de arrastar. Esse tipo de ação é enviado ao listener de um objeto View somente se o listener retornar o valor booleano true em resposta ao evento de arrastar ACTION_DRAG_STARTED. Esse tipo de ação não é enviado se o usuário soltar a sombra de arraste em uma View cujo listener não está registrado ou se o usuário soltar a sombra de arraste em algo que não faz parte do layout atual. O listener retorna o valor booleano true se processar o ato de soltar. Caso contrário, ele precisa retornar false.
ACTION_DRAG_ENDED	O sistema está finalizando a operação de arrastar e soltar. Esse tipo de ação não é necessariamente precedido por um evento ACTION_DROP. Se o sistema enviar um ACTION_DROP, o recebimento do tipo de ação ACTION_DRAG_ENDED não implica que a operação de soltar foi concluída. O listener precisa chamar getResult(), conforme mostrado na tabela 2, para receber o valor retornado em resposta a ACTION_DROP. Se um evento ACTION_DROP não for enviado, getResult() vai retornar false.

O objeto DragEvent também contém os dados e metadados que o aplicativo fornece ao sistema na chamada para startDragAndDrop(). Alguns dados são válidos apenas para determinados tipos de ação, conforme resumido na tabela 2. Para mais informações sobre eventos e os dados associados, consulte a seção Uma operação de arrastar e soltar.

Tabela 2. Dados válidos de DragEvent por tipo de ação

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		✓				✓

Os métodos DragEvent getAction(), describeContents(), writeToParcel() e toString() sempre retornam dados válidos.

Se um método não contiver dados válidos para um tipo de ação específico, ele retornará null ou 0, dependendo do tipo de resultado.

Ação de arrastar

Durante uma operação de arrastar e soltar, o sistema exibe uma imagem que o usuário arrasta. Para o movimento de dados, essa imagem representa os dados sendo arrastados. Para outras operações, a imagem representa algum aspecto da operação de arrastar.

A imagem é chamada de ação de arrastar. Você pode a criar usando os métodos que declara para um objeto View.DragShadowBuilder. Você transmite o builder ao sistema quando inicia uma operação de arrastar e soltar usando startDragAndDrop(). Como parte da resposta a startDragAndDrop(), o sistema invoca os métodos de callback que você define em View.DragShadowBuilder para ter uma sombra de arrasto.

A classe View.DragShadowBuilder tem dois construtores:

View.DragShadowBuilder(View)

Esse construtor aceita todos os objetos View do aplicativo. O construtor armazena o objeto View no objeto View.DragShadowBuilder para que os callbacks possam o acessar a fim de construir a ação de arrastar. A visualização não precisa ser uma View selecionada pelo usuário para iniciar a operação de arrastar.

Se você usar esse construtor, não vai precisa estender o View.DragShadowBuilder nem substituir os métodos dele. Por padrão, você recebe uma sombra da ação de arrastar com a mesma aparência da View transmitida como argumento, centralizada no local em que o usuário toca na tela.

View.DragShadowBuilder()

Se você usar esse construtor, nenhum objeto View estará disponível no objeto View.DragShadowBuilder. O campo está definido como null. Estenda View.DragShadowBuilder e substitua os métodos. Caso contrário, você vai ter uma ação de arrastar invisível. O sistema não gera um erro.

A classe View.DragShadowBuilder tem dois métodos que, juntos, criam a ação de arrastar:

onProvideShadowMetrics()

O sistema chama esse método imediatamente após startDragAndDrop() ser chamado. Use o método para enviar as dimensões e o ponto de contato da ação de arrastar ao sistema. O método tem dois parâmetros:

outShadowSize:um objeto Point. A largura da sombra de arraste aparece em x e a altura em y.

outShadowTouchPoint:um objeto Point. O ponto de toque é a área dentro da sombra de arraste que precisa estar sob o dedo do usuário durante a ação de arrastar. A posição X vai para x, e a posição Y vai para y.

onDrawShadow()

Imediatamente após a chamada do método onProvideShadowMetrics(), o sistema chama onDrawShadow() para criar a ação de arrastar. O método tem um único argumento, um objeto Canvas que o sistema cria a partir dos parâmetros fornecidos em onProvideShadowMetrics(). O método exibe a ação de arrastar na Canvas fornecida.

Para melhorar a performance, use um tamanho pequeno para a ação de arrastar. Para um único item, recomendamos usar um ícone. Para uma seleção de vários itens, recomendamos usar ícones em uma pilha em vez de imagens completas espalhadas pela tela.

Listeners de eventos de arrastar e métodos de callback

Uma View recebe eventos de arrastar com um listener de eventos de arrastar que implementa View.OnDragListener ou com o método de callback onDragEvent() da visualização. Quando o sistema chama o método ou listener, ele fornece um argumento DragEvent.

Na maioria dos casos, é preferível usar um listener que um método de callback. Ao projetar IUs, você normalmente não cria subclasses de View, mas usar o método de callback força a criação de subclasses para substituir o método. Por comparação, você pode implementar uma classe de listener e a usar com vários objetos View diferentes. Também é possível a implementar como uma classe in-line anônima ou uma expressão lambda. Para definir o listener de um objeto View, chame setOnDragListener().

Como alternativa, é possível alterar a implementação padrão de onDragEvent() sem substituir o método. Defina um OnReceiveContentListener em uma visualização. Para mais detalhes, consulte setOnReceiveContentListener(). O método onDragEvent() faz o seguinte por padrão:

• Retorna verdadeiro em resposta à chamada para startDragAndDrop().

• Chama performReceiveContent() se os dados de arrastar e soltar forem soltos na visualização. Os dados são transmitidos para o método como um objeto ContentInfo. O método invoca o OnReceiveContentListener.

• Retorna verdadeiro se os dados de arrastar e soltar forem soltos na visualização e o OnReceiveContentListener consumir qualquer conteúdo.

Defina o OnReceiveContentListener para processar os dados específicos do app. Se quiser oferecer compatibilidade com versões anteriores até a API nível 24, use a versão do OnReceiveContentListener do Jetpack.

Você pode ter um listener de eventos de arrastar e um método de callback para um objeto View. Nesse caso, o sistema chama o listener primeiro. O sistema não chama o método de callback, a menos que o listener retorne false.

A combinação dos métodos onDragEvent() e View.OnDragListener é análoga à combinação de onTouchEvent() e View.OnTouchListener usados com eventos de toque.

Termo-chave: as seções a seguir se referem ao método que recebe eventos de arrastar como o listener de eventos de arrastar. No entanto, o método pode ser um callback onDragEvent(), um método View.OnDragListener ou ambos.