[e] (0) Tidy up how event handlers are defined to line up better with…

… WebIDL and DOM Core git-svn-id: http://svn.whatwg.org/webapps@6654 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Oct 7, 2011 · 8226f21 · 8226f21
1 parent 864984a
commit 8226f21
Show file tree

Hide file tree

Showing 3 changed files with 163 additions and 112 deletions.
diff --git a/complete.html b/complete.html
@@ -69285,13 +69285,14 @@ <h5 id=event-handler-attributes><span class=secno>7.1.6.1 </span>Event handlers<
   list of <a href=#concept-event-listener title=concept-event-listener>event listeners</a>
   associated with <var title="">T</var> with <i>type</i> set to the
   <dfn id=event-handler-event-type>event handler event type</dfn> corresponding to <var title="">H</var>, <i>capture</i> set to false, and <i>listener</i>
-  set to be an anonymous function that does nothing when the event
-  handler's value is not a <code><a href=#function>Function</a></code> object and <a href=#concept-function-invoke title=concept-Function-invoke>invokes the <code>Function</code>
-  object</a> associated with the <a href=#event-handlers title="event handlers">event
-  handler</a> otherwise. <a href=#refsDOMCORE>[DOMCORE]</a></p>
+  set to <a href=#the-event-handler-processing-algorithm>the event handler processing algorithm</a> defined
+  below. <a href=#refsDOMCORE>[DOMCORE]</a></p>
 
   <p class=note>The <i>listener</i> is emphatically <em>not</em> the
-  <a href=#event-handlers title="event handlers">event handler</a> itself.</p>
+  <a href=#event-handlers title="event handlers">event handler</a> itself. Every
+  event handler ends up registering the same <i>listener</i>, the
+  algorithm defined below, which takes care of invoking the right
+  callback, and processing the callback's return value.</p>
 
   <p class=note>This only happens the first time the <a href=#event-handlers title="event handlers">event handler</a>'s value is set. Since
   listeners are called in the order they were registered, the order of
@@ -69331,36 +69332,53 @@ <h5 id=event-handler-attributes><span class=secno>7.1.6.1 </span>Event handlers<
   not influence whether an <a href=#event-handlers title="event handlers">event
   handler</a> is triggered or not.</p>
 
-  <p>When an <a href=#event-handlers title="event handlers">event handler</a>'s
-  <code><a href=#function>Function</a></code> object is <dfn id=concept-function-invoke title=concept-Function-invoke>invoked</dfn>, its <code title=dom-function-call><a href=#dom-function-call>call()</a></code> callback must be invoked
-  with one argument, set to the <code><a href=#event>Event</a></code> object of the event
-  in question.</p>
+  <p>The <dfn id=the-event-handler-processing-algorithm>the event handler processing algorithm</dfn> for an
+  <a href=#event-handlers title="event handlers">event handler</a> <var title="">H</var> and an <code><a href=#event>Event</a></code> object <var title="">E</var> is as follows:</p>
 
-  <p>The handler's return value must then be processed as follows:</p>
+  <ol><li><p>If <var title="">H</var>'s value is null, then abort these
+   steps.</li>
 
-  <dl class=switch><dt>If the event type is <code class=event-mouseover>mouseover</code></dt>
+   <li><p>Let <var title="">callback</var> be <var title="">H</var>'s
+   value, the <code><a href=#function>Function</a></code> object that the <a href=#event-handlers title="event
+   handlers">event handler</a> was last set to.</li>
 
-   <dd><p>If the return value is a boolean with the value true, then
-   the event must be canceled.</dd>
+   <li><p>Invoke <var title="">callback</var>'s <code title=dom-function-call><a href=#dom-function-call>call()</a></code> operation with one
+   argument, the value of which is the <code><a href=#event>Event</a></code> object <var title="">E</var>, with the <i title=dfn-callback-this-value>callback this value</i> set to the
+   <var title="">E</var>'s <code title=dom-Event-currentTarget>currentTarget</code>. Let the
+   return value be <var title="">return value</var>. <a href=#refsWEBIDL>[WEBIDL]</a></p>
 
-   <dt>If the event object is a <code><a href=#beforeunloadevent>BeforeUnloadEvent</a></code> object</dt>
+   <li>
 
-   <dd><p>If the return value is a string, and the event object's
-   <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
-   attribute's value is the empty string, then set the <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
-   attribute's value to the return value.</dd>
+   <li>
 
-   <dt>Otherwise</dt>
+    <p>Process <var title="">return value</var> as follows:</p>
 
-   <dd><p>If the return value is a boolean with the value false, then
-   the event must be canceled.</dd>
+    <dl class=switch><dt>If the event type is <code class=event-mouseover>mouseover</code></dt>
 
-  </dl></div>
+     <dd><p>If <var title="">return value</var> is a boolean with the
+     value true, then cancel the event.</dd>
+
+     <dt>If the <code><a href=#event>Event</a></code> object <var title="">E</var> is a
+     <code><a href=#beforeunloadevent>BeforeUnloadEvent</a></code> object</dt>
 
