Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Editorial: mark up algorithms about Events #1240

Merged
merged 1 commit into from
Dec 14, 2023
Merged

Editorial: mark up algorithms about Events #1240

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion dom.bs
View file
Open in desktop
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