Last week I introduced a new series here at InsideRIA.com. To start this series, I will be examining the Clipboard support within AIR.

Introduction

Native clipboard support is an essential element of AIR's system integration. The clipboard's use can be as simple as copying a line of text from one document to another or as detailed as passing references of complex objects from one application to another. In this tutorial I will demonstrate the basics of the clipboard functionality within the AIR API.

The entire clipboard functionality is contained within three classes in the AIR API.

• Clipboard ( Reference: Flex, JavaScript )
• ClipboardFormats ( Reference: Flex, JavaScript )
• ClipboardTransferMode ( Reference: Flex, JavaScript )

The main class that you will use is Clipboard. The two helper classes, ClipboardFormats, ClipboardTransferMode define constants that are used when calling methods on the main class.

The Clipboard Class

The Clipboard class can be instantiated as often as you would like, but creating an instance of the Clipboard class does not give you access to the operating system clipboard (but rather a clipboard that is limited to your application). The Clipboard class contains a property, generalClipboard, which is a reference to the actual operating system clipboard. To call a method on the operating system (such as the clear method which we will discuss later), you simply need to use the following syntax:

// Calling a Method on the Native Clipboard
Clipboard.generalClipboard.clear();

This tells your application to use the actual operating system clipboard for this method. Note that AIR creates the reference to the operating system clipboard. It will be there in each of your AIR applications by default.

Understanding Clipboard Data Formats

Not all clipboard data is the same. For example, you wouldn't copy an image from your desktop and paste it into a simple text editor. If you tried, the application wouldn't receive the data because it is not configured to work with that type of data. In AIR you have the same flexibility as a developer. You can configure your application to work with different pieces of data differently (or not at all). The class ClipboardFormats gives constants for the five clipboard data formats that are predefined in AIR. Several methods in the Clipboard class require that you pass in one of these constants to define the format of the data that you will be utilizing.

• BITMAP_FORMAT - This format allows for storing bitmap (image) data
• FILE_LIST_FORMAT - This format allows for an array of File objects
• HTML_FORMAT - This format is for HTML formatted text
• TEXT_FORMAT - This format is for plain text
• URL_FORMAT - This format is for text that is formatted as a URL

A single clipboard item can have multiple formats. For example, you could add an image as each of the formats listed above: the image data in bitmap format, a reference to its File object, an img tag in HTML, the filename as text, and the URL for the filename. By adding an object in multiple formats, you increase the ways that the data can be used.

The Clipboard class contains a method, hasFormat which can tell the developer if the current clipboard has any of these formats in it. For example, if you were building a simple text editor in AIR, you could test to see if the clipboard contained data in the TEXT_FORMAT. If the clipboard does contain data in the requested format, the method will return true. Otherwise the method will return false.

// Check to See if the Clipboard Contains Text
if(Clipboard.generalClipboard.hasFormat( ClipboardFormats.TEXT_FORMAT)) {
	trace("This Clipboard contains data in the Text Format");
} else {
	trace("This Clipboard doesn't contain data in the Text Format");
}

Clearing the Clipboard

In the same way, you can also clear the clipboard with the methods clear (which clears the entire clipboard irrespective of its current data type) and clearData (which clears data in the format that you specify). The following examples clear the operating system clipboard.

// Clear All Data
Clipboard.generalClipboard.clear();
// Clear All Bitmap Data
Clipboard.generalClipboard.clearData( ClipboardFormats.BITMAP_FORMAT );

Placing Data on the Clipboard

The setData method allows you to specify what format and what data that you want to place on the clipboard. This method takes three arguments, but for most applications, you will only need to worry about the first two arguments. The first argument is the format that the data will be in. In most situations, this will need to match one of the constants defined in ClipboardFormats. The second argument is the data that will be placed on the clipboard. The following example illustrates the placing of basic text on the operating system's clipboard.

// Place Basic Text on the Clipboard
Clipboard.generalClipboard.setData( 
	ClipboardFormats.TEXT_FORMAT, "Sample Text" );

In this example the words "Sample Text" were placed on the operating system clipboard (and could now be utilized in other applications).

Getting Data From the Clipboard

The method getData allows you to retrieve data from the clipboard. This method can take two arguments, but in most basic situations, you will only need to worry about the first one. You only need to pass in the format of the data that you want to retrieve from the clipboard. The following example retrieves all of the text data from the operating system clipboard.

// Getting Text from the Clipboard
var textData:String = Clipboard.generalClipboard.getData(
	ClipboardFormats.TEXT_FORMAT );

Coming Up

In the next article, I will look at some of the more advanced features of the Clipboard class and its helper classes. I will also demonstrate a sample application that uses the clipboard functionality.