Skip to content

Commit cddfc43

Browse files
committed
Tweak "Observing event listeners" section
Addresses @annevk feedback: WICG/EventListenerOptions#20 (comment) Also exports a definition for the "passive event listener" concept.
1 parent 29925e7 commit cddfc43

File tree

2 files changed

+29
-20
lines changed

2 files changed

+29
-20
lines changed

dom.bs

+13-10
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,8 @@ urlPrefix: https://html.spec.whatwg.org/multipage/
102102
text: effective script origin
103103
text: origin alias; url: #concept-origin-alias
104104
text: Unicode serialization of an origin
105+
urlPrefix: infrastructure.html
106+
text: in parallel
105107
urlPrefix: https://w3c.github.io/webcomponents/spec/shadow/
106108
type: dfn; urlPrefix: #dfn-
107109
text: shadow root
@@ -988,8 +990,9 @@ dictionary EventListenerOptions {
988990
invoked if <a>event</a>'s {{Event/eventPhase}} attribute value is {{Event/AT_TARGET}}.
989991

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

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

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

dom.html

+16-10
Original file line numberDiff line numberDiff line change
@@ -687,7 +687,8 @@ <h3 class="heading settled" data-level="3.6" id="dictionary-eventlisteneroptions
687687
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>.
688688
<dt><code class="idl"><a data-link-type="idl" href="#dom-eventlisteneroptions-passive">passive</a></code>
689689
<dd>
690-
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>.
690+
When the <var>passive</var> member is set to true, it indicates that the listener
691+
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>.
691692
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.
692693
<p class="note no-backref" role="note"> Setting <b>passive</b> to true can enable the user agent to perform performance
693694
optimizations described in <a href="#observing-event-listeners">§3.8 Observing event listeners</a>. </p>
@@ -767,18 +768,18 @@ <h3 class="heading settled" data-level="3.7" id="interface-eventtarget"><span cl
767768
<li><a data-link-type="dfn" href="#concept-event-dispatch">Dispatch</a> the <var>event</var> and return the value that returns.
768769
</ol>
769770
<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>
770-
In general, developers don’t expect the presence of an event listener to be
771-
observable. The impact of an event listener is determined by it’s callback.
772-
That is, a developer adding a no-op event listener would not expect it to have
771+
In general, developers do not expect the presence of an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> to be
772+
observable. The impact of an <a data-link-type="dfn" href="#concept-event-listener">event listener</a> is determined by its <b>callback</b>.
773+
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
773774
any side effects.
774775
<p>Unfortunately, some event APIs have been designed such that implementing them
775-
efficiently requires observing event listeners. For example, sensor APIs which
776+
efficiently requires observing <a data-link-type="dfn" href="#concept-event-listener">event listeners</a>. For example, sensor APIs which
776777
enable an underlying device sensor, and touch APIs which can be used to block
777-
async scrolling. In some cases this problem can be mitigated by specifying
778+
asynchronous scrolling. In some cases this problem can be mitigated by specifying
778779
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
779-
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
780-
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).
781-
New event types should be defined such that they don’t need this
780+
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
781+
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).
782+
Ideally, any new event types are defined such that they don’t need this
782783
property (use <a href="https://lists.w3.org/Archives/Public/public-script-coord/">[email protected]</a> for discussion).</p>
783784
<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>
784785
<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
@@ -5106,7 +5107,12 @@ <h3 class="no-num heading settled" id="index-defined-here"><span class="content"
51065107
<li><a href="#dom-treewalker-parentnode">parentNode()</a><span>, in §6.2</span>
51075108
<li><a href="#partially-contained">partially contained</a><span>, in §5.2</span>
51085109
<li><a href="#concept-tree-participate">participate</a><span>, in §2.1</span>
5109-
<li><a href="#dom-eventlisteneroptions-passive">passive</a><span>, in §3.6</span>
5110+
<li>
5111+
passive
5112+
<ul>
5113+
<li><a href="#dom-eventlisteneroptions-passive">dict-member for EventListenerOptions</a><span>, in §3.6</span>
5114+
<li><a href="#concept-passive-event-listener">dfn for event listener</a><span>, in §3.6</span>
5115+
</ul>
51105116
<li><a href="#passive-flag">passive flag</a><span>, in §3.2</span>
51115117
<li><a href="#dom-nodeiterator-pointerbeforereferencenode">pointerBeforeReferenceNode</a><span>, in §6.1</span>
51125118
<li><a href="#concept-range-bp-position">position</a><span>, in §5.2</span>

0 commit comments

Comments
 (0)