Initial cut at EventListenerOptions spec

WICG · Jul 3, 2015 · b367181 · tdresser · Jul 3, 2015 · RByers
1 parent 3f7098d
commit b367181
Showing 1 changed file with 150 additions and 0 deletions.
diff --git a/EventListenerOptions.html b/EventListenerOptions.html
@@ -0,0 +1,150 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>EventListenerOptions</title>
+    <meta charset='utf-8'>
+    <script src='https://www.w3.org/Tools/respec/respec-w3c-common'
+            async class='remove'></script>
+    <script class='remove'>
+      var respecConfig = {
+          specStatus: "unofficial",
+          shortName: "EventListenerOptions",
+          edDraftURI: "https://rbyers.github.io/EventListenerOptions/EventListenerOptions.html",
+          testSuiteURI: "http://rbyers.github.io/EventListenerOptions/tests/",
+          editors: [
+                {   name:       "Rick Byers",
+                    url:        "http://rbyers.net",
+                    company:    "Google",
+                    companyURL: "http://google.com/" }
+          ],
+          otherLinks: [{
+            key: 'Participation',
+            data: [
+                {
+                    value: 'GitHub repository',
+                    href: 'https://github.com/RByers/EventListenerOptions/'
+                }, {
+                    value: 'File a bug / view open issues',
+                    href: 'https://github.com/RByers/EventListenerOptions/issues'
+                }, {
+                    value: 'E-mail feedback',
+                    href: 'mailto:input-dev@chromium.org?subject=%5BEventListenerOptions%5D'
+                }
+             ]
+          }],
+      };
+    </script>
+  </head>
+  <body>
+    <section id='abstract'>
+      <p>This document defines an extension to DOM events which allows authors to
+      specify their intention not to call preventDefault on events, enabling important
+      performance optimizations. 
+      </p>
+    </section>
+
+    <section id='sotd'>
+      <p>
+        This proposal was produced in discussion with members of the W3C
+        <a href="http://www.w3.org/2012/pointerevents/">Pointer Events Working Group</a>.
+        It is my hope that the work here will ultimately be integrated into the [[DOM4]] specification.
+      </p>
+    </section>
+
+    <section id="intro" class="informative">
+      <h2>Introduction</h2>
+      <p>Smooth scrolling performance is essential to a good experience on the web,
+      especially on touch-based devices.  Yet a substantial fraction of touch scrolls
+      take longer than 100ms to begin on popular mobile browsers (and a catastrophic
+      500ms delay is not unusual during page load).</p>
+      <p>Modern browsers all
+      have a threaded scrolling feature to permit scrolling to run smoothly even
+      when expensive JavaScript is running, but this optimization can be defeated by
+      the need to wait for the results of any touchstart and touchmove handlers
+      (which may prevent the scroll entirely by calling <code>TouchEvent.preventDefault</code>
+      ([[Touch-Events]]).
+      However, analysis indicates that the majority of touch event handlers on the web will
+      never actually call <code>preventDefault</code>.  Many developers are surprised
+      to learn that simply adding an empty touch handler to their document can
+      have a significant negative impact on scroll performance.  The fundamental
+      problem here is not limited to touch events.  <code>wheel</code>
+      events ([[UIEvents]]) suffer from an identical issue.</p>
+      </p>
+      <p>This proposal provides a way for authors to indicate at handler registration
+      time whether the handler requires the ability to call <code>preventDefault</code>
+      on the event (i.e. whether it needs an event that is cancelable).  When no
+      touch handlers at a particular point require a cancelable event, a user agent
+      is free to start scrolling immediately without waiting for JavaScript.</p>
+    </section>
+    <section dfn-for="EventListenerOptions">
+      <h2>The <code>EventListenerOptions</code> dictionary</h2>
+      <pre class="idl">
+        dictionary EventListenerOptions {
+          boolean capture = false;
+          boolean? requireCancelable = null;
+        };
+      </pre>
+      <dl>
+        <dt><dfn>capture</dfn></dt>
+        <dd>          
+          Same as the <code>capture</code> argument to <code>addEventListener</code> in [[!DOM4]].
+          </div>
+        </dd>
+        <dt><dfn>requireCancelable</dfn></dt>
+        <dd>
+          Whether the handler requires the ability to call <code>preventDefault</code> on the
+          event.  An event dispatched to a handler which was installed with <code>requireCancelable=false</code>
+          will have <code>cancelable=false</code> for the duration of the handler
+          (and so any calls to preventDefault will be ignored).
+          <p class="note">
+            This property is necessary for reasonable composition
+            of handler behavior.  If a requireCancelable=false handler happens to
+            invoke preventDefault, the behavior shouldn't depend on what other handlers
+            happen to be installed for the event.
+          </p>
+          <code>null</code> means the default for the event type - equivalent to
+          <code>true</code> for all cancelable events, and <code>false</code> otherwise.        
+        </dd>
+      </dl>
+    </section>
+    <section>
+      <h2>Extensions to the <code>EventTarget</code> interface</h2>
+      <p><code>EventTarget</code> is defined in [[!DOM4]].</p>
+      <pre class="idl">
+        partial interface EventTarget {
+          boolean addEventListener(DOMString type, EventListener? callback, EventListenerOptions options);
+          boolean removeEventListener(DOMString type, EventListener? callback, EventListenerOptions options);
+        };
+      </pre>
+      <dl dfn-for="EventTarget">
+        <dt><dfn>addEventListener</dfn></dt>
+        <dd>
+          <p>If <code>options</code> contains <code>requiresCancelable=true</code> but
+           <code>type</code> represents an event which is never cancelable, then
+           throw a <code>NotSupportedError</code>.</p>
+          <p>Otherwise, append an event listener to the list as defined by [[!DOM4]]
+          including the specified <code>options</code> unless a handler with the same
+          type and equivalent options already exists.</p>
+          <p class="note">Calling <code>addEventListener(type, handler, capture)</code> behaves exactly
+          the same as <code>addEventListener(type, handler, {capture: capture})</code>.</p>
+        </dd>
+        <dt><dfn>removeEventListener</dfn></dt>
+        <dd>
+          <p>Remove the event listener as defined by [[!DOM4]] if one exists with
+          the specified type and options.</p>
+        </dd>
+      </dl>
+    </section>
+    <section class="informative">
+      <h2>Examples</h2>
+      <p>The following are examples that demonstrate how the APIs in this specification might
+      be used</p>
+      <pre id="example_1" resource="#example_1" class="example" title="Passively monitoring touch activity without blocking scrolling">
+        var lastTouchTime;
+        document.addEventListener('touchstart', function(e) {
+          lastTouchTime = Date.now();
+        }, {requireCancelable: false});
+      </pre>
+    </section>
+  </body>
+</html>