HTML Standard Tracker

Diff (omit for latest revision)
Filter

Short URL: http://html5.org/r/2282

File a bug

SVNBugCommentTime (UTC)
2282WF2: input and change events; activation behaviors for <input> element.2008-10-05 09:19
Index: source
===================================================================
--- source	(revision 2281)
+++ source	(revision 2282)
@@ -26277,6 +26277,52 @@
      <td class="no"> &middot; <!-- Reset Button -->
 <!-- <td class="no"> &middot;      Button -->
 
+    <tr>
+     <th> <code title="event-input-input">input</code> event
+     <td class="no"> &middot; <!-- Hidden -->
+     <td class="yes"> Yes     <!-- Text -->
+<!-- <td class="yes"> Yes          E-mail -->
+<!-- <td class="yes"> Yes          URL -->
+     <td class="yes"> Yes     <!-- Password -->
+     <td class="yes"> Yes     <!-- Date and Time -->
+<!-- <td class="yes"> Yes          Date -->
+<!-- <td class="yes"> Yes          Month -->
+<!-- <td class="yes"> Yes          Week -->
+<!-- <td class="yes"> Yes          Time -->
+     <td class="yes"> Yes     <!-- Local Date and Time -->
+<!-- <td class="yes"> Yes          Number -->
+     <td class="yes"> Yes     <!-- Range -->
+     <td class="yes"> Yes     <!-- Checkbox -->
+<!-- <td class="yes"> Yes          Radio Button -->
+     <td class="no"> &middot; <!-- File Upload -->
+     <td class="no"> &middot; <!-- Submit Button -->
+     <td class="no"> &middot; <!-- Image Button -->
+     <td class="no"> &middot; <!-- Reset Button -->
+<!-- <td class="no"> &middot;      Button -->
+
+    <tr>
+     <th> <code title="event-input-change">change</code> event
+     <td class="no"> &middot; <!-- Hidden -->
+     <td class="yes"> Yes     <!-- Text -->
+<!-- <td class="yes"> Yes          E-mail -->
+<!-- <td class="yes"> Yes          URL -->
+     <td class="yes"> Yes     <!-- Password -->
+     <td class="yes"> Yes     <!-- Date and Time -->
+<!-- <td class="yes"> Yes          Date -->
+<!-- <td class="yes"> Yes          Month -->
+<!-- <td class="yes"> Yes          Week -->
+<!-- <td class="yes"> Yes          Time -->
+     <td class="yes"> Yes     <!-- Local Date and Time -->
+<!-- <td class="yes"> Yes          Number -->
+     <td class="yes"> Yes     <!-- Range -->
+     <td class="yes"> Yes     <!-- Checkbox -->
+<!-- <td class="yes"> Yes          Radio Button -->
+     <td class="yes"> Yes     <!-- File Upload -->
+     <td class="no"> &middot; <!-- Submit Button -->
+     <td class="no"> &middot; <!-- Image Button -->
+     <td class="no"> &middot; <!-- Reset Button -->
+<!-- <td class="no"> &middot; Button -->
+
   </table>
 
   <p>When an <code>input</code> element's <code
@@ -26456,11 +26502,8 @@
   serialisation. e.g. should it be 2008-01-01T00:00 or
   2008-01-01t00:00? should it be 1e2 or 100? -->
 
-  <!-- XXX for each of these, need to say when to fire oninput and
-  onchange -->
 
 
-
   <h6><dfn title="attr-input-type-hidden">Hidden</dfn> state</h6>
 
   <p>When an <code>input</code> element's <code
@@ -26518,6 +26561,9 @@
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code>, and
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> methods.</p>
 
+  <p>The <code class="no-backref"
+  title="event-input-input">input</code> and <code class="no-backref"
+  title="event-input-change">change</code> events do not fire.</p>
 
 
   <h6><dfn title="attr-input-type-text">Text</dfn> state</h6>
@@ -26556,6 +26602,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -26630,6 +26679,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -26700,6 +26752,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -26755,6 +26810,9 @@
   <code title="attr-input-size">size</code> content attributes;
   <code title="attr-input-value">value</code> DOM attribute.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -26895,6 +26953,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27024,6 +27085,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27155,6 +27219,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27285,6 +27352,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27410,6 +27480,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27522,6 +27595,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27623,6 +27699,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27762,6 +27841,9 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-value">value</span>.</p>
 
+  <p>The <code title="event-input-input">input</code> and <code
+  title="event-input-change">change</code> events apply.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27799,16 +27881,21 @@
   false, a negative selection.</p>
 
   <p>If the element is <i title="concept-input-mutable">mutable</i>,
