Clipboard  - AS3

Tablica ciągów zawierających nazwy formatów danych dostępnych w tym obiekcie Clipboard.

Stałe ciągów znaków dla nazw standardowych formatów są zdefiniowane w klasie ClipboardFormats. Jako nazwy formatów stanowiące dane do przesyłania w formie obiektów mogą zostać użyte również inne zdefiniowane w aplikacji ciągi znaków.

Powiązane elementy interfejsu API

 var availableFormats:Array = Clipboard.generalClipboard.formats;

Systemowy obiekt clipboard.

Wszelkie dane przeklejone do systemowego obiektu clipboard są dostępne dla innych aplikacji. Może to również dotyczyć niezabezpieczonego zdalnego kodu, działającego w przeglądarce sieciowej.

Uwaga: W aplikacjach Flash Player 10 operacja wklejania ze schowka najpierw wymaga zdarzenia użytkownika (np. użycia skrótu klawiszowego dla polecenia Wklej lub kliknięcia myszą polecenia Wklej z menu kontekstowego). Metoda Clipboard.getData() zwróci treść schowka jedynie wtedy, gdy obiekt InteractiveObject ją odebrał i przetwarza zdarzenie paste. W innym wypadku wywołanie metody Clipboard.getData() zakończy się niepowodzeniem. To samo ograniczenie dotyczy treści spoza obszaru izolowanego aplikacji w środowisku AIR.

Obiekt generalClipboard jest tworzony automatycznie. Nie można przypisać następnej instancji obiektu Clipboard do tej właściwości. Zamiast tego należy użyć metod getData() i setData() do odczytu i zapisu danych w istniejącym obiekcie.

Należy zawsze wyczyścić zawartość schowka przed zapisaniem w nim nowych danych, aby zapewnić usunięcie starych danych we wszystkich formatach.

Obiektu generalClipboard nie można przekazać do obiektu NativeDragManager środowiska AIR. Do obsługi rodzimych operacji przeciągania i upuszczania w aplikacji AIR należy utworzyć nowy obiekt Clipboard.

 import flash.desktop.ClipboardFormats;
 
 var copy:String = "A string to copy to the system clipboard.";
 Clipboard.generalClipboard.clear();
 Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, copy);

 import flash.desktop.ClipboardFormats;
 
 var pasteData:String  = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;

Wskazuje, czy format przyrzeczenia pliku w schowku jest obsługiwany w systemie klienckim.

Tworzy pusty obiekt Clipboard.

W celu przechowywania danych związanych z rodzimym gestem przeciągania i upuszczania w środowisku AIR należy tworzyć obiekty Clipboard. Obiekty Clipboard mogą być używane dla tylko jednego gestu przeciągania i upuszczania; nie można ich używać wielokrotnie.

Nie należy tworzyć obiektu Clipboard do obsługi operacji kopiowania i wklejania. Zamiast niego należy użyć jednego obiektu Clipboard.generalClipboard.

Powiązane elementy interfejsu API

 import flash.desktop.Clipboard;
 
 var clipboard:Clipboard = new Clipboard();

Usuwa wszystkie reprezentacje danych z tego obiektu Clipboard.

 Clipboard.generalClipboard.clear();

Usuwa reprezentację danych dla określonego formatu.

Parametry

 import flash.desktop.ClipboardFormats;
 
 Clipboard.generalClipboard.clearData(ClipboardFormats.TEXT_FORMAT);

Pobiera dane obiektu clipboard jeżeli obecne są dane w określonym formacie.

Program Flash Player wymaga, aby metoda getData() była wywoływana w programie obsługi zdarzenia paste. W środowisku AIR to ograniczenie obowiązuje tylko wobec zawartości spoza obszaru izolowanego aplikacji.

Kiedy uzyskiwany jest dostęp do formatu danych standardowych, dane są zwracane jako nowy obiekt odpowiedniego typu danych programu Flash.

