mozilla

Revision 48916 of DataTransfer

  • Revision slug: DragDrop/DataTransfer
  • Revision title: DataTransfer
  • Revision id: 48916
  • Created:
  • Creator: SylvainPasche
  • Is current revision? No
  • Comment add anchor for the files property; no wording changes

Revision Content

{{ Fx_minversion_header("3") }} The DataTransfer object is used to hold the data that is being dragged during a drag and drop operation. It may hold one or more data items, each of one or more data types. For more information about drag and drop, see Drag and Drop.

{{ InterfaceStatus("nsIDOMDataTransfer", "dom/public/idl/events/nsIDOMDataTransfer.idl", "unfrozen", "Mozilla 1.9.2", "yes") }}

This object is available from the dataTransfer property of all drag events. It cannot be created separately.

Property overview

Properties Type
dropEffect String
effectAllowed String
files {{ gecko_minversion_inline("1.9.2") }} {{ interface("nsIDOMFileList") }}
mozItemCount unsigned long
types StringList

Method overview

void addElement(in Element image)
void clearData([in String type])
String getData(in String type)
void setData(in String type, in String data)
void setDragImage(in nsIDOMElement image, in long x, in long y)
void mozClearDataAt([in String type, in unsigned long index])
nsIVariant mozGetDataAt(in String type), in unsigned long index)
void mozSetDataAt(in String type, in nsIVariant data, in unsigned long index)
StringList mozTypesAt([in unsigned long index])

Properties

dropEffect

The actual effect that will be used, and should always be one of the possible values of effectAllowed.

For the dragenter and dragover events, the 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 to adjust which action is desired. Within an event handler for the dragenter and dragover events, the dropEffect should be modified if the action the user is requesting is not the one that is desired.

For dragstart, drag, and dragleave events, the dropEffect is initialized to "none". Any value assigned to the dropEffect will be set, but the value isn't used for anything.

For the drop and dragend events, the dropEffect will be initialized to the action that was desired, which will be the value that the dropEffect had after the last dragenter or dragover event.

Possible values:

  • copy: A copy of the source item is made at the new location.
  • move: An item is moved to a new location.
  • link: A link is established to the source at the new location.
  • none: The item may not be dropped.

Assigning any other value has no effect and retains the old value.

effectAllowed

Specifies the effects that are allowed for this drag. You may set this in the dragstart event to set the desired effects for the source, and within the dragenter and dragover events to set the desired effects for the target. The value is not used for other events.

Possible values:

  • copy: A copy of the source item may be made at the new location.
  • move: An item may be moved to a new location.
  • link: A link may be established to the source at the new location.
  • copyLink: A copy or link operation is permitted.
  • copyMove: A copy or move operation is permitted.
  • linkMove: A link or move operation is permitted.
  • all: All operations are permitted.
  • none: the item may not be dropped.
  • uninitialized: the default value when the effect has not been set, equivalent to all.

Assigning any other value has no effect and retains the old value.

files

{{ gecko_minversion_header("1.9.2") }}

Contains a list of all the local files available on the data transfer. If the drag operation doesn't involve dragging files, this property is an empty list. An invalid index access on the {{ interface("nsIDOMFileList") }} specified by this property will return null.

Example

This example dumps the list of files dragged into the browser window.

{{ embed_text("filednd.html", "html") }}

types

Holds a list of the format types of the data that is stored for the first item, in the same order the data was added. An empty list will be returned if no data was added.

mozItemCount

The number of items being dragged.

mozUserCancelled

This property applies only to the dragend event, and will be true if the user cancelled the drag operation by pressing escape. It will be false in all other cases, including if the drag failed for any other reason, for instance due to a drop over an invalid location. This property is not currently implemented on Linux.

Methods

addElement

Set the drag source. Usually you would not change this, but it will affect which node the drag and dragend events are fired at. The default target is the node that was dragged.

 void addElement(
   in Element element
 );
Parameters
element
The element to add.

clearData

Remove the data associated with a given type. The type argument is optional. If the type is empty or not specified, the data associated with all types is removed. If data for the specified type does not exist, or the data transfer contains no data, this method will have no effect.

 void clearData(
   [optional] in String type
 );
Parameters
type
The type of data to remove.

getData

