Skip to content

Commit

Permalink
Editorial: mark up algorithms about Events
Browse files Browse the repository at this point in the history
Also fix a typo that Bikeshed was able to find thanks to this.
  • Loading branch information
Ms2ger committed Dec 14, 2023
1 parent 277983d commit 03357df
Showing 1 changed file with 27 additions and 1 deletion.
28 changes: 27 additions & 1 deletion dom.bs
Original file line number Diff line number Diff line change
Expand Up @@ -510,6 +510,7 @@ string.
<p>The <dfn attribute for=Event><code>currentTarget</code></dfn> attribute must return the value it
was initialized to. When an <a>event</a> is created the attribute must be initialized to null.

<div algorithm>
<p>The <dfn method for=Event><code>composedPath()</code></dfn> method steps are:

<ol>
Expand Down Expand Up @@ -608,6 +609,7 @@ was initialized to. When an <a>event</a> is created the attribute must be initia

<li><p>Return <var>composedPath</var>.
</ol>
</div>

<p>The <dfn attribute for=Event><code>eventPhase</code></dfn> attribute must return the value it was
initialized to, which must be one of the following:
Expand Down Expand Up @@ -703,6 +705,7 @@ initialized to.

<hr>

<div algorithm>
<p>To <dfn export for=Event id=concept-event-initialize>initialize</dfn> an <var>event</var>, with
<var>type</var>, <var>bubbles</var>, and <var>cancelable</var>, run these steps:

Expand All @@ -722,7 +725,9 @@ initialized to.

<li><p>Set <var>event</var>'s {{Event/cancelable}} attribute to <var>cancelable</var>.
</ol>
</div>

<div algorithm>
<p>The
<dfn method for=Event><code>initEvent(<var>type</var>, <var>bubbles</var>, <var>cancelable</var>)</code></dfn>
method steps are:
Expand All @@ -733,6 +738,7 @@ method steps are:
<li><p><a>Initialize</a> <a>this</a> with <var>type</var>, <var>bubbles</var>, and
<var>cancelable</var>.
</ol>
</div>

