Clipboard formats describe the data placed in a Clipboard object. AIR automatically translates the standard data formats between ActionScript data types and system clipboard formats. In addition, application objects can be transferred within and between AIR applications using application-defined formats.

A Clipboard object can contain representations of the same information in different formats. For example, a Clipboard object representing a Sprite could include a reference format for use within the same application, a serialized format for use by another AIR application, a bitmap format for use by an image editor, and a file list format, perhaps with deferred rendering to encode a PNG file, for copying or dragging a representation of the Sprite to the file system.

Contents

• Standard data formats
• Custom data formats
• Deferred rendering

Standard data formats

The constants defining the standard format names are provided in the ClipboardFormats class:

When copying and pasting data in response to a copy, cut, or paste event in HTML content, MIME types must be used instead of the ClipboardFormat strings. The valid data MIME types are:

Custom data formats

You can use application-defined custom formats to transfer objects as references or as serialized copies. References are only valid within the same AIR application. Serialized objects can be transferred between Adobe AIR applications, but can only be used with objects that remain valid when serialized and deserialized. Objects can usually be serialized if their properties are either simple types or serializable objects.

To add a serialized object to a Clipboard object, set the serializable parameter to true when calling the Clipboard.setData() method. The format name can be one of the standard formats or an arbitrary string defined by your application.

Transfer modes

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:

Reading and writing custom data formats

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.

Deferred rendering

If creating a data format is computationally expensive, you can use deferred rendering by supplying a function that supplies the data on demand. The function is only called if a receiver of the drop or paste operation requests data in the deferred format.

The rendering function is added to a Clipboard object using the setDataHandler() method. The function must return the data in the appropriate format. For example, if you called setDataHandler(ClipboardFormat.TEXT_FORMAT, writeText), then the writeText() function must return a string.

If a data format of the same type is added to a Clipboard object with the setData() method, that data will take precedence over the deferred version (the rendering function is never called). The rendering function may or may not be called again if the same clipboard data is accessed a second time.

Pasting text using a deferred rendering function

The following example illustrates implementing a function to provide deferred rendering.

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>