HTML Standard Tracker

Diff (omit for latest revision)
Filter

Short URL: http://html5.org/r/5650

File a bug

SVNBugCommentTime (UTC)
565010712[Gecko] [Internet Explorer] [Opera] [Webkit] dropzone 4/5, part 1: DataTransferItems (WIP); also contains some WebIDL terminology fixes.2010-10-29 18:59
Index: source
===================================================================
--- source	(revision 5649)
+++ source	(revision 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>&times;<var title="">w</var>&times;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

|