-  <!-- IE actually uncancels the event if the function returns true -->
+     <dd><p>If <var title="">return value</var> is a string, and the
+     <code><a href=#event>Event</a></code> object <var title="">E</var>'s <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
+     attribute's value is the empty string, then set the <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
+     attribute's value to <var title="">return value</var>.</dd>
+
+     <dt>Otherwise</dt>
+
+     <dd><p>If <var title="">return value</var> is a boolean with the
+     value false, then cancel the event.</dd>
+
+     <!-- IE actually uncancels the event if the function returns true -->
+
+    </dl></li>
+
+  </ol></div>
 
   <hr><p>The <code><a href=#function>Function</a></code> interface represents a function in the
-  scripting language being used. It is represented in IDL as
+  scripting language being used. It is represented in Web IDL as
   follows:</p>
 
   <pre class=idl>[Callback=FunctionOnly, NoInterfaceObject]
@@ -69374,11 +69392,6 @@ <h5 id=event-handler-attributes><span class=secno>7.1.6.1 </span>Event handlers<
   <p class=note>In JavaScript, any <code title="">Function</code>
   object implements this interface.</p>
 
-  <p>If the <code><a href=#function>Function</a></code> object is a JavaScript <code title="">Function</code>, then when it is invoked by the user agent,
-  the user agent must set the <var title="">thisArg</var> (as defined
-  by ECMAScript edition 5 section 10.4.3 Entering Function Code) to
-  the <a href=#event-handlers title="event handlers">event handler</a>'s object. <a href=#refsECMA262>[ECMA262]</a></p>
-
   <div class=example>
 
    <p>For example, the following document fragment:</p>
@@ -69391,11 +69404,13 @@ <h5 id=event-handler-attributes><span class=secno>7.1.6.1 </span>Event handlers<
 
   </div>
 
-  <p>The return value of the function affects whether the event is
-  canceled or not: <span class=impl>as described above,</span> if
-  the return value is false, the event is canceled (except for <code class=event-mouseover>mouseover</code> events, where the return
-  value has to be true to cancel the event). With <code title=event-beforeunload>beforeunload</code> events, the value is
-  instead used to determine the message to show the user.</p>
+  <p class=note>The return value of the function affects whether the
+  event is canceled or not: <span class=impl>as described
+  above,</span> if the return value is false, the event is canceled
+  (except for <code class=event-mouseover>mouseover</code> events,
+  where the return value has to be true to cancel the event). With
+  <code title=event-beforeunload>beforeunload</code> events, the
+  value is instead used to determine the message to show the user.</p>
 
 
   <h5 id=event-handlers-on-elements,-document-objects,-and-window-objects><span class=secno>7.1.6.2 </span>Event handlers on elements, <code><a href=#document>Document</a></code> objects, and <code><a href=#window>Window</a></code> objects</h5>

diff --git a/index b/index
@@ -69285,13 +69285,14 @@ currently this is unnecessary: http://www.w3.org/Bugs/Public/show_bug.cgi?id=119
   list of <a href=#concept-event-listener title=concept-event-listener>event listeners</a>
   associated with <var title="">T</var> with <i>type</i> set to the
   <dfn id=event-handler-event-type>event handler event type</dfn> corresponding to <var title="">H</var>, <i>capture</i> set to false, and <i>listener</i>
-  set to be an anonymous function that does nothing when the event
-  handler's value is not a <code><a href=#function>Function</a></code> object and <a href=#concept-function-invoke title=concept-Function-invoke>invokes the <code>Function</code>
-  object</a> associated with the <a href=#event-handlers title="event handlers">event
-  handler</a> otherwise. <a href=#refsDOMCORE>[DOMCORE]</a></p>
+  set to <a href=#the-event-handler-processing-algorithm>the event handler processing algorithm</a> defined
+  below. <a href=#refsDOMCORE>[DOMCORE]</a></p>
 
   <p class=note>The <i>listener</i> is emphatically <em>not</em> the
-  <a href=#event-handlers title="event handlers">event handler</a> itself.</p>
+  <a href=#event-handlers title="event handlers">event handler</a> itself. Every
+  event handler ends up registering the same <i>listener</i>, the
+  algorithm defined below, which takes care of invoking the right
+  callback, and processing the callback's return value.</p>
 
   <p class=note>This only happens the first time the <a href=#event-handlers title="event handlers">event handler</a>'s value is set. Since
   listeners are called in the order they were registered, the order of
@@ -69331,36 +69332,53 @@ currently this is unnecessary: http://www.w3.org/Bugs/Public/show_bug.cgi?id=119
   not influence whether an <a href=#event-handlers title="event handlers">event
   handler</a> is triggered or not.</p>
 
-  <p>When an <a href=#event-handlers title="event handlers">event handler</a>'s
-  <code><a href=#function>Function</a></code> object is <dfn id=concept-function-invoke title=concept-Function-invoke>invoked</dfn>, its <code title=dom-function-call><a href=#dom-function-call>call()</a></code> callback must be invoked
-  with one argument, set to the <code><a href=#event>Event</a></code> object of the event
-  in question.</p>
+  <p>The <dfn id=the-event-handler-processing-algorithm>the event handler processing algorithm</dfn> for an
+  <a href=#event-handlers title="event handlers">event handler</a> <var title="">H</var> and an <code><a href=#event>Event</a></code> object <var title="">E</var> is as follows:</p>
 
