ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
Clipboard

Package | flash.desktop
Class | public class Clipboard
Inheritance | Clipboard Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The Clipboard class provides a container for transferring data and objects through the clipboard and through drag-and-drop operations. The operating system clipboard can be accessed through the static `generalClipboard` property.

A Clipboard object can contain the same information in more than one format. By supplying information in multiple formats, you increase the chances that another application will be able to use that information. Add data to a Clipboard object with the `setData()` or `setDataHandler()` method.

The standard formats are:

- BITMAP_FORMAT: a BitmapData object (AIR only)
- FILE_LIST_FORMAT: an array of File objects (AIR only)
- HTML_FORMAT: HTML-formatted string data
- TEXT_FORMAT: string data
- RICH_TEXT_FORMAT: a ByteArray containing Rich Text Format data
- URL_FORMAT: a URL string (AIR only)

Constants for these formats are defined in the ClipboardFormats class.

When a transfer between FlashPlayer or an AIR application and the operating system occurs, the standard formats are automatically translated between data types and the native clipboard.

You can use application-defined formats to add objects to a Clipboard object. If an object is serializable, both a reference and a clone of the object can be made available. Object references are valid only within the originating application.

When it is computationally expensive to convert the information to be transferred into a particular format, you can supply the name of a function that performs the conversion. The function is called if and only if that format is read by the receiving component or application. Add a deferred rendering function to a Clipboard object with the `setDataHandler()` method.

Note for AIR applications: The clipboard objects referenced by the event objects dispatched for HTML drag-and-drop and copy-and-paste events are not the same type as the AIR Clipboard object. The JavaScript clipboard object is described in the AIR developer's guide.

View the examples

See also

flash.desktop.NativeDragManager
flash.desktop.ClipboardFormats
flash.desktop.ClipboardTransferMode

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | formats : Array [read-only] An array of strings containing the names of the data formats available in this Clipboard object. | Clipboard
|  | generalClipboard : Clipboard [static] [read-only] The operating system clipboard. | Clipboard
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Clipboard() Creates an empty Clipboard object. | Clipboard
|  | clear():void Deletes all data representations from this Clipboard object. | Clipboard
|  | clearData(format:String):void Deletes the data representation for the specified format. | Clipboard
|  | getData(format:String, transferMode:String):Object Gets the clipboard data if data in the specified format is present. | Clipboard
|  | hasFormat(format:String):Boolean Checks whether data in the specified format exists in this Clipboard object. | Clipboard
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setData(format:String, data:Object, serializable:Boolean = true):Boolean Adds a representation of the information to be transferred in the specified data format. | Clipboard
|  | setDataHandler(format:String, handler:Function, serializable:Boolean = true):Boolean Adds a reference to a handler function that produces the data for the specified format on demand. | Clipboard
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

formats | property

`formats:Array` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

An array of strings containing the names of the data formats available in this Clipboard object.

String constants for the names of the standard formats are defined in the ClipboardFormats class. Other, application-defined, strings may also be used as format names to be transfer data as an object.

Implementation
`public function get formats():Array`

See also

flash.desktop.ClipboardFormats
Example
The following example reads the `formats` array of the system clipboard:

     var availableFormats:Array = Clipboard.generalClipboard.formats;

generalClipboard | property |

`generalClipboard:Clipboard` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The operating system clipboard.

Any data pasted to the system clipboard is available to other applications. This may include insecure remote code running in a web browser.

Note for Flash Player 10: For security reasons, in Flash Player 10 applications, a paste event can only be triggered by the user, not via Actionscript. `Clipboard.getData()` will return the contents of the clipboard only if the InteractiveObject has received and is acting on a paste event. Calling `Clipboard.getData()` under any circumstances will be unsuccessful.

The `generalClipboard` object is created automatically. You cannot assign another instance of a Clipboard to this property. Instead, you use the `getData()` and `setData()` methods to read and write data to the existing object.

You should always clear the clipboard before writing new data to it to ensure that old data in all formats is erased.

Implementation
`public static function get generalClipboard():Clipboard`
Example
How to use examples
Constructor Detail

Clipboard | () | Constructor

`public function Clipboard()`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Creates an empty Clipboard object.

Throws

| `IllegalOperationError` — `new Clipboard()` is not supported in Flash Player, since only the operating system clipboard should be used in Flash Player. For copy-and-paste operations involving the operating system clipboard, use the Clipboard.generalClipboard object rather than creating a new Clipboard object. Does not throw an error in an AIR application.

