Packageflash.desktop
Classpublic class Clipboard
InheritanceClipboard Inheritance Object

Language version: ActionScript 3.0
Runtime version: 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:

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 JavaScript ActionScript data types and the native operating system clipboard types.

You can use application-defined formats to add JavaScript 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.

See also

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


Public Properties
 PropertyDefined by
 Inheritedconstructor : 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
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  supportsFilePromise : Boolean
[read-only] Indicates whether the file promise clipboard format is supported on the client system.
Clipboard
Public Methods
 MethodDefined by
  
Creates an empty Clipboard object.
Clipboard
  
Deletes all data representations from this Clipboard object.
Clipboard
  
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
  
Checks whether data in the specified format exists in this Clipboard object.
Clipboard
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
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
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
Property detail
formatsproperty
formats:Array  [read-only]

Language version: ActionScript 3.0
Runtime version: 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

See also


Example
The following example reads the formats array of the system clipboard:
 var availableFormats:Array = Clipboard.generalClipboard.formats;

generalClipboardproperty 
generalClipboard:Clipboard  [read-only]

Language version: ActionScript 3.0
Runtime version: 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
To write to the operating system clipboard:
 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:
 import flash.desktop.ClipboardFormats;
 
 var pasteData:String  = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;

supportsFilePromiseproperty 
supportsFilePromise:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: 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 version: 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
Error 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.

See also


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
Runtime version: 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
The following example clears the system clipboard:
 Clipboard.generalClipboard.clear();

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

Language version: ActionScript 3.0
Runtime version: 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
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 = "originalPreferred"):Object

Language version: ActionScript 3.0
Runtime version: 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.
 
Error — 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.

See also


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
Runtime version: 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
Booleantrue, if data in the specified format is present.

Throws
Error — The Clipboard object requested is no longer in scope.
 
SecurityError — Reading from or writing to the clipboard is not permitted in this context.

See also


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
Runtime version: 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:

FormatTypeDescription
ClipboardFormats.TEXT_FORMATStringstring data
ClipboardFormats.HTML_FORMATStringHTML string data
ClipboardFormats.URL_FORMATStringURL string (AIR only)
ClipboardFormats.RICH_TEXT_FORMATByteArrayRich Text Format data
ClipboardFormats.BITMAP_FORMATBitmapDatabitmap data (AIR only)
ClipboardFormats.FILE_LIST_FORMATarray of Filean array of files (AIR only)
Custom format nameanyobject 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
Booleantrue 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
Error — 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.

See also


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
Runtime version: 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:

FormatReturn Type
ClipboardFormats.TEXT_FORMATString
ClipboardFormats.HTML_FORMATString
ClipboardFormats.URL_FORMATString (AIR only)
ClipboardFormats.RICH_TEXT_FORMATByteArray
ClipboardFormats.BITMAP_FORMATBitmapData (AIR only)
ClipboardFormats.FILE_LIST_FORMATArray of File (AIR only)
ClipboardFormats.FILE_PROMISE_LIST_FORMATArray of File (AIR only)
Custom format nameNon-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
Booleantrue if the handler was succesfully set; false otherwise.

Throws
TypeError format or handler is null.
 
Error — 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.

See also

setData()
flash.desktop.ClipboardFormats
flash.desktop.URLFilePromise

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
examples\ClipboardExample
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.

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