dataTransfer

NN n/a IE 5(Win) DOM n/a

The dataTransfer object (accessible as a property of the event object) is a temporary container that scripts in IE 5 and later for Windows can use to transfer text data, particularly during script-controlled operations that simulate cutting, copying, and pasting, or that control dragging. Your script controls what data is stored in the dataTransfer object, such as just the text of an element, an element's entire HTML, or the URL of an image. For example, a page for children could display simple icon images of several different kinds of animals. If the user starts dragging the dog icon, the script initiated by the img element's ondragstart event handler can store a custom attribute value of that element (perhaps the URL of a pretty dog photo) into the dataTransfer object. When the user drops the icon into the designated area, the ondrop event handler's function reads the dataTransfer object's data, and loads the photo image into position on the page.

Even though an event object changes its properties with each new event action, the dataTransfer object preserves its data from one event to the next, until a script removes the data from the object or other data is stored in it. Properties of the dataTransfer object distinguish its powers from those of the clipboardData object. By setting the dropEffect and effectAllowed properties, your scripts can control the type of cursor icon that appears during drag and drop operations. Example 9-1 demonstrates how the properties and methods of the dataTransfer object can be wired to dragging events such that the cursor changes to a "copy" style when rolled atop a desired drop target.

For more information on transferring data via this object and the clipboardData object, visit http://msdn.microsoft.com/workshop/author/datatransfer/overview.asp.

HTML Equivalent

None.

Object Model Reference

[window.]event.dataTransfer

Object-Specific Properties

dropEffect

effectAllowed

Object-Specific Methods

clearData( )

getData( )

setData( )

Object-Specific Event Handler Properties

None.

dropEffect, effectAllowed	NN n/a IE 5 DOM n/a
	Read/Write
These two properties work together but at different stages along a dragging operation that involves the dataTransfer object. They both control the appearance of the cursor during the drag and drop process. Assign a cursor style at the beginning of a drag operation via the ondragstart event and effectAllowed property. The drop target's ondragover and ondragenter event handlers should set the dropEffect property to the desired cursor style, and also set the event.returnValue property to false. This opens the way for the ondrop event handler not only to set the cursor via the dropEffect property, but to process the drop action. See Example 9-1 for a simple demonstration of the interaction of all these events and properties.

Example

event.dataTransfer.dropEffect= "copy";

Value
Case-insensitive constant (as a string): copy \| link \| move \| none.

Default
none

clearData( )	NN n/a IE 5(Win) DOM n/a
clearData([dataFormat])
Removes data from the dataTransfer object.

Parameters

`dataFormat` An optional string specifying the format for the data to be removed. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text. Omitting the parameter deletes all data of all types.

Returned Value
None.

getData( )	NN n/a IE 5(Win) DOM n/a
getData(dataFormat)
Returns a copy of data from the dataTransfer object. The dataTransfer contents remain intact for subsequent reading in other script statements.

Parameters

`dataFormat` A string specifying the format for the data to be read. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text.

Returned Value
String.

setData( )	NN n/a IE 5(Win) DOM n/a
setData(dataFormat, stringData)
Stores string data in the dataTransfer object. Returns Boolean true if the assignment is successful

Parameters

`dataFormat` A string specifying the format for the data to be read. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text. While the method accepts URL as a format, reading a set value in that format is not successful. `stringData` Any string value, including strings that contain HTML tags.

Returned Value
Boolean value: true \| false.