Clarification of Description:

Section 4.10.7.5 (Common event behaviors) states:
>When the input event applies, any time the user causes the element's value to >change, the user agent must queue a task to fire a simple event that bubbles >named input at the input element....
>
>When the change event applies, if the element does not have an activation >behavior defined but uses a user interface that involves an explicit commit >action, then any time the user commits a change to the element's value or list >of selected files, the user agent must queue a task to fire a simple event that >bubbles named change at the input element....

It is not clearly emphasized (and it took me some time to find this, including an incorrect answer on StackOverflow) that if the value is changed by a script, then these events are _not_ generated, although this is indeed the case. Perhaps an extra line to this effect should be inserted.

In addition, I think the terms "apply" and the inverse "does not apply" are not defined clearly enough; the terms (where used) are links to uses of the terms, not concise definitions. Also, the spec is silent as to what happens when an event (or attribute) that "does not apply" is generated (or set/read).

The second suggestion is to add links to the Event handlers/types table in section 7.1.6.2 (Event handlers on elements, Document objects, and Window objects) to the input and change event descriptions in section 4.10.7.5 (and to other event types missing links to their definitions).

While I'm on the subject, would "event type" be any less specific or concise than the current mouthful "event handler event type"?

Thanks for your consideration.

> It is not clearly emphasized (and it took me some time to find this,
> including an incorrect answer on StackOverflow) that if the value is changed
> by a script, then these events are _not_ generated, although this is indeed
> the case. Perhaps an extra line to this effect should be inserted.

Done.


> In addition, I think the terms "apply" and the inverse "does not apply" are
> not defined clearly enough; the terms (where used) are links to uses of the
> terms, not concise definitions.

How should they be defined? I mean, their meaning _is_ their use, as far as I can tell. They link to a definition that says "The subsections that define each type also clearly define in normative "bookkeeping" sections which of these feature apply, and which do not apply, to each type"; I don't really know what else could be said. Can you elaborate on what you had in mind here?


> Also, the spec is silent as to what happens
> when an event (or attribute) that "does not apply" is generated (or
> set/read).

If an event doesn't apply, it's not generated. That's all. When a content attribute that doesn't apply is set/read, nothing happens beyond what the DOM specs says (i.e. it's set/read, that's all).

What more should be said?


> The second suggestion is to add links to the Event handlers/types table in
> section 7.1.6.2 (Event handlers on elements, Document objects, and Window
> objects) to the input and change event descriptions in section 4.10.7.5 (and
> to other event types missing links to their definitions).

Event names are just that, names, so they often don't actually have definitions. They're just mostly-opaque identifiers. The definition in 4.10.7.5 (now 4.10.5.5; the section named "Common event behaviors") is just for the 'input' and 'change' names when used on <input>, other elements, e.g. <textarea>, use the name as well, but the definition there doesn't apply. That's why the table in the "Event handlers..." section doesn't link to this section — it would be misleading.

I don't know where else to link to. I suppose I could have a section somewhere that non-normatively describes some of the event names, though if it's non-normative it's not really a definition either. Anyway, see bug 23530 for this.


> While I'm on the subject, would "event type" be any less specific or concise
> than the current mouthful "event handler event type"?

"Event type" would be the type of an event. "Event handler event type" is specifically the type of events that that event handler handles.


Leaving open for two the apply/do-not-apply questions above.

Checked in as WHATWG revision r8286.
Check-in comment: Mention that scripted changes don't fire 'input' and 'change' on <input>.
http://html5.org/tools/web-apps-tracker?from=8285&to=8286

>> It is not clearly emphasized (and it took me some time to find this,
>> including an incorrect answer on StackOverflow) that if the value is changed
>> by a script, then these events are _not_ generated, although this is indeed
>> the case. Perhaps an extra line to this effect should be inserted.
> 
> Done.

Thanks.

>> In addition, I think the terms "apply" and the inverse "does not apply" are
>> not defined clearly enough; the terms (where used) are links to uses of the
>> terms, not concise definitions.
> 
> How should they be defined? I mean, their meaning _is_ their use, as far as
> I can tell. They link to a definition that says "The subsections that define
> each type also clearly define in normative "bookkeeping" sections which of
> these feature apply, and which do not apply, to each type"; I don't really
> know what else could be said. Can you elaborate on what you had in mind here?

I found what I had in mind in Section 4.10.5.3 - Common input element (WHATWG; in W3, its Section 4.10.7.3):
"These attributes only apply to an input element if its type attribute is in a state whose definition declares that the attribute applies. When an attribute doesn't apply to an input element, user agents must ignore the attribute, regardless of the requirements and definitions below."