-  <p>The handler's return value must then be processed as follows:</p>
+  <ol><li><p>If <var title="">H</var>'s value is null, then abort these
+   steps.</li>
 
-  <dl class=switch><dt>If the event type is <code class=event-mouseover>mouseover</code></dt>
+   <li><p>Let <var title="">callback</var> be <var title="">H</var>'s
+   value, the <code><a href=#function>Function</a></code> object that the <a href=#event-handlers title="event
+   handlers">event handler</a> was last set to.</li>
 
-   <dd><p>If the return value is a boolean with the value true, then
-   the event must be canceled.</dd>
+   <li><p>Invoke <var title="">callback</var>'s <code title=dom-function-call><a href=#dom-function-call>call()</a></code> operation with one
+   argument, the value of which is the <code><a href=#event>Event</a></code> object <var title="">E</var>, with the <i title=dfn-callback-this-value>callback this value</i> set to the
+   <var title="">E</var>'s <code title=dom-Event-currentTarget>currentTarget</code>. Let the
+   return value be <var title="">return value</var>. <a href=#refsWEBIDL>[WEBIDL]</a></p>
 
-   <dt>If the event object is a <code><a href=#beforeunloadevent>BeforeUnloadEvent</a></code> object</dt>
+   <li>
 
-   <dd><p>If the return value is a string, and the event object's
-   <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
-   attribute's value is the empty string, then set the <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
-   attribute's value to the return value.</dd>
+   <li>
 
-   <dt>Otherwise</dt>
+    <p>Process <var title="">return value</var> as follows:</p>
 
-   <dd><p>If the return value is a boolean with the value false, then
-   the event must be canceled.</dd>
+    <dl class=switch><dt>If the event type is <code class=event-mouseover>mouseover</code></dt>
 
-  </dl></div>
+     <dd><p>If <var title="">return value</var> is a boolean with the
+     value true, then cancel the event.</dd>
+
+     <dt>If the <code><a href=#event>Event</a></code> object <var title="">E</var> is a
+     <code><a href=#beforeunloadevent>BeforeUnloadEvent</a></code> object</dt>
 
-  <!-- IE actually uncancels the event if the function returns true -->
+     <dd><p>If <var title="">return value</var> is a string, and the
+     <code><a href=#event>Event</a></code> object <var title="">E</var>'s <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
+     attribute's value is the empty string, then set the <code title=dom-BeforeUnloadEvent-returnValue><a href=#dom-beforeunloadevent-returnvalue>returnValue</a></code>
+     attribute's value to <var title="">return value</var>.</dd>
+
+     <dt>Otherwise</dt>
+
+     <dd><p>If <var title="">return value</var> is a boolean with the
+     value false, then cancel the event.</dd>
+
+     <!-- IE actually uncancels the event if the function returns true -->
+
+    </dl></li>
+
+  </ol></div>
 
   <hr><p>The <code><a href=#function>Function</a></code> interface represents a function in the
-  scripting language being used. It is represented in IDL as
+  scripting language being used. It is represented in Web IDL as
   follows:</p>
 
   <pre class=idl>[Callback=FunctionOnly, NoInterfaceObject]
@@ -69374,11 +69392,6 @@ interface <dfn id=function>Function</dfn> {
   <p class=note>In JavaScript, any <code title="">Function</code>
   object implements this interface.</p>
 
-  <p>If the <code><a href=#function>Function</a></code> object is a JavaScript <code title="">Function</code>, then when it is invoked by the user agent,
-  the user agent must set the <var title="">thisArg</var> (as defined
-  by ECMAScript edition 5 section 10.4.3 Entering Function Code) to
-  the <a href=#event-handlers title="event handlers">event handler</a>'s object. <a href=#refsECMA262>[ECMA262]</a></p>
-
   <div class=example>
 
    <p>For example, the following document fragment:</p>
@@ -69391,11 +69404,13 @@ interface <dfn id=function>Function</dfn> {
 
   </div>
 
-  <p>The return value of the function affects whether the event is
-  canceled or not: <span class=impl>as described above,</span> if
-  the return value is false, the event is canceled (except for <code class=event-mouseover>mouseover</code> events, where the return
-  value has to be true to cancel the event). With <code title=event-beforeunload>beforeunload</code> events, the value is
-  instead used to determine the message to show the user.</p>
+  <p class=note>The return value of the function affects whether the
+  event is canceled or not: <span class=impl>as described
+  above,</span> if the return value is false, the event is canceled
+  (except for <code class=event-mouseover>mouseover</code> events,
+  where the return value has to be true to cancel the event). With
+  <code title=event-beforeunload>beforeunload</code> events, the
+  value is instead used to determine the message to show the user.</p>
 
 
   <h5 id=event-handlers-on-elements,-document-objects,-and-window-objects><span class=secno>7.1.6.2 </span>Event handlers on elements, <code><a href=#document>Document</a></code> objects, and <code><a href=#window>Window</a></code> objects</h5>