flash.desktop

# Clipboard - AS3

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

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.0

The Clipboard class provides a container for transferring data and objects through the clipboard. 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)

These constants for the names of the standard formats are defined in the ClipboardFormats class.

When a transfer to or from the operating system occurs, the standard formats are automatically translated between ActionScript data types and the native operating system clipboard types.

You can use application-defined formats to add ActionScript 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 that in some cases, the operating system calls the function before a drop occurs. For example, when you use a handler function to provide the data for a file dragged from an AIR application to the file system, the operating system calls the data handler function as soon as the drag gesture leaves the AIR application—typically resulting in an undesireable pause as the file data is downloaded or created.

Note for AIR applications: The clipboard object 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.

Note for Flash Player applications: In Flash Player 10, a paste operation from the clipboard first requires a user event (such as a keyboard shortcut for the Paste command or a mouse click on the Paste command in a context menu). `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 other circumstances will be unsuccessful. The same restriction applies in AIR for content outside the application sandbox.

On Linux, clipboard data does not persist when an AIR application closes.

View the examples

More examples

Copy and paste
Drag and drop in AIR

Related API Elements

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
|  | supportsFilePromise : Boolean [read-only] Indicates whether the file promise clipboard format is supported on the client system. | Clipboard

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 = "originalPreferred"):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 to be transfered. | Clipboard
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | 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

Runtime Versions: | Flash Player 10, AIR 1.0

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 transfer data as an object.

Implementation
`public function get formats():Array`

Related API Elements

flash.desktop.ClipboardFormats
Example ( How to use this example )
The following example reads the `formats` array of the system clipboard:
Copy

     var availableFormats:Array = Clipboard.generalClipboard.formats;

### generalClipboard

property

`generalClipboard:Clipboard` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.0

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: In Flash Player 10 applications, a paste operation from the clipboard first requires a user event (such as a keyboard shortcut for the Paste command or a mouse click on the Paste command in a context menu). `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 other circumstances will be unsuccessful. The same restriction applies in AIR for content outside the application sandbox.

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.

The `generalClipboard` object cannot be passed to the AIR NativeDragManager. Create a new Clipboard object for native drag-and-drop operations in an AIR application.

Implementation
`public static function get generalClipboard():Clipboard`
Example ( How to use this example )
To write to the operating system clipboard:
Copy

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

To read from the operating system clipboard:
Copy

     import flash.desktop.ClipboardFormats;

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

### supportsFilePromise

property

`supportsFilePromise:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Indicates whether the file promise clipboard format is supported on the client system.

Implementation
`public function get supportsFilePromise():Boolean`
Constructor Detail

### Clipboard

()
Constructor

`public function Clipboard()`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.0

Creates an empty Clipboard object.

Create Clipboard objects to hold the data of a native drag-and-drop gesture in Adobe AIR. Clipboard objects can be used for only one drag-and-drop gesture; they cannot be reused.

Do not create a Clipboard object for copy-and-paste operations. Use the single `Clipboard.generalClipboard` object instead.

Throws

| `IllegalOperationError` — `new Clipboard()` is not supported in Flash Player, since only the operating system clipboard can 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.

Related API Elements

generalClipboard
Example ( How to use this 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.

Copy

     import flash.desktop.Clipboard;

     var clipboard:Clipboard = new Clipboard();

Method Detail

### clear

()
method

`public function clear():void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.0

Deletes all data representations from this Clipboard object.

Throws

