HTML Standard Tracker

Filter

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
@@ -7666,46 +7666,49 @@ interface <dfn>PropertyNodeList</dfn> : <span>NodeList</span> {
   native mechanisms for property access.</p>
 
   <div class="impl">
 
   <p>When a <code>DOMStringMap</code> object is instantiated, it is
   associated with three algorithms, one for getting the list of
   name-value pairs, one for setting names to certain values, and one
   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
   <code>DOMStringMap</code> object at any instant are the names of
   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>
 
   <p class="note">The <code>DOMStringMap</code> interface definition
   here is only intended for JavaScript environments. Other language
   bindings will need to define how <code>DOMStringMap</code> is to be
   implemented for those languages.</p>
 
   </div>
 
@@ -36728,31 +36731,30 @@ v5DVT (also check for '- -' bits in the part above) -->
   <p>The <code>CanvasPixelArray</code> object thus represents <var
   title="">h</var>&times;<var title="">w</var>&times;4 integers. The
   <dfn title="dom-canvaspixelarray-length"><code>length</code></dfn>
   attribute of a <code>CanvasPixelArray</code> object must return this
   number.</p>
 
   <p>The object's <span>supported property indices</span> are the
   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>
   and <var title="">sh</var> arguments to the above methods, e.g. if
   the canvas is backed by a high-resolution bitmap, or if the <var
   title="">sw</var> and <var title="">sh</var> arguments are
   negative.</p>
 
   <p>The <dfn
   title="dom-context-2d-putImageData"><code>putImageData(<var
@@ -64753,29 +64755,29 @@ interface <dfn>Window</dfn> {
   <!-- in other words, frames are only accessible to same-thread processes -->
 
   <p>The <span>supported property indices</span> on the
   <code>Window</code> object at any instant are the numbers in the
   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">length</code> IDL attribute. If <var
   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>
 
   </div>
 
 
 
   <h4>Named access on the <code>Window</code> object</h4>
 
@@ -74916,45 +74918,20 @@ interface <dfn>NavigatorAbilities</dfn> {
        We should let potential drop targets see the types (but not the
        contents!) of dragged data so they can establish if they care
        or not. (dataTransfer.hasType())
 
        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".
 
-     * 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>
 
   <p>This specification does not define exactly what a
   <em>drag-and-drop operation</em> actually is.</p>
 
   <p>On a visual medium with a pointing device, a drag operation could
   be the default action of a <code
   title="event-mousedown">mousedown</code> event that is followed by a
@@ -75129,42 +75106,49 @@ interface <dfn>NavigatorAbilities</dfn> {
      <dt><dfn>The drag data item kind</dfn></dt>
 
      <dd>
 
       <p>The kind of data:</p>
 
       <dl>
 
        <dt><i>Plain Unicode string</i></dt>
        <dd>
-        <p>Raw text.</p>
+        <p>Text.</p>
        </dd>
 
        <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:
+       <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 <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>
 
    </li>
 
    <li>
 
     <p>The following information, used to generate the UI feedback
     during the drag:</p>
 
@@ -75357,30 +75341,20 @@ interface <dfn>NavigatorAbilities</dfn> {
     <p>Adds the given element to the list of elements used to render the drag feedback.</p>
 
    </dd>
 
   </dl>
 
   <p><code>DataTransfer</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>DataTransfer</code> object is associated with a
   <code>drag data store</code> while it is valid.</p>
 
   <p>The <dfn
   title="dom-DataTransfer-dropEffect"><code>dropEffect</code></dfn>
   attribute controls the drag-and-drop feedback that the user is given
   during a drag-and-drop operation. When the <code>DataTransfer</code>
   object is created, the <code
@@ -75621,20 +75595,25 @@ plan:
    <!-- <li><p>Sort the list...?</p></li> -->
 
    <li><p>The files found by these steps are those in the list <var
    title="">L</var>.</p></li>
 
   </ol>
 
   <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
   title="">y</var>)</code></dfn> method must run the following
   steps:</p>
 
   <ol>
 
    <li><p>If the <code>DataTransfer</code> object is no longer
    associated with a <span>drag data store</span>, abort these steps.
@@ -75685,20 +75664,182 @@ plan:
   <code title="dom-DataTransfer-addElement">addElement()</code> is
   that the latter automatically generates the image based on the
   current rendering of the elements added (potentially keeping it
   updated as the drag continues, e.g. if the elements include an
   actively playing video), whereas the former uses the exact specified
   image at the time the method is invoked.</p>
 
   </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
   all use the <code>DragEvent</code> interface.</p>
 
   <pre class="idl">interface <dfn>DragEvent</dfn> : <span>MouseEvent</span> {
   readonly attribute <span>DataTransfer</span> <span title="dom-DragEvent-dataTransfer">dataTransfer</span>;
 
   void <span title="dom-DragEvent-initDragEvent">initDragEvent</span>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any dummyArg<!-- used to be viewArg, back when we had views -->, in long detailArg, in long screenXArg, in long screenYArg, in long clientXArg, in long clientYArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in unsigned short buttonArg, in EventTarget relatedTargetArg, in <span>DataTransfer</span> dataTransferArg);

|