Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Adobe AIR - Using A Clipboard To Transfer Data

DZone's Guide to

Adobe AIR - Using A Clipboard To Transfer Data

· Web Dev Zone
Free Resource

Start coding today to experience the powerful engine that drives data application’s development, brought to you in partnership with Qlik.

Drag-and-drop and copy-and-paste are very similar in nature. In both cases, the operation involves moving or copying data from one location to another. The only thing that differs between these operations is the way in which the user interacts with the data in order to move or copy it.

In the case of drag-and-drop, the user clicks on a UI element (an image or text file, for example), drags it to a new location, and the releases the mouse button to complete the transaction, thereby moving or copying the data (the image or text file.)

Copy-and-paste requires that the user selects a UI element by way of a menu option, keyboard shortcut, or a button, and then the user can move or copy to a new location by way of a menu option, keyboard shortcut, or button in the new location. In both operations, however, there must be a transfer medium – a place where the data is placed temporarily while it is either being moved or copied. In AIR this transfer medium is called a clipboard, and in the next few sections we’ll learn more about what a clipboard is and how you can work with them.

This article is based on chapter 4 from Adobe Air in Action by Joseph Lott, Kathryn Rotondo, Sam Ahn, and Ashley Atkins. It is being reproduced here by permission from Manning Publications. Manning early access books and ebooks are sold exclusively through Manning. Visit the book's page for more information