<p class=note>{{Event/initEvent()}} is redundant with <a>event</a> constructors and
incapable of setting {{Event/composed}}. It has to be supported for legacy content.
Expand Down Expand Up @@ -792,6 +798,7 @@ dictionary CustomEventInit : EventInit {
<p>The <dfn attribute for=CustomEvent><code>detail</code></dfn> attribute must return the value it
was initialized to.

<div algorithm>
<p>The
<dfn method for=CustomEvent><code>initCustomEvent(<var>type</var>, <var>bubbles</var>, <var>cancelable</var>, <var>detail</var>)</code></dfn>
method steps are:
Expand All @@ -804,6 +811,7 @@ method steps are:

<li><p>Set <a>this</a>'s {{CustomEvent/detail}} attribute to <var>detail</var>.
</ol>
</div>


<h3 id=constructing-events>Constructing events</h3>
Expand All @@ -816,6 +824,7 @@ method steps are:
<p class=note>This construct can be used by {{Event}} subclasses that have a more complex structure
than a simple 1:1 mapping between their initializing dictionary members and IDL attributes.

<div algorithm>
<p>When a <dfn export for=Event id=concept-event-constructor>constructor</dfn> of the {{Event}}
interface, or of an interface that inherits from the {{Event}} interface, is invoked, these steps
must be run, given the arguments <var>type</var> and <var>eventInitDict</var>:
Expand All @@ -828,7 +837,9 @@ must be run, given the arguments <var>type</var> and <var>eventInitDict</var>:

<li><p>Return <var>event</var>.
</ol>
</div>

<div algorithm>
<p>To
<dfn export id=concept-event-create lt="creating an event|create an event">create an event</dfn>
using <var>eventInterface</var>, which must be either {{Event}} or an interface that inherits from
Expand Down Expand Up @@ -858,13 +869,15 @@ it, and optionally given a <a>realm</a> <var>realm</var>, run these steps:</p>

<li><p>Return <var>event</var>.
</ol>
</div>

<p class=note><a>Create an event</a> is meant to be used by other specifications which need to
separately <a lt="create an event">create</a> and <a>dispatch</a> events, instead of simply
<a lt="fire an event">firing</a> them. It ensures the event's attributes are initialized to the
correct defaults.</p>

<p>The <dfn noexport>inner event creation steps</dfn>, given an <var>interface</var>,
<div algorithm>
<p>The <dfn noexport>inner event creation steps</dfn>, given an <var>eventInterface</var>,
<var>realm</var>, <var>time</var>, and <var>dictionary</var>, are as follows:</p>

<ol>
Expand All @@ -890,6 +903,7 @@ correct defaults.</p>

<li><p>Return <var>event</var>.
</ol>
</div>


<h3 id=defining-event-interfaces>Defining event interfaces</h3>
Expand Down Expand Up @@ -1246,6 +1260,7 @@ property of the event being dispatched.
<p>Ideally, any new event APIs are defined such that they do not need this property. (Use
<a href="https://github.com/whatwg/dom/issues">whatwg/dom</a> for discussion.)

<div algorithm>
<p>To <dfn export>legacy-obtain service worker fetch event listener callbacks</dfn> given a
{{ServiceWorkerGlobalScope}} <var>global</var>, run these steps. They return a <a for=/>list</a> of
{{EventListener}} objects.
Expand All @@ -1265,10 +1280,12 @@ property of the event being dispatched.

<li><p>Return <var>callbacks</var>.
</ol>
</div>


<h3 id=dispatching-events>Dispatching events</h3>

<div algorithm>
<p>To <dfn export id=concept-event-dispatch>dispatch</dfn> an <var>event</var> to a
<var>target</var>, with an optional <var>legacy target override flag</var> and an optional
<var>legacyOutputDidListenersThrowFlag</var>, run these steps:
Expand Down Expand Up @@ -1468,7 +1485,9 @@ property of the event being dispatched.

<li><p>Return false if <var>event</var>'s <a>canceled flag</a> is set; otherwise true.
</ol>
</div>

<div algorithm>
<p>To <dfn noexport id=concept-event-path-append>append to an event path</dfn>, given an
<var>event</var>, <var>invocationTarget</var>, <var>shadowAdjustedTarget</var>,
<var>relatedTarget</var>, <var>touchTargets</var>, and a <var>slot-in-closed-tree</var>, run these
Expand All @@ -1494,7 +1513,9 @@ steps:</p>
<a for=Event/path>root-of-closed-tree</a> is <var>root-of-closed-tree</var>, and
<a for=Event/path>slot-in-closed-tree</a> is <var>slot-in-closed-tree</var>.
</ol>
</div>

<div algorithm>
<p>To <dfn noexport id=concept-event-listener-invoke>invoke</dfn>, given a <var>struct</var>,
<var>event</var>, <var>phase</var>, and an optional <var>legacyOutputDidListenersThrowFlag</var>,
run these steps:
Expand Down Expand Up @@ -1559,7 +1580,9 @@ run these steps:
<li><p>Set <var>event</var>'s {{Event/type}} attribute value to <var>originalEventType</var>.
</ol>
</ol>
</div>

<div algorithm>
<p>To <dfn noexport id=concept-event-listener-inner-invoke>inner invoke</dfn>, given an
<var>event</var>, <var>listeners</var>, <var>phase</var>, <var>invocationTargetInShadowTree</var>,
and an optional <var>legacyOutputDidListenersThrowFlag</var>, run these steps:
Expand Down Expand Up @@ -1633,10 +1656,12 @@ and an optional <var>legacyOutputDidListenersThrowFlag</var>, run these steps:

<li><p>Return <var>found</var>.
</ol>
</div>


<h3 id=firing-events>Firing events</h3>

<div algorithm>
<p>To <dfn export id=concept-event-fire>fire an event</dfn> named <var>e</var> at <var>target</var>,
optionally using an <var>eventConstructor</var>, with a description of how IDL attributes are to be
initialized, and a <var>legacy target override flag</var>, run these steps:
Expand All @@ -1659,6 +1684,7 @@ initialized, and a <var>legacy target override flag</var>, run these steps:
<li><p>Return the result of <a>dispatching</a> <var>event</var> at <var>target</var>, with
<var>legacy target override flag</var> set if set.
</ol>
</div>

<p class=note>Fire in the context of DOM is short for
<a lt="create an event">creating</a>, initializing, and <a>dispatching</a> an <a>event</a>.
Expand Down

0 comments on commit 03357df

Please sign in to comment.