- From: Bjoern Hoehrmann <derhoermi@gmx.net>
- Date: Wed, 19 Apr 2006 14:43:38 +0200
- To: Cameron McCormack <cam@mcc.id.au>
- Cc: public-webapi@w3.org
* Cameron McCormack wrote:
>[...]
Thanks for your comments. I've made a number of changes in response to
them as detailed below. The latest version of the document is available:
http://dev.w3.org/cvsweb/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html
There are some things I didn't change yet but will try to do so later;
some other things are better discussed in a separate thread, I would
appreciate if you could submit these issues as separate comments. In
general it would be good if at least comments about typos, errors in
the document, and requests for clarifications are in separate mails.
Please let us know if you have further input on the document and
whether these changes are satisfactory. Thanks.
>* 1.1 Introduction
>
> The second goal of the DOM Events is to provide [...]
>
>s/the // (to be consistent with calling the document just "DOM Events"
>in the previous paragraph)
Done.
>* 1.2.1 Phases
>
> The event dispatching (also called event propagation) occurs in three
> phases and the following order:
>
>s/and/in/
"Event propagation occurs in three phases in the following order:"
> If the target node is removed during the dispatching, [...]
>
>s/dispatching/dispatch/
"while the event is being dispatched"
>* 1.2.2.1 Registration of event listeners
>
> If the event listener is being registered on a node while an event
> gets processed on this node, the event listener will not be triggered
> during the current phase but may be triggered during a later phase in
> the event flow, i.e. the bubbling phase.
>
>If the event being processed was during the capture phase, then the
>target phase is also a possible later phase.
>s/, i\.e\. the bubbling phase//
"If an event is currently being dispatched and the event listener is
being registered for the current phase on the current target for the
event type that is currently being dispatched, the listener will not
be triggered by the current event" is what this is trying to say, so
the "i.e." is correct even if confusingly phrased.
TODO: I think this should be replaced by prose in 1.2.2.3 that says
the listener will be triggered if and only if it has been registered
before processing of listeners on the current target began; see also
ISSUE-77.
>* 1.2.2.2 Event groups
>
> It is either explicitly in a group if a group has been specified at
> the registration or implicitly in the default group if no group has
> been specified.
>
>s/the registration/registration/
TODO: This text starts out poorly, claiming that "An event listener
is always part of a group" which is rather misleading. I'll look at
this once the group decided whether to keep event groups.
> Within a group, event listeners are ordered in their order of
> registration.
>
>s/in/by/ (or s/in/according to/)
Done, though I'm not very happy with it yet. I will look at this
again in a context of some other changes.
> While this specification does not specify a full ordering [...]
>
>/full ordering/total ordering for event triggering/
I have not made this change. Could you elaborate on why you think the
current text is not optimal and what you would like to see improved?
>* 1.2.2.3 Triggering an event listener
>
>Consistent punctuation should be used at the end of the list items.
Done.
>* 1.2.2.4 Removing an event listener
>
> [...] it will not be triggered by the current actions.
>
>s/by the current actions/in the current or any later phases of
>propagation/
I have raised ISSUE-77 to confirm that the current behavior is desired;
pending that I'll use more appropriate wording.
>* 1.2.2.6 Event propagation and event groups
>
> An event listener may prevent event listeners that are part of a same
> group from being triggered.
>
>s/a same/the same/
Done.
> [...] have been triggered on the current node, i.e. the event
> listeners [...]
>
>s/, i\.e\./:/ (to be consistent with the colon used in the previous list
>item)
"deferred: all event listeners from the same group on the current node
will be triggered, but event listeners from the same group attached on
other nodes will not be triggered (see Event.stopPropagation())."
>* 1.3 Default actions and cancelable events
>
> [...] e.g. by pressing on a submit button [...]
>
>s/pressing/clicking/
I think pressing is fine for a touch screen.
> Implementations could react to an event before dispatching it and do
> changes on the display and the DOM tree.
>
>s/do changes on/make changes to/
Done.
> In such case, if a DOM attribute is changed before the event is fired,
> cancelling the device event type will also reverse the change.
>
>s/case/a case/
n/a, see below.
>Just to clarify: if the UA would cause a modification to a non-attribute
>node in the DOM just before the event is dispatched, would these
>modifications not be rolled back (because the above text just talks
>about attributes)?
"DOM attribute" refers to DOM attributes (IDL), not attribute nodes.
This does not cover non-device event types and other side-effects, e.g.
some state could be exposed through methods rather than attributes, so
this is now "Preventing the default action of such an event will
reverse these changes."
> A good example is the attribute HTMLInputElement.checked: as described
> in [DOM Level 2 HTML], the value of this property may be changed
> before the dispatch of the event; the user clicks on the radio button,
> the radio button is being checked (or unchecked) on the display, the
> attribute HTMLInputElement.checked is changed as well, and then the
> device event type click is being dispatched.
>
>I guess that by "the attribute HTMLInputElement.checked" it means the
>IDL attribute on the HTMLInputElement interface. This might be confused
>with DOM attributes by readers, especially since in this case changing
>the value of the attribute on the HTMLInputElement object will cause a
>change to the DOM attribute. It is also referred to as a property in
>this paragraph though, so more consistent language would be good.
I have replaced "property" by "attribute". DOM attributes are referred
to as "properties" only in the ECMAScript bindings, as explained in the
DOM Level 3 Core glossary. I don't think "HTMLInputElement.checked"
could be mistaken for the XML attribute in <input checked="...">.
>* 1.4 Activation requests and behavior
>
> Implementations dispatch the DOMActivate event as default action of a
> click event. This click event is either part of the activation request
> (e.g., a user requests activiation using a mouse), or synthesized by
> the implementation to accomodate legacy applications.
>
>I don't understand why synthesised DOMActivate events are always to
>"accommodate legacy applications". Is this because they assume that
>activation always is because of a click event?
The subject of the sentence is the click event, while the text has many
known shortcomings, I don't think it invites for this confusion.
> Context information of such a click event is implementation dependent.
>
>Does this mean all of the attributes on the Event interface for the
>event object could have any value? Maybe this should only be the
>context information accessible from the UIEvent and MouseEvent
>interfaces.
See below.
> When implementations dispatch a synthesized click event, the
> expectation is that they do so as default action of another event
> type. For example, when a user activates a hyperlink using a
> keyboard, the click event would be dispatched as default action of
> respective keyboard event.
>
>s/as/as the/g
The keyboard event might have other default actions associated with it,
so "the" would be incorrect. There may be cases where the draft uses a
singular reference incorrectly, I'd rather fix those.
>s/respective/the relevant/
"the respective"?
> Implementations are, however, required to dispatch the synthesized
> click event as described above even if they do not dispatch such an
> event (e.g., when activation is requested by a voice command since
> this specification does not address event types for voice input).
>
>s/, however,// (it's not that it is required despite the previous text)
>s/command/command,/
Done.
>* 1.5.2 Complete list of event types
>
> [...] e.g., mouse, keyboard, touch screen, and voice [...]
>
>s/and/or/
Well, okay.
>In 1.5 it says "All events defined in this specification are in no
>namespace." and in 1.5.2 "All event types are in no namespace and this
>specification refers to them by their local name only." Is it the
>events or the event types that are in namespaces?
TODO: the draft makes inconsistent reference to "event", "event type",
"event object", and related terminology, some instances should be fixed.
>The first column of the table should have a capitalised header.
>
> The event objects associated with the event types described above may
> contain context information.
>
>Won't all event objects have context information? The text describing
>the Event interface later on says "The Event interface is used to
>provide contextual information about an event to the listener processing
>the event", which is why I thought that the attributes on Event are also
>considered to be "context".
TODO: the draft makes ambiguous use of the term "contextual information"
but I'm not yet sure how to address that.
>* 1.6 Event listener registration
>
> There are mainly two ways to associate an event listener to a node in
> the tree:
>
>s/mainly two/two main/
I think the text is good as is.
>* 1.6.3 Using VoiceXML Events
>
> [VoiceXML 2.0] does not address namespaces in event types but uses the
> notion of event categories. The event type
> "connection.disconnect.hangup" could be associated to the event
> categories {"http://www.example.org/2003/voicexml", "connection"} and
> {"http://www.example.org/2003/voicexml", "connection.disconnect"}.
>
>VoiceXML 2.0 doesn't seem to mention event categories explicitly, just
>some method of matching event types using prefixes. Also, since DOM3EV
>doesn't specify any actual association of event types to event
>categories, I'm not sure what the purpose of these sentences are.
>(Maybe they are aimed at spec authors, saying that one way to fix
>VoiceXML to make it fit into the DOM3EV model is for it to define these
>categories?)
I think so, yes. This might get addressed in the context of ACTION-125.
>* 1.7 Basic interfaces
>
>* * Interface Event
>
> An object which implements the Event interface is passed as the
> parameter to an EventListener.
>
>It's passed as the parameter to the handleEvent method on an
>EventListener. This sentence also doesn't say what happens for event
>listeners that weren't added via addEventListener(NS) (such as on*
>attributes).
I think this text is fine, could you elaborate on how you think this
should be changed? It should not refer to handleEvent since there might
not be such a method on some implementations of the interface (think
ECMAScript Function objects). I don't think this is the right place to
discuss on* attributes or similar features.
> More specific context information is passed to event listeners by
> deriving additional interfaces from Event which contain information
> directly relating to the type of event they represent. These derived
> interfaces are also implemented by the object passed to the event
> listener.
>
>It's not the deriving of the interfaces that passes more specific
>context information. (The deriving of the interfaces is done by the
>spec authors.) Maybe:
>
> More specific context information is passed to event listeners by
> having the event object implement additional interfaces derived from
> Event, providing access to information directly relating to the type
> of event those interfaces represent.
>
>.
"The object passed to the event listener may also implement derived
interfaces that provide access to information directly relating to the
type of event they represent."
> To create an instance of the Event interface, use the
> DocumentEvent.createEvent("Event") method call.
>
>s/instance of/object that implements/, since you can't create an
>instance of an interface, but you can create an instance of a class that
>implements the interface. This applies to this sentence for each of the
>other interfaces, too.
I disagree, this phraseology is very common and I don't think it is
misleading or particularily incorrect.
> The namespace URI associated with this event at creation time, or null
> if it is unspecified. For events initialized with a DOM Level 2
> Events method, such as Event.initEvent(), this is always null.
>
>namespaceURI won't always be null if the event is initialised with
>initEvent and then later with initEventNS with a non-null namespace URI.
>Also, there will never be a namespace URI at creation time, only after
>one of the init*EventNS methods is called. Perhaps:
>
> The namespace URI associated with the event at the time of
> initialization. For events initialized with a DOM Level 2 Events
> method, such as Event.initEvent(), the namespaceURI will be null.
>
>.
"The namespace URI associated with this event at initialization time,
or null if it is unspecified. DOM Level 2 Events initialization methods,
such as Event.initEvent(), set the value to null."?
TODO: find out whether this should really discuss DOM Level 2 methods,
it seems that rather belongs to the method definitions.
> Used to specify the time at which the event was created in
> milliseconds relative to 1970-01-01T00:00:00Z. Due to the fact that
> some systems may not provide this information the value of timeStamp
> may be not available for all events.
>
>Does "1970-01-01T00:00:00Z" use a common enough time format to warrant
>not mentioning how it should be parsed (by readers)? Are leap seconds
>included in this offset?
The format is common enough and I think the relationship to leap seconds
is clear. I don't think it would be appropriate to include an elaborate
discussion of leap seconds in this context.
> If an event is cancelable, the preventDefault method is used to
> signify that the event is to be canceled, meaning any default action
> normally taken by the implementation as a result of the event will not
> occur (see also Default actions and cancelable events), and thus
> independently of event groups.
>
>s/, and thus independently of event groups// (what was that bit trying
>to say?)
Done, though:
TODO: if we keep event groups, there should be a note somewhere that an
event cannot have its default action prevented for a single group only.
>[initEventNS]
> The initEventNS method is used to initialize the value of an Event
> object and has the same behavior as Event.initEvent().
>
>That's not true, since initEventNS initializes the namespaceURI
>attribute, which initEvent doesn't do. Maybe this should say that it
>has the same general behaviour (modulo the particular attributes being
>initialized). This applies to the description for each init*Event(NS)
>method in the document.
That is incorrect, initEvent sets the namespaceURI to null just like
initEventNS would when namespaceURI is null or the empty string. I do
not think this should be changed for the reasons you cite, even a minor
change like s/same behavior/same general behavior/ would invite readers
to investigate which subtle differences there might be, while there are
just incredibly obvious differences.
>[stopImmediatePropagation]
> This method is used to prevent event listeners of the same group to be
> triggered[...]. Once it has been called, further calls to that method
> have no additional effect.
>
>s/to be/from being/
>s/that/this/
>
>These two also apply to the text for stopPropagation.
Done.
>* * Interface EventTarget
>
> The EventTarget interface is implemented by all the objects which
> could be event targets in an implementation which supports the Event
> flows.
>
>s/the Event flows/an Event flow/, to make the distinction between
>general event flows, and the DOM event flow that is mentioned in the
>next paragraph.
TODO: I'll have to find a way to do that that doesn't break stuff...
> When used with DOM event flow, [...]
>
>s/with/with the/
Done.
>* * Interface EventListener
>
> The EventListener interface is the primary way for handling events.
>
>s/for handling/to handle/
Why?
>* 1.7.1 Event creation
>
>* * Interface DocumentEvent
>
>[canDispatch]
> Test if the implementation can generate events of a specified type.
>
>Other method descriptions begin with "This method" or "Method xxx", so
>maybe this should be brought in line with those for consistency:
>
> This method tests if the implementation can generate events of a
> specified type.
This wasn't so consistent as you suggest. It should be considerably more
consistent now. "This method" is poor style, "The method xxx" is good if
the expactation is that the description would typically be read out of
context which I think is not the case here, so the descriptions now
start with a verb that signifies the behavior of the method from the
perspective of the caller. s/Test/Tests/ for this instance.
>[createEvent]
>
>This seems to be missing a description. Suggested text:
>
> This method creates and returns a new event object that implements the
> specified interface.
Done (along those lines).
>The parameter name should be changed from "eventType" to
>"eventInterfaceName" or something similar, to indicate more accurately
>its purpose.
This is an identifier that identifies the interface, your name suggests
that it is the name of the interface which it is not. I don't know of a
better name, if you can find one...
> If the Event is to be dispatched via the EventTarget.dispatchEvent()
> method the appropriate event init method must be called after creation
> in order to initialize the Event's values.
>
>s/init/initialization/
Done.
>* 1.8.1 User Interface event types
>
> A DOM application may use the hasFeature(feature, version) method of
> the DOMImplementation interface with parameter values "UIEvents" and
> "3.0" (respectively) to determine whether or not the DOM Level 3 User
> Interface event module are supported by the implementation.
>
>s/are/is/
Done.
>The DOMFocusIn and DOMFocusOut event types are listed as being within
>the XML Events namespace, but they should be in no namespace.
Already fixed.
>* 1.8.3 Mouse event types
>
>* * Interface MouseEvent
>
> Ancestors of the targeted element may use bubbling to obtain
> notification of mouse events which occur within theirs descendent
> elements.
>
>s/theirs/their/
Done.
>Should the descriptions for clientX and clientY mention that they are
>coordinates relative to the visual display being presented by the view
>given in the view attribute?
Please raise a separate issue for this.
>[getModifierState]
> This methods queries the state of a modifier using a key identifier.
>
>s/methods/method/
Done (both instances).
>I think it would be helpful for the description of this method to list
>all of the modifier keys that are listed in Appendix A, and also that
>others may be used for other modifiers. There should also be a way to
>get a list of all of the modifiers that are in effect, so that
>applications can make use of modifiers that aren't listed in Appendix A.
Please raise a separate issue for this.
>These comments relating to modifier state also apply to the
>KeyboardEvent section.
>
> true if it is modifier key and the modifier is activated, false
> otherwise.
>
>s/is/is a/
Done.
>With initMouseEventNS, what happens if a key that is not a modifier is
>given in the modifiersList argument, such as "Tab"? What if it
>specifies a key that the implementation does not know about?
Please raise a separate issue for this.
>The paragraph beginning "The Mouse event types are listed below" repeats
>two sentences from above the MouseEvent IDL.
>
> The definition of a click depends on the environment configuration;
> i.e. may depend on the screen location or the delay between the press
> and release of the pointing device button.
>
>s/; i\.e\./, i.e. it/
Done.
>* * Interface KeyboardEvent
>
> These attributes are equivalent to use the method
> KeyboardEvent.getModifierState(keyIdentifierArg) with "Control",
> "Shift", "Alt", or "Meta" respectively.
>
>s/use/using/
Done.
> In case a DOM implementation wishes to provide a new location
> information, a value different from the following constant values must
> be used.
>
>s/provide a new location information/specify a different key location/
>
>Appendix A should mention the "Unidentified" key identifier referred to
>in the description of the keyIdentifier attribute.
TODO: add this in the prose preceding the list; the identifier is not
part of the set.
>The descriptions of altKey, ctrlKey, keyLocation, metaKey, shiftKey and
>getModifierState duplicate those in the MouseEvent section, sometimes
>with slightly different text ("if the alt (alternative) key modifier is
>activated" for MouseEvent.altKey, "if the alternative (Alt) key modifier
>is activated" for KeyboardEvent.altKey).
TODO: Find a way to fix this. I guess the best solution here would be
to merge the information, put them only in the keyboard interface
description, move the keyboard stuff before the mouse stuff, and refer
to the keyboard stuff on any later occurence.
>[initKeyboardEvent modifiersList]
> A white space separated list of modifier key identifiers to be
> activated on this object.
>
>"Activated" sounds strange. "Set"?
I can see how this might sound strange but I don't think "set" is better
(and I don't have a better wording at the moment).
> This event should logically happen before the event keyup is produced.
> [...]
> This event should logically happen after the event keydown is
> produced.
>
>s/logically happen/be dispatched/g, if that is what it means.
Implementations generate and dispatch event objects because the event
that corresponds to the object occured or happened; I think this is fine
as is.
>* 1.8.5 Mutation and mutation name event types
>
>Are the DOMElementNameChanged and DOMAttributeNameChanged events fired
>if the renameNode just fell back to removing the node and adding a new
>one?
Please raise a separate issue for this.
regards,
--
Björn Höhrmann · mailto:bjoern@hoehrmann.de · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/
Received on Wednesday, 19 April 2006 13:10:29 UTC