[cssom-view] Change MediaQueryList to use events. Fixes https://www.w3.org/Bugs/Public/show_bug.cgi?id=25304

Author: Simon Pieters

cssom-view/Overview.html

@@ -16,7 +16,7 @@
 
  <h1>CSSOM View Module</h1>
 
- <h2 class="no-num no-toc" id="w3c-doctype">Editor's Draft 9 January 2014</h2>
+ <h2 class="no-num no-toc" id="w3c-doctype">Editor's Draft 6 June 2014</h2>
 
  <dl>
 
@@ -83,7 +83,7 @@ <h2 class="no-num no-toc" id="sotd">Status of This Document</h2>
 can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
 index at http://www.w3.org/TR/.</a></em>
 
-<p>This is the 9 January 2014 Editor's Draft of CSSOM View. Please send
+<p>This is the 6 June 2014 Editor's Draft of CSSOM View. Please send
 comments to
 <a href="mailto:www-style@w3.org?subject=%5Bcssom-view%5D%20">www-style@w3.org</a>
 (<a href="http://lists.w3.org/Archives/Public/www-style/">archived</a>)
@@ -815,45 +815,106 @@ <h4 id="the-features-argument-to-the-open()-method"><span class="secno">5.1 </sp
 
 <h3 id="the-mediaquerylist-interface"><span class="secno">5.2 </span>The <code title="">MediaQueryList</code> Interface</h3>
 
-<p>A <code><a href="#mediaquerylist">MediaQueryList</a></code> object has an associated media query list set on creation and an associated
-<dfn id="list-of-media-query-list-listeners">list of media query list listeners</dfn>, which is initially empty.</p>
-<p>If the associated media query list changes in evaluation then, for each
-listener in the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a> — in
-appending order, <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> that invokes the listener,
-passing as argument the <code><a href="#mediaquerylist">MediaQueryList</a></code> object.</p>
+<p>A <code><a href="#mediaquerylist">MediaQueryList</a></code> object has an associated media query list set on creation.</p>
+
+<p>A <code><a href="#mediaquerylist">MediaQueryList</a></code> object has an associated <dfn id="concept-mediaquerylist-media" title="concept-MediaQueryList-media">media</dfn> which is the
+<a class="external" data-anolis-spec="cssom" href="http://dev.w3.org/csswg/cssom/#serialize-a-media-query-list" title="serialize a media query list">serialized</a> form of the associated media query list.</p>
+
+<p>A <code><a href="#mediaquerylist">MediaQueryList</a></code> object has an associated <dfn id="concept-mediaquerylist-matches" title="concept-MediaQueryList-matches">matches state</dfn> which is
+true if the associated media query list matches the state of the rendered <code class="external" data-anolis-spec="dom"><a href="http://dom.spec.whatwg.org/#document">Document</a></code>, and false otherwise.</p>
+
+<p>If the associated media query list changes in evaluation, the user agent must <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> to run these steps:</p>
+
+<ol>
+
+ <li><p>Let <var>target</var> be the <code><a href="#mediaquerylist">MediaQueryList</a></code> object.</li>
+
+ <li><p>Let <var>event</var> be a new <a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#concept-event" title="concept-event">event</a>
+ using the <code><a href="#mediaquerylistevent">MediaQueryListEvent</a></code> interface,
+ with its <code class="external" data-anolis-spec="dom" title="dom-Event-type"><a href="http://dom.spec.whatwg.org/#dom-event-type">type</a></code> attribute initialized to <code title="">change</code>,
+ its <code class="external" data-anolis-spec="dom" title="dom-Event-isTrusted"><a href="http://dom.spec.whatwg.org/#dom-event-istrusted">isTrusted</a></code> attribute initialized to true,
+ its <code title="dom-MediaQueryListEvent-media"><a href="#dom-mediaquerylistevent-media">media</a></code> attribute initialized to <var>target</var>'s <a href="#concept-mediaquerylist-media" title="concept-MediaQueryList-media">media</a>,
+ and its <code title="dom-MediaQueryListEvent-matches"><a href="#dom-mediaquerylistevent-matches">matches</a></code> attribute initialized to <var>target</var>'s <a href="#concept-mediaquerylist-matches" title="concept-MediaQueryList-matches">matches state</a>. <!--fingerprint--></li>
+
+ <li><p><a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#concept-event-dispatch" title="concept-event-dispatch">Dispatch</a> <var>event</var> to <var>target</var>.</li>
+
+</ol>
+
 <div class="example">
 <p>A simple piece of code that detects changes in the orientation of the viewport can be written as follows:</p>
