Flash lets you use the System clipboard to copy and paste data. These features are provided in the Clipboard class.

Import related classes first:

	import flash.desktop.Clipboard;

	import flash.desktop.ClipboardFormats;

	import flash.desktop.ClipboardTransferMode;

	

The Clipboard class holds a reference to the system clipboard which we can use to access it:

	var clipboard:Clipboard = Clipboard.generalClipboard;

	

Just note that you cannot create new Clipboard instances. If you try to do so an error will be thrown.

Copying data

The clipboard can hold multiple data of different types at the same time. Standard types are defined in the ClipboardFormats class as consts:

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

You can also define custom types to hold Actionscript objects, but references will be valid only within the application itself.

To set data into the clipboard we'll use the setData method. You need to specify the data format before. For example, let's save a string:

	clipboard.setData(ClipboardFormats.TEXT_FORMAT, "Saved text");

	

The string will be saved in the system clipboard and you'll be able to paste it even outside your application.

To save custom data we will use a custom data format. It's usually good practice to specify the qualified class name of the object to avoid name conflicts. Custom data format name cannot begins with "air:" or "flash:".

For example, let's say we have a PlayerInfo object we want to copy and paste to another instance of our game. We'll copy it using this:

	clipboard.setData("com.himeki.player.PlayerInfo", playerInfo);

	

A third optional parameter, serializable, specifies if you want to save both a copy and reference of your object (true) or just a reference (false). It has to be set to true if you want your data to be available between different Flash applications. Serializable is true by default

If you try to save data using a data format already used, old data will be overwritten.

You can check what formats are used in the clipboard object reading the formats array property:

	var formatsUsed : Array = clipboard.formats;

	

Or you can use the hasFormat method to check if the clipboard contains data of the specified format:

	var hasTextData : Boolean = clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT);

	var hasPlayerData : Boolean = clipboard.hasFormat("com.himeki.player.PlayerInfo");

	

Copying data using a data handler

We can define a function as a data handler to generate data everytime we request it. To do that we use the setDataHandler method. Let's say we have this function to generate a representation of the user info to show in the game lobby:

	public function getUserInfoAsString():String

	{

	   return "Player : " + playerInfo.name + " - Level: " + playerInfo.level;

	}

	

We can set it as a handler for the clipboard:

	clipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, getUserInfoAsString):

	

Everytime we'll request the related data, this function will be called.

Just note that, if you set both data and data handler of the same type, data handler will never be called.

Pasting data

You can then retrieve data using the getData method. Under Flash Player you can only use this method inside an Event.PASTE event handler.

Data of standard types are returned as a new object in their specified type:

	var copiedText : String = clipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;

	

When requesting custom format data we can specify if we want a reference or a clone of the object using the optional second parameter of the getData method. Transfer modes are defined in the ClipboardTransferMode class as static literal consts:

• CLONE_ONLY: Copy only
• CLONE_PREFERRED: Copy if available, reference otherwise
• ORIGINAL_ONLY: Reference only
• ORIGINAL_PREFERRED: Reference if available, copy otherwise

By default transfer mode is set to ORIGINAL_PREFERRED.

We can then use it to retrieve custom data:

	var playerInfo : Object = clipboard.getData("com.himeki.player.PlayerInfo", ClipboardTransferMode.CLONE_ONLY);

	

If we use CLONE_ONLY or ORIGINAL_ONLY and the requested object is not available it will return null.

Clearing the clipboard

To clear all data inside the clipboard use the clear method:

	clipboard.clear():

	

Instead, if you want to delete just one format of data you can use clearData, specifying the format:

	clipboard.clearData(ClipboardFormats.TEXT_FORMAT);