| `SecurityError` — Call to generalClipboard.clear() is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a user event (as in a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox.

Example ( How to use this example )
The following example clears the system clipboard:
Copy

     Clipboard.generalClipboard.clear();

### clearData

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.0

Deletes the data representation for the specified format.

Parameters

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

Throws

| `SecurityError` — Call to generalClipboard.clearData() is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a user event (as in a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox.

Example ( How to use this example )
The following example clears any data having the format `ClipboardFormats.TEXT_FORMAT` from the system clipboard:
Copy

     import flash.desktop.ClipboardFormats;

     Clipboard.generalClipboard.clearData(ClipboardFormats.TEXT_FORMAT);

### getData

()
method

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

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10, AIR 1.0

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

Flash Player requires that the `getData()` be called in a `paste` event handler. In AIR, this restriction only applies to content outside of the application security sandbox.

When a standard data format is accessed, the data is returned as a new object of the corresponding Flash data 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 `null` 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 = "`originalPreferred`")`` — 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; a copy is always returned.

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 Flash Player, you can only call this method successfully during the processing of a `paste` event. In AIR, this restriction only applies to content outside of the application security sandbox.

Related API Elements

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

     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

Runtime Versions: | Flash Player 10, AIR 1.5

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

Use the constants in the ClipboardFormats class to reference the standard format names.

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.
| `SecurityError` — Reading from or writing to the clipboard is not permitted in this context.

Related API Elements

flash.desktop.ClipboardFormats
Example ( How to use this example )
The following example tests the system clipboard to determine whether text-formatted data is available:
Copy

    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

Runtime Versions: | Flash Player 10, AIR 1.0

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

In the application sandbox of Adobe AIR, `setData()` can be called anytime. In other contexts, `setData()` can only be called in response to a user-generated event such as a key press or mouse click.

Different representations of the same information can be added to the clipboard as different formats, which increases the ability of other components or applications to make use of the available data. For example, an image could be added as bitmap data for use by image editing applications, as a URL, 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:". 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 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 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-based 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.

Note: On Mac OS, when you set the `format` parameter to `ClipboardFormats.URL_FORMAT`, the URL is transferred only if it is a valid URL. Otherwise, the Clipboard object is emptied (and calling `getData()` returns `null`).

Parameters

| `format:String` — The format of the data.
| `data:Object` — The information to add.
| `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`, `ClipboardFormats.FILE_PROMISE_LIST_FORMAT`, or `ClipboardFormats.BITMAP_FORMAT`).

Throws

| `IllegalOperationError` — The Clipboard object requested is no longer in scope (which can occur with clipboards created for drag-and-drop operations).
| `SecurityError` — Reading from or writing to the clipboard is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a user event (as in a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox.
| `TypeError` — `format` or `data` is `null`.

Related API Elements

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

     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

Runtime Versions: | Flash Player 10, AIR 1.0

Adds a reference to a handler function that produces the data to be transfered.

Use a handler function 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)
`ClipboardFormats.FILE_PROMISE_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 in some cases, the operating system calls the function before a drop occurs. For example, when you use a handler function to provide the data for a file dragged from an AIR application to the file system, the operating system calls the data handler function as soon as the drag gesture leaves the AIR application—typically resulting in an undesireable pause as the file data is downloaded or created. You can use a URLFilePromise for this purpose instead.

Note that the underlying data can change between the 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. The clipboard might return the data produced by the first function call or it might call the function again. Do not rely on either behavior.

In the application sandbox of Adobe AIR, `setDataHandler()` can be called anytime. In other contexts, `setDataHandler()` can only be called in response to a user-generated event such as a key press or mouse click.

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

Note: On Mac OS, when you set the `format` parameter to `ClipboardFormats.URL_FORMAT`, the URL is transferred only if the handler function returns a valid URL. Otherwise, the Clipboard object is emptied (and calling `getData()` returns `null`).

Parameters

| `format:String` — A function that returns the data to be transferred.
| `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

| `TypeError` — `format` or `handler` is `null`.
| `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 Flash Player, you can only call this method successfully during the processing of a user event (such as a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox.

Related API Elements

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

     import flash.desktop.ClipboardFormats;

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

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

Examples How to use this example
ClipboardExample.as
The following example, for Adobe AIR, 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`.

Note: Because of security restrictions on accessing clipboard data, this example does not work in Flash Player. In Flash Player, you can only call the `getData()` method of the Clipboard object in a `paste` event handler.

Copy

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

        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00