HTML Standard Tracker

Diff (omit for latest revision)
Filter

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

File a bug

SVNBugCommentTime (UTC)
565110712[Gecko] [Internet Explorer] [Opera] [Webkit] dropzone 4/5, part 2/2: DataTransferItem.2010-10-29 22:03
Index: source
===================================================================
--- source	(revision 5650)
+++ source	(revision 5651)
@@ -74883,7 +74883,7 @@
 
   <h3 id="dnd"><dfn>Drag and drop</dfn></h3>
 
-<!-- v2 ideas for drag and drop:
+<!-- v2: ideas for drag and drop:
 
      * being able to animate a drop target:
 
@@ -74921,10 +74921,18 @@
 
        Ack: Ben Laurie (@g)
 
-     * Promises. Should be able to say "if you accept this drop, then
-       I can provide the File object that corresponds to it
-       eventually".
+     Other things listed below:
+      DND-v2: more native support: text/html from selections, etc
+      DND-v3: add Blob support
+      DND-v4: add structured clone support
+      DND-v5: add promises (should be able to say "if you accept this
+              drop, then I can provide the File object that
+              corresponds to it eventually")
 
+         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
+
 -->
 
   <p>This section defines an event-based drag-and-drop mechanism.</p>
@@ -75089,20 +75097,6 @@
 
     <dl>
 
-     <dt><dfn>The drag data item type string</dfn></dt>
-
-     <dd>
-
-      <p>A Unicode string giving the type or format of the data,
-      generally given by a <span>MIME type</span>. Some values that
-      are not <span title="MIME type">MIME types</span> are
-      special-cased for legacy reasons. The API does not enforce the
-      use of <span title="MIME type">MIME types</span>; other values
-      can be used as well. In all cases, however, the values are all
-      <span>converted to ASCII lowercase</span> by the API.</p>
-
-     </dd>
-
      <dt><dfn>The drag data item kind</dfn></dt>
 
      <dd>
@@ -75116,17 +75110,19 @@
         <p>Text.</p>
        </dd>
 
+<!-- DND-v3:
        <dt><i>Blob</i></dt>
        <dd>
         <p>Binary data.</p>
        </dd>
+-->
 
        <dt><i>File</i></dt>
        <dd>
         <p>Binary data with a file name.</p>
        </dd>
 
-<!-- v2:
+<!-- DND-v4:
        <dt><i>Structured object</i></dt>
        <dd>
         <p>An object that will be cloned using the <span>structured clone</span> algorithm.</p>
@@ -75137,14 +75133,32 @@
 
      </dd>
 
+     <dt><dfn>The drag data item type string</dfn></dt>
+
+     <dd>
+
+      <p>A Unicode string giving the type or format of the data,
+      generally given by a <span>MIME type</span>. Some values that
+      are not <span title="MIME type">MIME types</span> are
+      special-cased for legacy reasons. The API does not enforce the
+      use of <span title="MIME type">MIME types</span>; other values
+      can be used as well. In all cases, however, the values are all
+      <span>converted to ASCII lowercase</span> by the API.</p>
+
+     </dd>
+
      <dt>The actual data</dt>
 
      <dd><p>A Unicode or binary string, optionally with a file name
-     (itself a Unicode string), <!-- (v2:) or an object, --> as per
+     (itself a Unicode string), <!-- (DND-v4:) or an object, --> as per
      <span>the drag data item kind</span>.</p></dd>
 
     </dl>
 
+    <p>The <span>drag data store item list</span> is ordered in the
+    order that the items were added to the list; most recently added
+    last.</p>
+
    </li>
 
    <li>
@@ -75587,10 +75601,10 @@
 
    <li><p>For each item in the <span>drag data store item list</span>
    <!-- in some order...? --> whose <span title="the drag data item
-   kind">kind</span> is <i>File</i> (not <i>Blob</i>), add the item's
-   data (the file, in particular its name and contents, as well as its
-   <span title="the drag data item type string">type</span>) to the
-   list <var title="">L</var>.</p></li>
+   kind">kind</span> is <i>File</i> <!-- DND-v3: (not <i>Blob</i>) -->,
+   add the item's data (the file, in particular its name and contents,
+   as well as its <span title="the drag data item type
+   string">type</span>) to the list <var title="">L</var>.</p></li>
 
    <!-- <li><p>Sort the list...?</p></li> -->
 
@@ -75682,12 +75696,11 @@
   <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);-->
