Bug 16285 - Default actions section is quite confusing; review and polish
Default actions section is quite confusing; review and polish
Status: RESOLVED FIXED
Product: WebAppsWG
Classification: Unclassified
Component: DOM3 Events
unspecified
PC Windows NT
: P2 minor
: ---
Assigned To: Travis Leithead [MSFT]
public-webapps-bugzilla
http://lists.w3.org/Archives/Public/w...
: LC, needsReview
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2012-03-09 17:23 UTC by Travis Leithead [MSFT]
Modified: 2012-03-21 00:03 UTC (History)
4 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Travis Leithead [MSFT] 2012-03-09 17:23:51 UTC
From: Anne van Kesteren [mailto:annevk@opera.com]

>> It [DOM3 Events] also describes basic concepts such as default actions and their
>> effect on cancelable events, trusted events, etc., for which having a
>> central reference is quite informative.

Except the way it talks about default actions has been quite confusing,
making people think it was somehow more tied to the event than it actually
was.

-------------------------

Review that section; see if any confusing portions can be cleaned up.
Comment 1 Travis Leithead [MSFT] 2012-03-17 00:18:10 UTC
I made a sweep through this section and did indeed end-up re-writing it extensively. I believe what I've written qualifies as reducing the confusion and divorcing the concept of the default action from the event objects as much as is fair to do so. 

Anne, give it a read and let me know how it can be futher polished, or if you are satisfied with it.

http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html?rev=1.216#event-flow-default-cancel
Comment 2 Anne 2012-03-18 16:03:16 UTC
It still talks about as if they are somehow associated with the event object. While the code for implementing this goes like:

function run() {
  if(obj.dispatchEvent(ev)) {
    defaultAction()
  }
}

I.e. defaultAction is associated with run, not ev.
Comment 3 Olli Pettay 2012-03-18 16:15:29 UTC
(In reply to comment #2)
> It still talks about as if they are somehow associated with the event object.
> While the code for implementing this goes like:
> 
> function run() {
>   if(obj.dispatchEvent(ev)) {
>     defaultAction()
>   }
> }
That is not what implementations do.
Comment 4 Anne 2012-03-18 16:29:43 UTC
That is the logic if you look at it from JavaScript.
Comment 5 Travis Leithead [MSFT] 2012-03-20 00:30:39 UTC
(In reply to comment #2)
> It still talks about as if they are somehow associated with the event object.
> While the code for implementing this goes like:
> 
> function run() {
>   if(obj.dispatchEvent(ev)) {
>     defaultAction()
>   }
> }
> 
> I.e. defaultAction is associated with run, not ev.

Hmm. So, "defaultAction()" is something I can easily describe. Similarly, "dispatchEvent(ev)" is something else I can describe. Both of these are related since the result of one (ev) is fed into the course of action for defaultAction().

"run" is not so easy to describe :-)

While I agree with you from a browser-maker, technical point of view, as an introduction to the concept of default actions (which the section is supposed to be), I think it's OK to have the two related to some degree.

Since you re-opened the bug, would you mind providing some replacement text for parts of that section that could be improved? My goal is not require defining "run", unless you can manage it succinctly.
Comment 6 Anne 2012-03-20 01:42:34 UTC
http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#introduction-to-dom-events has introductory text on the matter. Ideally we align the text between Level 3 and 4. I basically started from scratch to get a fresh perspective on things.
Comment 7 Travis Leithead [MSFT] 2012-03-21 00:03:54 UTC
(In reply to comment #6)
> http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#introduction-to-dom-events
> has introductory text on the matter. Ideally we align the text between Level 3
> and 4. I basically started from scratch to get a fresh perspective on things.

After reading your "fresh perspective", I took another stab at this:
http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#event-flow-default-cancel

Should harmonize slightly better with DOM4 prose.