Retrieves the data for a given type, or an empty string if data for that type does not exist or the data transfer contains no data.

A security error will occur if you attempt to retrieve data during a drag that was set from a different domain, or the caller would otherwise not have access to. This data will only be available once a drop occurs during the drop event.

 void getData(
   in String type
 );
Parameters
type
The type of data to retrieve.

setData

Set the data for a given type. If data for the type does not exist, it is added at the end, such that the last item in the types list will be the new format. If data for the 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.

 void setData(
   in String type,
   in String data
 );
Parameters
type
The type of data to add.
data
The data to add.

setDragImage

Set the image to be used for dragging if a custom one is desired. Most of the time, this would not be set, as a default image is created from the node that was dragged.

If the node is an HTML img element, an HTML canvas element or a XUL image element, the image data is used. Otherwise, image should be a visible node and the drag image will be created from this. If image is null, any custom drag image is cleared and the default is used instead.

The coordinates specify the offset into the image where the mouse cursor should be. To center the image for instance, use values that are half the width and height of the image.

 void setDragImage(
   in Element image,
   in long x,
   in long y
 );
Parameters
image
An element to use as the drag feedback image
x
Horizontal offset within the image.
y
Vertical offset within the image.

mozClearDataAt

Remove the data associated with the given format for an item at the specified index. The index is in the range from zero to the number of items minus one.

If the last format for the item is removed, the entire item is removed, reducing mozItemCount by one.

If format is empty, then the data associated with all formats is removed. If the format is not found, then this method has no effect.

 void mozClearDataAt(
   [optional] in String type,
   in unsigned long index
 );
Parameters
type
The type of data to remove.
index
The index of the data to remove.

mozGetDataAt

Retrieve the data associated with the given format for an item at the specified index, or null if it does not exist. The index should be in the range from zero to the number of items minus one.

 nsIVariant mozGetDataAt(
   [optional] in String type,
   in unsigned long index
 );
Parameters
type
The type of data to retrieve.
index
The index of the data to retrieve.

mozSetDataAt

A data transfer may store multiple items, each at a given zero-based index. mozSetDataAt may only be called with an index argument less than mozItemCount in which case an existing item is modified, or equal to mozItemCount in which case a new item is added, and the mozItemCount is incremented by one.

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

The data should be either a string, a primitive boolean or number type (which will be converted into a string) or an nsISupports.

 void mozSetDataAt(
   [optional] in String type,
   in nsIVariant data,
   in unsigned long index
 );
Parameters
type
The type of data to add.
data
The data to add.
index
The index of the data to add.

mozTypesAt

Holds a list of the format types of the data that is stored for an item at the specified index. If the index is not in the range from 0 to the number of items minus one, an empty string list is returned.

 nsIVariant mozTypesAt(
   in unsigned long index
 );
Parameters
index
The index of the data for which to retrieve the types.

See also

Drag and Drop

{{ languages( { "ja": "Ja/DragDrop/DataTransfer" } ) }}

Revision Source

