NativeDragManager  - AS3

Paket	flash.desktop
Klasse	public class NativeDragManager
Vererbung	NativeDragManager Object

Laufzeitversionen:

AIR 1.0

Die NativeDragManager-Klasse koordiniert Drag-and-Drop-Vorgänge. Mit der nativen Ziehen-und-Ablegen-API können Sie es dem Benutzer ermöglichen, Daten durch Ziehen und Ablegen zwischen einer AIR-Anwendung und dem nativen Betriebssystem, zwischen zwei Anwendungen oder zwischen Komponenten einer einzelnen Anwendung zu kopieren.

Die folgenden Datentypen können übertragen werden:

• Bitmaps
• Dateien
• Text
• URL-Strings
• Serialisierte Objekte
• Objektverweise (nur gültig in der ursprünglichen Anwendung)

Hinweis: Alle NativeDragManager-Mitglieder sind statisch. Es muss keine Instanz dieser Klasse erstellt werden.

Ein Ziehen-und-Ablegen-Vorgang ist eine Bewegung auf der Benutzeroberfläche, die mit dem Klicken auf ein sichtbares Element beginnt, das dann an eine andere Position gezogen wird. Während der Ziehbewegung durch das AIR-Anwendungsfenster lösen interaktive Objekte in der Anzeigeliste native Ziehereignisse aus. Prozeduren für diese Ereignisse können Methoden der NativeDragManager-Klasse aufrufen, um anzuzeigen, ob das gezogene Element auf einem anderen Objekt abgelegt werden kann. Daraufhin ändert der NativeDragManager den Mauszeiger, sodass der Benutzer informiert wird.

AIR-Profilunterstützung: Diese Funktion wird auf Geräten mit AIR für TV nicht unterstützt. Des Weiteren wird sie nicht auf allen mobilen Geräten unterstützt. Mit der NativeDragManager.isSupported-Eigenschaft können Sie testen, ob zur Laufzeit Unterstützung gegeben ist. Weitere Informationen zum AIR-Support über mehrere Profile finden Sie unter Unterstützung von AIR-Profilen.

Ziehen-Aktionen

Ziehen-und-Ablegen-Bewegungen werden normalerweise für drei Arten von Vorgängen, Aktionen genannt, verwendet. Da die Bedeutung dieser Aktionen vom Anwendungskontext abhängig ist, wird zur Laufzeit kein bestimmtes Verhalten bezüglich der Aktionen erzwungen. Mit der richtigen Implementierung der Aktionen können Sie die Benutzerfreundlichkeit der Anwendung jedoch verbessern.

Mögliche Aktionen sind:

• Kopieren: Es wird eine Kopie der Daten erstellt. Das Original bleibt unverändert. (Beim Ziehen von Objekten innerhalb einer Anwendung sollte darauf geachtet werden, dass das Originalobjekt selbst und nicht ein Verweis auf dieses Objekt kopiert wird.)
• Verschieben: Die Daten werden aus dem ursprünglichen Kontext in den vom Drop-Ziel definierten Kontext verschoben, zum Beispiel wenn ein Element aus einer Liste in eine andere verschoben wird.
• Verknüpfen: Es wird ein Verweis auf die Originaldaten oder eine Verknüpfung damit erstellt. Das Element verbleibt dabei in seinem ursprünglichen Kontext.

Die zulässigen Aktionen können für eine Ziehbewegung festgelegt werden, indem ein allowedActions-Parameter an den NativeDragManager.doDrag()-Aufruf übergeben wird, der den Ziehvorgang startet. Wenn kein allowedActions-Parameter angegeben wird, sind alle Aktionen zulässig. Potenzielle Drop-Ziele können anhand der allowedActions-Eigenschaft eines NativeDragEvent-Objekts überprüfen, welche Aktionen zulässig sind, und sollten kein Ablegen akzeptieren, das nur inkompatible Aktionen zulässt (dies wird von der Laufzeitumgebung jedoch nicht erzwungen).

