Clipboard data formats

Contents [Hide]

Standard data formats
Custom data formats
- Transfer modes
- Reading and writing custom data formats
Deferred rendering
- Pasting text using a deferred rendering function

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.

Standard data formats

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

Constant	Description
TEXT_FORMAT	Text-format data is translated to and from the ActionScript String class.
HTML_FORMAT	Text with HTML markup.
RICH_TEXT_FORMAT	Rich-text-format data is translated to and from the ActionScript ByteArray class. The RTF markup is not interpreted or translated in any way.
BITMAP_FORMAT	Bitmap-format data is translated to and from the ActionScript BitmapData class.
FILE_LIST_FORMAT	File-list-format data is translated to and from an array of ActionScript File objects.
URL_FORMAT	URL-format data is translated to and from the ActionScript String 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:

MIME type	Description
Text	"text/plain"
URL	"text/uri-list"
Bitmap	"image/x-vnd.adobe.air.bitmap"
File list	"application/x-vnd.adobe.air.file-list"

Note: Rich text format data is not available from the clipboardData property of the event object dispatched as a result of a paste event within HTML content.

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:

Transfer mode	Description
ClipboardTransferModes.ORIGINAL_ONLY	Only a reference is returned. If no reference is available, a null value is returned.
ClipboardTransferModes.ORIGINAL_PREFFERED	A reference is returned, if available. Otherwise a serialized copy is returned.
ClipboardTransferModes.CLONE_ONLY	Only a serialized copy is returned. If no serialized copy is available, then a null value is returned.
ClipboardTransferModes.CLONE_PREFFERED	A serialized copy is returned, if available. Otherwise a reference is returned.

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:

function createClipboardObject(object){ 
    var transfer = new air.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 = clipboard.getData("object", air.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 =  
    clipboard.getData("object", air.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.

Note: On Mac OS X, deferred rendering does not occur when using the standard AIR clipboard formats. The rendering function is called immediately.

Pasting text using a deferred rendering function

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.)

<html> 
<head> 
    <title>Deferred rendering</title>         
    <script src="AIRAliases.js" type="text/javascript"></script>     
    <script language="javascript" type="text/javascript"> 
        function doCopy(){ 
            air.Clipboard.generalClipboard.clear(); 
            air.Clipboard.generalClipboard.setDataHandler( 
                            air.ClipboardFormats.TEXT_FORMAT, renderData); 
        } 
         
        function doPaste(){ 
            document.getElementById("destination").innerHTML = 
                air.Clipboard.generalClipboard.getData(air.ClipboardFormats.TEXT_FORMAT); 
        } 
         
        function renderData(){ 
            air.trace("Rendering data"); 
            return document.getElementById("source").innerHTML; 
        }             
    </script> 
</head> 
<body> 
    <button onClick="doCopy()">Copy</button> 
<button onClick="doPaste()">Paste</button> 
<p>Source:</p> 
    <p id="source" contentEditable="true">Neque porro quisquam est qui dolorem ipsum  
    quia dolor sit amet, consectetur, adipisci velit.</p> 
<hr> 
<p>Destination:</p> 
<p id="destination"></p> 
</body> 
</html>