-<pre>function handleOrientationChange(mql) {
-    if(mql.matches) // landscape
+<pre>function handleOrientationChange(event) {
+    if(event.matches) // landscape
       …
     else
       …
   }
   var mql = matchMedia("(orientation:landscape)")
-  mql.addListener(handleOrientationChange)</pre>
+  mql.onchange = handleOrientationChange</pre>
 </div>
 
-<pre class="idl">interface <dfn id="mediaquerylist">MediaQueryList</dfn> {
+<pre class="idl">interface <dfn id="mediaquerylist">MediaQueryList</dfn> : <a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#eventtarget">EventTarget</a> {
   readonly attribute DOMString <a href="#dom-mediaquerylist-media" title="dom-MediaQueryList-media">media</a>;
   readonly attribute boolean <a href="#dom-mediaquerylist-matches" title="dom-MediaQueryList-matches">matches</a>;
-  void <a href="#dom-mediaquerylist-addlistener" title="dom-MediaQueryList-addListener">addListener</a>(<a href="#mediaquerylistlistener">MediaQueryListListener</a> listener);
-  void <a href="#dom-mediaquerylist-removelistener" title="dom-MediaQueryList-removeListener">removeListener</a>(<a href="#mediaquerylistlistener">MediaQueryListListener</a> listener);
-};
-
-callback <dfn id="mediaquerylistlistener">MediaQueryListListener</dfn> = void (<a href="#mediaquerylist">MediaQueryList</a> list);</pre>
+  void <a href="#dom-mediaquerylist-addlistener" title="dom-MediaQueryList-addListener">addListener</a>(<a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#eventlistener">EventListener</a>? listener);
+  void <a href="#dom-mediaquerylist-removelistener" title="dom-MediaQueryList-removeListener">removeListener</a>(<a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#eventlistener">EventListener</a>? listener);
+           attribute <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler">EventHandler</a> onchange;
+};</pre>
 
-<p>The <dfn id="dom-mediaquerylist-media" title="dom-MediaQueryList-media"><code>media</code></dfn> attribute must return the
-<a class="external" data-anolis-spec="cssom" href="http://dev.w3.org/csswg/cssom/#serialize-a-media-query-list" title="serialize a media query list">serialized</a> form of the associated media query list.</p>
+<p>The <dfn id="dom-mediaquerylist-media" title="dom-MediaQueryList-media"><code>media</code></dfn> attribute must return
+the associated <a href="#concept-mediaquerylist-media" title="concept-MediaQueryList-media">media</a>.</p>
 
-<p>The <dfn id="dom-mediaquerylist-matches" title="dom-MediaQueryList-matches"><code>matches</code></dfn> attribute must return true if the associated media query list
-matches the state of the rendered <code class="external" data-anolis-spec="dom"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> and false if it does not. <!--fingerprint--></p>
+<p>The <dfn id="dom-mediaquerylist-matches" title="dom-MediaQueryList-matches"><code>matches</code></dfn> attribute must return
+the associated <a href="#concept-mediaquerylist-matches" title="concept-MediaQueryList-matches">matches state</a>. <!--fingerprint--></p>
 
-<p>When the <dfn id="dom-mediaquerylist-addlistener" title="dom-MediaQueryList-addListener"><code>addListener(<var>listener</var>)</code></dfn> method is invoked <var>listener</var> must
-be appended to the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a>, unless
-it is already in the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a>.</p>
+<p>When the <dfn id="dom-mediaquerylist-addlistener" title="dom-MediaQueryList-addListener"><code>addListener(<var>listener</var>)</code></dfn> method is invoked
+the user agent must invoke the <code class="external" data-anolis-spec="dom" title="dom-EventTarget-addEventListener"><a href="http://dom.spec.whatwg.org/#dom-eventtarget-addeventlistener">addEventListener</a></code> method
+with <code title="">change</code> as the first argument and <var>listener</var> as the second argument.</p>
 
 <p>When the <dfn id="dom-mediaquerylist-removelistener" title="dom-MediaQueryList-removeListener"><code>removeListener(<var>listener</var>)</code></dfn> method is invoked
-<var>listener</var> must be removed from the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a>.</p>
+the user agent must invoke the <code class="external" data-anolis-spec="dom" title="dom-EventTarget-removeEventListener"><a href="http://dom.spec.whatwg.org/#dom-eventtarget-removeeventlistener">removeEventListener</a></code> method
+with <code title="">change</code> as the first argument and <var>listener</var> as the second argument.</p>
+
+<p class="note">This specification initially had a custom callback mechanism with <code title="dom-MediaQueryList-addListener"><a href="#dom-mediaquerylist-addlistener">addListener</a></code> and
+<code title="dom-MediaQueryList-removeListener"><a href="#dom-mediaquerylist-removelistener">removeListener</a></code>, and the callback was invoked with the associated media query list as argument.
+Now the normal event mechanism is used instead.
+For backwards compatibility, the <code title="dom-MediaQueryList-addListener"><a href="#dom-mediaquerylist-addlistener">addListener</a></code> and <code title="dom-MediaQueryList-removeListener"><a href="#dom-mediaquerylist-removelistener">removeListener</a></code> methods
+are basically aliases for <code class="external" data-anolis-spec="dom" title="dom-EventTarget-addEventListener"><a href="http://dom.spec.whatwg.org/#dom-eventtarget-addeventlistener">addEventListener</a></code> and <code class="external" data-anolis-spec="dom" title="dom-EventTarget-removeEventListener"><a href="http://dom.spec.whatwg.org/#dom-eventtarget-removeeventlistener">removeEventListener</a></code>, respectively,
+and the <code title="">change</code> event masquerades as a <code><a href="#mediaquerylist">MediaQueryList</a></code>.</p>
+
+<p>The following are the <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers">event handlers</a>
+(and their corresponding <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type" title="event handler event type">event handler event types</a>) that must be supported,
+as <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-idl-attributes">event handler IDL attributes</a>, by all objects implementing the <code><a href="#mediaquerylist">MediaQueryList</a></code> interface:</p>
+
+<table class="complex data">
+ <thead>
+  <tr>
+   <th><a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handlers" title="event handlers">Event handler</a></th>
+   <th><a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#event-handler-event-type">Event handler event type</a></th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td><dfn id="handler-mediaquerylist-onchange" title="handler-MediaQueryList-onchange">onchange</dfn>
+   <td><code title="">change</code>
+  </tr>
+ </tbody>
+</table>
+
+<pre class="idl">[<a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#concept-event-constructor" title="concept-event-constructor">Constructor</a>(DOMString type, optional <a href="#mediaquerylisteventinit">MediaQueryListEventInit</a> eventInitDict),
+ Exposed=Window,Worker]
+interface <dfn id="mediaquerylistevent">MediaQueryListEvent</dfn> : <a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#event">Event</a> {
+  readonly attribute DOMString <a href="#dom-mediaquerylistevent-media" title="dom-MediaQueryListEvent-media">media</a>;
+  readonly attribute boolean <a href="#dom-mediaquerylistevent-matches" title="dom-MediaQueryListEvent-matches">matches</a>;
+};
+
+dictionary <dfn id="mediaquerylisteventinit">MediaQueryListEventInit</dfn> : <a class="external" data-anolis-spec="dom" href="http://dom.spec.whatwg.org/#eventinit">EventInit</a> {
+  DOMString media = '';
+  boolean matches = false;
+};</pre>
+
+<p>The <dfn id="dom-mediaquerylistevent-media" title="dom-MediaQueryListEvent-media"><code>media</code></dfn> attribute must return the value it was initialized to.</p>
+
+<p>The <dfn id="dom-mediaquerylistevent-matches" title="dom-MediaQueryListEvent-matches"><code>matches</code></dfn> attribute must return the value it was initialized to.</p>
 
 <h3 id="the-screen-interface"><span class="secno">5.3 </span>The <code title="">Screen</code> Interface</h3>
 
@@ -1491,7 +1552,7 @@ <h2 id="extensions-to-the-htmlelement-interface"><span class="secno">8 </span>Ex
 
 <h2 id="excensions-to-the-htmlimageelement-interface"><span class="secno">9 </span>Excensions to the <code title="">HTMLImageElement</code> Interface</h2>
 
-<pre class="idl">partial interface <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/embedded-content-1.html#htmlimageelement">HTMLImageElement</a> {
+<pre class="idl">partial interface <a class="external" data-anolis-spec="html" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/edits.html#htmlimageelement">HTMLImageElement</a> {
   readonly attribute double <a href="#dom-htmlimageelement-x" title="dom-HTMLImageElement-x">x</a>;
   readonly attribute double <a href="#dom-htmlimageelement-y" title="dom-HTMLImageElement-y">y</a>;
 };</pre>