[img_assist|nid=7614|title=|desc=|link=url|url=http://www.manning.com/lott/|align=right|width=150|height=198]
What’s a Clipboard?

The clipboard is the metaphor that computers use to move or copy data. You are likely already familiar with the system clipboard used by your operating system, which allows you to copy and paste. For example, if you want to copy text from your email program and paste it into a Word document you are using the system clipboard behind the scenes.

We’ll be working with two different sorts of clipboards. One type of clipboard is the system clipboard that we just mentioned. You’ll see how you can write data to the system clipboard for use in other applications. We’ll also work with AIR-specific clipboards. Regardless, AIR treats both of these clipboards in the same way, and you can access them via instances of the flash.desktop.Clipboard class.

What can you do with Clipboard objects? Turns out Clipboard objects are relatively simple. In very simple terms you can do just three things with clipboards: add data to a clipboard, read data from a clipboard, clear data off a clipboard. We’ll elaborate on different ways to accomplish these tasks, but generally speaking that is what you can do with a Clipboard object.

If you want to work with a Clipboard object the first thing you need to do is create a reference one. We’ll be working with both types of clipboards: AIR-specific and the system clipboard. Therefore, you’ll need to know how to reference both types. Getting a reference to the system clipboard is as simple as accessing the static Clipboard.generalClipboard property.

var systemClipboard:Clipboard = Clipboard.generalClipboard;

We’ll also use lots of AIR-specific clipboards. In these cases you’ll need to use the Clipboard constructor, which requires no parameters. The following creates a new Clipboard object.

var clipboard:Clipboard = new Clipboard();

The next step would be to add or retrieve data. However, before we can do that we need to understand the formats that we can use with a clipboard.

Understanding Data Formats

You may store and retrieve data to and from a clipboard in a variety of formats. You’re probably familiar with this concept even if you’ve never thought about it before. When you use the system clipboard on your computer you sometimes copy and paste text and you sometimes copy and paste files. Text and files are different formats, but you can store both on the system clipboard. When you’re working with AIR the same is true.

As a result, you need to be able to specify what format you want to use to store or retrieve data. Many of the Clipboard methods require that you specify a format, including the methods for writing data to the clipboard and reading data from the clipboard. For example, in the next section we’ll look at the setData() method used to write data to the clipboard. This method always requires that you give it a format as well as the data that you want to write to the clipboard. For example, the following code writes text to the clipboard, specifying the text format.

clipboard.setData(ClipboardFormats.TEXT_FORMAT, “example text”);

As we just saw in this example you can use the flash.desktop.ClipboardFormats constants to refer to the most common formats. These constants and their ActionScript equivalents are shown in table 1. These are the formats that are most universally understood by other applications. That means that you can add a bitmap-formatted or a text-formatted data to the clipboard from an AIR application and know that it is likely that the user will be able to copy that to another application on their computer (e.g. Word.) Likewise, the inverse is also true: These are the formats that most applications will write to a clipboard, and therefore they are available for reading into an AIR application.

Constant Actionscript Equivalent
BITMAP_FORMAT
BitmapData
FILE_LIST_FORMAT
Array of File objects
HTML_FORMAT HTML-formatted String
TEXT_FORMAT
String
URL_FORMAT
String

In addition to the standard formats listed in Table 4.1 you can transfer objects by reference for use in the same application or in a serialized format that might be valid in other applications that know how to interpret the data.

For example, suppose you have several pieces of information such as name, street address, city, state/province, and postal code that you would like to bundle up together in one unit in an instance of a custom Address class. Using the standard formats it would be possible to write any one of these pieces of data to the clipboard, but not all grouped together. You can use your own custom format name instead. In this example the format name address might be appropriate. All that is necessary then is that the application that reads from the clipboard knows both the data format name (address) and how to deserialize the data. When we talk about serializing data that could refer to custom serialization (e.g. an XML string) or the use of AIR’s native support of AMF. The following example assumes that userAddress is an Address object (remember that in our scenario Address is a custom class,) and it serializes the object automatically using AMF.

clipboard.setData(“address”, userAddress);

Now we know what clipboards are and we know what formats we can store or retrieve from clipboards. The next logical step is to start reading and writing data from and to a clipboard.

Reading and Writing Data

Clipboards are fairly passive objects. They don’t do much. Rather, they are storage areas where you can write data and read data. For example, if you want to take a snapshot of an AIR window’s contents and make that available to paste into a Word document you’ll want to write that image data to the clipboard. On the flip side, if you’ve copied a file from your desktop and you want to paste that into an AIR application to add it to a list of files, for example, you’ll need to read that file information from the clipboard.

You can write data to a clipboard using the setData() method as we’ve already seen examples of in the previous section. The setData() method always requires that you specify two parameters: the format and the data to write to the clipboard. The following example writes the current value of a text input control to a clipboard using text format.

clipboard.setData(ClipboardFormats.TEXT_FORMAT, textInput.text);

You can add more than one format to a clipboard at a time. For example, if a user copies an image from your AIR application you may want to allow them to paste it into an image editing program or on to the desktop as an image file. In this case you’d need to add the data in two formats: BITMAP_FORMAT and FILE_LIST_FORMAT. Each format requires a different type of data for it to make sense to the recipient of the data, in this case. The BITMAP_FORMAT data would need to be a BitmapData object, while the FILE_LIST_FORMAT would need to be an array of one or more File objects.

You can read data from a clipboard using the getData() method. The getData() method requires just one parameter: the format of the data to retrieve. The following example retrieves the data from a clipboard in text format.

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

You’ll notice that in this example the return value of getData() is cast as a String. That’s because getData() necessarily has a return type of a generic Object. If you try to use the value in a way that requires a more specific type (as in assigning the value to a typed variable) you’ll need to cast appropriately. Of course, it’s up to you to know what the correct type should be for casting. In the case of text format, url format, and html format, you know that you should cast as a String. For bitmap format you should cast as BitmapData. And for file list format you should cast as an Array (knowing that each element of the array is a File object.) For custom formats you’ll need to know the original format of the data before it was written to the clipboard.

If you’re uncertain whether or not a clipboard has data in a particular format you can use the hasFormat() method to query for that information. The method requires that you specify a format, and it returns a Boolean value: true if the clipboard has data for that format, and false otherwise.

Removing Data from a Clipboard

Not only might you want to set and get data on a clipboard, but you might also want to remove data from a clipboard. For example, if you write data to the system clipboard in a particular format you aren’t necessarily guaranteed that there aren’t already other pieces of data written to that clipboard in different formats. When the user goes to request the data from the clipboard the results could be unpredictable because different applications may have differing format precedents. For example, if you paste in Word that application always pastes text from the clipboard if it is available, ignoring other formats that might be on the clipboard. It’s possible that you could write bitmap formatted data to the system clipboard from an AIR application and then if the user pastes it into a Word document she would see only other text that she had previously copied from a different program. Therefore, you need methods to remove data from a clipboard.

NOTE
For exactly the reason described in the preceding scenario you should always clear the system clipboard before writing data to it.

The clearData() method allows you to clear the data from a clipboard for a particular format. For example, if you want to remove URL format data from a clipboard you could use the following code.

clipboard.clearData(ClipboardFormats.URL_FORMAT);

On the other hand, there are times when you simply want to remove all data of all formats from a clipboard. In those cases you can use the clear() method.

clipboard.clear();

As you can see, the clear() method does not require any parameters. It just deletes all the data.
You’ve now seen how to write data, read data, and delete data. What we haven’t yet talked about is how the data gets stored to a clipboard and how that can impact the way in which the data is available, both within an AIR application and outside of AIR. In the following section we’ll talk about how you can use transfer modes to affect the way in which data is stored.

Understanding Transfer Modes

There are a variety of scenarios in which you might use a clipboard. The basic three are as follows.

  • Transfer data within a single AIR application
  • Transfer data between AIR applications
  • Transfer data between an AIR application and the operating system or another, non-AIR application

The second and third scenarios require that a copy of the data is made. For example, if you want to copy text from an AIR application to a Word document, Word is not capable of reading the text directly from the AIR application. Instead, an actual copy of the text must be made. This is true between AIR applications as well. If you have a custom Address type that is available in two AIR applications and you want to transfer an Address object from one AIR application to another, you must make a copy of the Address object. The second AIR application cannot access the original Address object in order to read from it.

However, the first scenario is different. When you want to transfer data within a single AIR application it is possible to access data by reference, not just by value. By default when you write data to a clipboard it is always serializable, meaning that both a copy and a reference are written to the clipboard. If you want to explicitly control whether or not the data you write is serializable you can specify a third Boolean parameter for the setData() method. A value of true (the default) means a copy and a reference are written and false means that only a reference is written. You only need to use this parameter if you want to make sure that data isn’t serialized and copied.

NOTE
Even if you set the third parameter of setData() to false, all standard formats are still available to non-AIR applications. Using a value of false only affects data in custom formats for use within AIR applications.

On the flip side, you can also specify how you want to retrieve data when calling getData(). You can do this by way of a second, optional parameter that indicates a transfer mode. There are four transfer modes, each with a constant in the flash.desktop.ClipboardTransferMode class. The constants are as follows.

  • ORIGINAL_PREFERRED – In this mode a reference to the original is returned if it is available. If no reference is available then a copy is returned. Remember that references are only available within the same AIR application from which the data originated. If you specify this transfer mode and the data originated from another application then it will always return the copy of the data. This transfer mode is the default.
  • ORIGINAL_ONLY – In this mode the reference to the original data is returned if it is available. Otherwise, if the original is unavailable null is returned.
  • CLONE_PREFERRED – In this mode a copy of the data is returned if available. Otherwise a reference is returned.
  • CLONE_ONLY – In this mode only a copy is returned if available. Otherwise null is returned.
We’ve got just one more topic to cover before we can jump to actually using clipboards. Next we’ll discuss how you can be clever with how and when you write data to a clipboard.


Deferred Rendering

Generally we write data to a clipboard as soon as the request is made. For example, if a user selects a menu option to copy text from a text area we probably expect that the application immediately writes the text to the clipboard. However, there are some cases in which it is better to defer the writing of the actual data to the clipboard. Instead, we just want to set a note about where to find the necessary data when the user tries to retrieve it from the clipboard. There are two basic scenarios for this deferral:

  • The data is large or it would be computationally-intensive to write the data to the clipboard
  • The data might update between the time it is selected and the time it is requested, and you want to always get the most up-to-date data at the time it is requested

Admittedly both of these are edge-cases, but it’s good to know that should you have such a need AIR supports deferred rendering. If you want to enabled deferred rendering then you should not use setData(). Instead, you should use setDataHandler(). The setDataHandler() method also requires that you specify the format. However, instead of specifying the data, you instead pass the method a reference to a handler method. When the user requests the data of that format from the clipboard AIR will call the handler method and use the value returned by the handler method. That means you must make sure the return value of the handler method is the expected type for the format. Consider the following example.

clipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, getText);

In this example the format is set to text, which means that the handler method (getText()) must return a String as in the following.

private function getText():String {
return textArea.text;
}

If you want to defer rendering by using setDataHandler() then you must make sure you haven’t set data using setData() because setData() will always take precedence over setDataHandler(). If you’ve already written data to a clipboard using setData() and you want to use deferred rendering for the same format just call clearData() for that format before calling setDataFormat().

The handler method specified by setDataHandler() does not get called until the user requests the data (e.g. she pastes into a Word document.) However, AIR will only call the handler method that once. Subsequent requests for the data will retrieve the same data from the clipboard that was returned when the method was first called.

Now we’ve covered all the necessary preliminary topics related to clipboards, and we’re ready to start writing code that uses clipboards.

Create data driven applications in Qlik’s free and easy to use coding environment, brought to you in partnership with Qlik.

Topics:

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}