NativeDragManager  - AS3

Pacote	flash.desktop
Classe	public class NativeDragManager
Herança	NativeDragManager Object

Versões de runtime:

AIR 1.0

A classe NativeDragManager coordena as operações de arrastar e soltar. Com a API nativa de arrastar e soltar, você pode permitir que o usuário arraste os dados entre um aplicativo AIR e o sistema operacional nativo, entre dois aplicativos ou entre componentes dentro de um único aplicativo.

Podem ser transferidos os seguintes tipos de dados:

• Bitmaps
• Arquivos
• Texto
• Strings URL
• Objetos serializados
• Referências de objetos (válido apenas dentro do aplicativo originador)

Observação: todos os membros NativeDragManager são estáticos. Uma ocorrência dessa classe não precisa ser criada.

Uma operação de arrastar e soltar é um gesto da interface do usuário que inicia com o usuário clicando em um item visível e o arrastando para algum lugar. Durante o gesto de arrastar, os objetos interativos na lista de exibição despacham os eventos de arrastar nativos conforme o gesto se move pela janela do aplicativo AIR. Os manipuladores desses eventos podem chamar os métodos da classe NativeDragManager para indicar se um item arrastado pode ser solto em um objeto. Em resposta, o NativeDragManager altera o ponteiro do mouse para fornecer feedback ao usuário.

Suporte a perfil do AIR: não há suporte para este recurso em dispositivos AIR for TV. Além disso, não há suporte em nenhum dispositivo móvel. Você pode testar o suporte em tempo de execução usando a propriedade NativeDragManager.isSupported. Consulte Suporte a perfil do AIR para obter mais informações sobre o suporte de API através de múltiplos perfis.

Ações de arrastar

Os gestos de arrastar e soltar são, geralmente, usados para três tipos de operações, chamadas ações. Uma vez que o significado dessas ações depende do contexto do aplicativo, o tempo de execução não impõe nenhum comportamento em particular em relação às ações. No entanto, implementar devidamente as ações aperfeiçoa a experiência do usuário com o aplicativo.

As ações possíveis são:

• Copiar – Deverá ser feita uma cópia dos dados, deixando o original intocado. (Ao arrastar objetos dentro de um aplicativo, deve-se tomar cuidado para copiar o próprio objeto original em vez de fazer referência a esse objeto.)
• Mover – Os dados são movidos de seu contexto original para o contexto definido pelo destino da ação de soltar, como ao mover um item de uma lista para outra.
• Vincular – É criada uma referência ou atalho para os dados originais, deixando o item dentro de seu contexto original.

As ações permitidas podem ser definidas para um gesto de arrastar fornecendo um parâmetro allowedActions na chamada NativeDragManager.doDrag() que inicia a operação de arrastar. Se nenhum parâmetro allowedActions for fornecido, todas as ações serão permitidas. Os destinos em potencial da ação de arrastar podem verificar que ações são permitidas usando a propriedade allowedActions de um objeto NativeDragEvent e não deverão aceitar uma ação de soltar que só permita ações incompatíveis (porém, isso não é imposto pelo tempo de execução).

Se o destino da ação de soltar só implementa uma única ação, o objeto pode definir a propriedade dropAction do NativeDragManager nos manipuladores para os eventos nativeDragEnter e nativeDragOver. O ajuste da propriedade antes da ação de soltar permite que o gerenciador dessa ação atualize o ponteiro do mouse para indicar a ação suportada e também impeça que o usuário escolha uma ação incompatível usando as teclas do modificador. Se a ação especificada não for uma das ações permitidas, então a ação de soltar não é permitida, mesmo que o destino chame o método acceptDrop().

Ao aceitar uma ação de soltar, um destino em potencial da ação de soltar deve especificar a ação escolhida definindo a propriedade NativeDragManager.dropAction em resposta ao evento nativeDragDrop. Essa ação é reportada de volta ao objeto de exibição iniciante no evento nativeDragComplete. Se nenhuma ação for definida por um destino da ação de soltar, então, é escolhida uma ação padrão entre as ações permitidas nessa ordem de precedência: copiar, mover, vincular. O objeto iniciante é responsável pela atualização de seu estado interno em reposta à ação escolhida.

As constantes das strings para os nomes de ações são definidas na classe NativeDragActions.

Sequência dos eventos

O gesto de arrastar é iniciado chamando o método NativeDragManager.doDrag() em um manipulador de eventos mouseDown ou mouseMove e continua com a sequência de eventos seguinte em resposta às ações do usuários:

