NativeDragManager  - AS3

Pakiet	flash.desktop
Klasa	public class NativeDragManager
Dziedziczenie	NativeDragManager Object

Wersje środowiska wykonawczego:

AIR 1.0

Klasa NativeDragManager koordynuje operacje przeciągania i upuszczania. Dzięki macierzystemu interfejsowi API przeciągania i upuszczania użytkownik może transportować dane między aplikacją AIR i macierzystym systemem operacyjnym, pomiędzy dwoma aplikacjami lub pomiędzy składnikami pojedynczej aplikacji.

Można przesyłać następujące rodzaje danych:

• Bitmapy
• Pliki
• Tekst
• Ciągi URL
• Obiekty serializowane
• Odwołania obiektów (poprawne jedynie w aplikacji źródłowej)

Uwaga: wszystkie elementy menedżera NativeDragManager są statyczne. Instancja tej klasy nie musi być tworzona.

Operacja przeciągnij i upuść jest ruchem interfejsu użytkownika, który zaczyna się kliknięciem widocznego elementu, a następnie przeciągnięciu go w inne miejsce. W trakcie przeciągania obiekty interaktywne listy wyświetlania wywołują macierzyste zdarzenia przeciągania w momencie przesunięcia się na okno aplikacji AIR. Moduły obsługi dla tych zdarzeń mogą wywołać metody NativeDragManager, w celu określenia, czy przeciągany element może być upuszczony na obiekt. Jednocześnie NativeDragManager zmieni wygląd wskaźnika myszy, w celu dostarczenia użytkownikowi informacji zwrotnych.

Obsługa profilów AIR: Ta funkcja nie jest obsługiwana na urządzeniach telewizyjnych ze środowiskiem AIR. Nie jest też obsługiwana na niektórych urządzeniach przenośnych. W czasie wykonywania można sprawdzić, czy ta funkcja jest obsługiwana, odczytując właściwość NativeDragManager.isSupported. Więcej informacji o obsłudze elementów interfejsu API w różnych profilach można znaleźć w sekcji Obsługa profilów aplikacji AIR.

Akcje przeciągania

Operacje przeciągnij i upuść są z reguły stosowane dla trzech typów operacji zwanych akcjami. Ponieważ znaczenie tych akcji zależy od kontekstu aplikacji, środowisko wykonawcze nie wymusza żadnych konkretnych operacji względem akcji. Jednakże właściwa implementacja akcji usprawni pracę użytkownika z aplikacją.

Możliwe są następujące akcje:

• Kopiowanie — tworzona jest kopia danych, pozostawiając oryginał nietknięty. (Podczas przeciągania obiektów w aplikacji należy uważnie skopiować oryginalny obiekt, a nie odwołanie do niego).
• Przesuwanie — dane przenoszone są z oryginalnego kontekstu do kontekstu określonego przez obiekt docelowy, na przykład przenoszenie elementu z jednej listy do drugiej.
• Łączenie — tworzone jest odwołanie lub skrót do oryginalnych danych, pozostawiając element w oryginalnym kontekście.

Można ustawić akcje dozwolone dla ruchu przeciągania poprzez dostarczenie parametru allowedActions w menedżerze NativeDragManager.doDrag(), który rozpoczyna tę operację. Jeśli nie ma dostarczonego parametru allowedActions dozwolone są wszystkie akcje. Potencjalne cele przeciągania mogą sprawdzić które akcje są dozwolone stosując właściwość allowedActions obiektu NativeDragEvent, oraz nie powinny akceptować upuszczeń, na które pozwalałyby jedynie akcje niekompatybilne (jednak nie jest to wymuszane przez środowisko wykonawcze).

Jeżeli cel upuszczania implementuje jedynie pojedynczą akcję, obiekt może ustawić właściwość dropAction obiektu NativeDragManager w modułach obsługi dla obu zdarzeń: nativeDragEnter oraz nativeDragOver. Ustawienie właściwości przed upuszczeniem pozwala menedżerowi przeciągania na aktualizowanie wskaźnika myszy w celu wskazania obsługiwanej akcji i jednocześnie ogranicza możliwość wybrania przez użytkownika niezgodnej akcji za pomocą klawiszy modyfikujących. Jeśli określona akcja nie jest jedną z dozwolonych akcji, wówczas upuszczenie jest niedozwolone, nawet jeśli cel wywoła metodęacceptDrop().

Podczas akceptowania upuszczenia potencjalny cel upuszczenia powinien wskazywać akcję wybraną przez właściwość NativeDragManager.dropAction w odpowiedzi na zdarzenie nativeDragDrop. Akcja ta jest raportowana z powrotem do wyświetlanego obiektu inicjującego zdarzenia nativeDragComplete. Jeśli żadna akcja nie jest określana przez cel upuszczenia, wówczas akcja domyślna wybierana jest spośród akcji dozwolonych, w następującej kolejności: kopiowanie, przesuwanie, łączenie. Obiekt inicjujący jest odpowiedzialny za uaktualnianie swego stanu wewnętrznego w odpowiedzi na wybraną akcję.

Stałe ciągów znaków dla nazw akcji są zdefiniowane w klasie NativeDragActions.

Kolejność zdarzeń

Ruch przeciągania rozpoczyna się wywołaniem metody NativeDragManager.doDrag() wewnątrz modułów obsługi zdarzeń mouseDown lub mouseMove i w odpowiedzi na akcje użytkownika przechodzi przez następującą sekwencję zdarzeń:

