hixie: Drag and drop model documentation. (whatwg r3889)

hixie: Drag and drop model documentation. (whatwg r3889)

http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.3051&r2=1.3052&f=h
http://html5.org/tools/web-apps-tracker?from=3888&to=3889

===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.3051
retrieving revision 1.3052
diff -u -d -r1.3051 -r1.3052
--- Overview.html 18 Sep 2009 05:06:40 -0000 1.3051
+++ Overview.html 18 Sep 2009 06:53:17 -0000 1.3052
@@ -52199,7 +52199,88 @@
   not canceled, there must be at least one element in the middle
   step).</p>
 
-  </div><h4 id="introduction-4"><span class="secno">7.9.1 </span>Introduction</h4><p><i>This section is non-normative.</i><p class="XXX">It's also currently non-existent.<h4 id="the-dragevent-and-datatransfer-interfaces"><span class="secno">7.9.2 </span>The <code><a href="#dragevent">DragEvent</a></code> and <code><a href="#datatransfer">DataTransfer</a></code> interfaces</h4><p>The drag-and-drop processing model involves several events. They
+  </div><h4 id="introduction-4"><span class="secno">7.9.1 </span>Introduction</h4><p><i>This section is non-normative.</i><p>To make an element draggable is simple: give the element a <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> attribute, and set an event
+  listener for <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code> that
+  stores the data being dragged.<p>The event handler typically needs to check that it's not a text
+  selection that is being dragged, and then needs to store data into
+  the <code><a href="#datatransfer">DataTransfer</a></code> object and set the allowed effects
+  (copy, move, link, or some combination).<p>For example:<pre>&lt;p&gt;What fruits do you like?&lt;/p&gt;
+&lt;ol ondragstart="dragStartHandler(event)"&gt;
+ &lt;li draggable data-value="fruit-apple"&gt;Apples&lt;/li&gt;
+ &lt;li draggable data-value="fruit-orange"&gt;Oranges&lt;/li&gt;
+ &lt;li draggable data-value="fruit-pear"&gt;Pears&lt;/li&gt;
+&lt;/ol&gt;
+&lt;script&gt;
+  var internalDNDType = 'text/x-example'; // set this to something specific to your site
+  function dragStartHandler(event) {
+    if (event.target instanceof HTMLLIElement) {
+      // use the element's data-value="" attribute as the value to be moving:
+      event.dataTransfer.setData(internalDNDType, event.target.dataset.value);
+      event.effectAllowed = 'move'; // only allow moves
+    } else {
+      event.preventDefault(); // don't allow selection to be dragged
+    }
+  }
+&lt;/script&gt;</pre><hr><p>To accept a drop, the drop target has to listen to at least three
+  events. First, the <code title="event-dragenter"><a href="#event-dragenter">dragenter</a></code>
+  event, which is used to determine whether or not the drop target is
+  to accept the drop. If the drop is to be accepted, then this event
+  has to be canceled. Second, the <code title="event-dragover"><a href="#event-dragover">dragover</a></code> event, which is used to
+  determine what feedback is to be shown to the user. If the event is
+  not canceled, then the feedback (typically the cursor) is updated
+  based on the <code title="dom-DataTransfer-DropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code> attribute's
+  value, as set by the event handler. Finally, the <code title="event-drop"><a href="#event-drop">drop</a></code> event, which allows the actual drop
+  to be performed. This event also needs to be canceled so that the
+  <code title="dom-DataTransfer-DropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code>
+  attribute's value can be used by the source (otherwise it's
+  reset).<p>For example:<pre>&lt;p&gt;Drop your favourite fruits below:&lt;/p&gt;
+&lt;ol class="dropzone"
+    ondragenter="dragEnterHandler(event)"
+    ondragover="dragOverHandler(event)"
+    ondrop="dropHandler(event)"&gt;
+&lt;/ol&gt;
+&lt;script&gt;
+  var internalDNDType = 'text/x-example'; // set this to something specific to your site
+  function dragEnterHandler(event) {
+    // cancel the event if the drag contains data of our type
+    if (event.dataTransfer.types.contains(internalDNDType)
+      event.preventDefault();
+  }
+  function dragOverHandler(event) {
+    event.dataTransfer.dropEffect = 'move';
+    event.preventDefault();
+  }
+  function dropHandler(event) {
+    // drop the data
+    var li = document.createElement('li');
+    var data = event.dataTransfer.getData(internalDNDType);
+    if (data == 'fruit-apple') {
+      li.textContent = 'Apples';
+    } else if (data == 'fruit-orange') {
+      li.textContent = 'Oranges';
+    } else if (data == 'fruit-pear') {
+      li.textContent = 'Pears';
+    } else {
+      li.textContent = 'Unknown Fruit';
+    }
+    event.target.appendChild(li);
+  }
+&lt;/script&gt;</pre><hr><p>To remove the original element (the one that was dragged) from
+  the display, the <code title="event-dragend"><a href="#event-dragend">dragend</a></code> event
+  can be used.<p>For our example here, that means updating the original markup to
+  handle that event:<pre>&lt;p&gt;What fruits do you like?&lt;/p&gt;
+&lt;ol ondragstart="dragStartHandler(event)" ondragend="dragEndHandler(event)"&gt;
+ <em>...as before...</em>
+&lt;/ol&gt;
+&lt;script&gt;
+  function dragStartHandler(event) {
+    // <em>...as before...</em>
+  }
+  function dragEndHandler(event) {
+    // remove the dragged element
+    event.target.parentNode.removeChild(event.target);
+  }
+&lt;/script&gt;</pre><h4 id="the-dragevent-and-datatransfer-interfaces"><span class="secno">7.9.2 </span>The <code><a href="#dragevent">DragEvent</a></code> and <code><a href="#datatransfer">DataTransfer</a></code> interfaces</h4><p>The drag-and-drop processing model involves several events. They
   all use the <code><a href="#dragevent">DragEvent</a></code> interface.<pre class="idl">interface <dfn id="dragevent">DragEvent</dfn> : <span>MouseEvent</span> {
   readonly attribute <a href="#datatransfer">DataTransfer</a> <a href="#dom-dragevent-datatransfer" title="dom-DragEvent-dataTransfer">dataTransfer</a>;

Received on Friday, 18 September 2009 06:54:26 UTC