Clipboard data formats

When an object is written to the clipboard using a custom data format, the object data can be read from the clipboard either as reference or as a serialized copy of the original object. AIR defines four transfer modes that determine whether objects are transferred as references or as serialized copies:

You can use any string that does not begin with the reserved prefix air: for the format parameter when writing an object to the clipboard. Use the same string as the format to read the object. The following examples illustrate how to read and write objects to the clipboard:

public function createClipboardObject(object:Object):Clipboard{ 
    var transfer:Clipboard = new Clipboard(); 
    transfer.setData("object", object, true); 
} 

To extract a serialized object from the clipboard object (after a drop or paste operation), use the same format name and the cloneOnly or clonePreferred transfer modes.

var transfer:Object = clipboard.getData("object", ClipboardTransferMode.CLONE_ONLY); 

A reference is always added to the Clipboard object. To extract the reference from the clipboard object (after a drop or paste operation), instead of the serialized copy, use the originalOnly or originalPreferred transfer modes:

var transferredObject:Object =  
    clipboard.getData("object", ClipboardTransferMode.ORIGINAL_ONLY); 

References are only valid if the Clipboard object originates from the current AIR application. Use the originalPreferred transfer mode to access the reference when it is available, and the serialized clone when the reference is not available.

The following example illustrates how to implement a deferred rendering function.

When the Copy button in the example is pressed, the application clears the system clipboard to ensure that no data is left over from previous clipboard operations, then puts the renderData() function onto the clipboard with the clipboard setDataHandler() method.

When the Paste button is pressed, the application accesses the clipboard and sets the destination text. Since the text data format on the clipboard has been set with a function rather than a string, the clipboard will call the renderData() function. The renderData() function returns the text in the source text, which is then assigned to the destination text.

Notice that if you edit the source text before pressing the Paste button, the edit will be reflected in the pasted text, even when the edit occurs after the copy button was pressed. This is because the rendering function doesn’t copy the source text until the paste button is pressed. (When using deferred rendering in a real application, you might want to store or protect the source data in some way to prevent this problem.)

<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"  
width="326" height="330"> 
<mx:Script> 
    <![CDATA[ 
        import flash.desktop.Clipboard; 
        import flash.desktop.ClipboardFormats; 
         
        public function doCopy():void{ 
            Clipboard.generalClipboard.clear(); 
            Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, 
                                                    renderData); 
        } 
         
        public function doPaste():void{ 
            destination.text = 
                Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String; 
        } 
         
        public function renderData():String{ 
            trace("Rendering data"); 
            return source.text; 
        }             
    ]]> 
</mx:Script> 
    <mx:Label x="10" y="10" text="Source"/> 
    <mx:TextArea id="source" x="10" y="36" width="300" height="100"> 
    <mx:text>Neque porro quisquam est qui dolorem ipsum  
    quia dolor sit amet, consectetur, adipisci velit.</mx:text> 
    </mx:TextArea> 
    <mx:Label x="10" y="181" text="Destination"/> 
    <mx:TextArea id="destination"  x="12" y="207" width="300" height="100"/> 
    <mx:Button click="doPaste();" x="166" y="156" label="Paste"/> 
    <mx:Button click="doCopy();" x="91" y="156" label="Copy"/> 
</mx:WindowedApplication>