re: [DOM3 Events] Some comments on Basic Event Interfaces

Ms2ger,

Thanks for all your suggestions on DOM3Events.  There's some good grammatical fix ups that you suggest. These shouldn't affect implementers, but Doug and I can integrate these suggestions to improve the readability.

As for the functional comments:

> 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.

I disagree. It's a statement that says if you have an interface that could have an event dispatched to it, then it must implement EventTarget. DOM Events is meant to be an event model which can be applied to lots of different objects and data structures.


>> 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.

It just is a note towards authors that you can use inline functions as well:
addEventListener("foo",function(evt) { //inline function}, false)


>> This parameter may be optional, on an implementation-specific basis.

>

> This should be a "must" unless there is a very good reason against that.

>



The reason is that some languages do not support optional arguments.



>> 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 is a note that suggests a workaround for implementations in languages that don't support optional arguments. It's not normative. An implementation may do this, or it may not-up to the implementer (since optional useCapture isn't required).


>> 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.



This is intended for authors:



target.addEventListener("foo",bar,false);

target.addEventListener("foo",bar,true);

target.removeEventListener("foo",bar,false);



This only removes the first of the two listeners.



>> 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".



It's a coding "best practices" suggestion towards authors.





> EventException

> --------------

>

> First, I think there is no need for a separate exception interface for

> two single-use exception codes.



We discussed this in Issue 179 and resolved that it is useful to have a separate exception to provide better context about the exception.



> 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.



document.createEvent("Foo") should throw if the implementation doesn't support the Foo event interface.  The spec does define which exception:



"If the parameter does not match an event interface name supported by the implementation, the implementation must raise a NOT_SUPPORTED_ERRDOMException"




Regards,

Jacob