Half a Review: Proximity Events - W3C Editor's Draft 16 May 2012

Hi,  
Below is half a review of the 16 May Proximity Events spec… ran out of time to do the whole doc, sorry.   

On Wednesday, 16 May 2012 at 11:26, Marcos Caceres wrote:

> 1. Introduction
>  
> The DeviceProximityEvent interface provides web developers information about the distance between the hosting device and the nearby object.
Please change to:   
A DeviceProximityEvent informs a web developer that the proximity sensor of the hosting device has sensed a nearby object. Proximity sensors detect the presence of physical objects within a distance that is usually predefined by the sensor manufacturer.  

Rationale for the change: you can't reliably measure distance… you can only measure if an object is within the distance range that the sensor supports.   
> The proximitystate and the corresponding event handler abstract the proximity by providing a user-agent- and platform-specific approximation of the proximity.
>  
> 2. Conformance
>  
> As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
>  
> The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
>  
> This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
>  
> 3. Terminology
>  
> The Function interface represents a function in the scripting language being used as defined in [HTML5].
We should define our own callback:  
callback ProximityCB = void(DeviceProximityEvent event);  

> The concepts queue a task and fires a simple event are defined in [HTML5].
>  
> The terms event handlers and event handler event types are defined in [HTML5].
>  
> The concepts create an event and fire an event are defined in [DOM4].
>  
> The current device proximity is the distance between the hosting device and the nearby object, in centimeters.
This is misleading. Distance is only the measure of the sensors's range. That is, a sensor can detect physical objects within 5cm… it can't tell you the distance because properties of materials screw with the sensor (see my other email about this).   
> The minimum device proximity is the minimum supported value for the current device proximity.
>  
> The maximum device proximity is the maximum supported value for the current device proximity.
The above two are defined in "cm".   
>  
> The current user proximity state is a user-agent- and platform-specific approximation of the proximity of a physical object with the hosting device.
Big warning needed here about how material properties change the ability for the proximity sensor to accurately detect distances.   
>  
> The near user proximity, a current user proximity state, is an approximation that a physical object is near.
I would add: (i.e., the sensor is sensing a physical object somewhere between its maximum and minimum device proximity).   
> The far user proximity, a current user proximity state, is an approximation that no physical object is near.

I would add: (i.e., no physical object is being detected by the sensor)  
>  
> 4. Security and privacy considerations
>  
> 5. Device proximity
>  
> The HTML5 specification [HTML5] defines a Window interface, which this specification extends:
>  
> partial interface Window {
> [TreatNonCallableAsNull]
> attribute Function? ondeviceproximity;
> };


I'm not sure if this needs to be on Window or on Navigator… I thought general consensus was to put device relate things on Navigator?  
  
> 5.1 Attributes
>  
> ondeviceproximity of type Function, nullable
> The ondeviceproximity event handler and its corresponding event handler event type deviceproximity must be supported as an IDL attribute by all objects implementing the Window interface.

The above statement is redundant (the WebIDL already says this). Change this to:  

The ondeviceproximity attribute is an event handler IDL attribute that a developer can use to receive device proximity events.
>  
> 5.2 DeviceProximityEvent Interface
>  
> [Constructor (DOMString type, optional DeviceProximityEventInit eventInitDict)]
> interface DeviceProximityEvent : Event {
> readonly attribute double value;
> readonly attribute double min;
> readonly attribute double max;
> };
> dictionary DeviceProximityEventInit : EventInit {
> double value;
> double min;
> double max;
> };
> 5.2.1 Attributes
>  
> max of type double, readonly
> The maximum device proximity.
> min of type double, readonly
> The minimum device proximity.
> value of type double, readonly
> The current proximity.
> 5.2.2 Dictionary DeviceProximityEventInit Members
>  
> max of type double
> min of type double
> value of type double
> When a user agent is required to fire a device proximity event, the user agent must run the following steps:
>  
> Create an event that uses the DeviceProximityEvent interface, with the name deviceproximity, which bubbles, is not cancelable, and has no default action, that also meets the following conditions:
> If the implementation is unable to report the current proximity, initialize the value attribute to positive Infinity, otherwise initialize the attribute to the current proximity.

What's the rationale for using +Infinity?    
> If the implementation is unable to report the minimum device proximity, initialize the min attribute to negative Infinity, otherwise initialize the attribute to the minimum device proximity.

Why not just 0? Is there any sensor that can detect -cm?  
> If the implementation is unable to report the maximum device proximity, initialize the max attribute to positive Infinity, otherwise initialize the attribute to the maximum device proximity.

Add: "in cm" to the end of the sentence.   

Now that I think about it, the above should be defined as part of the definition of min/max for the sensor (in the terminology section). It's not as if the min/max range of the sensor changes dynamically over time (or not for the common use cases, AFAIK). That keeps things related to the definition of min/max in one place. Then in the algorithm you can just say:  

"Initialize the min attribute to the minimum device proximity".

and:

"Initialize the max attribute to the maximum device proximity".

With links back to the the right definitions.  
   


> Queue a task to dispatch the newly created event at the Window object.
> When the current proximity changes, the user agent must fire a device proximity event.

> The definition of granularity i.e. how often the event is fired is left to the implementation. Different devices may also support different minimum and maximum device proximities as well as different resolution, thus authors are strongly advised not to assume near or far proximity solely based on the min and max attributes' values.  
> 5.2.3 Event handlers
>  
> The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the Window object:
>  
> event handler event handler event type
> ondeviceproximity deviceproximity
> 6. User proximity
>  
> This section is work in progress to specify an abstract proximity event that fires only when the screen is close to the user's face.
> 6.1 The proximitystate attribute
>  
> The HTML5 specification [HTML5] defines a Navigator interface, which this specification extends:
>  
> partial interface Navigator {
> readonly attribute DOMString proximitystate;
> [TreatNonCallableAsNull]
> attribute Function? onproximitystatechange;
> };
> 6.1.1 Attributes
>  
> onproximitystatechange of type Function, nullable
> proximitystate of type DOMString, readonly
> The current user proximity state.
> Each document has a current user proximity state. When a Navigator object is created, it must have its current user proximity state set to the string "near", if the current user proximity state represented is the near user proximity state, or to the string "far", if the current state proximity state represented is the far user proximity state. If the implementation is unable to report the state, or otherwise, the string must be set to "uninitialized".
>  
> The proximitystate IDL attribute must, on getting, return the current user proximity state.
>  
> When the current user proximity state changes, the user agent must queue a task which sets the proximitystate attribute's value and fires a simple event named proximitystatechange at the Window object.
>  
> 6.1.2 Event handlers
>  
> The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the Navigator object:
>  
> event handler event handler event type
> onproximitystatechange proximitystatechange
>  
>  
> --  
> Marcos Caceres
> http://datadriven.com.au

Received on Thursday, 17 May 2012 10:21:42 UTC