View source for XUL:Specs:TransferData

==Current State==

*Clipboard and drag/drop APIs require too much code, and don't really do much of the hard work for you.

==Requirements==

*Should be able to do clipboard and drag/drop operations without complex code.
*Need drag/drop APIs that are unprivileged
*Need to have an event which is fired on the drag source when a drag is cancelled and when a drop is done on another application
*Drag images showing what is being dragged, for example icons or treecells.
*Shouldn't have to serialize and deserialize DOM nodes or other objects when moving between the same application.

The WhatWG defines some [http://whatwg.org/specs/web-apps/current-work/#scs-drag drag and drop] functionality, based on the IE model. It mostly concerns the way the drag/drop events are fired. Need clarfication on it, but it seems that only strings can be specified as the dragged data.

==Security==

*An application should only be able to retrieve items being dragged from the same origin domain. This means that a drag can occur between different domains. For different domains, the drag data is only available to a different domain after the drop.
*Clipboard operations are only available for privileged applications, apart from built in behaviour of widgets or shortcut keys.

<breadcrumbs></breadcrumbs>

= DataTransferItem =

A DataTransferItem holds data to be used for inter-application transfer,
such as the data being dragged during a drag and drop operation or the data
on the clipboard. The data may be provided in multiple formats, where each
format is a MIME type, such as text/plain or image/png. Multiple formats are
used to provide data in more specific formats for those applications that
can receive them, and more general formats for applications that can only
handle certain formats.

The format text/plain should be used for string data. For compatability,
the format text/unicode is equivalent to text/plain. Data stored in either
will be retrievable in either format as well.

The data may be any object, stored as an nsIVariant. In script, nsIVariant
objects may hold any type of data, and will automatically convert between the
script type and the nsIVariant. For instance, a string may supplied directly
to the methods below which accept an nsIVariant as an argument.

Generally, only objects that implement nsISupports and strings are stored.
Other primitive formats such as boolean and integer are converted to strings
when stored.

Data may be added to the DataTransferItem using the addData method. Data
is stored in the order that it is added. Thus, data of formats with greater
specificity should be added first while data that is more general should be
added last. Generally, text/plain string data is the most likely format a
drop target will be able to support at minimum, so this format should be
added last.

All data added to the DataTransferItem is stored with the principal of the caller
adding the data. Code with lower privileges that cannot access objects of that
principal will not be able to access or change the data, and a security exception
will be thrown. For example, if a privileged application adds data, an ordinary
web page will not be able to access data via that flavor, however, it may add
data of other flavors.

More information about formats may be found in [[DataTransferItem:Formats]].

= Methods =

== hasData ==

<code>boolean hasData ( string format )</code>

Determine whether data of the given format is present. Returns true if the
DataTransferItems contains data of the given format, or false otherwise.

'''Parameters'''

<code>format</code>
: the format of the data to look up. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.


== getData ==

<code>nsIVariant getData ( string format )</code>

Retrieve the data for a particular format, or null if data of that format doesn't exist.

'''Parameters'''

<code>format</code>
: the format of the data to retrieve. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.


== getDataInSet ==

<code>nsIVariant getDataInSet ( string formats, out string foundFormat )</code>

Retrieve the data from a set of formats, or null if it doesn't exist. The set of formats is supplied in the formats argument, and is a space separated list of formats to look for. This method will return the data corresponding to the first format that is found, or null if the data was not found. The found format is set in the out argument format.

If the formats argument is an empty string, then the first data of any format is returned.

This method is most useful when the caller wants to retrieve the best data given a set of formats that the caller knows can be supported.

'''Parameters'''

<code>format</code>
: the format of the data to retrieve. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.
<code>foundFormat</code>
: foundFormat will be set to the first format that will be found, or an empty string if no data was found


== setData ==

<code>nsIVariant setData ( string format , nsIVariant data )</code>

Add data to the transferable of the given format. Data should be added in order of preference, with the most specific format first and the least specific format last. If data of the given format already exists, it is replaced in the same position as the old data.

If data implements nsIFlavorDataProvider, the real data will be requested through the flavor data provider only when it is accessed. This would be used when the data is large or when it would be a lengthy computation to compute it.

'''Parameters'''

<code>format</code>
: the format of the data to add. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.
<code>data</code>
: the data to add. If this is null, a null pointer exception will be thrown.


== removeData ==

<code>void removeData ( string format )</code>

Remove the data associated with the given format. If data for that format is not contained within the DataTransferItem, a DOM_NOT_FOUND_ERR exception will be thrown.

'''Parameters'''

<code>formats</code>
: the format of the data to remove. If this is an empty string, a DOM_INVALID_CHARACTER_ERR exception will be thrown.


== allowAnyAccess ==

<code>[noscript] void allowAnyAccess ( )</code>

Indicate that any caller may access the data contained within the transferable, and not just those with appropriate principals. This effectively clears the principals that were stored with the data. This is called when dropping the data.

This non-scriptable method is used by the drag and drop code to allow the data to be accessed within a drop event.

= Properties =

== transferable ==

<code>nsITransferable transferable</code>

Converts the data into an nsITransferable to be used for drag and drop or clipboard operations. Usually, you don't need to call this yourself.

== formats ==

<code>DOMStringList formats</code>

Holds a list of the formats of the data that is stored, in the same order the data was added.

= See Also =

[[DataTransfer]] - used to hold a collection of DataTransferItem objects for drag and drop or clipboard use.

= History =

This interface was added in Mozilla 1.9.