That's a clear description of what "do not apply" means and its requirements, namely, the browser is to (and will) ignore it.  Perhaps the <dfn>'s for "apply" and "does not apply" should be here.

>> Also, the spec is silent as to what happens when an event (or attribute)
>> that "does not apply" is generated (or set/read).
> 
> If an event doesn't apply, it's not generated. That's all. When a content
> attribute that doesn't apply is set/read, nothing happens beyond what the
> DOM specs says (i.e. it's set/read, that's all).
> 
> What more should be said?

What if it's generated by a script?  For example, if a script calls dispatchEvent(InputEvent) on a checkbox, does that call the element's oninput handler (it would call an "input" event listener)?  I don't think a script generating a "giggle" event will cause the browser to call element's ongiggle handler, only its "giggle" eventListeners; so how are events that do not apply treated?

>> The second suggestion is to add links to the Event handlers/types table in
>> section 7.1.6.2 (Event handlers on elements, Document objects, and Window
>> objects) to the input and change event descriptions in section 4.10.7.5 (and
>> to other event types missing links to their definitions).
> 
> Event names are just that, names, so they often don't actually have
> definitions. They're just mostly-opaque identifiers. The definition in
> 4.10.7.5 (now 4.10.5.5; the section named "Common event behaviors") is just
> for the 'input' and 'change' names when used on <input>, other elements,
> e.g. <textarea>, use the name as well, but the definition there doesn't
> apply. That's why the table in the "Event handlers..." section doesn't link
> to this section — it would be misleading.
> 
> I don't know where else to link to. I suppose I could have a section
> somewhere that non-normatively describes some of the event names, though if
> it's non-normative it's not really a definition either. Anyway, see bug
> 23530 for this.

The section described in Bug 23530 comment 2 would be perfect.  Consider this a "please do" request.

>> While I'm on the subject, would "event type" be any less specific or concise
>> than the current mouthful "event handler event type"?
> 
> "Event type" would be the type of an event. "Event handler event type" is
> specifically the type of events that that event handler handles.

Yeah, I figured as much.  Still a mouthful, though.  What I meant was, read the paragraph, and substitute "event type" for "event handler event type": I don't see the shorter version to be any less concise, though it seems you disagree with me.

Thanks for your consideration.

> I found what I had in mind in Section 4.10.5.3 - Common input element
> (WHATWG; in W3, its Section 4.10.7.3):
> "These attributes only apply to an input element if its type attribute is in
> a state whose definition declares that the attribute applies. When an
> attribute doesn't apply to an input element, user agents must ignore the
> attribute, regardless of the requirements and definitions below."

That's the requirement for content attributes that "do not apply", but there's also IDL attributes, events, and methods. If we linked here, it would leave those others even less well defined.

The definition for "do not apply" does say "The behavior of these features depends on whether they apply or not, as defined in their various sections", which is referencing the text you quote above. I've added a cross-reference there to try to make that clearer.


> What if it's generated by a script?  For example, if a script calls
> dispatchEvent(InputEvent) on a checkbox, does that call the element's
> oninput handler (it would call an "input" event listener)?

Sure, that's defined by other parts of the spec and unaffected by "apply" vs "do not apply".


> I don't think a
> script generating a "giggle" event will cause the browser to call element's
> ongiggle handler, only its "giggle" eventListeners; so how are events that
> do not apply treated?

http://whatwg.org/html#common-input-element-events doesn't mention anything about affecting how event handlers work, or whether manual dispatch is affected, only whether the events are fired by the user agent itself.

Event handlers are defined here, with no reference to "apply" vs "do not apply":

   http://whatwg.org/html#events


> What I meant was, read
> the paragraph, and substitute "event type" for "event handler event type": I
> don't see the shorter version to be any less concise, though it seems you
> disagree with me.

Which paragraph do you mean, exactly?

Checked in as WHATWG revision r8309.
Check-in comment: try to add a cross-reference at the dfn of 'do not apply' to link people to where those terms are used
http://html5.org/tools/web-apps-tracker?from=8308&to=8309

(In reply to Ian 'Hixie' Hickson from comment #5)
>> What I meant was, read
>> the paragraph, and substitute "event type" for "event handler event type": I
>> don't see the shorter version to be any less concise, though it seems you
>> disagree with me.
> 
> Which paragraph do you mean, exactly?

I meant http://whatwg.org/html#event-handler-event-type, and other uses of the the term on that page, but it's not that important.  Thanks for the other fixes.  I hope I'm not the only one to find them an improvement.

Ah, I see. Yeah, the term "event handler event type" is used to contrast it with the "event event type", that is, the event type of an Event.

BTW, I added an index that defines all the events, which should help.

Index is beautiful.  Exactly what is needed.  Thanks.