-  the user should allow the user to toggle the <span
-  title="concept-fe-checked">checkedness</span> state.</p>
+  then: The <span>pre-click activation steps</span> consist of setting
+  the element's <span title="concept-fe-checked">checkedness</span> to
+  its opposite value (i.e. true if it is false, false if it is
+  true). The <span>canceled activation steps</span> consist of setting
+  the <span title="concept-fe-checked">checkedness</span> back to the
+  value it had before the <span>pre-click activation steps</span> were
+  run. The <span>activation behavior</span> is to <span>fire a simple
+  event</span> called <code title="event-change">change</code> at the
+  element.</p>
 
   <p><strong>Constraint validation:</strong> If the element is <i
   title="concept-input-required">required</i> and its <span
   title="concept-fe-checkedness">checkedness</span> is false, then the
   element is <span>suffering from being missing</span>.</p>
 
-  <!-- XXX event timing; activation behavior -->
-
   <p>The following common <code>input</code> element content
   attributes and DOM attributes apply to the element:
   <code title="attr-input-checked">checked</code>, and
@@ -27819,6 +27906,8 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-default-on">default/on</span>.</p>
 
+  <p>The <code title="event-input-change">change</code> event applies.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27846,8 +27935,11 @@
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> and
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code> methods.</p>
 
+  <p>The <code title="event-input-input">input</code> event does not
+  apply.</p>
 
 
+
   <h6><dfn title="attr-input-type-radio">Radio Button</dfn> state</h6>
 
   <p>When an <code>input</code> element's <code
@@ -27891,17 +27983,12 @@
   <p>A document must not contain an <code>input</code> element whose
   <i>radio button group</i> contains only that element.</p>
 
-  <p>If the element is <i title="concept-input-mutable">mutable</i>,
-  the user should allow the user to set the <span
-  title="concept-fe-checked">checkedness</span> state of the
-  element to true.</p>
-
   <p>When any of the following events occur, if the element's <span
   title="concept-fe-checked">checkedness</span> state is true after
   the event, the <span
   title="concept-fe-checked">checkedness</span> state of all the
   other elements in the same <i>radio button group</i> must be set to
-  false:</p> <!-- XXX event firing order and timing -->
+  false:</p>
 
   <ul>
 
@@ -27917,6 +28004,15 @@
 
   </ul>
 
+  <p>If the element is <i title="concept-input-mutable">mutable</i>,
+  then: The <span>pre-click activation steps</span> consist of setting
+  the element's <span title="concept-fe-checked">checkedness</span> to
+  true. The <span>canceled activation steps</span> consist of setting
+  the element's <span title="concept-fe-checked">checkedness</span> to
+  false. The <span>activation behavior</span> is to <span>fire a
+  simple event</span> called <code title="event-change">change</code>
+  at the element.</p>
+
   <p><strong>Constraint validation:</strong> If the element is <i
   title="concept-input-required">required</i> and all of the
   <code>input</code> elements in the <i>radio button group</i> have a
@@ -27924,8 +28020,6 @@
   false, then the element is <span>suffering from being
   missing</span>.</p>
 
-  <!-- XXX event timing; activation behavior -->
-
   <p>The following common <code>input</code> element content
   attributes and DOM attributes apply to the element:
   <code title="attr-input-checked">checked</code> and
@@ -27936,6 +28030,8 @@
   <p>The <code title="dom-input-value">value</code> DOM attribute is
   in mode <span title="dom-input-value-default-on">default/on</span>.</p>
 
+  <p>The <code title="event-input-change">change</code> event applies.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-input-accept">accept</code>,
@@ -27963,9 +28059,12 @@
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> and
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code> methods.</p>
 
+  <p>The <code title="event-input-input">input</code> event does not
+  apply.</p>
 
 
 
+
   <h6><dfn title="attr-input-type-file">File Upload</dfn> state</h6>
 
   <p>When an <code>input</code> element's <code
@@ -28039,6 +28138,8 @@
   <code title="attr-input-accept">accept</code> and
   <code title="attr-input-required">required</code>.</p>
 
+  <p>The <code title="event-input-change">change</code> event applies.</p>
+
   <p>The following content attributes must not be specified and do not
   apply to the element:
   <code class="no-backref" title="attr-fs-action">action</code>,
@@ -28071,9 +28172,12 @@
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> and
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code> methods.</p>
 
