16339 2012-03-12 21:50:20 +0000 Some comments on Basic Event Interfaces 2012-04-07 00:29:42 +0000 1 1 1 Unclassified WebAppsWG HISTORICAL - DOM3 Events unspecified PC Windows NT RESOLVED FIXED http://lists.w3.org/Archives/Public/www-dom/2011JulSep/0131.html LC, needsReview P2 normal --- 1 travil travil annevk mike Ms2ger www-dom public-webapps-bugzilla oldest_to_newest 65413 0 travil 2012-03-12 21:50:20 +0000 This is a PORT of TRACKER, ISSUE-186 (DOM3Events Outstanding Issues) https://www.w3.org/2008/webapps/track/issues/186 [see http://lists.w3.org/Archives/Public/www-dom/2011JulSep/0131.html] Hi Doug, Jacob Reading through the D3E section on Basic Event Interfaces, I found a number of things that could benefit from clarification. 4.1 Interface Event =================== > An object which implements the Event interface must be passed as the > parameter to an EventListener. Interfaces don't have parameters, and this seems like a strange place to put this requirement. eventPhase: > Used to indicate which phase of event flow is currently being > accomplished. There must be a better word than "accomplished" that could be used here. type: > The name must be a DOMString. Redundant with the IDL. initEvent: > This method sets the Event.type attribute to eventTypeArg. Either this is redundant with the "Parameters" section below, or the respective requirements for bubbles and cancelable are missing. 4.2 Interface CustomEvent ========================= initCustomEvent: > detailArg of type any > Specifies CustomEvent.detail. This value may be null. This last sentence is redundant with the type of the argument. 4.3 Interface EventTarget ========================= > The EventTarget interface must be implemented by all the objects > which could be event targets in an implementation which supports an > event flow. This is unimplementable without a normative description of "all the objects which could be event targets in an implementation which supports an event flow". I suggest leaving this up to the specifications that define event targets, as happens in practice. addEventListener: > If listener is a function that also has a handleEvent method, the > function itself must be used as the callback and not its handleEvent > method. This is redundant with the previous sentence, so should be a note and should not use "must". > Note: If the listener is a function, then it may be a reference to a > function object or an inline function object literal. I'm not sure what this is supposed to mean. About useCapture: > This parameter may be optional, on an implementation-specific basis. This should be a "must" unless there is a very good reason against that. > Note: For programming languages which do not allow optional method > parameters, such as Java, the implementation may provide two > EventTarget.addEventListener methods, one with 2 parameters, and one > with 3 parameters. Is this a note or is it normative? You can't have both. removeEventListener: Same comments, and > If a listener was registered twice, once for the capture and target > phases and once for the target and bubbling phases, each must be > removed separately. It's not clear if this is a UA requirement. 4.4 Interface EventListener =========================== EventListener ------------- > The EventListener interface is the primary way to handle events. > Content authors must define on object, such as a function, which the > EventListener interface and register their event listener on an > EventTarget. I don't believe this is correct English. > The content authors should also remove their EventListener from its > EventTarget after they have completed using the listener. I wonder why this is a "should". > Copying a Node, with methods such as Node.cloneNode or > Range.cloneContents, must not copy the event listeners attached to > it. Event listeners must be attached to the newly created Node > afterwards, if so desired. And why this is a "must". > Moving a Node, with methods Document.adoptNode, Node.appendChild, or > Range.extractContents, must not affect the event listeners attached > to it. You seem to have missed "such as" here. It also seems like a reference to a DOM Range specification is missing. EventException -------------- First, I think there is no need for a separate exception interface for two single-use exception codes. Second, > Event operations may throw an EventException as specified in their > method descriptions. uses "may" inappropriately. Third, the "code" attribute is not actually defined in the prose. Fourth, it makes little sense to put this in §4.4 "Interface EventListener". I would suggest a separate section. 4.5 Interface DocumentEvent =========================== The description of createEvent's eventInterface argument has: > If the Event is to be dispatched via the EventTarget.dispatchEvent() > method, the appropriate event initialization method must be called > after creation in order to initialize the Event's values. This suggests that the user agent must call initEvent, which I assume isn't the goal here. > For backward compatibility reason, … "reasons" > If the parameter does not match an event interface name supported by > the implementation, the implementation must raise a NOT_SUPPORTED_ERR > DOMException Missing period at the end of the sentence, and redundant with the "Exceptions" section below. 4.5.1 Event creation ==================== > The Event objects created must be known by the DOM Events > implementation; otherwise an event exception must be thrown. I'm not sure what this means. In any case, it should be specified which exception is meant. HTH Ms2ger 66496 1 travil 2012-04-07 00:29:42 +0000 (In reply to comment #0) > This is a PORT of TRACKER, ISSUE-186 (DOM3Events Outstanding Issues) > https://www.w3.org/2008/webapps/track/issues/186 > [see http://lists.w3.org/Archives/Public/www-dom/2011JulSep/0131.html] > > Hi Doug, Jacob > > Reading through the D3E section on Basic Event Interfaces, I found a > number of things that could benefit from clarification. > > 4.1 Interface Event > =================== > > > An object which implements the Event interface must be passed as the > > parameter to an EventListener. > > Interfaces don't have parameters, and this seems like a strange place to > put this requirement. Re-worded this in the spirit for which the original sentence was intended. It should now be more readable and more technically correct. > eventPhase: > > > Used to indicate which phase of event flow is currently being > > accomplished. > > There must be a better word than "accomplished" that could be used here. Ha ha! Yeah, re-worked that sentence and linked to the propagation path info. > type: > > > The name must be a DOMString. > > Redundant with the IDL. Looks like this was fixed in some prior draft. At least I couldn't find that text. > initEvent: > > > This method sets the Event.type attribute to eventTypeArg. > > Either this is redundant with the "Parameters" section below, or the > respective requirements for bubbles and cancelable are missing. Dropped the sentence. It was redundant. > 4.2 Interface CustomEvent > ========================= > > initCustomEvent: > > > detailArg of type any > > Specifies CustomEvent.detail. This value may be null. > > This last sentence is redundant with the type of the argument. Dropped it. > 4.3 Interface EventTarget > ========================= > > > The EventTarget interface must be implemented by all the objects > > which could be event targets in an implementation which supports an > > event flow. > > This is unimplementable without a normative description of "all the > objects which could be event targets in an implementation which supports > an event flow". I suggest leaving this up to the specifications that > define event targets, as happens in practice. Agree. Dropped this sentence, leaving the explanitory sentence that follows. > addEventListener: > > > If listener is a function that also has a handleEvent method, the > > function itself must be used as the callback and not its handleEvent > > method. > > This is redundant with the previous sentence, so should be a note and > should not use "must". Dropped the redundant sentence. > > Note: If the listener is a function, then it may be a reference to a > > function object or an inline function object literal. > > I'm not sure what this is supposed to mean. I removed this. I think it was supposed to be describing lambda (or anonymous) functions versus function pointers. It's irrelevant to the spec. > About useCapture: > > > This parameter may be optional, on an implementation-specific basis. > > This should be a "must" unless there is a very good reason against that. Updated. > > Note: For programming languages which do not allow optional method > > parameters, such as Java, the implementation may provide two > > EventTarget.addEventListener methods, one with 2 parameters, and one > > with 3 parameters. > > Is this a note or is it normative? You can't have both. This was fixed in a prior revision of the document, apparently. > removeEventListener: > > Same comments, and > > > If a listener was registered twice, once for the capture and target > > phases and once for the target and bubbling phases, each must be > > removed separately. > > It's not clear if this is a UA requirement. I added the UA requirement text. > 4.4 Interface EventListener > =========================== > > EventListener > ------------- > > > The EventListener interface is the primary way to handle events. > > Content authors must define on object, such as a function, which the > > EventListener interface and register their event listener on an > > EventTarget. > > I don't believe this is correct English. I fixed this in a previous update. > > The content authors should also remove their EventListener from its > > EventTarget after they have completed using the listener. > > I wonder why this is a "should". Also fixed in a previous update. Yes, the wording was a hurdle... > > Copying a Node, with methods such as Node.cloneNode or > > Range.cloneContents, must not copy the event listeners attached to > > it. Event listeners must be attached to the newly created Node > > afterwards, if so desired. > > And why this is a "must". Now a "can" statement. > > Moving a Node, with methods Document.adoptNode, Node.appendChild, or > > Range.extractContents, must not affect the event listeners attached > > to it. > > You seem to have missed "such as" here. Got it now. > It also seems like a reference to a DOM Range specification is missing. Added it. DOM L2 Range is OK for the purposes of these APIs. > > EventException > -------------- > > First, I think there is no need for a separate exception interface for > two single-use exception codes. > > Second, > > > Event operations may throw an EventException as specified in their > > method descriptions. > > uses "may" inappropriately. > > Third, the "code" attribute is not actually defined in the prose. > > Fourth, it makes little sense to put this in §4.4 "Interface > EventListener". I would suggest a separate section. I've previously deleted this entire section. In the conversion to WebIDL :) > 4.5 Interface DocumentEvent > =========================== > > The description of createEvent's eventInterface argument has: > > > If the Event is to be dispatched via the EventTarget.dispatchEvent() > > method, the appropriate event initialization method must be called > > after creation in order to initialize the Event's values. > > This suggests that the user agent must call initEvent, which I assume > isn't the goal here. Re-phrased this into a Note. > > For backward compatibility reason, … > > "reasons" This was previously fixed :-) > > If the parameter does not match an event interface name supported by > > the implementation, the implementation must raise a NOT_SUPPORTED_ERR > > DOMException > > Missing period at the end of the sentence, and redundant with the > "Exceptions" section below. This was re-written with the change to WebIDL exceptions previously. > 4.5.1 Event creation > ==================== > > > The Event objects created must be known by the DOM Events > > implementation; otherwise an event exception must be thrown. > > I'm not sure what this means. In any case, it should be specified which > exception is meant. This was redundant with the prior sentence under "Exceptions". So I removed it. (The exception was NotSupportedError.) > > HTH > Ms2ger Yep. Thanks!