Review of the Battery Status Event specification

Hi all,

we recently published a FPWD of the Battery Status Event, here are some comments on the current draft in the hope of making it progress towards the next steps.

First and foremost, I looked at existing battery APIs to get a sense for what's straightforward to implement.

    • Android provides a lot of detail, including lots of things we almost certainly don't need. Overall it's pretty poorly documented, but you can get the level (as a value and a max, but I think we're fine to stick to just 0-1). You can know if a battery is present or not (e.g. you're plugged into the charger but have removed the battery), you can know whether it's charging, discharging, not charging, or full, and you can know if it's plugged into AC or USB.

    • Flash provides the level, also as a value plus max. It has nothing else but then again that's not a platform.

    • iOS exposes a battery level (as a simple value) and a state which is one of four values: unknown, unplugged, charging, and full.

    • I tried to get a sense for what was possible in J2ME but you have to click a million links to get to JSR-256 or dig through "simple" examples that show you over twelve pages of code how to get the current level, so I gave up. From what I gather, you can get at the level as a single value, and have a boolean about the charging state.

    • PhoneGap doesn't seem to have a battery level API (there are plugins though).

So the first conclusion I have is that we can kill timeRemaining. It doesn't seem to be available outside of desktop APIs (which are far more complete, including UPS support and all that).

Also, the isBattery/isCharging distinction is unclear to me, and doesn't seem to map perfectly to what's available in existing APIs. All the use cases I can think of that need these involve minimising power consumption on devices that have a limited amount of power available. Could we replace these two with a simple boolean isPlugged? Is there anything that wouldn't cover?

# Abstract:
  • "the battery status of the hosting device and associated auxiliary devices" What are those "associated auxiliary devices"? The first hit on Google is this spec :) I think we should either drop that part of the sentence of clarify it.


# BatteryStatusEvent Interface:
    • The initBatteryStatusEvent() method is copied from the style of other events, but it's unclear that we need all of that. Do we need a type name when there's only one event type? Do we need to state that it bubbles when its target is Window? Do we need to care whether it's cancellable given that it can't bubble and doesn't have a default action? Everyone else seems to be doing this in this exact way though, so I'm guessing we shouldn't worry too much about it.

    • Assuming we keep it, based on the above, the new IDL would look something like this:

[NoInterfaceObject]
interface BatteryStatusEvent : Event {
    readonly attribute boolean        isPlugged;
    readonly attribute float?         level;
    void initBatteryStatusEvent (DOMString type, boolean bubbles, boolean cancelable, boolean isPlugged, float? level);
};

    • "The initBatteryStatusEvent() method must initialize the event in a manner analogous to the similarly-named method in [DOM-LEVEL-3-EVENTS]." That's a bit too fuzzy. It should refer specifically to initEvent() in http://www.w3.org/TR/DOM-Level-3-Events/#events-event-type-initEvent and probably state that the isPlugged and level arguments initialise the attributes with the same names.

    • "If a change in the battery status of the hosting device occurs, then the User Agent must dispatch a BatteryStatusEvent event on the Window [HTML5] object." There are a few problems here. There should be a conformance section earlier in the document which defines the user agent as a conformance class, linked from such statements. Then the condition for event triggering is hard to pin down and test. We probably can't make it perfect, but I think that we can improve on it, especially by not making it happen whenever a 0.0000001 change takes place. There is a list of SHOULDs at the end of the section which I think could be merged with this statement here as they clarify it.

    • "If a change in the battery status of an auxiliary device occurs..." Do we need this notion? It seems to me that this could be added at a later stage, with a clearer view of what an auxiliary device is.

    • "The onbatterystatus event handler must be supported by Window objects" Do we want to have a piece of WebIDL here?

    • "If an event listener is registered with the event type batterystatus" I'd say "When an event listener..."


# The batterystatus Event
    • We need to provide a more complete description of the event, perhaps similar to one of those: http://www.w3.org/TR/DOM-Level-3-Events/#event-type-load. Something like:

Type		batterystatus
Interface	BatteryStatusEvent if generated by the user agent, Event otherwise.
Sync / Async	Async 
Bubbles		No
Target 		defaultView
Cancelable	No
Default action	none 
Context info
	• Event.target: defaultView

I could perhaps add support in ReSpec for the generation of such tables.

    • "User Agents must dispatch this event type to indicate a change in the battery status." This does not need to be there, the previous section gives enough information (or, conversely, the description in the previous section could go here).


# Examples
    • These should be marked with "<pre class='example sh_javascript'>".

I think that with these changes in place we'll be able to release a new draft. Given the simplicity of the spec, we have to think about LC soon. Thoughts?


This sends ACTION-395 to sleep with the fish.

-- 
Robin Berjon - http://berjon.com/

Received on Wednesday, 25 May 2011 12:45:58 UTC