+  <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in DOMString data, in DOMString type);<!--
+DND-v3:  <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);<!--
+DND-v4:  <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in any data, in DOMString type);--><!--
+DND-v5:  <span>DataTransferItem</span> <span title="dom-DataTransferItems-add">add</span>(in <span>DataTransferPromise</span> data);-->
 };</pre>
 
   <dl class="domintro">
@@ -75730,7 +75743,7 @@
    <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 -->
+    store</span>. If the data is plain text <!-- DND-v4: or an object -->
     then a <var title="">type</var> string has to be provided
     also.</p>
 
@@ -75747,12 +75760,12 @@
   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>
+  object's <i>mode</i> is the <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>
@@ -75773,7 +75786,11 @@
   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>
+  title="">i</var>th item in the <span>drag data store</span>. The
+  same object must be returned each time. The
+  <code>DataTransferItem</code> object must be associated with the
+  same <code>DataTransfer</code> object as the
+  <code>DataTransferItems</code> object when it is created.</p>
 
   <p>To <dfn title="dom-DataTransferItems-removeItem">delete an
   existing indexed property</dfn> <var title="">i</var> of a
@@ -75799,41 +75816,282 @@
   items from the <span>drag data store</span>. Otherwise, it must do
   nothing.</p>
 
+  <p>The <dfn
+  title="dom-DataTransferItems-add"><code>add()</code></dfn> method
+  must run the following steps:</p>
+
+  <ol>
+
+   <li><p>If the <code>DataTransferItems</code> object is not in the
+   <i title="concept-dnd-rw">read/write mode</i>, return null and
+   abort these steps.</p></li>
+
+   <li>
+
+  </ol>
+
   </div>
 
 
   <h5>The <code>DataTransferItem</code> interface</h5>
 
-  <p class="XXX">...</p>
+  <p>Each <code>DataTransferItem</code> object is associated with a
+  <code>DataTransfer</code> object.</p>
 
-<!--
+  <pre class="idl">interface <dfn>DataTransferItem</dfn> {
+    readonly attribute DOMString <span title="dom-DataTransferItem-kind">kind</span>;
+    readonly attribute DOMString <span title="dom-DataTransferItem-type">type</span>;
+    void <span title="dom-DataTransferItem-getAsText">getAsText</span>(in <span>FunctionStringCallback</span> callback);<!--
+DND-v3:    <span>Blob</span> <span title="dom-DataTransferItem-getAsBlob">getAsBlob</span>();-->
+    <span>File</span> <span title="dom-DataTransferItem-getAsFile">getAsFile</span>();<!--
+DND-v4:    void <span title="dom-DataTransferItem-getAsObject">getAsObject</span>(in <span>FunctionObjectCallback</span> callback);-->
+};
 
