Skip to content

Commit

Permalink
Tweak "Observing event listeners" section
Browse files Browse the repository at this point in the history
Addresses @annevk feedback: WICG/EventListenerOptions#20 (comment)

Also exports a definition for the "passive event listener" concept.
  • Loading branch information
RByers committed Sep 25, 2015
1 parent 29925e7 commit cddfc43
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 20 deletions.
23 changes: 13 additions & 10 deletions dom.bs
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,8 @@ urlPrefix: https://html.spec.whatwg.org/multipage/
text: effective script origin
text: origin alias; url: #concept-origin-alias
text: Unicode serialization of an origin
urlPrefix: infrastructure.html
text: in parallel
urlPrefix: https://w3c.github.io/webcomponents/spec/shadow/
type: dfn; urlPrefix: #dfn-
text: shadow root
Expand Down Expand Up @@ -988,8 +990,9 @@ dictionary EventListenerOptions {
invoked if <a>event</a>'s {{Event/eventPhase}} attribute value is {{Event/AT_TARGET}}.

<dt>{{EventListenerOptions/passive}}
<dd>When the <var>passive</var> member is set to true, it indicates that the listener's
<b>callback</b> will not cancel the event by invoking {{preventDefault()}}.
<dd>When the <var>passive</var> member is set to true, it indicates that the listener
is <dfn export for="event listener" id=concept-passive-event-listener>passive</dfn>
in that it's <b>callback</b> will not cancel the event by invoking {{preventDefault()}}.
Invoking {{preventDefault()}} from within such a <b>callback</b> will have no effect.
<p class="note no-backref">
Setting <b>passive</b> to true can enable the user agent to perform performance
Expand Down Expand Up @@ -1135,21 +1138,21 @@ method must run these steps:
</ol>

<h3 id=observing-event-listeners>Observing event listeners</h3>
In general, developers don't expect the presence of an event listener to be
observable. The impact of an event listener is determined by it's callback.
That is, a developer adding a no-op event listener would not expect it to have
In general, developers do not expect the presence of an <a>event listener</a> to be
observable. The impact of an <a>event listener</a> is determined by its <b>callback</b>.
That is, a developer adding a no-op <a>event listener</a> would not expect it to have
any side effects.

Unfortunately, some event APIs have been designed such that implementing them
efficiently requires observing event listeners. For example, sensor APIs which
efficiently requires observing <a>event listeners</a>. For example, sensor APIs which
enable an underlying device sensor, and touch APIs which can be used to block
async scrolling. In some cases this problem can be mitigated by specifying
asynchronous scrolling. In some cases this problem can be mitigated by specifying
the event to be {{Event/cancelable}} only when there is at least one
non-{{EventListenerOptions/passive}} listener. For example, non-passive
non-<a>passive</a> listener. For example, non-passive
{{TouchEvent}} listeners must block scrolling, but if all listeners are passive then
scrolling can be allowed to start asynchronously by making the {{TouchEvent}}
scrolling can be allowed to start <a>in parallel</a> by making the {{TouchEvent}}
uncancelable (so that calls to {{Event/preventDefault()}} are ignored).
New event types should be defined such that they don't need this
Ideally, any new event types are defined such that they don't need this
property (use <a href="https://lists.w3.org/Archives/Public/public-script-coord/">public-scrip-coord@w3.org</a>
for discussion).

Expand Down
26 changes: 16 additions & 10 deletions dom.html
Original file line number Diff line number Diff line change
Expand Up @@ -687,7 +687,8 @@ <h3 class="heading settled" data-level="3.6" id="dictionary-eventlisteneroptions
invoked if <a data-link-type="dfn" href="#concept-event">event</a>’s <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code> attribute value is <code class="idl"><a data-link-type="idl" href="#dom-event-at_target">AT_TARGET</a></code>.
<dt><code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code>
<dd>
When the <var>passive</var> member is set to true, it indicates that the listener’s <b>callback</b> will not cancel the event by invoking <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code>.
When the <var>passive</var> member is set to true, it indicates that the listener
is <dfn data-dfn-for="event listener" data-dfn-type="dfn" data-export="" id="concept-passive-event-listener">passive<a class="self-link" href="#concept-passive-event-listener"></a></dfn> in that it’s <b>callback</b> will not cancel the event by invoking <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code>.
Invoking <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> from within such a <b>callback</b> will have no effect.
<p class="note no-backref" role="note"> Setting <b>passive</b> to true can enable the user agent to perform performance
optimizations described in <a href="#observing-event-listeners">§3.8 Observing event listeners</a>. </p>
Expand Down Expand Up @@ -767,18 +768,18 @@ <h3 class="heading settled" data-level="3.7" id="interface-eventtarget"><span cl
<li><a data-link-type="dfn" href="#concept-event-dispatch">Dispatch</a> the <var>event</var> and return the value that returns.
</ol>
<h3 class="heading settled" data-level="3.8" id="observing-event-listeners"><span class="secno">3.8. </span><span class="content">Observing event listeners</span><a class="self-link" href="#observing-event-listeners"></a></h3>
In general, developers don’t expect the presence of an event listener to be
observable. The impact of an event listener is determined by it’s callback.
That is, a developer adding a no-op event listener would not expect it to have
In general, developers do not expect the presence of an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> to be
observable. The impact of an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> is determined by its <b>callback</b>.
That is, a developer adding a no-op <a data-link-type="dfn" href="#concept-event-listener">event listener</a> would not expect it to have
any side effects.
<p>Unfortunately, some event APIs have been designed such that implementing them
efficiently requires observing event listeners. For example, sensor APIs which
efficiently requires observing <a data-link-type="dfn" href="#concept-event-listener">event listeners</a>. For example, sensor APIs which
enable an underlying device sensor, and touch APIs which can be used to block
async scrolling. In some cases this problem can be mitigated by specifying
asynchronous scrolling. In some cases this problem can be mitigated by specifying
the event to be <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> only when there is at least one
non-<code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code> listener. For example, non-passive <code class="idl"><a data-link-type="idl" href="http://www.w3.org/TR/touch-events/#touchevent-interface">TouchEvent</a></code> listeners must block scrolling, but if all listeners are passive then
scrolling can be allowed to start asynchronously by making the <code class="idl"><a data-link-type="idl" href="http://www.w3.org/TR/touch-events/#touchevent-interface">TouchEvent</a></code> uncancelable (so that calls to <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> are ignored).
New event types should be defined such that they don’t need this
non-<a data-link-type="dfn" href="#concept-passive-event-listener">passive</a> listener. For example, non-passive <code class="idl"><a data-link-type="idl" href="http://www.w3.org/TR/touch-events/#touchevent-interface">TouchEvent</a></code> listeners must block scrolling, but if all listeners are passive then
scrolling can be allowed to start <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/infrastructure.html#in-parallel">in parallel</a> by making the <code class="idl"><a data-link-type="idl" href="http://www.w3.org/TR/touch-events/#touchevent-interface">TouchEvent</a></code> uncancelable (so that calls to <code class="idl"><a data-link-type="idl" href="#dom-event-preventdefault">preventDefault()</a></code> are ignored).
Ideally, any new event types are defined such that they don’t need this
property (use <a href="https://lists.w3.org/Archives/Public/public-script-coord/">public-scrip-coord@w3.org</a> for discussion).</p>
<h3 class="heading settled" data-level="3.9" id="dispatching-events"><span class="secno">3.9. </span><span class="content">Dispatching events</span><a class="self-link" href="#dispatching-events"></a></h3>
<p>To <dfn data-dfn-for="Event" data-dfn-type="dfn" data-export="" id="concept-event-dispatch">dispatch<a class="self-link" href="#concept-event-dispatch"></a></dfn> an <a data-link-type="dfn" href="#concept-event">event</a> to a
Expand Down Expand Up @@ -5106,7 +5107,12 @@ <h3 class="no-num heading settled" id="index-defined-here"><span class="content"
<li><a href="#dom-treewalker-parentnode">parentNode()</a><span>, in §6.2</span>
<li><a href="#partially-contained">partially contained</a><span>, in §5.2</span>
<li><a href="#concept-tree-participate">participate</a><span>, in §2.1</span>
<li><a href="#dom-eventlisteneroptions-passive">passive</a><span>, in §3.6</span>
<li>
passive
<ul>
<li><a href="#dom-eventlisteneroptions-passive">dict-member for EventListenerOptions</a><span>, in §3.6</span>
<li><a href="#concept-passive-event-listener">dfn for event listener</a><span>, in §3.6</span>
</ul>
<li><a href="#passive-flag">passive flag</a><span>, in §3.2</span>
<li><a href="#dom-nodeiterator-pointerbeforereferencenode">pointerBeforeReferenceNode</a><span>, in §6.1</span>
<li><a href="#concept-range-bp-position">position</a><span>, in §5.2</span>
Expand Down

0 comments on commit cddfc43

Please sign in to comment.