Suporte ao gesto de arrastar para dentro

Adobe AIR 1.0 e posterior

Para suportar o gesto de arrastar para dentro, seu aplicativo (ou, mais tipicamente, um componente visual do seu aplicativo) deve responder aos eventos nativeDragEnter ou nativeDragOver .

Etapas em uma operação típica de arrastar

A seguinte sequência de eventos é típica para uma operação de arrastar:

  1. O usuário arrasta um objeto da área de transferência sobre um componente.

  2. O componente despacha um evento nativeDragEnter .

  3. O manipulador de eventos nativeDragEnter examina o objeto de evento para verificar os formatos de dados disponíveis e as ações permitidas. Se o componente pode manipular a ação de soltar, ele chama NativeDragManager.acceptDragDrop() .

  4. O NativeDragManager altera o cursor do mouse para indicar que o objeto pode ser solto.

  5. O usuário solta o objeto sobre o componente.

  6. O componente receptor despacha um evento nativeDragDrop .

  7. O componente receptor lê os dados no formato desejado do objeto Clipboard dentro do objeto de evento.

  8. Se o gesto de arrastar foi originado no aplicativo do AIR, o objeto interativo iniciador despacha um evento nativeDragComplete . Se o gesto foi originado fora do AIR, nenhum comentário é enviado.

Reconhecimento de um gesto de arrastar para dentro

Quando um usuário arrasta um item da área de transferência para dentro dos limites de um componente visual, o componente despacha eventos nativeDragEnter e nativeDragOver . Para determinar se o componente pode aceitar o item da área de transferência, os manipuladores para esses eventos pode verificar as propriedades clipboard e allowedActions do objeto de evento. Para sinalizar que o componente pode aceitar a ação de soltar, o manipulador de eventos deve chamar o método NativeDragManager.acceptDragDrop() , transmitindo uma referência ao componente receptor. Se mais de um ouvinte de evento registrado chamar o método acceptDragDrop() , o último manipulador da lista tem precedência. A chamada acceptDragDrop() permanece válida até que o mouse deixe os limites do objeto recebedor, disparando o evento nativeDragExit .

Se mais de uma ação for permitida no parâmetro allowedActions transmitido a doDrag() , o usuário pode indicar qual das ações permitidas pretende mantendo pressionada uma tecla de modificador. O gerente de arrastar altera a imagem do cursor para dizer ao usuário que ação ocorreria se ele concluísse a ação de soltar. A ação pretendida é reportado pela propriedade dropAction do evento NativeDragEvent. O conjunto de ação para um gesto de arrastar é apenas consultivo. Os componentes envolvidos na transferência devem implementar o comportamento apropriado. Para completar uma ação de mover, por exemplo, o iniciador de arrastar poderia remover o item arrastado e o destino de soltar poderia adicioná-lo.

Seu destino de arrastar pode limitar a ação de soltar para uma das três ações possíveis definindo a propriedade dropAction da classe NativeDragManager. Se um usuário tenta escolher uma ação diferente usando o teclado, NativeDragManager exibe o cursor unavailable . Define a propriedade dropAction nos manipuladores para os eventos nativeDragEnter e nativeDragOver .

O exemplo a seguir ilustra um manipulador de eventos para um evento nativeDragEnter ou nativeDragOver . Esse manipulador aceita apenas um gesto de arrastar para dentro se a área de transferência sendo arrastada contiver dados em formato de texto.

import flash.desktop.NativeDragManager; 
import flash.events.NativeDragEvent; 
 
public function onDragIn(event:NativeDragEvent):void{ 
    NativeDragManager.dropAction = NativeDragActions.MOVE; 
    if(event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ 
        NativeDragManager.acceptDragDrop(this); //'this' is the receiving component 
    } 
}

Conclusão da ação de soltar

Quando o usuário solta um item arrastado em um objeto interativo que aceitou o gesto, o objeto interativo despacha um evento nativeDragDrop . O manipulador desse evento pode extrair os dados a propriedade clipboard do objeto de evento.

Quando a área de transferência contém um formato definido por aplicativo, o parâmetro transferMode transmitido ao método getData() do objeto Clipboard determina se o gerenciador de arrastar retorna uma referência ou uma versão serializada do objeto.

O exemplo a seguir ilustra um manipulador de eventos para o evento nativeDragDrop :

import flash.desktop.Clipboard; 
import flash.events.NativeDragEvent; 
 
public function onDrop(event:NativeDragEvent):void { 
    if (event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)) { 
    var text:String = 
        String(event.clipboard.getData(ClipboardFormats.TEXT_FORMAT,  
                                    ClipboardTransferMode.ORIGINAL_PREFERRED)); 
}

Depois que o manipulador de eventos for encerrado, o objeto Clipboard não será mais válido. Qualquer tentativa de acessar o objeto ou seus dados gera um erro.

Atualização da aparência visual de um componente

Um componente pode atualizar sua aparência visual com base nos eventos NativeDragEvent. A tabela a seguir descreve os tipos de alterações que um componente típico faria em resposta aos diferentes eventos:

Evento

Descrição

nativeDragStart

O objeto interativo iniciante pode usar o evento nativeDragStart para fornecer comentários visuais que o gesto de arrastar originou desse objeto interativo.

nativeDragUpdate

O objeto interativo iniciante pode usar o evento nativeDragUpdate para atualizar seu estado durante o gesto. (Este evento não existe no AIR for Linux.)

nativeDragEnter

Um possível objeto interativo receptor pode usar esse evento para assumir o foco ou indicar visualmente que ele pode ou não aceitar a ação de soltar.

nativeDragOver

Um possível objeto interativo receptor pode usar esse evento para responder ao movimento do mouse dentro do objeto interativo, como quando o mouse insere uma região “ativa” de um componente complexo, como uma exibição de mapa de rua.

nativeDragExit

Um possível objeto interativo receptor pode usar esse evento para restaurar seu estado quando um gesto de arrastar se move para fora de seus limites.

nativeDragComplete

O objeto interativo iniciante pode usar esse evento para atualizar seu modelo de dados associado, como removendo um item de uma lista e para restaurar seu estado visual.

Rastreamento da posição do mouse durante um gesto de arrastar para dentro

Enquanto um gesto de arrastar permanece sobre um componente, esse componente despacha eventos nativeDragOver . Esses eventos são despachados a cada poucos milissegundos e também sempre que o mouse se move. O objeto de evento nativeDragOver pode ser usado para determinar a posição do mouse sobre o componente. Ter acesso à posição do mouse pode ser útil em situações onde o componente receptor é complexo, mas não é formado de subcomponentes. Por exemplo, se seu aplicativo exibiu um bitmap contendo um mapa de rua e você desejava realçar zonas no mapa quando o usuário arrastasse informações a eles, você poderia usar as coordenadas do mouse reportadas no evento nativeDragOver para rastrear a posição do mouse no mapa.