W trakcie uzyskiwania dostępu do formatu zdefiniowanego przez aplikację wartość parametru transferMode określa, czy zostanie zwrócone odwołanie do oryginalnego obiektu, czy też anonimowy obiekt zawierający zserializowaną kopię oryginalnego obiektu. Jeśli określono tryb originalPreferred lub clonePreferred, program Flash Player lub aplikacja AIR zwraca alternatywną wersję, jeśli preferowana wersja jest niedostępna. Jeśli określono tryb originalOnly lub cloneOnly, program Flash Player lub aplikacja AIR zwraca wartość null, jeśli żądana wersja jest niedostępna.

Parametry

Powiązane elementy interfejsu API

 import flash.desktop.ClipboardFormats;

 var pasteData:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;

Sprawdza, czy dane w określonym formacie istnieją w danym obiekcie Clipboard.

Aby odwołać się do standardowych nazw formatów, należy użyć stałych klasy ClipboardFormats.

Parametry

Powiązane elementy interfejsu API

if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){
    //do something 
}

Dodaje reprezentację informacji do przesłania w określonym formacie danych.

W obszarze izolowanym aplikacji w środowisku Adobe AIR metodę setData() można wywołać w dowolnej chwili. W innych kontekstach metodę setData() można wywołać w odpowiedzi na zdarzenie wygenerowane przez użytkownika, takie jak naciśnięcie klawisza lub kliknięcie myszą.

Różne reprezentacje tej samej informacji można dodać do obiektu schowka w różnych formatach, co pozwala na szersze wykorzystanie danych przez inne składniki lub aplikacje. Na przykład obraz można dodać jako bitmapę na potrzeby aplikacji do edycji obrazów, jako adres URL i jako zakodowany plik PNG przeznaczony do przeniesienia do natywnego systemu plików.

Parametr data musi zawierać dane odpowiedniego typu dla określonego formatu:

Niestandardowe nazwy formatów nie mogą zaczynać się od słów „air:” ani „flash:”. Aby zapobiec kolizjom nazw w przypadku korzystania z formatów niestandardowych, należy stosować identyfikator aplikacji lub nazwę pakietu jako przedrostek formatu, np. „com.example.applicationName.dataPacket”.

Podczas przesyłania w aplikacji albo między aplikacjami parametr serializable określa, czy dostępne jest odwołanie i kopia, czy też samo odwołanie do obiektu. Aby udostępnić odwołanie i kopię danych obiektu, należy ustawić dla parametru serializable wartość true. Ustawienie dla parametru serializable wartości false sprawi, że dostępne będzie tylko odwołanie do obiektu. Odwołania do obiektów są poprawne tylko w aktualnej aplikacji, dlatego ustawienie dla parametru serializable wartości false oznacza również, że format nie jest już dostępny w innych aplikacjach Flash Player lub AIR. Składnik może pobrać odwołanie do obiektu lub kopię obiektu — w tym celu należy ustawić odpowiedni tryb przesyłania schowka podczas uzyskiwania dostępu do danych dla tego formatu.

Uwaga: Formaty standardowe są zawsze konwertowane na formaty natywne, gdy dane są wklejane lub przeciągane poza obsługiwaną aplikację, dlatego wartość parametru serializable nie wpływa na dostępność danych w formatach standardowych dla aplikacji innych niż aplikacje Flash.

Aby odroczyć renderowanie danych dla formatu, należy użyć metody setDataHandler(). Jeśli metody setData() i setDataHandler() są używane w celu dodawania reprezentacji danych o takiej samej nazwie formatu, wówczas funkcja modułu obsługi nigdy nie zostanie wywołana.

Uwaga: W systemie Mac OS ustawienie parametru format na wartość ClipboardFormats.URL_FORMAT spowoduje, że adres URL jest przenoszony tylko wtedy, gdy jest poprawnym adresem URL. W przeciwnym razie obiekt Clipboard zostanie opróżniony (a wywołanie metody getData() zwróci null).

Parametry

Powiązane elementy interfejsu API

 import flash.desktop.ClipboardFormats;
 
 var htmlString:String = "<html><body>Body content</body></html>";
 Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, urlString);
 Clipboard.generalClipboard.setData(ClipboardFormats.HTML_FORMAT, urlString);

