<commit_before><!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:       "<NAME>",
                    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:<EMAIL>?subject=%5BEventListenerOptions%5D'
                }
             ]
          }],
      };
    </script>
    <style>
      p {
        margin-top: 0;
      }
      dt {
        margin-top: 1em !important;
      }
    </style>
  </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 many websites on 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 <code>touchstart</code> and <code>touchmove</code> ([[Touch-Events]]) handlers,
      which may prevent the scroll entirely by calling <code>TouchEvent.preventDefault</code>.
      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.</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>
      <p>The fundamental problem here is not limited to touch events.  <code>wheel</code>
      events ([[UIEvents]]) suffer from an identical issue.  However pointer event
      handlers ([[PointerEvents]]) never block scrolling, so this mechanism brings
      the performance properties of pointer events to touch and wheel events.</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>
          <p class="note">
            User agents are encouraged to generate a console warning or other debugging
            aid to help authors identify places where their code is calling preventDefault
            on an uncancelable 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>
      <h2>Extensions to the <code>Event</code> interface</h2>
      <p><code>Event</code> is defined in [[!DOM4]].</p>
      <pre class="idl">
        partial interface Event {
          static EventListenerOptions getSupportedListenerOptions();
        };
      </pre>
      <dl dfn-for="Event">
        <dt><dfn>getSupportedListenerOptions</dfn></dt>
        <dd>
          <p>Return an <a>EventListenerOptions</a> with all dictionary members present.
          The values in the dictionary have no meaning.</p>
          <p class="note">This API is necessary for feature detection of support
          for <code>EventListenerOptions</code> and for additiona specific options
          that may be added in the future.
          </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><commit_msg>Fix note typo<commit_after><!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:       "<NAME>",
                    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:<EMAIL>?subject=%5BEventListenerOptions%5D'
                }
             ]
          }],
      };
    </script>
    <style>
      p {
        margin-top: 0;
      }
      dt {
        margin-top: 1em !important;
      }
    </style>
  </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 many websites on 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 <code>touchstart</code> and <code>touchmove</code> ([[Touch-Events]]) handlers,
      which may prevent the scroll entirely by calling <code>TouchEvent.preventDefault</code>.
      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.</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>
      <p>The fundamental problem here is not limited to touch events.  <code>wheel</code>
      events ([[UIEvents]]) suffer from an identical issue.  However pointer event
      handlers ([[PointerEvents]]) never block scrolling, so this mechanism brings
      the performance properties of pointer events to touch and wheel events.</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>
          <p class="note">
            User agents are encouraged to generate a console warning or other debugging
            aid to help authors identify places where their code is calling preventDefault
            on an uncancelable 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>
      <h2>Extensions to the <code>Event</code> interface</h2>
      <p><code>Event</code> is defined in [[!DOM4]].</p>
      <pre class="idl">
        partial interface Event {
          static EventListenerOptions getSupportedListenerOptions();
        };
      </pre>
      <dl dfn-for="Event">
        <dt><dfn>getSupportedListenerOptions</dfn></dt>
        <dd>
          <p>Return an <a>EventListenerOptions</a> with all dictionary members present.
          The values in the dictionary have no meaning.</p>
          <p class="note">This API is necessary for feature detection of support
          for <code>EventListenerOptions</code> generally, and for specific options
          that may be added in the future.
          </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>
{'fraction_non_alphanumeric': 0.10090548618097887, 'fraction_numerical': 0.004379475646564479, 'mean_word_length': 2.3668061366806135, 'pattern_counts': {'":': 0, '<': 361, '<?xml version=': 0, '>': 361, 'https://': 8, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1041570', 'n_tokens_mistral': 4379, 'n_tokens_neox': 4276, 'n_words': 1529}