<p>{{ Fx_minversion_header("3") }} The <code>DataTransfer</code> object is used to hold the data that is being dragged during a drag and drop operation. It may hold one or more data items, each of one or more data types. For more information about drag and drop, see <a class="internal" href="/En/DragDrop/Drag_and_Drop" title="En/DragDrop/Drag and Drop">Drag and Drop</a>.</p>
<p>{{ InterfaceStatus("nsIDOMDataTransfer", "dom/public/idl/events/nsIDOMDataTransfer.idl", "unfrozen", "Mozilla 1.9.2", "yes") }}</p>
<p>This object is available from the <code>dataTransfer</code> property of all drag events. It cannot be created separately.</p>
<h2 name="Properties">Property overview</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Properties</td> <td class="header">Type</td> </tr> <tr> <td><code><a href="/En/DragDrop/DataTransfer#dropEffect.28.29" title="en/DragDrop/DataTransfer#dropEffect.28.29">dropEffect</a></code></td> <td><code><a href="/en/String" title="en/String">String</a></code></td> </tr> <tr> <td><code><a href="/En/DragDrop/DataTransfer#effectAllowed.28.29" title="en/DragDrop/DataTransfer#effectAllowed.28.29">effectAllowed</a></code></td> <td><code><a href="/en/String" title="en/String">String</a></code></td> </tr> <tr> <td><a href="/En/DragDrop/DataTransfer#files.28.29" title="en/DragDrop/DataTransfer#files()"><code>files</code></a> {{ gecko_minversion_inline("1.9.2") }}</td> <td>{{ interface("nsIDOMFileList") }}</td> </tr> <tr> <td><code><a href="/En/DragDrop/DataTransfer#mozItemCount.28.29" title="en/DragDrop/DataTransfer#mozItemCount.28.29">mozItemCount</a></code></td> <td><code>unsigned long</code></td> </tr> <tr> <td><code><a href="/En/DragDrop/DataTransfer#types.28.29" title="en/DragDrop/DataTransfer#types.28.29">types</a></code></td> <td><code><a href="/en/DOMStringList" title="en/DOMStringList">StringList</a></code></td> </tr> </tbody>
</table>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#addElement.28.29">addElement</a>(in <a href="/en/XPCOM_Interface_Reference/nsIDOMElement" title="en/nsIDOMElement">Element</a> image)</code></td> </tr> <tr> <td><code>void <a href="#clearData.28.29">clearData</a>([in <a href="/en/String" title="en/String">String</a> type])</code></td> </tr> <tr> <td><code><a href="/en/String" title="en/String">String</a> <a href="#getData.28.29">getData</a>(in <a href="/en/String" title="en/String">String</a> type)</code></td> </tr> <tr> <td><code>void <a href="#setData.28.29">setData</a>(in <a href="/en/String" title="en/String">String</a> type, in <a href="/en/String" title="en/String">String</a> data)</code></td> </tr> <tr> <td><code>void <a href="#setDragImage.28.29">setDragImage</a>(in <a href="/en/XPCOM_Interface_Reference/nsIDOMElement" title="en/nsIDOMElement">nsIDOMElement</a> image, in long x, in long y)</code></td> </tr> <tr> <td><code>void <a href="#mozClearDataAt.28.29">mozClearDataAt</a>([in <a href="/en/String" title="en/String">String</a> type, in unsigned long index])</code></td> </tr> <tr> <td><code><a href="/en/XPCOM_Interface_Reference/NsIVariant" title="en/nsIVariant">nsIVariant</a> <a href="#mozGetDataAt.28.29">mozGetDataAt</a>(in <a href="/en/String" title="en/String">String</a> type), in unsigned long index)</code></td> </tr> <tr> <td><code>void <a href="#mozSetDataAt.28.29">mozSetDataAt</a>(in <a href="/en/String" title="en/String">String</a> type, in <a href="/en/XPCOM_Interface_Reference/NsIVariant" title="en/nsIVariant">nsIVariant</a> data, in unsigned long index)</code></td> </tr> <tr> <td><code><a href="/en/StringList" title="en/StringList">StringList</a> <a href="#mozTypesAt.28.29">mozTypesAt</a>([in unsigned long index])</code></td> </tr> </tbody>
</table>
<h2 name="Properties">Properties</h2>
<h3 name="dropEffect.28.29">dropEffect</h3>
<p>The actual effect that will be used, and should always be one of the possible values of <code>effectAllowed</code>.</p>
<p>For the <code>dragenter</code> and <code>dragover</code> events, the <code>dropEffect</code> 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 to adjust which action is desired. Within an event handler for the <code>dragenter</code> and <code>dragover</code> events, the <code>dropEffect</code> should be modified if the action the user is requesting is not the one that is desired.</p>
<p>For <code>dragstart</code>, <code>drag</code>, and <code>dragleave</code> events, the <code>dropEffect</code> is initialized to "none". Any value assigned to the <code>dropEffect</code> will be set, but the value isn't used for anything.</p>
<p>For the <code>drop</code> and <code>dragend</code> events, the <code>dropEffect</code> will be initialized to the action that was desired, which will be the value that the <code>dropEffect</code> had after the last <code>dragenter</code> or <code>dragover</code> event.</p>
<p>Possible values:</p>
<ul> <li><strong>copy</strong>: A copy of the source item is made at the new location.</li> <li><strong>move</strong>: An item is moved to a new location.</li> <li><strong>link</strong>: A link is established to the source at the new location.</li> <li><strong>none</strong>: The item may not be dropped.</li>
</ul>
<p>Assigning any other value has no effect and retains the old value.</p>
<h3 name="effectAllowed.28.29">effectAllowed</h3>
<p>Specifies the effects that are allowed for this drag. You may set this in the <code>dragstart</code> event to set the desired effects for the source, and within the <code>dragenter</code> and <code>dragover</code> events to set the desired effects for the target. The value is not used for other events.</p>
<p>Possible values:</p>
<ul> <li><strong>copy</strong>: A copy of the source item may be made at the new location.</li> <li><strong>move</strong>: An item may be moved to a new location.</li> <li><strong>link</strong>: A link may be established to the source at the new location.</li> <li><strong>copyLink</strong>: A copy or link operation is permitted.</li> <li><strong>copyMove</strong>: A copy or move operation is permitted.</li> <li><strong>linkMove</strong>: A link or move operation is permitted.</li> <li><strong>all</strong>: All operations are permitted.</li> <li><strong>none</strong>: the item may not be dropped.</li> <li><strong>uninitialized</strong>: the default value when the effect has not been set, equivalent to all.</li>
</ul>
<p>Assigning any other value has no effect and retains the old value.</p>
<h3 name="files.28.29">files</h3>
<p>{{ gecko_minversion_header("1.9.2") }}</p>
<p>Contains a list of all the local files available on the data transfer. If the drag operation doesn't involve dragging files, this property is an empty list. An invalid index access on the {{ interface("nsIDOMFileList") }} specified by this property will return <code>null</code>.</p>
<h4>Example</h4>
<p>This example dumps the list of files dragged into the browser window.</p>
<p>{{ embed_text("filednd.html", "html") }}</p>
<h3 name="types.28.29">types</h3>
<p>Holds a list of the format types of the data that is stored for the first item, in the same order the data was added. An empty list will be returned if no data was added.</p>
<h3 name="mozItemCount.28.29">mozItemCount</h3>
<p>The number of items being dragged.</p>
<h3 name="mozItemCount.28.29">mozUserCancelled</h3>
<p>This property applies only to the dragend event, and will be true if the user cancelled the drag operation by pressing escape. It will be false in all other cases, including if the drag failed for any other reason, for instance due to a drop over an invalid location. This property is not currently implemented on Linux.</p>
<h2 name="Methods">Methods</h2>
<h3 name="addElement.28.29">addElement</h3>
<p>Set the drag source. Usually you would not change this, but it will affect which node the drag and dragend events are fired at. The default target is the node that was dragged.</p>
<pre class="eval"> void addElement(
   in Element element
 );