Dodaje odwołanie do funkcji obsługi, która generuje dane przeznaczone do przeniesienia.

Funkcja obsługi umożliwia opóźnienie tworzenia lub renderowania danych do czasu, aż faktycznie nastąpi próba dostępu do nich.

Funkcja modułu obsługi musi zwrócić dane odpowiedniego typu dla danego formatu:

Funkcja modułu obsługi jest wywoływana wówczas i tylko wówczas, gdy dane w określonym formacie mogą zostać odczytane. W niektórych przypadkach system operacyjny wywołuje funkcję, zanim dojdzie do upuszczenia. Na przykład gdy funkcja obsługi udostępnia dane pliku przeciąganego z aplikacji AIR do systemu plików, system operacyjny wywołuje funkcję obsługi danych, gdy tylko przeciągany wskaźnik opuszcza aplikację AIR — co zwykle wywołuje niepożądane odczuwalne opóźnienie spowodowane pobieraniem lub tworzeniem danych pliku. Aby uniknąć takiej sytuacji, można użyć obiektu URLFilePromise.

Należy zauważyć, że dane podstawowe mogą ulec zmianie w czasie między dodaniem modułu obsługi a odczytaniem danych, chyba że aplikacja wykona odpowiednie kroki w celu ochrony danych. Nie ma gwarancji, że zostanie wykonana określona operacja, do jakiej dochodzi, gdy dane w schowku reprezentowane przez funkcję modułu obsługi są odczytywane więcej niż raz. Schowek może zwrócić dane wygenerowane przez pierwsze wywołanie funkcji lub może wywołać ponownie funkcję. Nie należy liczyć na to, że zostanie wykonana określona operacja.

W obszarze izolowanym aplikacji w środowisku Adobe AIR metodę setDataHandler() można wywołać w dowolnej chwili. W innych kontekstach metodę setDataHandler() można wywołać w odpowiedzi na zdarzenie wygenerowane przez użytkownika, takie jak naciśnięcie klawisza lub kliknięcie myszą.

Aby dodać dane bezpośrednio do danego obiektu Clipboard, należy zamiast tego użyć metody setData(). Jeśli metody setData() i setDataHandler() zostaną wywołane z taką samą nazwą formatu, wówczas funkcja modułu obsługi nigdy nie zostanie wywołana.

Uwaga: W systemie Mac OS ustawienie parametru format na wartość ClipboardFormats.URL_FORMAT powoduje, że adres URL jest przenoszony tylko wtedy, gdy funkcja obsługi zwraca poprawny adres URL. W przeciwnym razie obiekt Clipboard zostanie opróżniony (a wywołanie metody getData() zwróci wartość null).

Parametry

Powiązane elementy interfejsu API

 import flash.desktop.ClipboardFormats;
 
 Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, randomNumberGenerator);

 public function randomNumberGenerator():String{
     return Math.random().toString();
 }

1. Należy zapisać dane - w tym wypadku ciąg znaków do obiektu Clipboard.generalClipboard.
2. Należy odczytać zawartość obiektu clipboard Clipboard.generalClipboard.

Uwaga: Ten przykład nie działa w odtwarzaczu Flash Player z uwagi na ograniczenia w dostępie do danych w schowku wynikające ze względów bezpieczeństwa. W programie Flash Player metodę getData() obiektu Clipboard można wywołać tylko wewnątrz podprogramu obsługi zdarzenia paste.

package
{
    import flash.display.Sprite;
    import flash.desktop.Clipboard;
    import flash.desktop.ClipboardFormats;
    import flash.desktop.ClipboardTransferMode;

    public class ClipboardExample extends Sprite
    {
        public function ClipboardExample()
        {
            var sally:String = "Sally";
            var person:String;
            
            copy(sally);
            person = paste();
            trace(person); //traces: "Sally"
        }

        private function copy(text:String):void 
        {
            Clipboard.generalClipboard.clear();
            Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, text);
        }
        
        private function paste():String
        {
            if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT))
            {
                return String(Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT));
            } 
            else 
            {
                return null;
            }
        }
        
    }
}