+  <p>The <code title="event-input-input">input</code> event does not
+  apply.</p>
 
 
 
+
   <h6><dfn title="attr-input-type-submit">Submit Button</dfn> state</h6>
 
   <p>When an <code>input</code> element's <code
@@ -28090,12 +28194,11 @@
   <p>If the element is <i title="concept-input-mutable">mutable</i>,
   the user should allow the user to activate the element.</p>
 
-  <!-- XXX event timing; activation behavior -->
-
-  <p>When the element is activated, if the element has a <span>form
-  owner</span>, the element must <span
+  <p>The element's <span>activation behavior</span>, if the element
+  has a <span>form owner</span>, is to <span
   title="concept-form-submit">submit</span> the <span>form
-  owner</span> from the <code>input</code> element.</p>
+  owner</span> from the <code>input</code> element; otherwise, it is
+  to do nothing.</p>
 
   <p>The <code title="attr-fs-action">action</code>, <code
   title="attr-fs-enctype">enctype</code>, <code
@@ -28140,8 +28243,12 @@
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> and
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code> methods.</p>
 
+  <p>The <code class="no-backref"
+  title="event-input-input">input</code> and <code class="no-backref"
+  title="event-input-change">change</code> events do not fire.</p>
 
 
+
   <h6><dfn title="attr-input-type-image">Image Button</dfn> state</h6>
 
   <p>When an <code>input</code> element's <code
@@ -28253,24 +28360,28 @@
   attribute; if the element is <i
   title="concept-input-mutable">mutable</i>, the user should allow the
   user to select this <span
-  title="concept-input-type-image-coordinate">coordinate</span>, at
-  which point the element's <span>form owner</span>, if any, must be
-  <span title="concept-form-submit">submitted</span> from the
-  <code>input</code> element.</p>
+  title="concept-input-type-image-coordinate">coordinate</span>. The
+  <span>activation behavior</span> in this case consists of taking the
+  user's selected <span
+  title="concept-input-type-image-coordinate">coordinate</span>, and
+  then, if the element has a <span>form owner</span>, <span
+  title="concept-form-submit">submitting</span> the <code>input</code>
+  element's <span>form owner</span> from the <code>input</code>
+  element.</p>
 
   <p>Otherwise, the element represents a submit button whose label is
   given by the value of the <code title="attr-input-alt">alt</code>
   attribute; if the element is <i
   title="concept-input-mutable">mutable</i>, the user should allow the
-  user to activate the button, at which point the the <span
+  user to activate the button. The <span>activation behavior</span> in
+  this case consists of setting the <span
   title="concept-input-type-image-coordinate">selected
-  coordinate</span> must be set to (0,0) and the element's <span>form
-  owner</span>, if any, must be <span
-  title="concept-form-submit">submitted</span> from the
-  <code>input</code> element.</p>
+  coordinate</span> to (0,0), and then, if the element has a
+  <span>form owner</span>, <span
+  title="concept-form-submit">submitting</span> the <code>input</code>
+  element's <span>form owner</span> from the <code>input</code>
+  element.</p>
 
-  <!-- XXX event timing; activation behavior -->
-
   <p>The <dfn
   title="concept-input-type-image-coordinate">selected
   coordinate</dfn> must consist of an <var title="">x</var>-component
@@ -28329,6 +28440,10 @@
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> and
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code> methods.</p>
 
+  <p>The <code class="no-backref"
+  title="event-input-input">input</code> and <code class="no-backref"
+  title="event-input-change">change</code> events do not fire.</p>
+
   <p class="note">Many aspects of this state's behavior are similar to
   the behavior of the <code>img</code> element. Readers are encouraged
   to read that section, where many of the same requirements are
@@ -28352,13 +28467,11 @@
   <p>If the element is <i title="concept-input-mutable">mutable</i>,
   the user should allow the user to activate the element.</p>
 
-  <!-- XXX event timing; activation behavior -->
+  <p>The element's <span>activation behavior</span>, if the element
+  has a <span>form owner</span>, is to <span
+  title="concept-form-reset">reset</span> the <span>form owner</span>;
+  otherwise, it is to do nothing.</p>
 
-  <p>When the element is activated, if the element has a <span>form
-  owner</span>, the element must <span
-  title="concept-form-reset">reset</span> the <span>form
-  owner</span>.</p>
-
   <p><strong>Constraint validation:</strong> The element is
   <span>barred from constraint validation</span>.</p>
 
@@ -28396,8 +28509,12 @@
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> and
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code> methods.</p>
 