• Evento nativeDragStart – Quando se chama NativeDragManager.doDrag(), o objeto interativo passado como parâmetro para o método se torna o objeto iniciador e despacha um evento nativeDragStart.
• Evento nativeDragUpdate – Quando a ação de arrastar estiver em andamento, o objeto iniciador despacha continuamente os eventos nativeDragUpdate.
• Eventos nativeDragEnter, nativeDragOver – Quando um gesto de arrastar passa sobre um objeto interativo, esse objeto despacha um evento nativeDragEnter. Enquanto o gesto de arrastar permanecer sobre o objeto interativo, ele despachará continuamente os eventos nativeDragOver. Em resposta a qualquer um desses eventos, um objeto que sirva como destino em potencial da ação de soltar deverá verificar as propriedades do objeto de evento para decidir se ele pode aceitar a ação de soltar. Se o formato dos dados e as ações permitidas forem apropriadas, então, o manipulador de eventos para esses eventos deverá chamar NativeDragManager.acceptDrop(), passando uma referência ao objeto de exibição que serve como destino da ação de arrastar (geralmente, o objeto que despachou o evento nativeDragEnter ou nativeDragOver). O usuário então poderá soltar o item arrastado no destino.
• Evento nativeDragExit – Quando um gesto de arrastar passa por fora de um objeto interativo, o objeto despacha um evento nativeDragExit. Se o objeto tiver sido designado como o destino da ação de arrastar por uma chamada anterior do método NativeDragManager.acceptDrop(), essa chamada não será mais válida e acceptDrop() deverá ser chamado novamente se o gesto reinformar o objeto interativo.
• Evento nativeDragDrop – O objeto de exibição de destino despacha um evento nativeDragDrop quando o usuário libera o botão do mouse sobre o objeto. O manipulador para esse evento pode acessar os dados na propriedade transferable do objeto do evento e deverá definir a propriedade NativeDragManager.dropAction para sinalizar que ação deverá ser tomada pelo objeto iniciador.
• nativeDragComplete – Quando o usuário libera o mouse no final de um gesto de arrastar, o objeto iniciador despacha um evento nativeDragComplete (se a ação de soltar propriamente dita foi ou não consumada). O manipulador desse evento pode verificar a propriedade dropAction do objeto do evento para determinar que modificação, caso haja alguma, deverá ser feita no estado dos dados internos, tais como remoção de um item arrastado para fora de uma lista. Se dropAction for NativeDragActions.NONE, então o item arrastado não foi solto em um destino elegível.

Gestos entre aplicativos

Quando um gesto de arrastar informar uma janela de um aplicativo AIR a partir de um aplicativo que não seja o AIR, não haverá um objeto iniciador para despachar os eventos nativeDragStart ou nativeDragComplete. Diferentemente, os eventos despachados durante o gesto seguirão o mesmo padrão de um gesto que inicia e termina dentro do mesmo aplicativo AIR.

Quando um gesto de arrastar deixar uma janela de um aplicativo AIR, não haverá um objeto de destino para despachar os eventos nativeDragEnter, nativeDragOver ou nativeDragDrop. O objeto iniciador ainda assim despacha um evento nativeDragComplete, o qual reporta a ação de arrastar definida pelo sistema operacional nativo (ou none, se a ação de soltar não foi aceita).

Quando um gesto de arrastar se move de um aplicativo AIR para outro, os objetos iniciador e de exibição de destino despacham eventos dentro de seus aplicativos separados, como de costume.

Transferindo informações

Os dados transferidos durante um gesto de arrastar e soltar está contido em um objeto Clipboard. Esse objeto de dados é adicionado à operação de arrastar com o método NativeDragManager.doDrag() que inicia o gesto de arrastar. Os destinos em potencial da ação de soltar podem acessar o objeto Clipboard por meio da propriedade clipboard do objeto de evento da ação de arrastar nativa. Uma vez iniciada uma operação de arrastar, o objeto Clipboard só poderá ser acessado no manipulador de eventos de um NativeDragEvent. Qualquer outra tentativa de acessar o objeto gera um erro de tempo de execução.

Considerações sobre segurança

As caixas de proteção de segurança dos objetos iniciador e de destino em potencial determinam como os dados que estão sendo arrastados podem ser acessados. Se ambos os objetos estiverem na mesma caixa de proteção, então, os dados poderão ser acessados de qualquer objeto NativeDragEvent. No entanto, se os objetos iniciador e de destino estiverem em caixas de proteção diferentes, os dados só poderão ser acessados na caixa de proteção de destino dentro do manipulador de eventos para o evento nativeDragDrop. Outros manipuladores nativos de eventos da ação de arrastar ainda poderão acessar o objeto Clipboard referenciado na propriedade clipboard do evento para determinar que formatos de dados estão disponíveis, mas chamar o método clipboard.getData() gera um erro de segurança.

Elementos da API relacionados

---