See also

generalClipboard
Example
The following example creates a new clipboard for use with the NativeDragManager class.

Note: For copy-and-paste operations involving the operating system clipboard, use the `Clipboard.generalClipboard` object rather than creating a new clipboard.

     import flash.desktop.Clipboard;

     var clipboard:Clipboard = new Clipboard();

Method Detail

clear | () | method

`public function clear():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Deletes all data representations from this Clipboard object.

Example
The following example clears the system clipboard:

     Clipboard.generalClipboard.clear();

clearData | () | method |

`public function clearData(format:String):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Deletes the data representation for the specified format.

Parameters

| `format:String` — The data format to remove.

Example
The following example clears any data having the format `ClipboardFormats.TEXT_FORMAT` from the system clipboard:

     import flash.desktop.ClipboardFormats;

     Clipboard.generalClipboard.clearData(ClipboardFormats.TEXT_FORMAT);

getData | () | method |

`public function getData(format:String, transferMode:String):Object`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Gets the clipboard data if data in the specified format is present.

When a standard data format is accessed, the data is returned as a new object of the corresponding Flash Player or AIR type.

When an application-defined format is accessed, the value of the `transferMode` parameter determines whether a reference to the original object or an anonymous object containing a serialized copy of the original object is returned. When an `originalPreferred` or `clonePreferred` mode is specified, Flash Player or AIR returns the alternate version if the preferred version is not available. When an `originalOnly` or `cloneOnly` mode is specified, Flash Player or AIR returns `undefined` if the requested version is not available.

Parameters

| `format:String` — The data format to return. The format string can contain one of the standard names defined in the ClipboardFormats class, or an application-defined name.
| `transferMode:String` (default = `NaN`)`` — Specifies whether to return a reference or serialized copy when an application-defined data format is accessed. The value must be one of the names defined in the ClipboardTransferMode class. This value is ignored for the standard data formats.

Returns

| `Object` — An object of the type corresponding to the data format.

Throws

| `Error` — `transferMode` is not one of the names defined in the ClipboardTransferMode class.
| `IllegalOperationError` — The Clipboard object requested is no longer in scope (AIR only).
| `SecurityError` — Reading from or writing to the clipboard is not permitted in this context. In addition, in Flash Player, `Clipboard.getData()` may only be successfully called during the processing of `flash.events.Event.PASTE`.

See also

setData()
flash.desktop.ClipboardFormats
flash.desktop.ClipboardTransferMode
Example
The following example reads text from the system clipboard, if available:

     import flash.desktop.ClipboardFormats;

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

hasFormat | () | method |

`public function hasFormat(format:String):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Checks whether data in the specified format exists in this Clipboard object.

Use the constants in the ClipboardFormats class to check for the presence of data in the standard formats.

Parameters

| `format:String` — The format type to check.

Returns

| `Boolean` — `true`, if data in the specified format is present.

Throws

| `IllegalOperationError` — The Clipboard object requested is no longer in scope (AIR only).
| `SecurityError` — Reading from or writing to the clipboard is not permitted in this context.

See also

flash.desktop.ClipboardFormats
Example
The following example tests the system clipboard to determine whether text-formatted data is available:

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

setData | () | method |

`public function setData(format:String, data:Object, serializable:Boolean = true):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Adds a representation of the information to be transferred in the specified data format.

Different representations of the same information can be added to the clipboard in different formats, which increases the ability of other components or applications to make use of the available data. For example, in an AIR application, an image could be added as bitmap data for use by image editing applications, as a Bitmap object for use by other AIR applications, and as an encoded PNG file for transfer to the native file system.

The data parameter must be the appropriate data type for the specified format:

Format | Type | Description
--- | --- | ---
`ClipboardFormats.TEXT_FORMAT` | `String` | string data
`ClipboardFormats.HTML_FORMAT` | `String` | HTML string data
`ClipboardFormats.URL_FORMAT` | `String` | URL string (AIR only)
`ClipboardFormats.RICH_TEXT_FORMAT` | `ByteArray` | Rich Text Format data
`ClipboardFormats.BITMAP_FORMAT` | `BitmapData` | bitmap data (AIR only)
`ClipboardFormats.FILE_LIST_FORMAT` | array of `File` | an array of files (AIR only)
Custom format name | any | object reference and serialized clone

