[html5] r5650 - [giow] (0) dropzone 4/5, part 1: DataTransferItems (WIP); also contains some Web [...]
whatwg at whatwg.org
whatwg at whatwg.org
Fri Oct 29 11:59:05 PDT 2010
Author: ianh
Date: 2010-10-29 11:59:03 -0700 (Fri, 29 Oct 2010)
New Revision: 5650
Modified:
complete.html
index
source
Log:
[giow] (0) dropzone 4/5, part 1: DataTransferItems (WIP); also contains some WebIDL terminology fixes.
Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=10712
Modified: complete.html
===================================================================
--- complete.html 2010-10-28 23:14:48 UTC (rev 5649)
+++ complete.html 2010-10-29 18:59:03 UTC (rev 5650)
@@ -214,7 +214,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1>Web Applications 1.0</h1>
- <h2 class="no-num no-toc">Draft Standard — 28 October 2010</h2>
+ <h2 class="no-num no-toc">Draft Standard — 29 October 2010</h2>
</hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -959,7 +959,10 @@
<ol>
<li><a href=#introduction-7><span class=secno>8.7.1 </span>Introduction</a></li>
<li><a href=#the-drag-data-store><span class=secno>8.7.2 </span>The drag data store</a></li>
- <li><a href=#the-datatransfer-interface><span class=secno>8.7.3 </span>The <code>DataTransfer</code> interface</a></li>
+ <li><a href=#the-datatransfer-interface><span class=secno>8.7.3 </span>The <code>DataTransfer</code> interface</a>
+ <ol>
+ <li><a href=#the-datatransferitems-interface><span class=secno>8.7.3.1 </span>The <code>DataTransferItems</code> interface</a></li>
+ <li><a href=#the-datatransferitem-interface><span class=secno>8.7.3.2 </span>The <code>DataTransferItem</code> interface</a></ol></li>
<li><a href=#the-dragevent-interface><span class=secno>8.7.4 </span>The <code>DragEvent</code> interface</a></li>
<li><a href=#drag-and-drop-processing-model><span class=secno>8.7.5 </span>Drag-and-drop processing model</a></li>
<li><a href=#dndevents><span class=secno>8.7.6 </span>Events summary</a></li>
@@ -7800,10 +7803,10 @@
for deleting names.</p>
<pre class=idl>interface <dfn id=domstringmap>DOMStringMap</dfn> {
- getter DOMString (in DOMString name);
- setter void (in DOMString name, in DOMString value);
- creator void (in DOMString name, in DOMString value);
- deleter void (in DOMString name);
+ <a href=#dom-domstringmap-nameditem title=dom-DOMStringMap-namedItem>getter</a> DOMString (in DOMString name);
+ <a href=#dom-domstringmap-setitem title=dom-DOMStringMap-setItem>setter</a> void (in DOMString name, in DOMString value);
+ <a href=#dom-domstringmap-additem title=dom-DOMStringMap-addItem>creator</a> void (in DOMString name, in DOMString value);
+ <a href=#dom-domstringmap-removeitem title=dom-DOMStringMap-removeItem>deleter</a> void (in DOMString name);
};</pre>
<p>The <a href=#supported-property-names>supported property names</a> on a
@@ -7811,20 +7814,20 @@
each pair returned from the algorithm for getting the list of
name-value pairs at that instant.</p>
- <p>When a <code><a href=#domstringmap>DOMStringMap</a></code> object is indexed to retrieve a
- named property <var title="">name</var>, the value returned must be
- the value component of the name-value pair whose name component is
- <var title="">name</var> in the list returned by the algorithm for
+ <p>To <dfn id=dom-domstringmap-nameditem title=dom-DOMStringMap-namedItem>determine the value of
+ a named property</dfn> <var title="">name</var> in a
+ <code><a href=#domstringmap>DOMStringMap</a></code>, the user agent must return the value
+ component of the name-value pair whose name component is <var title="">name</var> in the list returned by the algorithm for
getting the list of name-value pairs.</p>
- <p>When a <code><a href=#domstringmap>DOMStringMap</a></code> object is indexed to create or
- modify a named property <var title="">name</var> with value <var title="">value</var>, the algorithm for setting names to certain
- values must be run, passing <var title="">name</var> as the name and
- the result of converting <var title="">value</var> to a
- <code>DOMString</code> as the value.</p>
+ <p>To set the value of a <dfn id=dom-domstringmap-additem title=dom-DOMStringMap-addItem>new</dfn> or <dfn id=dom-domstringmap-setitem title=dom-DOMStringMap-setItem>existing</dfn> named property <var title="">name</var> to value <var title="">value</var>, the
+ algorithm for setting names to certain values must be run, passing
+ <var title="">name</var> as the name and the result of converting
+ <var title="">value</var> to a <code>DOMString</code> as the
+ value.</p>
- <p>When a <code><a href=#domstringmap>DOMStringMap</a></code> object is indexed to delete a
- named property named <var title="">name</var>, the algorithm for
+ <p>To <dfn id=dom-domstringmap-removeitem title=dom-DOMStringMap-removeItem>delete an existing
+ named property</dfn> <var title="">name</var>, the algorithm for
deleting names must be run, passing <var title="">name</var> as the
name.</p>
@@ -33257,14 +33260,14 @@
<p>The object's <a href=#supported-property-indices>supported property indices</a> are the
numbers in the range 0 .. <span title=""><var title="">h</var>×<var title="">w</var>×4-1</span>.</p>
- <p>When a <code><a href=#canvaspixelarray>CanvasPixelArray</a></code> object is <dfn id=dom-canvaspixelarray-get title=dom-CanvasPixelArray-get>indexed to retrieve an indexed
- property</dfn> <var title="">index</var>, the value returned must be
- the value of the <var title="">index</var>th component in the
- array.</p>
+ <p>To <dfn id=dom-canvaspixelarray-get title=dom-CanvasPixelArray-get>determine the value of
+ an indexed property</dfn> <var title="">index</var>, the user agent
+ must return the value of the <var title="">index</var>th component
+ in the array.</p>
- <p>When a <code><a href=#canvaspixelarray>CanvasPixelArray</a></code> object is <dfn id=dom-canvaspixelarray-set title=dom-CanvasPixelArray-set>indexed to modify an indexed
- property</dfn> <var title="">index</var> with value <var title="">value</var>, the value of the <var title="">index</var>th
- component in the array must be set to <var title="">value</var>.</p>
+ <p>To <dfn id=dom-canvaspixelarray-set title=dom-CanvasPixelArray-set>set the value of an
+ existing indexed property</dfn> <var title="">index</var> to value
+ <var title="">value</var>, the value of the <var title="">index</var>th component in the array must be set to <var title="">value</var>.</p>
<p class=note>The width and height (<var title="">w</var> and <var title="">h</var>) might be different from the <var title="">sw</var>
and <var title="">sh</var> arguments to the above methods, e.g. if
@@ -57014,13 +57017,15 @@
range 0 .. <span title=""><var title="">n</var>-1</span>, where <var title="">n</var> is the number returned by the <code title=dom-length><a href=#dom-length>length</a></code> IDL attribute. If <var title="">n</var> is zero then there are no <a href=#supported-property-indices>supported property
indices</a>.</p>
- <p>When a <code><a href=#window>Window</a></code> object is <dfn id=dom-window-item title=dom-window-item>indexed to retrieve an indexed
- property</dfn> <var title="">index</var>, the value returned must be
- the <code><a href=#windowproxy>WindowProxy</a></code> object of the <var title="">index</var>th <a href=#child-browsing-context>child browsing context</a> of the
- <code><a href=#document>Document</a></code> that is nested through an element that is
- <a href=#in-a-document title="in a document">in the <code>Document</code></a>,
- sorted in the <a href=#tree-order>tree order</a> of the elements nesting those
- <a href=#browsing-context title="browsing context">browsing contexts</a>.</p>
+ <p>To <dfn id=dom-window-item title=dom-window-item>determine the value of an indexed
+ property</dfn> <var title="">index</var> of a <code><a href=#window>Window</a></code>
+ object, the user agent must return the <code><a href=#windowproxy>WindowProxy</a></code>
+ object of the <var title="">index</var>th <a href=#child-browsing-context>child browsing
+ context</a> of the <code><a href=#document>Document</a></code> that is nested through
+ an element that is <a href=#in-a-document title="in a document">in the
+ <code>Document</code></a>, sorted in the <a href=#tree-order>tree order</a>
+ of the elements nesting those <a href=#browsing-context title="browsing
+ context">browsing contexts</a>.</p>
<p>These properties are the <dfn id=dynamic-nested-browsing-context-properties>dynamic nested browsing context
properties</dfn>.</p>
@@ -65760,31 +65765,6 @@
I can provide the File object that corresponds to it
eventually".
- * Exposing more information about each item. Best idea (from
- Eduard Pascual) is to have a new attribute on dataTransfer
- that's a list of items, each of which has:
-
- dataTransfer.items = DataTransferItems
-
- DataTransferItems.length
- .getItem(n) = DataTransferItem
- .add(stringData, type)
- .add(blobData)
- .add(fileData)
- .add(dataTransferItem)
- .add(promise)
- .clear()
-
- DataTransferItem.kind = 'string', 'file', 'blob', ...
- .type = MIME type
- .binaryOnly
- .getTextData(function callback (data)) - throws if binary is true
- .getBlob() - returns File or Blob (which are async anyway)
-
- DataTransferPromise.type = 'string' or 'file' or 'blob'
- .onneeddata - can wait until this fires to provide data
- .setData() - call this once you have data, must be the right type
-
-->
<p>This section defines an event-based drag-and-drop mechanism.</p>
@@ -65959,7 +65939,7 @@
<dl><dt><i>Plain Unicode string</i></dt>
<dd>
- <p>Raw text.</p>
+ <p>Text.</p>
</dd>
<dt><i>Blob</i></dt>
@@ -65972,13 +65952,20 @@
<p>Binary data with a file name.</p>
</dd>
+<!-- v2:
+ <dt><i>Structured object</i></dt>
+ <dd>
+ <p>An object that will be cloned using the <span>structured clone</span> algorithm.</p>
+ </dd>
+-->
+
</dl></dd>
<dt>The actual data</dt>
<dd><p>A Unicode or binary string, optionally with a file name
- (itself a Unicode string), as per <a href=#the-drag-data-item-kind>the drag data item
- kind</a>.</dd>
+ (itself a Unicode string), <!-- (v2:) or an object, --> as per
+ <a href=#the-drag-data-item-kind>the drag data item kind</a>.</dd>
</dl></li>
@@ -66160,16 +66147,6 @@
</dl><p><code><a href=#datatransfer>DataTransfer</a></code> objects are used during the <a href=#dndevents>drag-and-drop events</a>, and are only valid while
those events are being dispatched.</p>
-<!--
-
-XXX
-
-plan:
- 4. expose model with new API
- 5. add dropzone="..." feature
-
--->
-
<div class=impl>
<p>A <code><a href=#datatransfer>DataTransfer</a></code> object is associated with a
@@ -66360,6 +66337,11 @@
</ol><p class=note>This version of the API does not expose the types of
the files during the drag.</p>
+ <p>The <dfn id=dom-datatransfer-items title=dom-DataTransfer-items><code>items</code></dfn>
+ attribute must return a <code><a href=#datatransferitems>DataTransferItems</a></code> object
+ associated with the <code><a href=#datatransfer>DataTransfer</a></code> object. The same
+ object must be returned each time.</p>
+
<p>The <dfn id=dom-datatransfer-setdragimage title=dom-DataTransfer-setDragImage><code>setDragImage(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>)</code></dfn> method must run the following
steps:</p>
@@ -66407,7 +66389,157 @@
</div>
+ <h5 id=the-datatransferitems-interface><span class=secno>8.7.3.1 </span>The <code><a href=#datatransferitems>DataTransferItems</a></code> interface</h5>
+ <p>Each <code><a href=#datatransfer>DataTransfer</a></code> object is associated with a
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object.</p>
+
+ <pre class=idl>interface <dfn id=datatransferitems>DataTransferItems</dfn> {
+ readonly attribute unsigned long <a href=#dom-datatransferitems-length title=dom-DataTransferItems-length>length</a>;
+ <a href=#dom-datatransferitems-item title=dom-DataTransferItems-item>getter</a> <span>DataTransferItem</span> (in unsigned long index);
+ <a href=#dom-datatransferitems-removeitem title=dom-DataTransferItems-removeItem>deleter</a> void (in unsigned long index);
+ void <a href=#dom-datatransferitems-clear title=dom-DataTransferItems-clear>clear</a>();
+
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in DOMString data, in DOMString type);
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in <span>Blob</span> data);
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in <span>File</span> data);
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in <span>DataTransferItem</span> data);<!--
+v2: <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in any data, in DOMString type);--><!--
+v3: <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in <span>DataTransferPromise</span> data);-->
+};</pre>
+
+ <dl class=domintro><dt><var title="">items</var> . <code title=dom-DataTransferItems-length><a href=#dom-datatransferitems-length>length</a></code></dt>
+
+ <dd><p>Returns the number of items in the <a href=#drag-data-store>drag data store</a>.</dd>
+
+
+ <dt><var title="">items</var>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Returns the <code>DataTransferItem</code> object representing the <var title="">index</var>th entry in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ </dd>
+
+
+ <dt><code title="">delete</code> <var title="">items</var>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Removes the <var title="">index</var>th entry in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ </dd>
+
+
+ <dt><var title="">items</var> . <code title=dom-DataTransferItems-clear><a href=#dom-datatransferitems-clear>clear</a></code>()</dt>
+
+ <dd>
+
+ <p>Removes all the entries in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ </dd>
+
+
+ <dt><var title="">items</var> . <code title=dom-DataTransferItems-add>add</code>(<var title="">data</var>)</dt>
+ <dt><var title="">items</var> . <code title=dom-DataTransferItems-add>add</code>(<var title="">data</var>, <var title="">type</var>)</dt>
+
+ <dd>
+
+ <p>Adds a new entry for the given data to the <a href=#drag-data-store>drag data
+ store</a>. If the data is plain text <!-- v2: or an object -->
+ then a <var title="">type</var> string has to be provided
+ also.</p>
+
+ </dd>
+
+ </dl><div class=impl>
+
+ <p>While the <code><a href=#datatransferitems>DataTransferItems</a></code> object's
+ <code><a href=#datatransfer>DataTransfer</a></code> object is associated with a <a href=#drag-data-store>drag
+ data store</a>, the <code><a href=#datatransferitems>DataTransferItems</a></code> object's
+ <i>mode</i> is the same as the <a href=#drag-data-store-mode>drag data store mode</a>.
+ When the <code><a href=#datatransferitems>DataTransferItems</a></code> object's
+ <code><a href=#datatransfer>DataTransfer</a></code> object is <em>not</em> associated with a
+ <a href=#drag-data-store>drag data store</a>, the <code><a href=#datatransferitems>DataTransferItems</a></code>
+ object's <i>mode</i> is <i>disabled mode</i>. The <a href=#drag-data-store>drag data
+ store</a> referenced in this section (which is used only when the
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object is not in the <i>disabled
+ mode</i>) is the <a href=#drag-data-store>drag data store</a> with which the
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object's <code><a href=#datatransfer>DataTransfer</a></code>
+ object is associated.</p>
+
+ <p>The <dfn id=dom-datatransferitems-length title=dom-DataTransferItems-length><code>length</code></dfn>
+ attribute must return zero if the object is in the <i>disabled
+ mode</i>; otherwise it must return the number of items in the
+ <a href=#drag-data-store-item-list>drag data store item list</a>.</p>
+
+ <p>When a <code><a href=#datatransferitems>DataTransferItems</a></code> object is not in the
+ <i>disabled mode</i>, its <a href=#supported-property-indices>supported property indices</a>
+ are the numbers in the range
+
+ <span title="">0 .. <var title="">n</var>-1</span>,
+
+ where <var title="">n</var> is the number of items in the <a href=#drag-data-store-item-list>drag
+ data store item list</a>.</p>
+
+ <p>To <dfn id=dom-datatransferitems-item title=dom-DataTransferItems-item>determine the value of
+ an indexed property</dfn> <var title="">i</var> of a
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object, the user agent must return a
+ <code>DataTransferItem</code> object representing the <var title="">i</var>th item in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ <p>To <dfn id=dom-datatransferitems-removeitem title=dom-DataTransferItems-removeItem>delete an
+ existing indexed property</dfn> <var title="">i</var> of a
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object, the user agent must run these
+ steps:</p>
+
+ <ol><li><p>If the <code><a href=#datatransferitems>DataTransferItems</a></code> object is not in the
+ <i title=concept-dnd-rw><a href=#concept-dnd-rw>read/write mode</a></i>, throw an
+ <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception and abort these
+ steps.</li>
+
+ <li><p>Remove the <var title="">i</var>th item from the <a href=#drag-data-store>drag
+ data store</a>.</li>
+
+ </ol><p>The <dfn id=dom-datatransferitems-clear title=dom-DataTransferItems-clear><code>clear</code></dfn> method,
+ if the <code><a href=#datatransferitems>DataTransferItems</a></code> object is in the <i title=concept-dnd-rw><a href=#concept-dnd-rw>read/write mode</a></i>, must remove all the
+ items from the <a href=#drag-data-store>drag data store</a>. Otherwise, it must do
+ nothing.</p>
+
+ </div>
+
+
+ <h5 id=the-datatransferitem-interface><span class=secno>8.7.3.2 </span>The <code>DataTransferItem</code> interface</h5>
+
+ <p class=XXX>...</p>
+
+<!--
+
+ DataTransferItem.kind = 'string', 'file', 'blob', 'data'?, ...
+ .type = MIME type
+ .getTextData(function callback (data)) - throws if kind is not 'string'
+ .getRawData(function callback (data)) - throws if kind is not 'data'
+ .getBlob() - returns File or Blob (which are async anyway); throws if kind is 'data'
+
+ DataTransferPromise.type = 'string' or 'file' or 'blob' or 'data'
+ .onneeddata - can wait until this fires to provide data
+ .setData() - call this once you have data, must be the right type
+-->
+
+<!-- xxx mention that if an item is removed from a data store, DataTransferItem objects become unusable -->
+
+
+<!--
+
+XXX DND WIP
+
+plan:
+ 4. expose model with new API
+ 5. add dropzone="..." feature
+
+-->
+
+
+
<h4 id=the-dragevent-interface><span class=secno>8.7.4 </span>The <code><a href=#dragevent>DragEvent</a></code> interface</h4>
<p>The drag-and-drop processing model involves several events. They
Modified: index
===================================================================
--- index 2010-10-28 23:14:48 UTC (rev 5649)
+++ index 2010-10-29 18:59:03 UTC (rev 5650)
@@ -218,7 +218,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1>HTML5 (including next generation additions still in development)</h1>
- <h2 class="no-num no-toc">Draft Standard — 28 October 2010</h2>
+ <h2 class="no-num no-toc">Draft Standard — 29 October 2010</h2>
</hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -966,7 +966,10 @@
<ol>
<li><a href=#introduction-7><span class=secno>8.7.1 </span>Introduction</a></li>
<li><a href=#the-drag-data-store><span class=secno>8.7.2 </span>The drag data store</a></li>
- <li><a href=#the-datatransfer-interface><span class=secno>8.7.3 </span>The <code>DataTransfer</code> interface</a></li>
+ <li><a href=#the-datatransfer-interface><span class=secno>8.7.3 </span>The <code>DataTransfer</code> interface</a>
+ <ol>
+ <li><a href=#the-datatransferitems-interface><span class=secno>8.7.3.1 </span>The <code>DataTransferItems</code> interface</a></li>
+ <li><a href=#the-datatransferitem-interface><span class=secno>8.7.3.2 </span>The <code>DataTransferItem</code> interface</a></ol></li>
<li><a href=#the-dragevent-interface><span class=secno>8.7.4 </span>The <code>DragEvent</code> interface</a></li>
<li><a href=#drag-and-drop-processing-model><span class=secno>8.7.5 </span>Drag-and-drop processing model</a></li>
<li><a href=#dndevents><span class=secno>8.7.6 </span>Events summary</a></li>
@@ -7777,10 +7780,10 @@
for deleting names.</p>
<pre class=idl>interface <dfn id=domstringmap>DOMStringMap</dfn> {
- getter DOMString (in DOMString name);
- setter void (in DOMString name, in DOMString value);
- creator void (in DOMString name, in DOMString value);
- deleter void (in DOMString name);
+ <a href=#dom-domstringmap-nameditem title=dom-DOMStringMap-namedItem>getter</a> DOMString (in DOMString name);
+ <a href=#dom-domstringmap-setitem title=dom-DOMStringMap-setItem>setter</a> void (in DOMString name, in DOMString value);
+ <a href=#dom-domstringmap-additem title=dom-DOMStringMap-addItem>creator</a> void (in DOMString name, in DOMString value);
+ <a href=#dom-domstringmap-removeitem title=dom-DOMStringMap-removeItem>deleter</a> void (in DOMString name);
};</pre>
<p>The <a href=#supported-property-names>supported property names</a> on a
@@ -7788,20 +7791,20 @@
each pair returned from the algorithm for getting the list of
name-value pairs at that instant.</p>
- <p>When a <code><a href=#domstringmap>DOMStringMap</a></code> object is indexed to retrieve a
- named property <var title="">name</var>, the value returned must be
- the value component of the name-value pair whose name component is
- <var title="">name</var> in the list returned by the algorithm for
+ <p>To <dfn id=dom-domstringmap-nameditem title=dom-DOMStringMap-namedItem>determine the value of
+ a named property</dfn> <var title="">name</var> in a
+ <code><a href=#domstringmap>DOMStringMap</a></code>, the user agent must return the value
+ component of the name-value pair whose name component is <var title="">name</var> in the list returned by the algorithm for
getting the list of name-value pairs.</p>
- <p>When a <code><a href=#domstringmap>DOMStringMap</a></code> object is indexed to create or
- modify a named property <var title="">name</var> with value <var title="">value</var>, the algorithm for setting names to certain
- values must be run, passing <var title="">name</var> as the name and
- the result of converting <var title="">value</var> to a
- <code>DOMString</code> as the value.</p>
+ <p>To set the value of a <dfn id=dom-domstringmap-additem title=dom-DOMStringMap-addItem>new</dfn> or <dfn id=dom-domstringmap-setitem title=dom-DOMStringMap-setItem>existing</dfn> named property <var title="">name</var> to value <var title="">value</var>, the
+ algorithm for setting names to certain values must be run, passing
+ <var title="">name</var> as the name and the result of converting
+ <var title="">value</var> to a <code>DOMString</code> as the
+ value.</p>
- <p>When a <code><a href=#domstringmap>DOMStringMap</a></code> object is indexed to delete a
- named property named <var title="">name</var>, the algorithm for
+ <p>To <dfn id=dom-domstringmap-removeitem title=dom-DOMStringMap-removeItem>delete an existing
+ named property</dfn> <var title="">name</var>, the algorithm for
deleting names must be run, passing <var title="">name</var> as the
name.</p>
@@ -33237,14 +33240,14 @@
<p>The object's <a href=#supported-property-indices>supported property indices</a> are the
numbers in the range 0 .. <span title=""><var title="">h</var>×<var title="">w</var>×4-1</span>.</p>
- <p>When a <code><a href=#canvaspixelarray>CanvasPixelArray</a></code> object is <dfn id=dom-canvaspixelarray-get title=dom-CanvasPixelArray-get>indexed to retrieve an indexed
- property</dfn> <var title="">index</var>, the value returned must be
- the value of the <var title="">index</var>th component in the
- array.</p>
+ <p>To <dfn id=dom-canvaspixelarray-get title=dom-CanvasPixelArray-get>determine the value of
+ an indexed property</dfn> <var title="">index</var>, the user agent
+ must return the value of the <var title="">index</var>th component
+ in the array.</p>
- <p>When a <code><a href=#canvaspixelarray>CanvasPixelArray</a></code> object is <dfn id=dom-canvaspixelarray-set title=dom-CanvasPixelArray-set>indexed to modify an indexed
- property</dfn> <var title="">index</var> with value <var title="">value</var>, the value of the <var title="">index</var>th
- component in the array must be set to <var title="">value</var>.</p>
+ <p>To <dfn id=dom-canvaspixelarray-set title=dom-CanvasPixelArray-set>set the value of an
+ existing indexed property</dfn> <var title="">index</var> to value
+ <var title="">value</var>, the value of the <var title="">index</var>th component in the array must be set to <var title="">value</var>.</p>
<p class=note>The width and height (<var title="">w</var> and <var title="">h</var>) might be different from the <var title="">sw</var>
and <var title="">sh</var> arguments to the above methods, e.g. if
@@ -56994,13 +56997,15 @@
range 0 .. <span title=""><var title="">n</var>-1</span>, where <var title="">n</var> is the number returned by the <code title=dom-length><a href=#dom-length>length</a></code> IDL attribute. If <var title="">n</var> is zero then there are no <a href=#supported-property-indices>supported property
indices</a>.</p>
- <p>When a <code><a href=#window>Window</a></code> object is <dfn id=dom-window-item title=dom-window-item>indexed to retrieve an indexed
- property</dfn> <var title="">index</var>, the value returned must be
- the <code><a href=#windowproxy>WindowProxy</a></code> object of the <var title="">index</var>th <a href=#child-browsing-context>child browsing context</a> of the
- <code><a href=#document>Document</a></code> that is nested through an element that is
- <a href=#in-a-document title="in a document">in the <code>Document</code></a>,
- sorted in the <a href=#tree-order>tree order</a> of the elements nesting those
- <a href=#browsing-context title="browsing context">browsing contexts</a>.</p>
+ <p>To <dfn id=dom-window-item title=dom-window-item>determine the value of an indexed
+ property</dfn> <var title="">index</var> of a <code><a href=#window>Window</a></code>
+ object, the user agent must return the <code><a href=#windowproxy>WindowProxy</a></code>
+ object of the <var title="">index</var>th <a href=#child-browsing-context>child browsing
+ context</a> of the <code><a href=#document>Document</a></code> that is nested through
+ an element that is <a href=#in-a-document title="in a document">in the
+ <code>Document</code></a>, sorted in the <a href=#tree-order>tree order</a>
+ of the elements nesting those <a href=#browsing-context title="browsing
+ context">browsing contexts</a>.</p>
<p>These properties are the <dfn id=dynamic-nested-browsing-context-properties>dynamic nested browsing context
properties</dfn>.</p>
@@ -65766,31 +65771,6 @@
I can provide the File object that corresponds to it
eventually".
- * Exposing more information about each item. Best idea (from
- Eduard Pascual) is to have a new attribute on dataTransfer
- that's a list of items, each of which has:
-
- dataTransfer.items = DataTransferItems
-
- DataTransferItems.length
- .getItem(n) = DataTransferItem
- .add(stringData, type)
- .add(blobData)
- .add(fileData)
- .add(dataTransferItem)
- .add(promise)
- .clear()
-
- DataTransferItem.kind = 'string', 'file', 'blob', ...
- .type = MIME type
- .binaryOnly
- .getTextData(function callback (data)) - throws if binary is true
- .getBlob() - returns File or Blob (which are async anyway)
-
- DataTransferPromise.type = 'string' or 'file' or 'blob'
- .onneeddata - can wait until this fires to provide data
- .setData() - call this once you have data, must be the right type
-
-->
<p>This section defines an event-based drag-and-drop mechanism.</p>
@@ -65965,7 +65945,7 @@
<dl><dt><i>Plain Unicode string</i></dt>
<dd>
- <p>Raw text.</p>
+ <p>Text.</p>
</dd>
<dt><i>Blob</i></dt>
@@ -65978,13 +65958,20 @@
<p>Binary data with a file name.</p>
</dd>
+<!-- v2:
+ <dt><i>Structured object</i></dt>
+ <dd>
+ <p>An object that will be cloned using the <span>structured clone</span> algorithm.</p>
+ </dd>
+-->
+
</dl></dd>
<dt>The actual data</dt>
<dd><p>A Unicode or binary string, optionally with a file name
- (itself a Unicode string), as per <a href=#the-drag-data-item-kind>the drag data item
- kind</a>.</dd>
+ (itself a Unicode string), <!-- (v2:) or an object, --> as per
+ <a href=#the-drag-data-item-kind>the drag data item kind</a>.</dd>
</dl></li>
@@ -66166,16 +66153,6 @@
</dl><p><code><a href=#datatransfer>DataTransfer</a></code> objects are used during the <a href=#dndevents>drag-and-drop events</a>, and are only valid while
those events are being dispatched.</p>
-<!--
-
-XXX
-
-plan:
- 4. expose model with new API
- 5. add dropzone="..." feature
-
--->
-
<div class=impl>
<p>A <code><a href=#datatransfer>DataTransfer</a></code> object is associated with a
@@ -66366,6 +66343,11 @@
</ol><p class=note>This version of the API does not expose the types of
the files during the drag.</p>
+ <p>The <dfn id=dom-datatransfer-items title=dom-DataTransfer-items><code>items</code></dfn>
+ attribute must return a <code><a href=#datatransferitems>DataTransferItems</a></code> object
+ associated with the <code><a href=#datatransfer>DataTransfer</a></code> object. The same
+ object must be returned each time.</p>
+
<p>The <dfn id=dom-datatransfer-setdragimage title=dom-DataTransfer-setDragImage><code>setDragImage(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>)</code></dfn> method must run the following
steps:</p>
@@ -66413,7 +66395,157 @@
</div>
+ <h5 id=the-datatransferitems-interface><span class=secno>8.7.3.1 </span>The <code><a href=#datatransferitems>DataTransferItems</a></code> interface</h5>
+ <p>Each <code><a href=#datatransfer>DataTransfer</a></code> object is associated with a
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object.</p>
+
+ <pre class=idl>interface <dfn id=datatransferitems>DataTransferItems</dfn> {
+ readonly attribute unsigned long <a href=#dom-datatransferitems-length title=dom-DataTransferItems-length>length</a>;
+ <a href=#dom-datatransferitems-item title=dom-DataTransferItems-item>getter</a> <span>DataTransferItem</span> (in unsigned long index);
+ <a href=#dom-datatransferitems-removeitem title=dom-DataTransferItems-removeItem>deleter</a> void (in unsigned long index);
+ void <a href=#dom-datatransferitems-clear title=dom-DataTransferItems-clear>clear</a>();
+
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in DOMString data, in DOMString type);
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in <span>Blob</span> data);
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in <span>File</span> data);
+ <span>DataTransferItem</span> <span title=dom-DataTransferItems-add>add</span>(in <span>DataTransferItem</span> data);<!--
+v2: <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in any data, in DOMString type);--><!--
+v3: <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in <span>DataTransferPromise</span> data);-->
+};</pre>
+
+ <dl class=domintro><dt><var title="">items</var> . <code title=dom-DataTransferItems-length><a href=#dom-datatransferitems-length>length</a></code></dt>
+
+ <dd><p>Returns the number of items in the <a href=#drag-data-store>drag data store</a>.</dd>
+
+
+ <dt><var title="">items</var>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Returns the <code>DataTransferItem</code> object representing the <var title="">index</var>th entry in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ </dd>
+
+
+ <dt><code title="">delete</code> <var title="">items</var>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Removes the <var title="">index</var>th entry in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ </dd>
+
+
+ <dt><var title="">items</var> . <code title=dom-DataTransferItems-clear><a href=#dom-datatransferitems-clear>clear</a></code>()</dt>
+
+ <dd>
+
+ <p>Removes all the entries in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ </dd>
+
+
+ <dt><var title="">items</var> . <code title=dom-DataTransferItems-add>add</code>(<var title="">data</var>)</dt>
+ <dt><var title="">items</var> . <code title=dom-DataTransferItems-add>add</code>(<var title="">data</var>, <var title="">type</var>)</dt>
+
+ <dd>
+
+ <p>Adds a new entry for the given data to the <a href=#drag-data-store>drag data
+ store</a>. If the data is plain text <!-- v2: or an object -->
+ then a <var title="">type</var> string has to be provided
+ also.</p>
+
+ </dd>
+
+ </dl><div class=impl>
+
+ <p>While the <code><a href=#datatransferitems>DataTransferItems</a></code> object's
+ <code><a href=#datatransfer>DataTransfer</a></code> object is associated with a <a href=#drag-data-store>drag
+ data store</a>, the <code><a href=#datatransferitems>DataTransferItems</a></code> object's
+ <i>mode</i> is the same as the <a href=#drag-data-store-mode>drag data store mode</a>.
+ When the <code><a href=#datatransferitems>DataTransferItems</a></code> object's
+ <code><a href=#datatransfer>DataTransfer</a></code> object is <em>not</em> associated with a
+ <a href=#drag-data-store>drag data store</a>, the <code><a href=#datatransferitems>DataTransferItems</a></code>
+ object's <i>mode</i> is <i>disabled mode</i>. The <a href=#drag-data-store>drag data
+ store</a> referenced in this section (which is used only when the
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object is not in the <i>disabled
+ mode</i>) is the <a href=#drag-data-store>drag data store</a> with which the
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object's <code><a href=#datatransfer>DataTransfer</a></code>
+ object is associated.</p>
+
+ <p>The <dfn id=dom-datatransferitems-length title=dom-DataTransferItems-length><code>length</code></dfn>
+ attribute must return zero if the object is in the <i>disabled
+ mode</i>; otherwise it must return the number of items in the
+ <a href=#drag-data-store-item-list>drag data store item list</a>.</p>
+
+ <p>When a <code><a href=#datatransferitems>DataTransferItems</a></code> object is not in the
+ <i>disabled mode</i>, its <a href=#supported-property-indices>supported property indices</a>
+ are the numbers in the range
+
+ <span title="">0 .. <var title="">n</var>-1</span>,
+
+ where <var title="">n</var> is the number of items in the <a href=#drag-data-store-item-list>drag
+ data store item list</a>.</p>
+
+ <p>To <dfn id=dom-datatransferitems-item title=dom-DataTransferItems-item>determine the value of
+ an indexed property</dfn> <var title="">i</var> of a
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object, the user agent must return a
+ <code>DataTransferItem</code> object representing the <var title="">i</var>th item in the <a href=#drag-data-store>drag data store</a>.</p>
+
+ <p>To <dfn id=dom-datatransferitems-removeitem title=dom-DataTransferItems-removeItem>delete an
+ existing indexed property</dfn> <var title="">i</var> of a
+ <code><a href=#datatransferitems>DataTransferItems</a></code> object, the user agent must run these
+ steps:</p>
+
+ <ol><li><p>If the <code><a href=#datatransferitems>DataTransferItems</a></code> object is not in the
+ <i title=concept-dnd-rw><a href=#concept-dnd-rw>read/write mode</a></i>, throw an
+ <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception and abort these
+ steps.</li>
+
+ <li><p>Remove the <var title="">i</var>th item from the <a href=#drag-data-store>drag
+ data store</a>.</li>
+
+ </ol><p>The <dfn id=dom-datatransferitems-clear title=dom-DataTransferItems-clear><code>clear</code></dfn> method,
+ if the <code><a href=#datatransferitems>DataTransferItems</a></code> object is in the <i title=concept-dnd-rw><a href=#concept-dnd-rw>read/write mode</a></i>, must remove all the
+ items from the <a href=#drag-data-store>drag data store</a>. Otherwise, it must do
+ nothing.</p>
+
+ </div>
+
+
+ <h5 id=the-datatransferitem-interface><span class=secno>8.7.3.2 </span>The <code>DataTransferItem</code> interface</h5>
+
+ <p class=XXX>...</p>
+
+<!--
+
+ DataTransferItem.kind = 'string', 'file', 'blob', 'data'?, ...
+ .type = MIME type
+ .getTextData(function callback (data)) - throws if kind is not 'string'
+ .getRawData(function callback (data)) - throws if kind is not 'data'
+ .getBlob() - returns File or Blob (which are async anyway); throws if kind is 'data'
+
+ DataTransferPromise.type = 'string' or 'file' or 'blob' or 'data'
+ .onneeddata - can wait until this fires to provide data
+ .setData() - call this once you have data, must be the right type
+-->
+
+<!-- xxx mention that if an item is removed from a data store, DataTransferItem objects become unusable -->
+
+
+<!--
+
+XXX DND WIP
+
+plan:
+ 4. expose model with new API
+ 5. add dropzone="..." feature
+
+-->
+
+
+
<h4 id=the-dragevent-interface><span class=secno>8.7.4 </span>The <code><a href=#dragevent>DragEvent</a></code> interface</h4>
<p>The drag-and-drop processing model involves several events. They
Modified: source
===================================================================
--- source 2010-10-28 23:14:48 UTC (rev 5649)
+++ source 2010-10-29 18:59:03 UTC (rev 5650)
@@ -7673,10 +7673,10 @@
for deleting names.</p>
<pre class="idl">interface <dfn>DOMStringMap</dfn> {
- getter DOMString (in DOMString name);
- setter void (in DOMString name, in DOMString value);
- creator void (in DOMString name, in DOMString value);
- deleter void (in DOMString name);
+ <span title="dom-DOMStringMap-namedItem">getter</span> DOMString (in DOMString name);
+ <span title="dom-DOMStringMap-setItem">setter</span> void (in DOMString name, in DOMString value);
+ <span title="dom-DOMStringMap-addItem">creator</span> void (in DOMString name, in DOMString value);
+ <span title="dom-DOMStringMap-removeItem">deleter</span> void (in DOMString name);
};</pre>
<p>The <span>supported property names</span> on a
@@ -7684,21 +7684,24 @@
each pair returned from the algorithm for getting the list of
name-value pairs at that instant.</p>
- <p>When a <code>DOMStringMap</code> object is indexed to retrieve a
- named property <var title="">name</var>, the value returned must be
- the value component of the name-value pair whose name component is
- <var title="">name</var> in the list returned by the algorithm for
+ <p>To <dfn title="dom-DOMStringMap-namedItem">determine the value of
+ a named property</dfn> <var title="">name</var> in a
+ <code>DOMStringMap</code>, the user agent must return the value
+ component of the name-value pair whose name component is <var
+ title="">name</var> in the list returned by the algorithm for
getting the list of name-value pairs.</p>
- <p>When a <code>DOMStringMap</code> object is indexed to create or
- modify a named property <var title="">name</var> with value <var
- title="">value</var>, the algorithm for setting names to certain
- values must be run, passing <var title="">name</var> as the name and
- the result of converting <var title="">value</var> to a
- <code>DOMString</code> as the value.</p>
+ <p>To set the value of a <dfn
+ title="dom-DOMStringMap-addItem">new</dfn> or <dfn
+ title="dom-DOMStringMap-setItem">existing</dfn> named property <var
+ title="">name</var> to value <var title="">value</var>, the
+ algorithm for setting names to certain values must be run, passing
+ <var title="">name</var> as the name and the result of converting
+ <var title="">value</var> to a <code>DOMString</code> as the
+ value.</p>
- <p>When a <code>DOMStringMap</code> object is indexed to delete a
- named property named <var title="">name</var>, the algorithm for
+ <p>To <dfn title="dom-DOMStringMap-removeItem">delete an existing
+ named property</dfn> <var title="">name</var>, the algorithm for
deleting names must be run, passing <var title="">name</var> as the
name.</p>
@@ -36735,17 +36738,16 @@
numbers in the range 0 .. <span title=""><var
title="">h</var>×<var title="">w</var>×4-1</span>.</p>
- <p>When a <code>CanvasPixelArray</code> object is <dfn
- title="dom-CanvasPixelArray-get">indexed to retrieve an indexed
- property</dfn> <var title="">index</var>, the value returned must be
- the value of the <var title="">index</var>th component in the
- array.</p>
+ <p>To <dfn title="dom-CanvasPixelArray-get">determine the value of
+ an indexed property</dfn> <var title="">index</var>, the user agent
+ must return the value of the <var title="">index</var>th component
+ in the array.</p>
- <p>When a <code>CanvasPixelArray</code> object is <dfn
- title="dom-CanvasPixelArray-set">indexed to modify an indexed
- property</dfn> <var title="">index</var> with value <var
- title="">value</var>, the value of the <var title="">index</var>th
- component in the array must be set to <var title="">value</var>.</p>
+ <p>To <dfn title="dom-CanvasPixelArray-set">set the value of an
+ existing indexed property</dfn> <var title="">index</var> to value
+ <var title="">value</var>, the value of the <var
+ title="">index</var>th component in the array must be set to <var
+ title="">value</var>.</p>
<p class="note">The width and height (<var title="">w</var> and <var
title="">h</var>) might be different from the <var title="">sw</var>
@@ -64760,15 +64762,15 @@
title="">n</var> is zero then there are no <span>supported property
indices</span>.</p>
- <p>When a <code>Window</code> object is <dfn
- title="dom-window-item">indexed to retrieve an indexed
- property</dfn> <var title="">index</var>, the value returned must be
- the <code>WindowProxy</code> object of the <var
- title="">index</var>th <span>child browsing context</span> of the
- <code>Document</code> that is nested through an element that is
- <span title="in a document">in the <code>Document</code></span>,
- sorted in the <span>tree order</span> of the elements nesting those
- <span title="browsing context">browsing contexts</span>.</p>
+ <p>To <dfn title="dom-window-item">determine the value of an indexed
+ property</dfn> <var title="">index</var> of a <code>Window</code>
+ object, the user agent must return the <code>WindowProxy</code>
+ object of the <var title="">index</var>th <span>child browsing
+ context</span> of the <code>Document</code> that is nested through
+ an element that is <span title="in a document">in the
+ <code>Document</code></span>, sorted in the <span>tree order</span>
+ of the elements nesting those <span title="browsing
+ context">browsing contexts</span>.</p>
<p>These properties are the <dfn>dynamic nested browsing context
properties</dfn>.</p>
@@ -74923,31 +74925,6 @@
I can provide the File object that corresponds to it
eventually".
- * Exposing more information about each item. Best idea (from
- Eduard Pascual) is to have a new attribute on dataTransfer
- that's a list of items, each of which has:
-
- dataTransfer.items = DataTransferItems
-
- DataTransferItems.length
- .getItem(n) = DataTransferItem
- .add(stringData, type)
- .add(blobData)
- .add(fileData)
- .add(dataTransferItem)
- .add(promise)
- .clear()
-
- DataTransferItem.kind = 'string', 'file', 'blob', ...
- .type = MIME type
- .binaryOnly
- .getTextData(function callback (data)) - throws if binary is true
- .getBlob() - returns File or Blob (which are async anyway)
-
- DataTransferPromise.type = 'string' or 'file' or 'blob'
- .onneeddata - can wait until this fires to provide data
- .setData() - call this once you have data, must be the right type
-
-->
<p>This section defines an event-based drag-and-drop mechanism.</p>
@@ -75136,7 +75113,7 @@
<dt><i>Plain Unicode string</i></dt>
<dd>
- <p>Raw text.</p>
+ <p>Text.</p>
</dd>
<dt><i>Blob</i></dt>
@@ -75149,6 +75126,13 @@
<p>Binary data with a file name.</p>
</dd>
+<!-- v2:
+ <dt><i>Structured object</i></dt>
+ <dd>
+ <p>An object that will be cloned using the <span>structured clone</span> algorithm.</p>
+ </dd>
+-->
+
</dl>
</dd>
@@ -75156,8 +75140,8 @@
<dt>The actual data</dt>
<dd><p>A Unicode or binary string, optionally with a file name
- (itself a Unicode string), as per <span>the drag data item
- kind</span>.</p></dd>
+ (itself a Unicode string), <!-- (v2:) or an object, --> as per
+ <span>the drag data item kind</span>.</p></dd>
</dl>
@@ -75364,16 +75348,6 @@
href="#dndevents">drag-and-drop events</a>, and are only valid while
those events are being dispatched.</p>
-<!--
-
-XXX
-
-plan:
- 4. expose model with new API
- 5. add dropzone="..." feature
-
--->
-
<div class="impl">
<p>A <code>DataTransfer</code> object is associated with a
@@ -75628,6 +75602,11 @@
<p class="note">This version of the API does not expose the types of
the files during the drag.</p>
+ <p>The <dfn title="dom-DataTransfer-items"><code>items</code></dfn>
+ attribute must return a <code>DataTransferItems</code> object
+ associated with the <code>DataTransfer</code> object. The same
+ object must be returned each time.</p>
+
<p>The <dfn
title="dom-DataTransfer-setDragImage"><code>setDragImage(<var
title="">element</var>, <var title="">x</var>, <var
@@ -75692,7 +75671,169 @@
</div>
+ <h5>The <code>DataTransferItems</code> interface</h5>
+ <p>Each <code>DataTransfer</code> object is associated with a
+ <code>DataTransferItems</code> object.</p>
+
+ <pre class="idl">interface <dfn>DataTransferItems</dfn> {
+ readonly attribute unsigned long <span title="dom-DataTransferItems-length">length</span>;
+ <span title="dom-DataTransferItems-item">getter</span> <span>DataTransferItem</span> (in unsigned long index);
+ <span title="dom-DataTransferItems-removeItem">deleter</span> void (in unsigned long index);
+ void <span title="dom-DataTransferItems-clear">clear</span>();
+
+ <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in DOMString data, in DOMString type);
+ <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in <span>Blob</span> data);
+ <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in <span>File</span> data);
+ <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in <span>DataTransferItem</span> data);<!--
+v2: <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in any data, in DOMString type);--><!--
+v3: <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in <span>DataTransferPromise</span> data);-->
+};</pre>
+
+ <dl class="domintro">
+
+ <dt><var title="">items</var> . <code title="dom-DataTransferItems-length">length</code></dt>
+
+ <dd><p>Returns the number of items in the <span>drag data store</span>.</p></dd>
+
+
+ <dt><var title="">items</var>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Returns the <code>DataTransferItem</code> object representing the <var title="">index</var>th entry in the <span>drag data store</span>.</p>
+
+ </dd>
+
+
+ <dt><code title="">delete</code> <var title="">items</var>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Removes the <var title="">index</var>th entry in the <span>drag data store</span>.</p>
+
+ </dd>
+
+
+ <dt><var title="">items</var> . <code title="dom-DataTransferItems-clear">clear</code>()</dt>
+
+ <dd>
+
+ <p>Removes all the entries in the <span>drag data store</span>.</p>
+
+ </dd>
+
+
+ <dt><var title="">items</var> . <code title="dom-DataTransferItems-add">add</code>(<var title="">data</var>)</dt>
+ <dt><var title="">items</var> . <code title="dom-DataTransferItems-add">add</code>(<var title="">data</var>, <var title="">type</var>)</dt>
+
+ <dd>
+
+ <p>Adds a new entry for the given data to the <span>drag data
+ store</span>. If the data is plain text <!-- v2: or an object -->
+ then a <var title="">type</var> string has to be provided
+ also.</p>
+
+ </dd>
+
+ </dl>
+
+ <div class="impl">
+
+ <p>While the <code>DataTransferItems</code> object's
+ <code>DataTransfer</code> object is associated with a <span>drag
+ data store</span>, the <code>DataTransferItems</code> object's
+ <i>mode</i> is the same as the <span>drag data store mode</span>.
+ When the <code>DataTransferItems</code> object's
+ <code>DataTransfer</code> object is <em>not</em> associated with a
+ <span>drag data store</span>, the <code>DataTransferItems</code>
+ object's <i>mode</i> is <i>disabled mode</i>. The <span>drag data
+ store</span> referenced in this section (which is used only when the
+ <code>DataTransferItems</code> object is not in the <i>disabled
+ mode</i>) is the <span>drag data store</span> with which the
+ <code>DataTransferItems</code> object's <code>DataTransfer</code>
+ object is associated.</p>
+
+ <p>The <dfn
+ title="dom-DataTransferItems-length"><code>length</code></dfn>
+ attribute must return zero if the object is in the <i>disabled
+ mode</i>; otherwise it must return the number of items in the
+ <span>drag data store item list</span>.</p>
+
+ <p>When a <code>DataTransferItems</code> object is not in the
+ <i>disabled mode</i>, its <span>supported property indices</span>
+ are the numbers in the range
+
+ <span title="">0 .. <var title="">n</var>-1</span>,
+
+ where <var title="">n</var> is the number of items in the <span>drag
+ data store item list</span>.</p>
+
+ <p>To <dfn title="dom-DataTransferItems-item">determine the value of
+ an indexed property</dfn> <var title="">i</var> of a
+ <code>DataTransferItems</code> object, the user agent must return a
+ <code>DataTransferItem</code> object representing the <var
+ title="">i</var>th item in the <span>drag data store</span>.</p>
+
+ <p>To <dfn title="dom-DataTransferItems-removeItem">delete an
+ existing indexed property</dfn> <var title="">i</var> of a
+ <code>DataTransferItems</code> object, the user agent must run these
+ steps:</p>
+
+ <ol>
+
+ <li><p>If the <code>DataTransferItems</code> object is not in the
+ <i title="concept-dnd-rw">read/write mode</i>, throw an
+ <code>INVALID_STATE_ERR</code> exception and abort these
+ steps.</p></li>
+
+ <li><p>Remove the <var title="">i</var>th item from the <span>drag
+ data store</span>.</p></li>
+
+ </ol>
+
+ <p>The <dfn
+ title="dom-DataTransferItems-clear"><code>clear</code></dfn> method,
+ if the <code>DataTransferItems</code> object is in the <i
+ title="concept-dnd-rw">read/write mode</i>, must remove all the
+ items from the <span>drag data store</span>. Otherwise, it must do
+ nothing.</p>
+
+ </div>
+
+
+ <h5>The <code>DataTransferItem</code> interface</h5>
+
+ <p class="XXX">...</p>
+
+<!--
+
+ DataTransferItem.kind = 'string', 'file', 'blob', 'data'?, ...
+ .type = MIME type
+ .getTextData(function callback (data)) - throws if kind is not 'string'
+ .getRawData(function callback (data)) - throws if kind is not 'data'
+ .getBlob() - returns File or Blob (which are async anyway); throws if kind is 'data'
+
+ DataTransferPromise.type = 'string' or 'file' or 'blob' or 'data'
+ .onneeddata - can wait until this fires to provide data
+ .setData() - call this once you have data, must be the right type
+-->
+
+<!-- xxx mention that if an item is removed from a data store, DataTransferItem objects become unusable -->
+
+
+<!--
+
+XXX DND WIP
+
+plan:
+ 4. expose model with new API
+ 5. add dropzone="..." feature
+
+-->
+
+
+
<h4>The <code>DragEvent</code> interface</h4>
<p>The drag-and-drop processing model involves several events. They
More information about the Commit-Watchers
mailing list