- From: <bugzilla@jessica.w3.org>
- Date: Mon, 12 Mar 2012 21:50:22 +0000
- To: www-dom@w3.org
https://www.w3.org/Bugs/Public/show_bug.cgi?id=16339 Summary: Some comments on Basic Event Interfaces Product: WebAppsWG Version: unspecified Platform: PC URL: http://lists.w3.org/Archives/Public/www-dom/2011JulSep /0131.html OS/Version: Windows NT Status: NEW Keywords: LC Severity: normal Priority: P2 Component: DOM3 Events AssignedTo: travil@microsoft.com ReportedBy: travil@microsoft.com QAContact: public-webapps-bugzilla@w3.org CC: mike@w3.org, annevk@opera.com, Ms2ger@gmail.com, www-dom@w3.org 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 -- Configure bugmail: https://www.w3.org/Bugs/Public/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug.
Received on Monday, 12 March 2012 21:50:24 UTC