NativeDragManager  - AS3

Pacchetto	flash.desktop
Classe	public class NativeDragManager
Ereditarietà	NativeDragManager Object

Versioni runtime:

AIR 1.0

La classe NativeDragManager coordina le operazioni di trascinamento e rilascio. Con l'API di trascinamento e rilascio nativa, potete consentire agli utenti di trasferire dati da un'applicazione AIR al sistema operativo nativo e vice versa, tra due applicazioni o da un componente all'altro di una stessa applicazione.

Potete trasferire i seguenti tipi di dati:

• Bitmap
• File
• Testo
• Stringhe URL
• Oggetti serializzati
• I riferimenti agli oggetti (validi solo all'interno dell'applicazione di origine)

Nota: tutti i membri di NativeDragManager sono statici. Non è necessario creare un'istanza di questa classe.

Un'operazione di trascinamento e rilascio è una manovra eseguibile dall'interfaccia utente in cui l'utente fa clic su un oggetto visibile e lo trascina in un'altra posizione. Durante il trascinamento, gli oggetti interattivi nell'elenco di visualizzazione inviano eventi di trascinamento nativi a mano a mano che la manovra viene eseguita nella finestra dell'applicazione AIR. I gestori di questi eventi possono chiamare i metodi della classe NativeDragManager per indicare se un elemento trascinato può essere rilasciato su un oggetto. In risposta, NativeDragManager modifica il puntatore del mouse per fornire un feedback all'utente.

Supporto profili AIR: questa funzione non è supportata nei dispositivi AIR per TV. Inoltre, non è supportata in tutti i dispositivi mobili. È possibile verificare se la funzionalità è supportata in fase runtime utilizzando la proprietà NativeDragManager.isSupported. Per ulteriori informazioni sul supporto delle API tra più profili, vedete Supporto dei profili AIR.

Azioni di trascinamento

Le manovre di trascinamento e rilascio vengono generalmente utilizzate per eseguire tre diversi tipi di operazioni, chiamate azioni. Poiché il significato di queste azioni dipende dal contesto dell'applicazione, durante l'esecuzione del runtime non viene applicato alcun comportamento specifico in relazione a tali azioni. Tuttavia, un'implementazione accurata di queste azioni migliora l'esperienza dell'utente con l'applicazione.

Le azioni possibili sono:

• Copy: viene eseguita una copia dei dati lasciando l'originale invariato. Se si trascinano oggetti all'interno di una stessa applicazione, è necessario fare attenzione a copiare l'oggetto originale e non un suo riferimento.
• Move: i dati vengono spostati dal contesto originale al contesto definito dal target di rilascio, come, ad esempio, quando si sposta un oggetto da un elenco a un altro.
• Link: viene creato un riferimento o un collegamento rapido ai dati originali, senza spostare l'oggetto dal contesto originale.

Per impostare le azioni consentite per una manovra di trascinamento, indicate un parametro allowedActions nella chiamata NativeDragManager.doDrag() che dà inizio all'operazione di trascinamento. Se non viene fornito alcun parametro allowedActions, tutte le azioni saranno consentite. I potenziali target di trascinamento possono verificare quali azioni sono consentite utilizzando la proprietà allowedActions di un oggetto NativeDragEvent, in modo da non accettare rilasci che permettano solo azioni incompatibili (che non vengono tuttavia applicate all'esecuzione del runtime).

Se un target di rilascio implementa solo una singola azione, l'oggetto può impostare la proprietà dropAction di NativeDragManager nei gestori di entrambi gli eventi nativeDragEnter e nativeDragOver. L'impostazione della proprietà prima del rilascio consente al gestore di trascinamento di aggiornare il puntatore del mouse per indicare l'azione supportata e impedire all'utente di scegliere un'azione non compatibile utilizzando i tasti di modifica. Se l'azione specificata non è una delle azioni consentite, il rilascio non è permesso anche se il target chiama il metodo acceptDrop().

In fase di accettazione di un rilascio, il potenziale target di rilascio deve specificare l'azione scelta impostando la proprietà NativeDragManager.dropAction in risposta all'evento nativeDragDrop. Tale azione viene risegnalata all'oggetto di visualizzazione da cui è partita l'operazione, nell'evento nativeDragComplete. Se un target di rilascio non definisce alcuna azione, viene scelta un'azione predefinita tra le azioni consentite, nel seguente ordine di precedenza: copy, move, link. L'oggetto da cui è partita l'operazione è responsabile dell'aggiornamento del suo stato interno in risposta all'azione selezionata.

Le costanti di stringa relative ai nomi delle azioni sono definite nella classe NativeDragActions.

Sequenza di eventi

Una manovra di trascinamento viene avviata mediante una chiamata al metodo NativeDragManager.doDrag() nell'ambito di un gestore di eventi mouseDown o mouseMove e procede attraverso la sequenza di eventi seguente, in risposta alle azioni dell'utente:

