LightLevelEvent draft
authorDoug Turner <dougt@dougt.org>
Tue, 18 Sep 2012 12:56:23 -0700
changeset 223 4ca38a394d1d
parent 222 e3c4d9a01f00
child 224 eaa158837194
LightLevelEvent draft
light/Overview.html
--- a/light/Overview.html	Tue Sep 18 10:26:35 2012 +0200
+++ b/light/Overview.html	Tue Sep 18 12:56:23 2012 -0700
@@ -47,9 +47,28 @@
       <h2>Introduction</h2>
       <p>
         The <a>DeviceLightEvent</a> interface provides web developers
-        information about the ambient light levels near the hosting.
+        information about the ambient light levels near the
+        hosting in terms of lux units.
       </p>
       <p>
+        The <a>LightLevelEvent</a> interface provides web
+        developers information about the ambient light
+        levels near the hosting in terms of general ranges.
+      </p>
+      <p>
+        The values of the <a>LightLevelEvent</a> event may
+        be "normal", "dim", or "bright".  "bright" is
+        supposed to mean "direct sunlight, or similarly
+        bright conditions that make it hard to see things
+        that aren't high-contrast".  "dim" is supposed to
+        mean "dark enough that the light produced by a white
+        background is eye-straining or distracting".  The
+        lux values for "dim" typical begin below 50, and the
+        values for "bright" begin above 10000.
+      </p>
+        
+
+      <p>
         This is achieved by interrogating a photosensors or similar detectors
         of a device.
       </p>
@@ -99,7 +118,7 @@
     </section>
     
     <section>
-      <h2>Device light</h2>
+      <h2>Device Light</h2>
       <p>
         The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
         which this specification extends:
@@ -190,6 +209,101 @@
         </section>
       </section>
     </section>
+
+    <section>
+      <h2>Light Level</h2>
+      <p>
+        The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+        which this specification extends:
+      </p>
+      <dl title="partial interface Window" class="idl">
+        <dt>attribute EventHandler onlightlevel</dt>
+        <dd>
+        </dd>
+      </dl>
+      <p>
+        The <code>onlightlevel</code> event handler and its corresponding
+        event handler event type <code>lightlevel</code> MUST be supported
+        as an IDL attribute by all objects implementing the <a>Window</a>
+        interface.
+      </p>
+      <section>
+        <h2><a>LightLevelEvent</a> Interface</h2>
+        <dl title="[Constructor (DOMString type, optional LightLevelEventInit eventInitDict)]
+                   interface LightLevelEvent : Event"
+            class="idl" data-merge='LightLevelEventInit'>
+          <dt>readonly attribute string value</dt>
+          <dd>
+            The <a>light level</a> may be one of the following
+	    strings: "normal", "dim", or "bright".  The
+	    corresponding lux values are left up to the UA.
+          </dd>
+        </dl>
+        <dl title="dictionary LightLevelEventInit : EventInit" class='idl'>
+          <dt>
+            string value
+          </dt>
+          <dd></dd>
+        </dl>
+        <p>
+          When a <dfn>user agent</dfn> is required to <dfn>fire a light
+          level event</dfn>, the <dfn>user agent</dfn> MUST run the
+          following steps:
+        </p>
+        <ol class="rule">
+          <li>
+            <a>Create an event</a> that uses the <a>LightLevelEvent</a>
+            interface, with the name <code>lightlevel</code>, which
+            bubbles, is not cancelable, and has no default action, that also
+            meets the following conditions:
+            <ol>
+              <li>
+                If the implementation is unable to report the <a>current
+                light level</a>, initialize the <code>value</code>
+                attribute to empty string, otherwise initialize the
+                attribute to the <a>current light level</a>.
+              </li>
+            </ol>
+          </li>
+          <li>
+            <a>Queue a task</a> to dispatch the newly created event at the
+            <a>Window</a> object.
+          </li>
+        </ol>
+        <p>
+          When <a>the current light</a> changes, the <a>user
+          agent</a> MUST <a>fire a light level event</a>.
+        </p>
+        <div class="note">
+          The definition of granularity i.e. how often the event is fired is
+          left to the implementation. Implementations may fire the event if
+          they have reason to believe that the page does not have sufficiently
+          fresh data.
+        </div>
+        <section>
+          <h2>Event handlers</h2>
+          <p>
+            The following are the <a>event handlers</a> (and their corresponding
+            <a>event handler event types</a>) that MUST be supported as
+            attributes by the <code>Window</code> object:
+          </p>
+          <table class="simple">
+            <thead>
+              <tr>
+                <th>event handler</th>
+                <th>event handler event type</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td><strong><code>onlightlevel</code></strong></td>
+                <td><code>lightlevel</code></td>
+              </tr>
+            </tbody>
+          </table>
+        </section>
+      </section>
+    </section>
       
     <section class="appendix">
       <h2>Acknowledgements</h2>