• Zdarzenie nativeDragStart — gdy wywołana jest metoda NativeDragManager.doDrag() obiekt interaktywny przekazany jako parametr metody staje się obiektem inicjującym i wywołuje zdarzenie nativeDragStart.
• Zdarzenie nativeDragUpdate — gdy przeciąganie jest w toku, obiekt inicjujący będzie ciągle wywoływać zdarzenia nativeDragUpdate.
• Zdarzenia nativeDragEnter, nativeDragOver — kiedy operacja przeciągania znajdzie się nad obiektem interaktywnym, wywołane zostanie zdarzenienativeDragEnter. Kiedy operacja przeciągania pozostaje nad obiektem interaktywnym, zdarzenia nativeDragOver będą ciągle wywoływane. W odpowiedzi na dowolne z tych dwóch zdarzeń obiekt będący potencjalnym celem upuszczenia powinien sprawdzić właściwości obiektu zdarzenia, aby zadecydować o akceptacji upuszczenia. Jeśli format danych i dozwolone akcje są prawidłowe moduł obsługi zdarzeń musi wywołać metodę NativeDragManager.acceptDrop(), przekazując odwołanie do obiektu wyświetlanego, który będzie celem przeciągnięcia (z reguły obiekt który wywołał zdarzenie nativeDragEnter lub nativeDragOver). Użytkownik będzie mógł wówczas upuścić przeciągany element na cel.
• Zdarzenie nativeDragExit — kiedy operacja przeciągania zostanie przesunięta poza obiekt interaktywny, wówczas obiekt wywoła zdarzenie nativeDragExit. Jeśli obiekt został określony jako cel przeciągnięcia wcześniejszego wywołania metody NativeDragManager.acceptDrop(), wówczas to wywołanie nie jest już prawidłowe i metoda acceptDrop() musi zostać wywołana ponownie jeśli ruch znajdzie się ponownie nad obiektem interaktywnym.
• Zdarzenie nativeDragDrop — docelowy obiekt wyświetlany wywołuje zdarzenie nativeDragDrop, gdy użytkownik zwalnia przycisk myszy nad tym obiektem. Moduł dla tego zdarzenia ma dostęp do danych we właściwości transferable obiektu zdarzenia oraz powinien ustawić właściwość NativeDragManager.dropAction do sygnalizacji która akcja powinna zostać podjęta przez obiekt inicjujący.
• Zdarzenie nativeDragComplete — gdy użytkownik zwalania przycisk myszy na końcu ruchu przeciągania, obiekt inicjujący wywołuje zdarzenie nativeDragComplete (bez względu na to, czy upuszczenie zostało zrealizowane). Moduł dla tego zdarzenia może sprawdzić właściwość dropAction obiektu zdarzenia, aby zdecydować, czy należy wprowadzić jakiekolwiek modyfikacje do wewnętrznego stanu danych, takich jak usuwanie elementów wyciągniętych z listy. Jeśli właściwość dropAction ma wartość NativeDragActions.NONE, wówczas przeciągany element nie został upuszczony na właściwy cel.

Ruchy między aplikacjami

Kiedy ruch przeciągania wchodzi na okno aplikacji AIR z aplikacji innej niż AIR, wówczas nie ma obiektu inicjującego, który wywoła zdarzenie nativeDragStart lub nativeDragComplete. W innym wypadku zdarzenia wywoływane podczas ruchu będą postępować według tego samego wzorca, jak ruch rozpoczynający się i kończący w tej samej aplikacji AIR.

Kiedy ruch przeciągania opuszcza okno aplikacji AIR, wówczas nie ma obiektu docelowego, który wywoła zdarzenia nativeDragEnter, nativeDragOver lub nativeDragDrop Obiekt inicjujący wciąż wywołuje zdarzenie nativeDragComplete, które raportuje akcję przeciągania, określoną przez macierzysty system operacyjny (lub none, jeśli upuszczenie nie zostało zaakceptowane).

Kiedy ruch przeciągania przesuwa się z jednej aplikacji AIR do drugiej, obiekty inicjujące i wyświetlane obiekty docelowe dysponują odpowiednie zdarzenia w swoich aplikacjach.

Przenoszenie informacji

Dane przenoszone podczas ruchu przeciągania i upuszczania są zawarte w obiekcie Clipboard. Obiekt danych jest dodawany do operacji przeciągania przez metodę NativeDragManager.doDrag(), która rozpoczyna ruch przeciągania. Potencjalne cele upuszczania mają dostęp do obiektu Clipboard poprzez właściwość clipboard obiektu zdarzenia przeciągania. Po rozpoczęciu operacji przeciągania, dostęp do obiektu Clipboard ma tylko moduł obsługi zdarzeń obiektu NativeDragEvent. Jakakolwiek inna próba otrzymania dostępu do obiektu generuje błąd uruchamiania.

Uwagi na temat bezpieczeństwa

Obszary izolowane obiektów inicjujących i potencjalnych obiektów docelowych określają sposób, w jaki można otrzymać dostęp do przeciąganych danych. Jeżeli oba obiekty znajdują się w tym samym obszarze izolowanym, wówczas do danych istnieje dostęp z dowolnego obiektu NativeDragEvent. W przypadku gdy obiekt inicjujący i obiekt docelowy znajdują się w różnych obszarach izolowanych, dostęp do danych jest możliwy tylko w docelowym obszarze izolowanym wewnątrz modułu obsługi zdarzeń (dotyczącego zdarzenia nativeDragDrop). Inne macierzyste moduły obsługi zdarzeń mają dostęp do obiektu Clipboard, do którego było odwołanie we właściwościach zdarzenia clipboard, w celu ustalenia które z formatów danych są dostępne, jednakże wywołanie metody clipboard.getData() generuje błąd bezpieczeństwa.

Powiązane elementy interfejsu API

---