- From: <bugzilla@jessica.w3.org>
- Date: Sat, 07 Apr 2012 00:29:45 +0000
- To: www-dom@w3.org
https://www.w3.org/Bugs/Public/show_bug.cgi?id=16339
Travis Leithead [MSFT] <travil@microsoft.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Keywords| |needsReview
Status|NEW |RESOLVED
Resolution| |FIXED
--- Comment #1 from Travis Leithead [MSFT] <travil@microsoft.com> 2012-04-07 00:29:42 UTC ---
(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!
--
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 Saturday, 7 April 2012 00:29:47 UTC