Wenn ein Ablageziel nur eine einzelne Aktion implementiert, kann das Objekt die dropAction-Eigenschaft von NativeDragManager sowohl in den Prozeduren für nativeDragEnter- als auch für nativeDragOver-Ereignisse setzen. Wird die Eigenschaft vor dem Ablegen gesetzt, kann der Ziehmanager den Mauszeiger aktualisieren, sodass die unterstützte Aktion angegeben wird und Benutzer davon abgehalten werden, mit Zusatztasten eine nicht unterstützte Aktion zu wählen. Handelt es sich bei der festgelegten Aktion nicht um eine der folgenden, so ist das Ablegen nicht erlaubt, selbst wenn das Ziel die acceptDrop()-Methode aufruft.

Wenn das Ablegen akzeptiert wird, sollte ein potenzielles Ablageziel die gewählte Aktion anzeigen, indem die NativeDragManager.dropAction-Eigenschaft als Antwort auf das nativeDragDrop-Ereignis gesetzt wird. Diese Aktion wird im nativeDragComplete-Ereignis an das auslösende Anzeigeobjekt gemeldet. Wenn von einem Ablageziel keine Aktion festgelegt wurde, wird aus der Liste der zulässigen Aktionen in der folgenden Reihenfolge eine Standardaktion gewählt: Kopieren, Verschieben, Verknüpfen. Das auslösende Objekt ist für die Aktualisierung des internen Status als Folge der gewählte Aktion zuständig.

Stringkonstanten für die Aktionsnamen sind in der NativeDragActions-Klasse definiert.

Reihenfolge der Ereignisse

Die Ziehbewegung beginnt mit dem Aufruf der NativeDragManager.doDrag()-Methode innerhalb einer mouseDown- oder mouseMove-Ereignisprozedur und wird in Reaktion auf Benutzeraktionen in der folgenden Ereignisreihenfolge fortgesetzt:

• nativeDragStart-Ereignis: Wenn NativeDragManager.doDrag() aufgerufen wird, wird das als Parameter an die Methode übergebene interaktive Objekt zum Initiatorobjekt und löst ein nativeDragStart-Ereignis aus.
• nativeDragUpdate-Ereignis: Während des Ziehens löst das Initiatorobjekt kontinuierlich nativeDragUpdate-Ereignisse aus.
• nativeDragEnter-, nativeDragOver-Ereignisse: Wenn eine Ziehbewegung über ein interaktives Objekt verläuft, löst dieses Objekt ein nativeDragEnter-Ereignis aus. Verweilt die Ziehbewegung über dem interaktiven Objekt, löst dieses kontinuierlich nativeDragOver-Ereignisse aus. Als Antwort auf jedes dieser Ereignisse sollte ein Objekt, das ein potenzielles Drop-Ziel ist, die Eigenschaften des Ereignisobjekts überprüfen, um festzustellen, ob das Ablegen akzeptiert werden kann. Wenn das Datenformat und die zulässigen Aktionen geeignet sind, muss die Ereignisprozedur für diese Ereignisse NativeDragManager.acceptDrop() aufrufen und dabei einen Verweis auf das Anzeigeobjekt übergeben, das als Ablageziel dient (normalerweise das Objekt, das das nativeDragEnter- oder nativeDragEnter-Ereignis ausgelöst hat). Der Benutzer kann das gezogene Element auf dem Ziel ablegen.
• nativeDragExit-Ereignis: Wenn eine Ziehbewegung über ein interaktives Objekt hinaus verläuft, löst das Objekt ein nativeDragExit-Ereignis aus. Wenn das Objekt von einem früheren Aufruf der NativeDragManager.acceptDrop()-Methode als Ablageziel bestimmt wurde, ist dieser Aufruf nicht mehr gültig und acceptDrop() muss erneut aufgerufen werden, wenn die Bewegung wieder über das interaktive Objekt verläuft.
• nativeDragDrop-Ereignis: Das Zielanzeigeobjekt löst ein nativeDragDrop-Ereignis aus, wenn der Benutzer die Maustaste über dem Objekt loslässt. Die Prozedur für dieses Ereignis kann auf die Daten in der transferable-Eigenschaft des Ereignisobjekts zugreifen und sollte die NativeDragManager.dropAction-Eigenschaft setzen, um anzugeben, welche Aktion vom Initiatorobjekt ausgeführt werden sollte.
• nativeDragComplete: Wenn der Benutzer am Ende einer Ziehbewegung die Maustaste loslässt, löst das Initiatorobjekt ein nativeDragComplete-Ereignis aus (unabhängig davon, ob das Element tatsächlich abgelegt wird oder nicht). Die Prozedur für dieses Ereignis kann die dropAction-Eigenschaft des Ereignisobjekts überprüfen, um festzustellen, welche Änderungen am internen Datenstatus vorgenommen werden sollten, zum Beispiel das Entfernen eines Elements aus einer Liste, nachdem es in eine andere Liste gezogen wurdet. Wenn dropAction die Einstellung NativeDragActions.NONE hat, wurde das gezogene Element nicht auf einem geeigneten Ziel abgelegt.

