Class DataTransfer

Namespace

CSharpToJavaScript.APIs.JS

Assembly

CSharpToJavaScript.dll

The DataTransfer object is used to hold any data transferred between contexts, such as a drag and drop operation, or clipboard read/write. It may hold one or more data items, each of one or more data types.

[Value("DataTransfer")]
public class DataTransfer

Inheritance

object

DataTransfer

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

DataTransfer was primarily designed for the HTML Drag and Drop API, as the DataTransfer property, and is still specified in the HTML drag-and-drop section, but it is now also used by other APIs, such as ClipboardData and DataTransfer. However, other APIs only use certain parts of its interface, ignoring properties such as dropEffect. Documentation of DataTransfer will primarily discuss its usage in drag-and-drop operations, and you should refer to the other APIs' documentation for usage of DataTransfer in those contexts.

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

Constructors

DataTransfer()

The DataTransfer constructor creates a new
DataTransfer object instance.

public DataTransfer()

Remarks

See also on MDN

Properties

DropEffect

The DataTransfer.dropEffect property controls the
feedback (typically visual) the user is given during a drag and drop operation. It will
affect which cursor is displayed while dragging. For example, when the user hovers over
a target drop element, the browser's cursor may indicate which type of operation will
occur.

[Value("dropEffect")]
public string DropEffect { get; set; }

Property Value

string

A string representing the drag operation effect. The possible values
are:Assigning any other value to dropEffect has no effect and the old value is
retained.

Remarks

When the DataTransfer object is created, dropEffect is set
to a string value. On getting, it returns its current value. On setting, if the new
value is one of the values listed below, then the property's current value will be set
to the new value and other values will be ignored.

For the HTMLElementdragenter and HTMLElementdragover events,
dropEffect will be initialized based on what action the user is requesting.
How this is determined is platform specific, but typically the user can press modifier
keys such as the alt key to adjust the desired action. Within event handlers for
HTMLElementdragenter and HTMLElementdragover events, dropEffect should
be modified if a different action is desired than the action that the user is
requesting.

For the HTMLElementdrop and HTMLElementdragend events, dropEffect will
be set to the action that was desired, which will be the value dropEffect
had after the last HTMLElementdragenter or HTMLElementdragover event. In a
HTMLElementdragend event, for instance, if the desired dropEffect is "move", then the
data being dragged should be removed from the source.

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

EffectAllowed

The DataTransfer.effectAllowed property specifies the
effect that is allowed for a drag operation. The copy operation is used to
indicate that the data being dragged will be copied from its present location to the
drop location. The move operation is used to indicate that the data being
dragged will be moved, and the link operation is used to indicate that some
form of relationship or connection will be created between the source and drop
locations.

[Value("effectAllowed")]
public string EffectAllowed { get; set; }

Property Value

string

A string representing the drag operation that is allowed. The
possible values are:Assigning any other value to effectAllowed has no effect and the old value
is retained.

Remarks

This property should be set in the HTMLElementdragstart event to set the desired drag
effect for the drag source. Within the HTMLElementdragenter and HTMLElementdragover
event handlers, this property will be set to whatever value was assigned during the
HTMLElementdragstart event, thus effectAllowed may be used to determine
which effect is permitted.

Assigning a value to effectAllowed in events other than
HTMLElementdragstart has no effect.

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

Files

The files read-only property of DataTransfer objects is a list of the files in the drag operation. If the operation includes no files, the list is empty.

[Value("files")]
public FileList Files { get; }

Property Value

FileList

A FileList of the files in a drag operation, one list item for
each file in the operation. If the drag operation had no files, the list is empty.

Remarks

This feature can be used to drag files from a user's desktop to the browser.

NOTE

The files property of DataTransfer objects can only be accessed from within the HTMLElementdrop and Elementpaste events. For all other events, the files property will be empty — because its underlying data store will be in a protected mode.

See also on MDN

Items

The read-only items property of the DataTransfer interface is a
DataTransferItemList of the {{domxref("DataTransferItem","data transfer items", "", "nocode")}} in a drag operation. The list includes one item for each item in the operation and if the operation had no items, the list is empty.

[Value("items")]
public DataTransferItemList Items { get; }

Property Value

DataTransferItemList

A DataTransferItemList object containing DataTransferItem
objects representing the items being dragged in a drag operation, one list item for each
object being dragged. If the drag operation had no data, the list is empty.

Remarks

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

Types

The DataTransfer.types read-only property returns the available types that exist in the Items.

[Value("types")]
public string[] Types { get; }

Property Value

string[]

An array of the data formats. Each format is a string
which is generally a MIME type such as text/plain or text/html. If the drag
operation included no data, this list will be empty. If any files are included in
the drag operation, then one of the types will be the string Files.

Remarks

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

Methods

ClearData(string)

The DataTransfer.clearData() method removes the drag
operation's drag data for the given type. If data for the
given type does not exist, this method does nothing.

[Value("clearData")]
public GlobalObject.Undefined ClearData(string format = null)

Parameters

format string

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

If this method is called with no arguments or the format is an empty
string, the data of all types will be removed.

This method does not remove files from the drag operation, so it's possible
for there still to be an entry with the type "Files" left in the object's
Types list if there are any files included in the drag.

NOTE

This method can only be used in the handler for the HTMLElementdragstart event,
because that's the only time the drag operation's data store is writable.

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

GetData(string)

The DataTransfer.getData()
method retrieves drag data (as a string) for the specified type.
If the drag operation does not include data, this method returns an empty
string.

[Value("getData")]
public string GetData(string format)

Parameters

format string

Returns

string

A string representing the drag data for the specified format. If the drag operation has no data or the operation has no data for the specified format, this method returns an empty string.Note that DataTransfer.getData() may not return an expected value, because it only allows reading and writing data for specified events. During the dragstart and drop events, it is safe to access the data. For all other events, the data should be considered unavailable. Despite this, the items and their formats can still be enumerated.

Remarks

Example data types are text/plain and text/uri-list.

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

SetData(string, string)

The DataTransfer.setData() method sets the drag
operation's drag data to the specified data and type. If
data for the given type does not exist, it is added at the end of the drag data store,
such that the last item in the Types list will be
the new type. If data for the given type already exists, the existing data is replaced
in the same position. That is, the order of the
Types list is not changed when replacing data of the
same type.

[Value("setData")]
public GlobalObject.Undefined SetData(string format, string data)

Parameters

format string

data string

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

Example data types are text/plain and text/uri-list.

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN

SetDragImage(Element, long, long)

When a drag occurs, a translucent image is generated from the drag target (the element
the HTMLElementdragstart event is fired at), and follows the mouse pointer during the
drag. This image is created automatically, so you do not need to create it yourself.
However, if a custom image is desired, the
DataTransfer.setDragImage() method can be used to set the
custom image to be used. The image will typically be an img element
but it can also be a canvas or any other visible element.

[Value("setDragImage")]
public GlobalObject.Undefined SetDragImage(Element image, long x, long y)

Parameters

image Element

x long

y long

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

The method's x and y coordinates define how the image should
appear relative to the mouse pointer. These coordinates define the offset into the image
where the mouse cursor should be. For instance, to display the image so that the pointer
is at its center, use values that are half the width and height of the image.

This method must be called in the HTMLElementdragstart event handler.

-Drag and drop
-Drag Operations
-Recommended Drag Types

See also on MDN