- From: Cameron McCormack <cam@mcc.id.au>
- Date: Sun, 16 Apr 2006 23:19:18 +1000
- To: public-webapi@w3.org
Dear Web APIs Working Group,
Firstly, well done on publishing the DOM 3 Events WD and getting it back
on track.
This mail just contains (mostly) editorial comments for chapter 1,
organised by section, for consideration by the hive mind. Feel free to
ignore my pedantry. :-)
Thanks,
Cameron
----
* 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)
* 1.2.1 Phases
The event dispatching (also called event propagation) occurs in three
phases and the following order:
s/and/in/
If the target node is removed during the dispatching, [...]
s/dispatching/dispatch/
* 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//
* 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/
Within a group, event listeners are ordered in their order of
registration.
s/in/by/ (or s/in/according to/)
While this specification does not specify a full ordering [...]
/full ordering/total ordering for event triggering/
* 1.2.2.3 Triggering an event listener
Consistent punctuation should be used at the end of the list items.
* 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/
* 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/
[...] 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)
* 1.3 Default actions and cancelable events
[...] e.g. by pressing on a submit button [...]
s/pressing/clicking/
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/
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/
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)?
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.
* 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?
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.
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
s/respective/the relevant/
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,/
* 1.5.2 Complete list of event types
[...] e.g., mouse, keyboard, touch screen, and voice [...]
s/and/or/
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?
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".
* 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/
* 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?)
* 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).
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.
.
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.
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.
.
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?
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?)
[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.
[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.
* * 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.
When used with DOM event flow, [...]
s/with/with the/
* * Interface EventListener
The EventListener interface is the primary way for handling events.
s/for handling/to handle/
* 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.
[createEvent]
This seems to be missing a description. Suggested text:
This method creates and returns a new event object that implements the
specified interface.
The parameter name should be changed from "eventType" to
"eventInterfaceName" or something similar, to indicate more accurately
its purpose.
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/
* 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/
The DOMFocusIn and DOMFocusOut event types are listed as being within
the XML Events namespace, but they should be in no namespace.
* 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/
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?
[getModifierState]
This methods queries the state of a modifier using a key identifier.
s/methods/method/
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.
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/
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?
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/
* * Interface KeyboardEvent
These attributes are equivalent to use the method
KeyboardEvent.getModifierState(keyIdentifierArg) with "Control",
"Shift", "Alt", or "Meta" respectively.
s/use/using/
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.
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).
[initKeyboardEvent modifiersList]
A white space separated list of modifier key identifiers to be
activated on this object.
"Activated" sounds strange. "Set"?
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.
* 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?
--
Cameron McCormack ICQ: 26955922
cam (at) mcc.id.au MSN: cam (at) mcc.id.au
http://mcc.id.au/ JBR: heycam (at) jabber.org
Received on Sunday, 16 April 2006 13:19:40 UTC