• Evento nativeDragStart: quando viene chiamato NativeDragManager.doDrag(), l'oggetto interattivo passato al metodo come parametro diventa l'oggetto iniziatore e invia un evento nativeDragStart.
• Evento nativeDragUpdate: durante il trascinamento, l'oggetto iniziatore continua a inviare eventi nativeDragUpdate.
• Eventi nativeDragEnter, nativeDragOver: quando una manovra di trascinamento passa sopra un oggetto interattivo, tale oggetto invia un evento nativeDragEnter. Quando la manovra di trascinamento si trova sopra l'oggetto interattivo, esso continua a inviare eventi nativeDragOver. In risposta a uno di questi eventi, un oggetto che funge da potenziale target di rilascio deve verificare le proprietà dell'oggetto evento e decidere se può accettare il rilascio. Se il formato dei dati e le azioni consentite sono appropriati, il gestore di questi eventi deve chiamare NativeDragManager.acceptDrop(), passando un riferimento all'oggetto di visualizzazione che funge da target di trascinamento (in genere, l'oggetto che ha inviato l'eventonativeDragEnter o nativeDragOver). A questo punto, l'utente può rilasciare l'oggetto trascinato sul target.
• Evento nativeDragExit: quando una manovra di trascinamento passa al di fuori di un oggetto interattivo, l'oggetto invia un evento nativeDragExit. Se l'oggetto è stato designato come target di trascinamento da una precedente chiamata al metodo NativeDragManager.acceptDrop(), tale chiamata non è più considerata valida e acceptDrop() deve essere richiamato se la manovra immette di nuovo l'oggetto interattivo.
• Evento nativeDragDrop: l'oggetto di visualizzazione target invia un evento nativeDragDrop quando l'utente rilascia il pulsante del mouse sopra l'oggetto. Il gestore di questo evento può accedere ai dati contenuti nella proprietà transferable dell'oggetto evento e deve impostare la proprietà NativeDragManager.dropAction in modo che segnali quale azione deve essere intrapresa dall'oggetto iniziatore.
• Evento nativeDragComplete: quando l'utente rilascia il pulsante del mouse al termine dell'operazione di trascinamento, l'oggetto iniziatore invia un evento nativeDragComplete (a prescindere dall'esito del rilascio). Il gestore di questo evento può verificare la proprietà dropAction dell'oggetto evento per determinare quali modifiche, se necessarie, devono essere apportate allo stato interno dei suoi dati, ad esempio, rimuovere da un elenco un oggetto che è stato spostato. Se dropAction è NativeDragActions.NONE, significa che l'oggetto trascinato non è stato rilasciato su un target idoneo.

Operazioni tra applicazioni

Se durante una manovra di trascinamento accedete alla finestra di un'applicazione AIR da un'applicazione non AIR, non vi sarà alcun oggetto iniziatore che invia l'evento nativeDragStart o l'evento nativeDragComplete. Gli eventi inviati durante la manovra seguiranno per il resto lo stesso schema di quelli di una manovra avviata e terminata all'interno della stessa applicazione AIR.

Quando una manovra di trascinamento esce dalla finestra di un'applicazione AIR, nessun oggetto target invia gli eventi nativeDragEnter, nativeDragOver o nativeDragDrop. L'oggetto iniziatore invia comunque un evento nativeDragComplete, che segnala l'azione di trascinamento impostata dal sistema operativo nativo (oppure none, se il rilascio non viene accettato).

Quando una manovra di trascinamento passa da un'applicazione AIR a un'altra, gli oggetti di visualizzazione iniziatore e target inviano eventi all'interno delle relative applicazioni come di consueto.

Trasferimento di informazioni

I dati trasferiti durante un'operazione di trascinamento e rilascio sono contenuti in un oggetto Clipboard. Tale oggetto di dati viene inserito nell'operazione di trascinamento con il metodo NativeDragManager.doDrag(), che dà inizio alla manovra di trascinamento. I potenziali target di rilascio possono accedere all'oggetto Clipboard dalla proprietà clipboard dell'oggetto evento di trascinamento nativo. Dopo l'avvio di un'operazione di trascinamento, l'accesso all'oggetto Clipboard può avvenire unicamente nel gestore di un evento NativeDragEvent. Qualsiasi altro tentativo di accedere a tale oggetto genera un errore di runtime.

Considerazioni relative alla sicurezza

Le sandbox di sicurezza degli oggetti iniziatore e potenziale target determinano la modalità di accesso ai dati che vengono trascinati. Se entrambi gli oggetti si trovano nella stessa sandbox, i dati sono accessibili da un qualsiasi oggetto NativeDragEvent. Tuttavia, se gli oggetti iniziatore e target si trovano in sandbox differenti, i dati saranno accessibili unicamente nella sandbox target, all'interno del gestore di eventi dell'evento nativeDragDrop. Gli altri gestori di eventi di trascinamento nativi possono comunque accedere all'oggetto Clipboard al quale si fa riferimento nella proprietà clipboard dell'evento per determinare quali formati di dati sono disponibili; tuttavia, una chiamata al metodo clipboard.getData() genera un errore di sicurezza.

Altri esempi

Elementi API correlati

---