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

Redesign fire an event and target override #344

Merged
merged 3 commits into from
Oct 14, 2016
Merged

Redesign fire an event and target override #344

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7298940
Redesign fire an event and target override
annevk Oct 13, 2016
6e9c3d3
address review feedback plus nits I found myself
annevk Oct 14, 2016
a7ce7c1
final nits
annevk Oct 14, 2016
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
74 changes: 51 additions & 23 deletions dom.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1184,18 +1184,18 @@ for discussion).
<h3 id=dispatching-events>Dispatching events</h3>

<p>To <dfn export for=Event id=concept-event-dispatch>dispatch</dfn> an <var>event</var> to a
<var>target</var>, with an optional <var>targetOverride</var>, run these steps:
<var>target</var>, with an optional <var>legacy target override flag</var>, run these steps:

<ol>
<li><p>Set <var>event</var>'s <a>dispatch flag</a>.

<li>
<p>If <var>targetOverride</var> is not given, let <var>targetOverride</var> be <var>target</var>.
<p>Let <var>targetOverride</var> be <var>target</var>, if <var>legacy target override flag</var>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I think "the legacy target override flag" is more consistent with what we've done so far.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not in my prose... (Aside: I'm really starting to dislike flags. I wish we'd just have optional arguments with default values and use booleans here.)

is not given, and <var>target</var>'s <a>associated <code>Document</code></a> otherwise.
[[!HTML]]

<p class="note">The <var>targetOverride</var> argument is only used by HTML and only under very
specific circumstances.
<!-- We should consider refactoring it to make it have less of a scope, since we don't really want
folks to start using it for non-legacy scenarios. -->
<p class="note"><var>legacy target override flag</var> is only used by HTML and only when
<var>target</var> is a {{Window}} object.

<li>Let <var>relatedTarget</var> be the result of <a>retargeting</a> <var>event</var>'s
<a>relatedTarget</a> against <var>target</var> if <var>event</var>'s <a>relatedTarget</a> is
Expand Down Expand Up @@ -1377,25 +1377,53 @@ an <var>object</var> with <var>event</var>, run these steps:
<li><p>Return <var>found</var>.
</ol>


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

To
<dfn export id=concept-event-fire lt="fire an event">fire an event named <var>e</var></dfn>
means that a new <a>event</a> using the
{{Event}} interface, with its
{{Event/type}} attribute initialized to
<var>e</var>, and its {{Event/isTrusted}}
attribute initialized to <code>true</code>, is to be
<a>dispatched</a> to the given object.

<p class="note no-backref">Fire in the context of DOM is short for creating, initializing,
and <a>dispatching</a> an <a>event</a>.
<a>Fire an event</a> makes that process easier to write
down. If the <a>event</a> needs its {{Event/bubbles}} or
{{Event/cancelable}} attribute initialized, one could write
"<a>fire an event</a> named
<code>submit</code> with its {{Event/cancelable}} attribute
initialized to true".
<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:

<ol>
<li><p>If <var>eventConstructor</var> is not given, then let <var>eventConstructor</var> be
{{Event}}.

<li><p>Let <var>event</var> be the result of <a for=Event lt=constructor>invoking</a> the initial
value of <var>eventConstructor</var> with the argument <var>e</var>.

<li><p>Initialize <var>event</var>'s {{Event/isTrusted}} attribute to true.

<li>
<p>Initialize any other IDL attributes of <var>event</var> as described in the invocation of this
algorithm.

<p class="note">This also allows for the {{Event/isTrusted}} attribute to be set to false.

<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>

<p class="note no-backref">Fire in the context of DOM is short for creating, initializing, and
<a>dispatching</a> an <a>event</a>. <a>Fire an event</a> makes that process easier to write down.

<div class="example no-backref" id=firing-events-example>
<p>If the <a>event</a> needs its {{Event/bubbles}} or {{Event/cancelable}} attribute initialized,
one could write "<a>fire an event</a> named <code>submit</code> at <var>target</var> with its
{{Event/cancelable}} attribute initialized to true".