</pre>
<h6 name="Parameters_addElement">Parameters</h6>
<dl> <dt><code>element </code></dt> <dd>The element to add.</dd>
</dl>
<h3 name="clearData.28.29">clearData</h3>
<p>Remove the data associated with a given type. The type argument is optional. If the type is empty or not specified, the data associated with all types is removed. If data for the specified type does not exist, or the data transfer contains no data, this method will have no effect.</p>
<pre class="eval"> void clearData(
   [optional] in String type
 );
</pre>
<h6 name="Parameters_clearData">Parameters</h6>
<dl> <dt><code>type </code></dt> <dd>The type of data to remove.</dd>
</dl>
<h3 name="getData.28.29">getData</h3>
<p>Retrieves the data for a given type, or an empty string if data for that type does not exist or the data transfer contains no data.</p>
<p>A security error will occur if you attempt to retrieve data during a drag that was set from a different domain, or the caller would otherwise not have access to. This data will only be available once a drop occurs during the drop event.</p>
<pre class="eval"> void getData(
   in String type
 );
</pre>
<h6 name="Parameters_getData">Parameters</h6>
<dl> <dt><code>type </code></dt> <dd>The type of data to retrieve.</dd>
</dl>
<h3 name="setData.28.29">setData</h3>
<p>Set the data for a given type. If data for the type does not exist, it is added at the end, such that the last item in the types list will be the new format. If data for the 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.</p>
<pre class="eval"> void setData(
   in String type,
   in String data
 );