Custom format names cannot begin with "air:" or "flash:". In an AIR application, to prevent name collisions when using custom formats, you may want to use your application ID or a package name as a prefix to the format, such as "com.example.applicationName.dataPacket".

When transferring within or between Flash Player or AIR applications, the `serializable` parameter determines whether both a reference and a copy are available, or whether only a reference to an object is available. Set `serializable` to `true` to make both the reference and a copy of the data object available. Set `serializable` to `false` to make only the object reference available. Object references are valid only within the current application so setting `serializable` to `false` also means that the data in that format is not available to other Flash Player or AIR applications. A component can choose to get the reference or the copy of the object by setting the appropriate clipboard transfer mode when accessing the data for that format.

Note: The standard formats are always converted to native formats when data is pasted or dragged (AIR only) outside a supported application, so the value of the `serializable` parameter does not affect the availability of data in the standard formats to non-Flash Player or non-AIR applications.

To defer rendering of the data for a format, use the `setDataHandler()` method instead. If both the `setData()` and the `setDataHandler()` methods are used to add a data representation with the same format name, then the handler function will never be called.

Parameters

| `format:String` — The information to add.
| `data:Object` — The format of the data.
| `serializable:Boolean` (default = `true`)`` — Specify `true` for objects that can be serialized (and deserialized).

Returns

| `Boolean` — `true` if the data was succesfully set; `false` otherwise. In Flash Player, returns `false` when `format` is an unsupported member of ClipboardFormats. (Flash Player does not support `ClipboardFormats.URL_FORMAT`, `ClipboardFormats.FILE_LIST_FORMAT`, or `ClipboardFormats.BITMAP_FORMAT`).

Throws

| `Error` — `data` is `undefined`.
| `IllegalOperationError` — The Clipboard object requested is no longer in scope (AIR only).
| `SecurityError` — Reading from or writing to the clipboard is not permitted in this context.

See also

setDataHandler()
getData()
flash.desktop.ClipboardFormats
flash.desktop.ClipboardTransferMode
Example
The following example adds content to the system clipboard in both text and HTML formats:

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

setDataHandler | () | method |

`public function setDataHandler(format:String, handler:Function, serializable:Boolean = true):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Adds a reference to a handler function that produces the data for the specified format on demand. Use this method to defer creation or rendering of the data until it is actually accessed.

The handler function must return the appropriate data type for the specified format:

Format | Return Type
--- | ---
`ClipboardFormats.TEXT_FORMAT` | `String`
`ClipboardFormats.HTML_FORMAT` | `String`
`ClipboardFormats.URL_FORMAT` | `String` (AIR only)
`ClipboardFormats.RICH_TEXT_FORMAT` | `ByteArray`
`ClipboardFormats.BITMAP_FORMAT` | `BitmapData` (AIR only)
`ClipboardFormats.FILE_LIST_FORMAT` | Array of `File` (AIR only)
Custom format name | Non-void

The handler function is called when and only when the data in the specified format is read. Note that the underlying data can change between time the handler is added and the time the data is read unless your application takes steps to protect the data. The behavior that occurs when data on the clipboard represented by a handler function is read more than once is not guaranteed. Flash Player or AIR might return the data produced by the first function call or it might call the function again. Do not rely on either behavior.

To add data directly to this Clipboard object, use the `setData()` method instead. If both the `setData()` and the `setDataHandler()` methods are called with the same format name, then the handler function is never be called.

Parameters

| `format:String` — A function that returns the data to be tranfered when called.
| `handler:Function` — The format of the data.
| `serializable:Boolean` (default = `true`)`` — Specify `true` if the object returned by `handler` can be serialized (and deserialized).

Returns

| `Boolean` — `true` if the handler was succesfully set; `false` otherwise.

Throws

| `Error` — `data` is `undefined`.
| `IllegalOperationError` — The Clipboard object requested is no longer in scope (AIR only).
| `SecurityError` — Reading from or writing to the clipboard is not permitted in this context.

See also

setData()
flash.desktop.ClipboardFormats
Example
The following example adds a random number to the system clipboard through a deferred data function:

     import flash.desktop.ClipboardFormats;

     Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, randomNumberGenerator);

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

Examples How to use examples
ClipboardExample.as
The following example uses the ClipboardExample class to copy a string from one variable to another via the system clipboard. This task is accomplished by performing the following steps:

1. Write the data, in this case a string, to `Clipboard.generalClipboard`.
2. Read the clipboard contents from `Clipboard.generalClipboard`.

    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;}
            }

        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00