-         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'
+[Callback=FunctionOnly, NoInterfaceObject]
+interface <dfn>FunctionStringCallback</dfn> {
+  void <span title="dom-FunctionStringCallback-handleEvent">handleEvent</span>(in DOMString 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
+// DND-v4:
+[Callback=FunctionOnly, NoInterfaceObject]
+interface <dfn>FunctionObjectCallback</dfn> {
+  void <span title="dom-FunctionObjectCallback-handleEvent">handleEvent</span>(in DOMString data);
+};--></pre>
+
+  <dl class="domintro">
+
+   <dt><var title="">item</var> . <code title="dom-DataTransferItem-kind">kind</code></dt>
+   <dd>
+
+    <p>Returns the <span>drag data item kind</span>, one of: "string",
+    <!-- DND-v3: "blob", --> "file"<!-- DND-v4: , "object" -->.</p>
+
+   </dd>
+
+   <dt><var title="">item</var> . <code title="dom-DataTransferItem-type">type</code></dt>
+   <dd>
+
+    <p>Returns the <span>drag data item type string</span>.</p>
+
+   </dd>
+
+   <dt><var title="">item</var> . <code title="dom-DataTransferItem-getAsString">getAsString</code>(<var title="">callback</var>)</dt>
+   <dd>
+
+    <p>Invokes the callback with the string data as the argument, if the <span>drag data item kind</span> is <i>Plain Unicode string</i>.</p>
+
+   </dd>
+
+<!-- DND-v3:
+   <dt><var title="">file</var> = <var title="">item</var> . <code title="dom-DataTransferItem-getAsBlob">getAsBlob</code>()</dt>
+   <dd>
+
+    <p>Returns a <code>Blob</code> object, if the <span>drag data item kind</span> is <i>Blob</i> or <i>File</i>.</p>
+
+   </dd>
 -->
 
-<!-- xxx mention that if an item is removed from a data store, DataTransferItem objects become unusable -->
+   <dt><var title="">file</var> = <var title="">item</var> . <code title="dom-DataTransferItem-getAsFile">getAsFile</code>()</dt>
+   <dd>
 
+    <p>Returns a <code>File</code> object, if the <span>drag data item kind</span> is <i>File</i>.</p>
 
-<!--
+   </dd>
 
-XXX DND WIP
+<!-- DND-v4:
+   <dt><var title="">file</var> = <var title="">item</var> . <code title="dom-DataTransferItem-getAsFile">getAsFile</code>()</dt>
+   <dd>
 
-plan:
- 4. expose model with new API
- 5. add dropzone="..." feature
+    <p>Invokes the callback with the cloned object data as the argument, if the <span>drag data item kind</span> is <i>Plain Unicode string</i> or <i>Object</i>.</p>
 
+   </dd>
 -->
 
+  </dl>
 
+  <div class="impl">
 
+  <p>While the <code>DataTransferItem</code> object's
+  <code>DataTransfer</code> object is associated with a <span>drag
+  data store</span> and that <span>drag data store</span>'s <span>drag
+  drop store item list</span> still contains the item that the
+  <code>DataTransferItem</code> object represents, the
+  <code>DataTransferItem</code> object's <i>mode</i> is the same as
+  the <span>drag data store mode</span>. When the
+  <code>DataTransferItem</code> object's <code>DataTransfer</code>
+  object is <em>not</em> associated with a <span>drag data
+  store</span>, or if the item that the <code>DataTransferItem</code>
+  object represents has been removed from the relevant <span>drag drop
+  store item list</span>, the <code>DataTransferItem</code> object's
+  <i>mode</i> is the <i>disabled mode</i>. The <span>drag data
+  store</span> referenced in this section (which is used only when the
+  <code>DataTransferItem</code> object is not in the <i>disabled
+  mode</i>) is the <span>drag data store</span> with which the
+  <code>DataTransferItem</code> object's <code>DataTransfer</code>
+  object is associated.</p>
+
+  <p>The <dfn
+  title="dom-DataTransferItem-kind"><code>kind</code></dfn> attribute
+  must return the empty string if the <code>DataTransferItem</code>
+  object is in the <i>disabled mode</i>; otherwise it must return the
+  string given in the cell from the second column of the following
+  table from the row whose cell in the first column contains <span>the
+  drag data item kind</span> of the item represented by the
+  <code>DataTransferItem</code> object:</p>
+
+  <table>
+   <thead>
+    <tr> <th> Kind <th> String
+   <tbody>
+    <tr> <td> <i>Plain Unicode string</i> <td> "<code title="">string</code>"
+<!-- DND-v3:    <tr> <td> <i>Blob</i> <td> "<code title="">blob</code>"-->
+    <tr> <td> <i>File</i> <td> "<code title="">file</code>"
+<!-- DND-v4:    <tr> <td> <i>Object</i> <td> "<code title="">object</code>"-->
+  </table>
+
+  <p>The <dfn
+  title="dom-DataTransferItem-type"><code>type</code></dfn> attribute
+  must return the empty string if the <code>DataTransferItem</code>
+  object is in the <i>disabled mode</i>; otherwise it must return
+  <span>the drag data item type string</span> of the item represented
+  by the <code>DataTransferItem</code> object.</p>
+
+  <p>The <dfn
+  title="dom-DataTransferItem-getAsString"><code>getAsString(<var
+  title="">callback</var>)</code></dfn> method must run the following
+  steps:</p>
+
+  <ol>
+
+   <li><p>If the <var title="">callback</var> is null, abort these
+   steps.</p></li>
+
+   <li><p>If the <code>DataTransferItem</code> object is not in the <i
+   title="concept-dnd-rw">read/write mode</i> or the <i
+   title="concept-dnd-ro">read-only mode</i>, abort these steps. The
+   callback is never invoked.</p></li>
+
+   <li><p>If the <span>data drag item kind</span> is not <i>Plain
+   Unicode string</i>, abort these steps. The callback is never
+   invoked.</p></li>
+
+   <li><p>Otherwise, <span>queue a task</span> to invoke <var
+   title="">callback</var>, passing the actual data of the item
+   represented by the <code>DataTransferItem</code> object as the
+   argument.</p></li>
+
+  </ol>
+
+<!--DND-v3:
+  <p>The <dfn
+  title="dom-DataTransferItem-getAsBlob"><code>getAsBlob()</code></dfn>
+  method must run the following steps:</p>
+
+  <ol>
+
+   <li><p>If the <code>DataTransferItem</code> object is not in the <i
+   title="concept-dnd-rw">read/write mode</i> or the <i
+   title="concept-dnd-ro">read-only mode</i>, return null and abort
+   these steps.</p></li>
+
+   <li>
+
+--><!--DND-v4:
+    <p>If the <span>data drag item kind</span> is <i>Object</i>,
+    return null.</p></li>
+--><!--DND-v3:
+
+    <p>If the <span>data drag item kind</span> is <i>File</i>, then
+    return a new <code>File</code> object representing the actual data
+    of the item represented by the <code>DataTransferItem</code>
+    object.</p>
+
+    <p>If the <span>data drag item kind</span> is <i>Unicode Data
+    string</i>, then return a new <code>Blob</code> object
+    representing the actual data of the item represented by the
+    <code>DataTransferItem</code> object, with the <code
+    title="dom-Blob-type">type</code> of the <code>Blob</code> being
+    <span>the drag data item type string</span> and with the binary
+    data of the <code>Blob</code> object being the Unicode string
+    encoded as UTF-8. <a href="#refsRFC3629">[RFC3629]</a></p>
+
+    <p>Otherwise, the <span>data drag item kind</span> is <i>Blob</i>;
+    return a new <code>Blob</code> object representing the actual data
+    of the item represented by the <code>DataTransferItem</code>
+    object.</p>
+
+   </li>
+
+  </ol>
+-->
+
+  <p>The <dfn
+  title="dom-DataTransferItem-getAsFile"><code>getAsFile()</code></dfn>
+  method must run the following steps:</p>
+
+  <ol>
+
+   <li><p>If the <code>DataTransferItem</code> object is not in the <i
+   title="concept-dnd-rw">read/write mode</i> or the <i
+   title="concept-dnd-ro">read-only mode</i>, return null and abort
+   these steps.</p></li>
+
+   <li><p>If the <span>data drag item kind</span> is not <i>File</i>,
+   then return null and abort these steps.</p></li>
+
+   <li><p>Return a new <code>File</code> object representing the
+   actual data of the item represented by the
+   <code>DataTransferItem</code> object.</p>
+
+  </ol>
+
+<!--DND-v4:
+  <p>The <dfn
+  title="dom-DataTransferItem-getAsObject"><code>getAsObject(<var
+  title="">callback</var>)</code></dfn> method must run the following
+  steps:</p>
+
+  <ol>
+
+   <li><p>If the <code>DataTransferItem</code> object is not in the <i
+   title="concept-dnd-rw">read/write mode</i> or the <i
+   title="concept-dnd-ro">read-only mode</i>, return null and abort
+   these steps.</p></li>
+
+   <li>
+
+    <p>Let <var title="">data</var> be the actual data of the item
+    represented by the <code>DataTransferItem</code> object.</p>
+
+    <p>If the <span>data drag item kind</span> is <i>Unicode Data
+    string</i>, then <var title="">data</var> is a <code
+    title="">DOMString</code> containing the actual data.</p>
+
+    <p>If the <span>data drag item kind</span> is <i>Blob</i>, then
+    <var title="">data</var> is a <code>Blob</code> representing the
+    actual data.</p>
+
+    <p>If the <span>data drag item kind</span> is <i>File</i>, then
+    <var title="">data</var> is a <code>File</code> representing the
+    actual data.</p>
+
+    <p>If the <span>data drag item kind</span> is <i>Object</i>, then
+    <var title="">data</var> is the object that is the actual
+    data.</p>
+
+   </li>
+
+   <li><span>Queue a task</span> to invoke <var
+   title="">callback</var>, passing a <span>structured clone</span> of
+   <var title="">data</var> as the argument.</p></li>
+
+  </ol>
+-->
+
+  </div>
+
+
+
   <h4>The <code>DragEvent</code> interface</h4>
 
   <p>The drag-and-drop processing model involves several events. They
@@ -76147,7 +76405,7 @@
 
    </li>
 
-   <!-- v2: text/html as an export format -->
+   <!-- DND-v2: text/html as an export format -->
 
 <!--END w3c-html--><!--MD-->
 
@@ -76182,37 +76440,8 @@
 
 <!--START complete--><!--START epub--><!--START html-->
 
-<!-- v2: deal with multiple vCards -->
-<!--
    <li>
 
-    (if you put this back, don't forget to update this text as above)
-
-    <p>The user agent must take the <span>list of dragged nodes</span>
-    and <span title="extracting a vCard">extract the vCard data from
-    those nodes</span>, and then must add the resulting string to the
-    <code title="dom-DragEvent-dataTransfer">dataTransfer</code>
-    member, associated with the <code
-    title="">text/directory;profile=vcard</code> format.</p>
-
-   </li>
-
-   <li>
-
-    (if you put this back, don't forget to update this text as above)
-
-    <p>The user agent must take the <span>list of dragged nodes</span>
-    and <span title="extracting vEvent data">extract the vEvent data
-    from those nodes</span>, and then must add the resulting string to
-    the <code title="dom-DragEvent-dataTransfer">dataTransfer</code>
-    member, associated with the <code
-    title="">text/calendar;component=vevent</code> format.</p>
-
-   </li>
--->
-
-   <li>
-
     <p>Run the following substeps:</p>
 
     <ol>
@@ -76243,7 +76472,7 @@
        title="attr-img-src">src</code> content attribute relative to
        the element.</dd>
 
-       <!-- v2: more -->
+       <!-- DND-v2: more -->
 
       </dl>
 
@@ -76894,6 +77123,11 @@
 
   <h4>The <dfn title="attr-draggable"><code>draggable</code></dfn> attribute</h4>
 
+<!--
+XXX DND WIP plan:
+ 5. add dropzone="..." feature
+-->
+
   <p>All <span>HTML elements</span> may have the <code
   title="attr-draggable">draggable</code> content attribute set. The
   <code title="attr-draggable">draggable</code> attribute is an

|