HTML Standard Tracker

Diff (omit for latest revision)
Filter

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

File a bug

SVNBugCommentTime (UTC)
564610712dropzone 1/5: the new model2010-10-25 22:32
Index: source
===================================================================
--- source	(revision 5645)
+++ source	(revision 5646)
@@ -75153,34 +75153,105 @@
   void <span title="dom-DataTransfer-addElement">addElement</span>(in Element element);
 };</pre>
 
-  <p><code>DataTransfer</code> objects can hold pieces of data, each
-  associated with a unique format. Formats are generally given by
-  <span title="MIME type">MIME types</span>, with some values
-  special-cased for legacy reasons. However, the API does not enforce
-  this; non-MIME-type values can be added as well. All formats are
-  identified by strings that are <span>converted to ASCII
-  lowercase</span> by the API.</p>
+  <p><code>DataTransfer</code> objects are used to expose the data
+  that underlies a drag-and-drop operation.</p>
 
-<!--
+  <p>The data that underlies a drag-and-drop operation, known as the
+  <dfn>drag data store</dfn>, consists of an unordered list of items
+  representing the dragged data, and some information used to generate
+  the UI feedback during the drag.</p>
 
-XXX
+  <p>Each item representing dragged data in a <span>drag data
+  store</span> has the following information:</p>
 
-here we say what the DataTransfer objects model is, and that it can be in a read/write mode, secret mode, read-only mode 
+  <ul>
 
-model is:
- - list of items (see DataTransferItem above)
- - the drag image (search for "drag feedback"):
-     - elements
-     - bitmap, x, y
+   <li>
 
-plan:
- 1. describe model
- 2. replace the existing API definitions with links to this model
- 3. expose model with new API
- 4. add dropzone="..." feature
+    <p>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>
 
--->
+   </li>
 
+   <li>
+
+    <p>The kind of data:</p>
+
+    <dl>
+
+     <dt>Plain Unicode string</dt>
+     <dd>
+      <p>Raw text.</p>
+     </dd>
+
+     <dt>Blob</dt>
+     <dd>
+      <p>Binary data.</p>
+     </dd>
+
+     <dt>File</dt>
+     <dd>
+      <p>Binary data with a file name.</p>
+     </dd>
+
+    </dl>
+
+   </li>
+
+  </ul>
+
+  <p>The information in a <span>drag data store</span> used to
+  generate the UI feedback during the drag consists of:</p>
+
+  <ul>
+
+   <li>A list of zero or more elements.</li>
+
+   <li>Optionally, a bitmap image and the coordinate of a point within
+   that image.</li>
+
+  </ul>
+
+  <p>A <span>drag data store</span> is created at the start of a
+  drag-and-drop operation in the <i>read/write mode</i>, and then
+  progresses through the following three modes as the operation
+  proceeds:</p>
+
+  <dl>
+
+   <dt>Read/write mode</dt>
+   <dd>
+
+    <p>At the start of the drag. New data can be added to the
+    <span>drag data store</span>.</p>
+
+   </dd>
+
+   <dt>Protected mode</dt>
+   <dd>
+
+    <p>During the drag. The formats and kinds in the <span>drag data
+    store</span> list of items representing dragged data can be
+    enumerated, but the data itself is unavailable and no new data can
+    be added.</p>
+
+   </dd>
+
+   <dt>Read-only mode</dt>
+   <dd>
+
+    <p>After the drop. The list of items representing dragged data can
+    be read, including the data. No new data can be added.</p>
+
+   </dd>
+
+  </dl>
+
   <dl class="domintro">
 
    <dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-dropEffect">dropEffect</code> [ = <var title="">value</var> ]</dt>
@@ -75278,6 +75349,18 @@
 
   </dl>
 
+<!--
+
+XXX
+
+plan:
+ 2. replace the existing API definitions with links to this model
+ 3. make it clear there's a new DataTransfer object with each event
+ 4. expose model with new API
+ 5. add dropzone="..." feature
+
+-->
+
   <div class="impl">
 
   <p>When a <code>DataTransfer</code> object is created, it must be

|