</pre>
<h6 name="Parameters_setData">Parameters</h6>
<dl> <dt><code>type </code></dt> <dd>The type of data to add.</dd> <dt><code>data </code></dt> <dd>The data to add.</dd>
</dl>
<h3 name="setDragImage.28.29">setDragImage</h3>
<p>Set the image to be used for dragging if a custom one is desired. Most of the time, this would not be set, as a default image is created from the node that was dragged.</p>
<p>If the node is an HTML img element, an HTML canvas element or a XUL image element, the image data is used. Otherwise, image should be a visible node and the drag image will be created from this. If image is null, any custom drag image is cleared and the default is used instead.</p>
<p>The coordinates specify the offset into the image where the mouse cursor should be. To center the image for instance, use values that are half the width and height of the image.</p>
<pre class="eval"> void setDragImage(
   in Element image,
   in long x,
   in long y
 );
</pre>
<h6 name="Parameters_setDragImage">Parameters</h6>
<dl> <dt><code>image </code></dt> <dd>An element to use as the drag feedback image</dd> <dt><code>x </code></dt> <dd>Horizontal offset within the image.</dd> <dt><code>y </code></dt> <dd>Vertical offset within the image.</dd>
</dl>
<h3 name="mozClearDataAt.28.29">mozClearDataAt</h3>
<p>Remove the data associated with the given format for an item at the specified index. The index is in the range from zero to the number of items minus one.</p>
<p>If the last format for the item is removed, the entire item is removed, reducing mozItemCount by one.</p>
<p>If format is empty, then the data associated with all formats is removed. If the format is not found, then this method has no effect.</p>
<pre class="eval"> void mozClearDataAt(
   [optional] in String type,
   in unsigned long index
 );
</pre>
<h6 name="Parameters_mozClearDataAt">Parameters</h6>
<dl> <dt><code>type </code></dt> <dd>The type of data to remove.</dd> <dt><code>index </code></dt> <dd>The index of the data to remove.</dd>
</dl>
<h3 name="mozGetDataAt.28.29">mozGetDataAt</h3>
<p>Retrieve the data associated with the given format for an item at the specified index, or null if it does not exist. The index should be in the range from zero to the number of items minus one.</p>
<pre class="eval"> nsIVariant mozGetDataAt(
   [optional] in String type,
   in unsigned long index
 );
</pre>
<h6 name="Parameters_mozClearDataAt">Parameters</h6>
<dl> <dt><code>type </code></dt> <dd>The type of data to retrieve.</dd> <dt><code>index </code></dt> <dd>The index of the data to retrieve.</dd>
</dl>
<h3 name="mozSetDataAt.28.29">mozSetDataAt</h3>
<p>A data transfer may store multiple items, each at a given zero-based index. mozSetDataAt may only be called with an index argument less than mozItemCount in which case an existing item is modified, or equal to mozItemCount in which case a new item is added, and the mozItemCount is incremented by one.</p>
<p>Data should be added in order of preference, with the most specific format added first and the least specific format added last. If data of the given format already exists, it is replaced in the same position as the old data.</p>
<p>The data should be either a string, a primitive boolean or number type (which will be converted into a string) or an nsISupports.</p>
<pre class="eval"> void mozSetDataAt(
   [optional] in String type,
   in nsIVariant data,
   in unsigned long index
 );
</pre>
<h6 name="Parameters_mozSetDataAt">Parameters</h6>
<dl> <dt><code>type </code></dt> <dd>The type of data to add.</dd> <dt><code>data </code></dt> <dd>The data to add.</dd> <dt><code>index </code></dt> <dd>The index of the data to add.</dd>
</dl>
<h3 name="mozTypesAt.28.29">mozTypesAt</h3>
<p>Holds a list of the format types of the data that is stored for an item at the specified index. If the index is not in the range from 0 to the number of items minus one, an empty string list is returned.</p>
<pre class="eval"> nsIVariant mozTypesAt(
   in unsigned long index
 );
</pre>
<h6 name="Parameters_mozTypesAt">Parameters</h6>
<dl> <dt><code>index </code></dt> <dd>The index of the data for which to retrieve the types.</dd>
</dl>
<h2 name="See_also">See also</h2>
<p><a class="internal" href="/En/DragDrop/Drag_and_Drop" title="Drag and Drop">Drag and Drop</a></p>
<p>{{ languages( { "ja": "Ja/DragDrop/DataTransfer" } ) }}</p>
Revert to this revision