+  <p>The <code class="no-backref"
+  title="event-input-input">input</code> and <code class="no-backref"
+  title="event-input-change">change</code> events do not fire.</p>
 
 
+
   <h6><dfn title="attr-input-type-button">Button</dfn> state</h6>
 
   <p>When an <code>input</code> element's <code
@@ -28412,10 +28529,9 @@
   string.</p>
 
   <p>If the element is <i title="concept-input-mutable">mutable</i>,
-  the user should allow the user to activate the element.</p>
+  the user should allow the user to activate the element. The
+  element's <span>activation behavior</span> is to do nothing.</p>
 
-  <!-- XXX event timing; activation behavior -->
-
   <p><strong>Constraint validation:</strong> The element is
   <span>barred from constraint validation</span>.</p>
 
@@ -28453,8 +28569,12 @@
   <code class="no-backref" title="dom-input-stepDown">stepDown()</code> and
   <code class="no-backref" title="dom-input-stepUp">stepUp()</code> methods.</p>
 
+  <p>The <code class="no-backref"
+  title="event-input-input">input</code> and <code class="no-backref"
+  title="event-input-change">change</code> events do not fire.</p>
 
 
+
   <h6>Common algorithms</h6>
 
   <p>When a user agent is to <dfn>strip line breaks from the
@@ -29025,8 +29145,57 @@
   <p class="XXX">... <dfn title="dom-input-selectedOption"><code>selectedOption</code></dfn></p>
 
 
+  <h5>Common event behaviors</h5>
 
+  <p>When the <dfn title="event-input-input"><code>input</code></dfn>
+  event applies, the user agent must <span>queue a task</span> to
+  <span>fire a simple event</span> called <code
+  title="event-input">input</code> at the <code>input</code> element
+  any time the user causes the element's <span
+  title="concept-fe-value">value</span> to change. User agents may
+  wait for a suitable break in the user's interaction before queuing
+  the task; for example, a user agent could wait for the user to have
+  not hit a key for 100ms, so as to only fire the event when the user
+  pauses, instead of continuously for each keystroke.</p>
 
+  <p>When the <dfn
+  title="event-input-change"><code>change</code></dfn> event applies,
+  if the element does not have an <span>activation behavior</span>
+  defined but uses a user interface that involves an explicit commit
+  action, then the user agent must <span>queue a task</span> to
+  <span>fire a simple event</span> called <code
+  title="event-change">change</code> at the <code>input</code> element
+  any time the <em>user</em> commits a change to the element's <span
+  title="concept-fe-value">value</span> or list of <span
+  title="concept-input-type-file-selected">selected files</span>.</p>
+
+  <p class="example">An example of a user interface with a commit
+  action would be a <span title="attr-input-type-file">File
+  Upload</span> control that consists of a single button that brings
+  up a file selection dialog: when the dialog is closed, if that the
+  <span title="concept-input-type-file-selected">file selection</span>
+  changed as a result, then the user has commited a new <span
+  title="concept-input-type-file-selected">file selection</span>.</p>
+
+  <p class="example">Another example of a user interface with a commit
+  action would be a <span title="attr-input-type-date">Date</span>
+  control that allows both text-based user input and user selection
+  from a drop-down calendar: while text input might not have an
+  explicit commit step, selecting a date from the drop down calendar
+  and then dismissing the drop down would be a commit action.</p>
+
+  <p>In addition, when the <code
+  title="event-input-change">change</code> event applies, <code
+  title="event-change">change</code> events can also be fired as part
+  of the element's <span>action behavior</span> and as part of the
+  <span>unfocusing steps</span>.</p>
+
+  <p>The <span>task source</span> for these <span
+  title="concept-tasks">task</span> is the <span>user interaction task
+  source</span>.</p>
+
+
+
   <h4>The <dfn><code>button</code></dfn> element</h4>
 
   <dl class="element">
@@ -43600,7 +43769,15 @@
 
   <ol>
 
-   <!-- XXX onchange event for input controls -->
+   <li><p>If the element is an <code>input</code> element, and the
+   <code title="event-input-change">change</code> event applies to the
+   element, and the element does not have a defined <span>activation
+   behavior</span>, and the user has changed the element's <span
+   title="concept-fe-value">value</span> or its list of <span
+   title="concept-input-type-file-selected">selected files</span>
+   while the control was focused without committing that change, then
+   <span>fire a simple event</span> called <code
+   title="event-change">change</code> at the element.</p>
 
    <li><p>Unfocus the element.</p></li>
 

|