Suporte ao gesto de arrastar para dentro

A seguinte seqüê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 AIR, o objeto interativo iniciador despacha um evento nativeDragComplete. Se o gesto foi originado fora do AIR, nenhum comentário é enviado.

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

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.

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:

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.