Package | flash.desktop |
Class | public class Clipboard |
Inheritance | Clipboard Object |
Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, AIR 1.0 |
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:
- 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)
These constants for the names of the standard formats are defined in the ClipboardFormats class.
When a transfer between Flash Player or an AIR application and the operating system occurs, the standard formats are automatically translated between ActionScript data types and the native clipboard.
You can use application-defined formats to add 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 for AIR applications: The clipboard objects 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.
On Linux, clipboard data does not persist when an AIR application closes.
See also
Property | Defined By | ||
---|---|---|---|
constructor : 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 | ||
prototype : Object [static]
A reference to the prototype object of a class or function object. | Object |
Method | Defined 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 | ||
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 | ||
Indicates whether an object has a specified property defined. | Object | ||
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
Adds a representation of the information to be transferred in the specified data format. | Clipboard | ||
Adds a reference to a handler function that produces the data for the specified format on demand. | Clipboard | ||
Sets the availability of a dynamic property for loop operations. | Object | ||
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
Returns the string representation of the specified object. | Object | ||
Returns the primitive value of the specified object. | Object |
formats | property |
formats:Array
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, 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 ( How to use this example )
formats
array of the system clipboard:
var availableFormats:Array = Clipboard.generalClipboard.formats;
generalClipboard | property |
generalClipboard:Clipboard
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, 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.
Implementation
public static function get generalClipboard():Clipboard
Example ( How to use this example )
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);
import flash.desktop.ClipboardFormats; var pasteData:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;
Clipboard | () | Constructor |
public function Clipboard()
Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, AIR 1.0 |
Creates an empty Clipboard object.
Throws
IllegalOperationError — 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 ( How to use this example )
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();
clear | () | method |
public function clear():void
Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, AIR 1.0 |
Deletes all data representations from this Clipboard object.
Example ( How to use this example )
Clipboard.generalClipboard.clear();
clearData | () | method |
public function clearData(format:String):void
Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, AIR 1.0 |
Deletes the data representation for the specified format.
Parameters
format:String — The data format to remove.
|
Example ( How to use this example )
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 Versions: | Flash Player 10, 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 Player or AIR 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.
|
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.
| |
IllegalOperationError — 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 ( How to use this example )
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 Versions: | Flash Player 10, 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.
|
Boolean — true , if data in the specified format is present.
|
Throws
IllegalOperationError — 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.
|
See also
Example ( How to use this example )
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 Versions: | Flash Player 10, AIR 1.0 |
Adds a representation of the information to be transferred in the specified data format.
Flash Player requires a user event (such as a key press or mouse click) before using setData()
.
In AIR, this restriction only applies to content outside of the
application security sandbox.
Different representations of the same information can be added to the clipboard in different formats, which increases the ability of other components or applications to make use of the available data. For example, in an AIR application, an image could be added as bitmap data for use by image editing applications, as a Bitmap object for use by other AIR applications, 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:
Format | Type | Description |
---|---|---|
ClipboardFormats.TEXT_FORMAT | String | string data |
ClipboardFormats.HTML_FORMAT | String | HTML string data |
ClipboardFormats.URL_FORMAT | String | URL string (AIR only) |
ClipboardFormats.RICH_TEXT_FORMAT | ByteArray | Rich Text Format data |
ClipboardFormats.BITMAP_FORMAT | BitmapData | bitmap data (AIR only) |
ClipboardFormats.FILE_LIST_FORMAT | array of File | an array of files (AIR only) |
Custom format name | any | object reference and serialized clone |
Custom format names cannot begin with "air:" or "flash:". In an AIR application, 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 Flash Player or AIR 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 (AIR only) 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 Player or non-AIR 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).
|
Boolean — true 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 , or ClipboardFormats.BITMAP_FORMAT ).
|
Throws
IllegalOperationError — 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
(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 ( How to use this example )
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 Versions: | Flash Player 10, AIR 1.0 |
Adds a reference to a handler function that produces the data for the specified format on demand.
Use this method to defer creation or rendering of the data until it is actually accessed.
Flash Player requires a user event (such as a key press or mouse click) before using setDataHandler()
.
In AIR, this restriction only applies to content outside of the
application security sandbox.
The handler function must return the appropriate data type for the specified format:
Format | Return Type |
---|---|
ClipboardFormats.TEXT_FORMAT | String |
ClipboardFormats.HTML_FORMAT | String |
ClipboardFormats.URL_FORMAT | String (AIR only) |
ClipboardFormats.RICH_TEXT_FORMAT | ByteArray |
ClipboardFormats.BITMAP_FORMAT | BitmapData (AIR only) |
ClipboardFormats.FILE_LIST_FORMAT | Array of File (AIR only) |
Custom format name | Non-void |
The handler function is called when and only when the data in the specified format is read. 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. Flash Player or AIR might return the data produced by the first function call or it might call the function again. Do not rely on either behavior.
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).
|
Boolean — true if the handler was succesfully set;
false otherwise.
|
Throws
TypeError — format or handler is null .
| |
IllegalOperationError — 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
Example ( How to use this example )
import flash.desktop.ClipboardFormats; Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, randomNumberGenerator); public function randomNumberGenerator():String{ return Math.random().toString(); }
- Write the data, in this case a string, to
Clipboard.generalClipboard
. - 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; } } } }
Fri Mar 19 2010, 02:45 AM -07:00