Bewegungen zwischen Anwendungen

Wenn ein Element aus einer Nicht-AIR-Anwendung in ein AIR-Anwendungsfenster gezogen wird, gibt es kein Initiatorobjekt, das die Ereignisse nativeDragStart oder nativeDragComplete auslösen könnte. Davon abgesehen folgen die während der Bewegung ausgelösten Ereignisse demselben Muster wie bei einer Bewegung, die innerhalb derselben AIR-Anwendung stattfindet.

Wenn ein Element aus einem AIR-Anwendungsfenster hinausgezogen wird, gibt es kein Zielobjekt, das die Ereignisse nativeDragEnter, nativeDragOver oder nativeDragDrop auslösen könnte. Das Initiatorobjekt löst dennoch ein nativeDragComplete-Ereignis aus, das die vom nativen Betriebssystem festgelegte Ziehaktion meldet (oder none, falls das Ablegen des Elements nicht akzeptiert wurde).

Wenn ein Element aus einer AIR-Anwendung in eine andere gezogen wird, lösen die Initiator- und Zielanzeigeobjekte wie gewohnt Ereignisse in den jeweiligen Anwendungen aus.

Übertragen von Informationen

Die Daten, die beim Ziehen und Ablegen übertragen werden, sind in einem Clipboard-Objekt enthalten. Dieses Datenobjekt wird dem Ziehvorgang mit der NativeDragManager.doDrag()-Methode hinzugefügt, die die Ziehbewegung startet. Potenzielle Ablageziele können auf das Clipboard-Objekt über die clipboard-Eigenschaft des nativen Ziehereignisobjekts zugreifen. Nachdem ein Ziehvorgang begonnen hat, kann nur über die Ereignisprozedur des NativeDragEvent auf das Clipboard-Objekt zugegriffen werden. Bei allen anderen Zugriffsversuchen auf das Objekt kommt es zu einem Laufzeitfehler.

Sicherheitserwägungen

Die Sicherheits-Sandboxen des Initiator- und des potenziellen Zielobjekts bestimmen, wie auf die gezogenen Daten zugegriffen werden kann. Wenn sich beide Objekte in derselben Sandbox befinden, kann von jedem NativeDragEvent-Objekt auf die Daten zugegriffen werden. Befinden sich die Initiator- und Zielobjekte dagegen in unterschiedlichen Sandboxen, kann nur in der Ziel-Sandbox innerhalb der Ereignisprozedur für das nativeDragDrop-Ereignis auf die Daten zugegriffen werden. Andere native Ziehereignisprozeduren können weiterhin auf das in der clipboard-Eigenschaft referenzierte Clipboard-Objekt zugreifen und ermitteln, welche Datenformate verfügbar sind. Das Aufrufen der clipboard.getData()-Methode löst jedoch einen Sicherheitsfehler aus.

Verwandte API-Elemente

---