Device orientation event review comments

Some mostly editorial comments from reviewing the spec [1]. I haven't 
been following the mailing list so apologies if these have come up before:

== Section 4.1 ==
Lots of things sound like they want to be normative requirements but are 
expressed without using RFC2119 terminology. For example

"If the orientation of the screen changes when the device is rotated or 
a slide-out keyboard is deployed, this does not affect the orientation 
of the coordinate frame relative to the device"

Sounds like it should be written something like
"A change in the orientation of the screen due to device rotation, or 
change in the physical configuration of a device e.g. deployment of a 
slide-out keyboard MUST NOT affect the orientation of the coordinate 
system relative to the device"

WGS 84 needs a reference

Is using a photo of a specific device considered OK for a spec?

== Section 4.2 ==

This should hook into the HTML5/WebDOM Core-defined stuff for event 
dispatch. Specifically I think the first section should read something like:

"When a significant change in device orientation occurs the user agent 
must queue a task to create a DeviceOrientation Event and dispatch that 
event on the window object

Note: the definition of a 'significant change in device orientation' is 
implementation specific"

I would then define "create a DeviceOrientation event" as a series of 
steps below

"Registration for orientation events is achieved by calling 
window.addEventListener with event type 'deviceorientation'"

This is just a statement of fact; I don't think it adds anything here.

"Implementations must only fire events asynchronously, after this call 
has returned"

I have no idea what that is supposed to mean? If you mean that 
implementations must not dispatch DeviceOrientation events before anyone 
has registered to listen for them, that seems like an inappropriate 
normative requirement since it it untestable. It might make for a useful 
informative note to implementors, however.

I would replace the following three paragraphs with a normative 
algorithm describing how to create a device orientation event, something 
like:

"1. Create an event /event/ implementing the DeviceOrientationEvent 
interface
2. Initialize /event/'s type property to "deviceorientation"
3. Initialize /event/'s absolute property to true if the orientation 
information is relative to the Earth coordinate frame or false otherwise.
4. Initialize /event/'s compassCalibrated property to true if the 
compass is known to be correctly calibrated or false otherwise
5. Initialize /event/'s alpha property to the value in the range [0, 
360) representing the rotation in degrees about the z axis of the 
device's coordinate system if this is known otherwise null
6. Initialize /event/'s beta property to the value in the range [-180, 
180) representing the rotation in degrees about the x axis of the 
device's coordinate system otherwise null
7. Initialize /event/'s gamma property to the value in the range [-90, 
90) representing the rotation in degrees about the y axis of the 
device's coordinate system otherwise null
8. Initialize /event/'s bubbles property to (whatever it should be)
9. Initialize /event/'s cancelable property to (whatever it should be)
10. Dispatch /event/ at the window object"

Steps 2-9 should perhaps be collapsed down into a single step giving all 
the right values for the properties. It is of course also OK to have 
informative prose describing what the properties are for; this should be 
clearly separate from the actual normative requirements however.

"If an implementation can never provide orientation information, the 
event should be fired exactly once, with all properties set to null."

I don't understand what this means. Dispatching an event once per window 
seems useless because it is likely to be missed by event handlers. 
Dispatching the event as a side effect of registering a handler seems 
quite unlike anything else on the platform. What are the use cases here? 
Could they be met by just having a property that one could query on, 
say, navigator, to see if orientation events are supported by the device/UA?

== Section 4.3 ==
Is this section intended to be normative? I suppose it is since the 
content isn't defined elsewhere, but it doesn't really use normative 
language (there are no MUSTs but several statements of fact). This isn't 
a problem assuming the right normative language is added to the 
following section.

== Section 4.4 ==

Mostly the same comments as for section 4.2 i.e. a clear normative 
description of what the properties on the object are must be given.

"Note that the interval is a constant for a given implementation."

There doesn't seem to be a normative requirement corresponding to this 
note. More importantly, such a normative requirement would be 
unimplementable. For example if I put my laptop to sleep I don't expect 
it to keep firing DeviceMotion events. One might also think a UA could 
fire these events less often for pages in the background than pages in 
the foreground.

[1] http://dev.w3.org/geo/api/spec-source-orientation.html

Received on Wednesday, 11 May 2011 15:00:31 UTC