In the last article, I introduced the key aspects of the clipboard support within Adobe AIR. There are a few additonal functions of the Clipboard in AIR of which you can take advantage. In this article we will example deferred rendering, transfer modes, and custom clipboard data types.

Deferred Rendering

Traditionally, to add data to the clipboard, you use the setData method. AIR gives you an additional option, the setDataHandler method. Instead of passing in the actual data to the clipboard, you pass in a method that will return the data when the data is requested from the clipboard.

// Use setDataHandler to Provide Deferred Rendering
private function putTextFormat( e:MouseEvent ):void {
	Clipboard.generalClipboard.setDataHandler(
		ClipboardFormats.TEXT_FORMAT, getTextData );
}
// Method the will be Called When Data is Retrieved
private function getTextData():String {
	return textFormat.text;
}

The above example demonstrates this functionality. It assumes that there is a text input named 'textFormat' on the stage as well as a button that calls the method putTextFormat. When the user presses the button, the reference to getTextData is added to the clipboard (instead of actual text data). When the data is pasted, the getTextData method returns the current value of the text in the 'textFormat' text field - even if the value has changed since the user pressed the copy button.

This can be advantageous in situations where you want to allow the information to be given in real-time when the user requests the data. It also can be useful if the creation of the clipboard data requires a large amount of system resources. In this way, the data would only need to be created when the user requested it, not when it was copied.

Transfer Modes

When the getData method of the Clipboard class is called, it needs to know how it is going to receive the data. It can receive data in two ways: as a clone (copy) of the original data or a reference to the original object. The class ClipboardTransferMode (Reference: ActionScript,JavaScript) defines four constants that be used to set the mode of a getData call.

• CLONE_ONLY: This mode will cause the getData call to return a clone of the original object if one is available. If there is not one available, nothing will be returned.
• ORIGINAL_ONLY: This mode will return a reference to the original object. If a reference is not available, nothing is returned.
• CLONE_PREFERRED: This mode will return a clone of the original data if it is available or a reference if the clone is not available.
• ORIGINAL_PREFERRED: This mode will return a reference to the original data if it is available or a clone if the reference is not available.

For a clone to be made available, the data previously needed to be set as serializable when it was added to the clipboard with the setData call. The third argument of the setData method is a boolean that indicates if the data is serializable. If this value is set to false, only the reference can be used. If it is set to true and the data is in a serializable format, both the reference and clone can be made available.

Note: If you have not dealt with serialization in Actionscript 3, you can read AIR Tip 8 - Serializing Objects from my blog to understand how to make custom classes serializable.

This also can be very important when working in FILE_LIST_FORMAT. If you only want to be working with a clone of the file, be sure to use CLONE_ONLY. Likewise, if you want to work with the actual file, be sure to use CLONE_ONLY.

Custom Clipboard Data Types

You are not limited to the five predefined Clipboard data types that are defined in ClipboardFormats. You can create custom types that correspond to classes in your AIR application. There are limitations to this however. Custom data cannot be pasted into a non-AIR application. In addition, only clones of the clipboard data can be passed from one AIR application to a different AIR application. Lastly, if you choose to pass the clipboard by reference, you can only paste that data within that AIR application.

For example, instead of passing a String as TEXT_FORMAT, you could pass an ArrayCollection (which is natively serializable) from one AIR application to another. To accomplish this, you would need to give this format a name (such as 'arraycollection') for the first parameter in the setData method. You also would need to be sure to set the third parameter to true, so that a clone of the data can be made available. As long as the second application understood the format 'arraycollection' it could be received on its clipboard.

Conclusion

In the next tutorial, I will have an AIR application that will allow you to test the many different ways that we can interact with the Clipboard inside of AIR (and view source will be enabled). I will also have a screencast that will demonstrate the usage of this application. As always, leave a comment if you have any questions or topics that you would like to have addressed.

Read more from David Tucker.