<p>Or, when a custom constructor is required, "<a>fire an event</a> named <code>click</code> at
<var>target</var> using {{MouseEvent}} with its {{Event/isTrusted}} attribute initialized to
false".

<p>Ocassionally the return value is important:

<ol>
<li><p>Let <var>doAction</var> be the result of <a lt="fire an event">firing an event</a> named
<code>like</code> at <var>target</var>.

<li><p>If <var>doAction</var> is true, then &hellip;
</ol>
</div>


<h3 id=action-versus-occurance>Action versus occurrence</h3>
Expand Down
53 changes: 40 additions & 13 deletions dom.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@
<p data-fill-with="logo"><a class="logo" href="https://whatwg.org/"> <img alt="WHATWG" height="100" src="https://resources.whatwg.org/logo-dom.svg"> </a> </p>
<hgroup>
<h1 class="p-name no-ref allcaps" id="title">DOM</h1>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Living Standard — Last Updated <time class="dt-updated" datetime="2016-10-11">11 October 2016</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Living Standard — Last Updated <time class="dt-updated" datetime="2016-10-14">14 October 2016</time></span></h2>
</hgroup>
<div data-fill-with="spec-metadata">
<dl>
Expand Down Expand Up @@ -871,14 +871,13 @@ <h3 class="heading settled" data-level="3.7" id="observing-event-listeners"><spa
of non-<code class="idl"><a data-link-type="idl" href="#dom-addeventlisteneroptions-passive">passive</a></code> listeners, and use that to clear the <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> property of the event being dispatched. </p>
<p>Ideally, any new event APIs are defined such that they do not need this property (use <a href="https://lists.w3.org/Archives/Public/public-script-coord/">[email protected]</a> for discussion). </p>
<h3 class="heading settled" data-level="3.8" id="dispatching-events"><span class="secno">3.8. </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 <var>event</var> to a <var>target</var>, with an optional <var>targetOverride</var>, run these steps: </p>
<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 <var>event</var> to a <var>target</var>, with an optional <var>legacy target override flag</var>, run these steps: </p>
<ol>
<li>
<p>Set <var>event</var>’s <a data-link-type="dfn" href="#dispatch-flag">dispatch flag</a>. </p>
<li>
<p>If <var>targetOverride</var> is not given, let <var>targetOverride</var> be <var>target</var>. </p>
<p class="note" role="note">The <var>targetOverride</var> argument is only used by HTML and only under very
specific circumstances. </p>
<p>Let <var>targetOverride</var> be <var>target</var>, if <var>legacy target override flag</var> is not given, and <var>target</var>’s <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#concept-document-window">associated <code>Document</code></a> otherwise. <a data-link-type="biblio" href="#biblio-html">[HTML]</a> </p>
<p class="note" role="note"><var>legacy target override flag</var> is only used by HTML and only when <var>target</var> is a <code class="idl"><a data-link-type="idl" href="https://html.spec.whatwg.org/multipage/browsers.html#window">Window</a></code> object. </p>
<li>Let <var>relatedTarget</var> be the result of <a data-link-type="dfn" href="#retarget">retargeting</a> <var>event</var>’s <a data-link-type="dfn" href="#event-relatedtarget">relatedTarget</a> against <var>target</var> if <var>event</var>’s <a data-link-type="dfn" href="#event-relatedtarget">relatedTarget</a> is
non-null, and null otherwise.
<li>
Expand Down Expand Up @@ -1015,7 +1014,7 @@ <h3 class="heading settled" data-level="3.8" id="dispatching-events"><span class
<li>
<p>If <var>listener</var>’s <b>passive</b> is true, set <var>event</var>’s <a data-link-type="dfn" href="#in-passive-listener-flag">in passive listener flag</a>. </p>
<li>
<p><a data-link-type="dfn">Call a user object’s operation</a> with <var>listener</var>’s <b>callback</b>,
<p><a data-link-type="dfn" href="https://heycam.github.io/webidl/#call-a-user-objects-operation">Call a user object’s operation</a> with <var>listener</var>’s <b>callback</b>,
"<code>handleEvent</code>", a list of arguments consisting of <var>event</var>, and <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code> attribute value as the <a data-link-type="dfn" href="https://heycam.github.io/webidl/#dfn-callback-this-value">callback this value</a>. If
this throws an exception, <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#report-the-exception">report the exception</a>. </p>
<li>
Expand All @@ -1028,12 +1027,39 @@ <h3 class="heading settled" data-level="3.8" id="dispatching-events"><span class
<p>Return <var>found</var>. </p>
</ol>
<h3 class="heading settled" data-level="3.9" id="firing-events"><span class="secno">3.9. </span><span class="content">Firing events</span><a class="self-link" href="#firing-events"></a></h3>
<p>To <dfn data-dfn-type="dfn" data-export="" data-lt="fire an event" id="concept-event-fire">fire an event named <var>e</var><a class="self-link" href="#concept-event-fire"></a></dfn> means that a new <a data-link-type="dfn" href="#concept-event">event</a> using the <code class="idl"><a data-link-type="idl" href="#event">Event</a></code> interface, with its <code class="idl"><a data-link-type="idl" href="#dom-event-type">type</a></code> attribute initialized to <var>e</var>, and its <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code> attribute initialized to <code>true</code>, is to be <a data-link-type="dfn" href="#concept-event-dispatch">dispatched</a> to the given object.</p>
<p class="note no-backref" role="note">Fire in the context of DOM is short for creating, initializing,
and <a data-link-type="dfn" href="#concept-event-dispatch">dispatching</a> an <a data-link-type="dfn" href="#concept-event">event</a>. <a data-link-type="dfn" href="#concept-event-fire">Fire an event</a> makes that process easier to write
down. If the <a data-link-type="dfn" href="#concept-event">event</a> needs its <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code> or <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute initialized, one could write
"<a data-link-type="dfn" href="#concept-event-fire">fire an event</a> named <code>submit</code> with its <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute
initialized to true". </p>
<p>To <dfn data-dfn-type="dfn" data-export="" id="concept-event-fire">fire an event<a class="self-link" href="#concept-event-fire"></a></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: </p>
<ol>
<li>
<p>If <var>eventConstructor</var> is not given, then let <var>eventConstructor</var> be <code class="idl"><a data-link-type="idl" href="#event">Event</a></code>. </p>
<li>
<p>Let <var>event</var> be the result of <a data-link-type="dfn" href="#concept-event-constructor">invoking</a> the initial
value of <var>eventConstructor</var> with the argument <var>e</var>. </p>
<li>
<p>Initialize <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code> attribute to true. </p>
<li>
<p>Initialize any other IDL attributes of <var>event</var> as described in the invocation of this
algorithm. </p>
<p class="note" role="note">This also allows for the <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code> attribute to be set to false. </p>
<li>
<p>Return the result of <a data-link-type="dfn" href="#concept-event-dispatch">dispatching</a> <var>event</var> at <var>target</var>, with <var>legacy target override flag</var> set if set. </p>
</ol>
<p class="note no-backref" role="note">Fire in the context of DOM is short for creating, initializing, and <a data-link-type="dfn" href="#concept-event-dispatch">dispatching</a> an <a data-link-type="dfn" href="#concept-event">event</a>. <a data-link-type="dfn" href="#concept-event-fire">Fire an event</a> makes that process easier to write down. </p>
<div class="example no-backref" id="firing-events-example">
<a class="self-link" href="#firing-events-example"></a>
<p>If the <a data-link-type="dfn" href="#concept-event">event</a> needs its <code class="idl"><a data-link-type="idl" href="#dom-event-bubbles">bubbles</a></code> or <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute initialized,
one could write "<a data-link-type="dfn" href="#concept-event-fire">fire an event</a> named <code>submit</code> at <var>target</var> with its <code class="idl"><a data-link-type="idl" href="#dom-event-cancelable">cancelable</a></code> attribute initialized to true". </p>
<p>Or, when a custom constructor is required, "<a data-link-type="dfn" href="#concept-event-fire">fire an event</a> named <code>click</code> at <var>target</var> using <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/uievents/#interface-mouseevent">MouseEvent</a></code> with its <code class="idl"><a data-link-type="idl" href="#dom-event-istrusted">isTrusted</a></code> attribute initialized to
false". </p>
<p>Ocassionally the return value is important: </p>
<ol>
<li>
<p>Let <var>doAction</var> be the result of <a data-link-type="dfn" href="#concept-event-fire">firing an event</a> named <code>like</code> at <var>target</var>. </p>
<li>
<p>If <var>doAction</var> is true, then … </p>
</ol>
</div>
<h3 class="heading settled" data-level="3.10" id="action-versus-occurance"><span class="secno">3.10. </span><span class="content">Action versus occurrence</span><a class="self-link" href="#action-versus-occurance"></a></h3>
<p>An <a data-link-type="dfn" href="#concept-event">event</a> signifies an occurrence, not an action. Phrased differently, it
represents a notification from an algorithm and can be used to influence the future course
Expand Down Expand Up @@ -4844,7 +4870,7 @@ <h2 class="heading settled" data-level="6" id="traversal"><span class="secno">6.
return <code class="idl"><a data-link-type="idl" href="#dom-nodefilter-filter_skip">FILTER_SKIP</a></code>.
<li>If <a data-link-type="dfn" href="#concept-traversal-filter">filter</a> is null,
return <code class="idl"><a data-link-type="idl" href="#dom-nodefilter-filter_accept">FILTER_ACCEPT</a></code>.
<li>Let <var>result</var> be the return value of <a data-link-type="dfn">call a user object’s operation</a> with <a data-link-type="dfn" href="#concept-traversal-filter">filter</a>, "<code>acceptNode</code>", and a list of arguments consisting of <var>node</var>. Rethrow any exceptions.
<li>Let <var>result</var> be the return value of <a data-link-type="dfn" href="https://heycam.github.io/webidl/#call-a-user-objects-operation">call a user object’s operation</a> with <a data-link-type="dfn" href="#concept-traversal-filter">filter</a>, "<code>acceptNode</code>", and a list of arguments consisting of <var>node</var>. Rethrow any exceptions.
<li>Return <var>result</var>.
</ol>
<h3 class="heading settled" data-level="6.1" id="interface-nodeiterator"><span class="secno">6.1. </span><span class="content">Interface <code class="idl"><a data-link-type="idl" href="#nodeiterator">NodeIterator</a></code></span><a class="self-link" href="#interface-nodeiterator"></a></h3>
Expand Down Expand Up @@ -6595,6 +6621,7 @@ <h3 class="no-num no-ref heading settled" id="index-defined-elsewhere"><span cla
<li><a href="https://heycam.github.io/webidl/#Unforgeable">Unforgeable</a>
<li><a href="https://heycam.github.io/webidl/#Unscopable">Unscopable</a>
<li><a href="https://heycam.github.io/webidl/#wrongdocumenterror">WrongDocumentError</a>
<li><a href="https://heycam.github.io/webidl/#call-a-user-objects-operation">call a user object's operation</a>
<li><a href="https://heycam.github.io/webidl/#dfn-callback-this-value">callback this value</a>
<li><a href="https://heycam.github.io/webidl/#dfn-dictionary-member">dictionary members</a>
<li><a href="https://heycam.github.io/webidl/#dfn-identifier">identifier</a>
Expand Down