Skip to content

Commit

Permalink
Editorial: put properties shared across globals on mixin
Browse files Browse the repository at this point in the history 
This makes the following editorial changes:

* Groups base64, timer, and ImageBitmap properties on a single mixin.
* Removes overloading of timer methods in favor of a union type

It is expected that other standards will make use of this mixin,
e.g., Fetch will use it to define fetch().
  • Loading branch information
@annevk @domenic
annevk authored and domenic committed Apr 6, 2016
1 parent 38139b4 commit cdd48e1
Showing 1 changed file with 108 additions and 102 deletions.
210 changes: 108 additions & 102 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87530,29 +87530,55 @@ interface <dfn>DocumentAndElementEventHandlers</dfn> {
</div>


<h3 id="atob">Base64 utility methods</h3>
<h3 id="windoworworkerglobalscope-mixin">The <code>WindowOrWorkerGlobalScope</code> mixin</h3>

<p>The <code data-x="dom-windowbase64-atob">atob()</code> and <code
data-x="dom-windowbase64-btoa">btoa()</code> methods allow authors to transform content to and from
the base64 encoding.</p>
<p>The <code>WindowOrWorkerGlobalScope</code> mixin is for use of APIs that are to be exposed on
<code>Window</code> and <code>WorkerGlobalScope</code> objects.</p>

<!-- v2: actual binary support -->
<p class="note">Other standards are encouraged to further extend it using <code data-x="">partial
interface <span>WindowOrWorkerGlobalScope</span> { &hellip; };</code> along with an appropriate
reference.</p>

<pre class="idl">[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn>WindowBase64</dfn> {
DOMString <span data-x="dom-windowbase64-btoa">btoa</span>(DOMString btoa);
DOMString <span data-x="dom-windowbase64-atob">atob</span>(DOMString atob);
<pre class="idl">typedef (DOMString or <span data-x="idl-Function">Function</span>) <dfn>TimerHandler</dfn>;

[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn>WindowOrWorkerGlobalScope</dfn> {
// base64 utility methods
DOMString <span data-x="dom-btoa">btoa</span>(DOMString data);
DOMString <span data-x="dom-atob">atob</span>(DOMString data);

// timers
long <span data-x="dom-setTimeout">setTimeout</span>(<span>TimerHandler</span> handler, optional long timeout = 0, any... arguments);
void <span data-x="dom-clearTimeout">clearTimeout</span>(optional long handle = 0);
long <span data-x="dom-setInterval">setInterval</span>(<span>TimerHandler</span> handler, optional long timeout = 0, any... arguments);
void <span data-x="dom-clearInterval">clearInterval</span>(optional long handle = 0);

// ImageBitmap
Promise&lt;<span>ImageBitmap</span>&gt; <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, optional <span>ImageBitmapOptions</span> options);
Promise&lt;<span>ImageBitmap</span>&gt; <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, long sx, long sy, long sw, long sh, optional <span>ImageBitmapOptions</span> options);
};
<span>Window</span> implements <span>WindowBase64</span>;
<span>WorkerGlobalScope</span> implements <span>WindowBase64</span>;</pre>
<span>Window</span> implements <span>WindowOrWorkerGlobalScope</span>;
<span>WorkerGlobalScope</span> implements <span>WindowOrWorkerGlobalScope</span>;</pre>

<!-- Demonstrating the need for wrapping of the timeout argument value treated as long rather than clamping or treating as double:
http://software.hixie.ch/utilities/js/live-dom-viewer/saved/1228
Demonstrating the need for the timeout argument to be signed rather than unsigned:
http://software.hixie.ch/utilities/js/live-dom-viewer/saved/1229
-->


<h3 id="atob">Base64 utility methods</h3>

<p>The <code data-x="dom-atob">atob()</code> and <code data-x="dom-btoa">btoa()</code> methods
allow developers to transform content to and from the base64 encoding.</p>

<p class="note">In these APIs, for mnemonic purposes, the "b" can be considered to stand for
"binary", and the "a" for "ASCII". In practice, though, for primarily historical reasons, both the
input and output of these functions are Unicode strings.</p>

<dl class="domintro">

<dt><var>result</var> = <var>window</var> . <code subdfn data-x="dom-windowbase64-btoa">btoa</code>( <var>data</var> )</dt>
<dt><var>result</var> = self . <code subdfn data-x="dom-btoa">btoa</code>( <var>data</var> )</dt>

<dd>

Expand All @@ -87565,7 +87591,7 @@ interface <dfn>WindowBase64</dfn> {

</dd>

<dt><var>result</var> = <var>window</var> . <code subdfn data-x="dom-windowbase64-atob">atob</code>( <var>data</var> )</dt>
<dt><var>result</var> = self . <code subdfn data-x="dom-atob">atob</code>( <var>data</var> )</dt>

<dd>

Expand All @@ -87583,17 +87609,19 @@ interface <dfn>WindowBase64</dfn> {

<div w-nodev>

<p>The <dfn><code data-x="dom-windowbase64-btoa">btoa()</code></dfn> method must throw an
<code>InvalidCharacterError</code> exception if the method's first argument contains any character
whose code point is greater than U+00FF. Otherwise, the user agent must convert that argument to a
sequence of octets whose <var>n</var>th octet is the eight-bit representation of the code
point of the <var>n</var>th character of the argument, and then must apply the base64
algorithm to that sequence of octets, and return the result. <ref spec=RFC4648><!--base64--></p> <!-- Aryeh says: This seems to be what all
browsers do as of January 2011 (except IE, which doesn't support these functions at all). -->
<p>The <dfn data-x="dom-btoa"><code id="dom-windowbase64-btoa">btoa(<var>data</var>)</code></dfn>
method must throw an <code>InvalidCharacterError</code> exception if <var>data</var> contains any
character whose code point is greater than U+00FF. Otherwise, the user agent must convert
<var>data</var> to a sequence of octets whose <var>n</var>th octet is the eight-bit representation
of the code point of the <var>n</var>th character of <var>data</var>, and then must apply the
base64 algorithm to that sequence of octets, and return the result. <ref
spec=RFC4648><!--base64--></p>
<!-- Aryeh says: This seems to be what all browsers do as of January 2011 (except IE, which
doesn't support these functions at all). -->


<p>The <dfn><code data-x="dom-windowbase64-atob">atob()</code></dfn> method must run the following
steps to parse the string passed in the method's first argument:</p>
<p>The <dfn data-x="dom-atob"><code id="dom-windowbase64-atob">atob(<var>data</var>)</code></dfn>
method, when invoked, must run the following steps:</p>

<ol>

Expand All @@ -87605,23 +87633,22 @@ interface <dfn>WindowBase64</dfn> {
https://lists.w3.org/Archives/Public/public-whatwg-archive/2011May/0207.html
-->

<li><p>Let <var>input</var> be the string being parsed.</p></li>

<li><p>Let <var>position</var> be a pointer into <var>input</var>, initially
<li><p>Let <var>position</var> be a pointer into <var>data</var>, initially
pointing at the start of the string.</p></li>

<li><p>Remove all <span data-x="space character">space characters</span> from <var>input</var>.</p></li>
<li><p>Remove all <span data-x="space character">space characters</span> from
<var>data</var>.</p></li>

<li><p>If the length of <var>input</var> divides by 4 leaving no remainder, then: if
<var>input</var> ends with one or two U+003D EQUALS SIGN (=) characters, remove them
from <var>input</var>.</p></li>
<li><p>If the length of <var>data</var> divides by 4 leaving no remainder, then: if
<var>data</var> ends with one or two U+003D EQUALS SIGN (=) characters, remove them from
<var>data</var>.</p></li>

<li><p>If the length of <var>input</var> divides by 4 leaving a remainder of 1, throw an
<li><p>If the length of <var>data</var> divides by 4 leaving a remainder of 1, throw an
<code>InvalidCharacterError</code> exception and abort these steps.</p>

<li>

<p>If <var>input</var> contains a character that is not in the following list of
<p>If <var>data</var> contains a character that is not in the following list of
characters and character ranges, throw an <code>InvalidCharacterError</code> exception and abort
these steps:</p>

Expand All @@ -87640,8 +87667,8 @@ interface <dfn>WindowBase64</dfn> {

<li>

<p>While <var>position</var> does not point past the end of <var>input</var>,
run these substeps:</p>
<p>While <var>position</var> does not point past the end of <var>data</var>, run these
substeps:</p>

<ol>

Expand Down Expand Up @@ -88256,31 +88283,13 @@ interface <dfn>WindowBase64</dfn> {

<h3 id="timers">Timers</h3>

<p>The <code data-x="dom-windowtimers-setTimeout">setTimeout()</code>
and <code data-x="dom-windowtimers-setInterval">setInterval()</code>
methods allow authors to schedule timer-based callbacks.</p>

<pre class="idl">[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn>WindowTimers</dfn> {
long <span data-x="dom-windowtimers-setTimeout">setTimeout</span>(<span data-x="idl-Function">Function</span> handler, optional long timeout = 0, any... arguments);
long <span data-x="dom-windowtimers-setTimeout">setTimeout</span>(DOMString handler, optional long timeout = 0, any... arguments);
void <span data-x="dom-windowtimers-clearTimeout">clearTimeout</span>(optional long handle = 0);
long <span data-x="dom-windowtimers-setInterval">setInterval</span>(<span data-x="idl-Function">Function</span> handler, optional long timeout = 0, any... arguments);
long <span data-x="dom-windowtimers-setInterval">setInterval</span>(DOMString handler, optional long timeout = 0, any... arguments);
void <span data-x="dom-windowtimers-clearInterval">clearInterval</span>(optional long handle = 0);
};
<span>Window</span> implements <span>WindowTimers</span>;
<span>WorkerGlobalScope</span> implements <span>WindowTimers</span>;</pre>

<!-- Demonstrating the need for wrapping of the timeout argument value treated as long rather than clamping or treating as double:
http://software.hixie.ch/utilities/js/live-dom-viewer/saved/1228
Demonstrating the need for the timeout argument to be signed rather than unsigned:
http://software.hixie.ch/utilities/js/live-dom-viewer/saved/1229
-->
<p>The <code data-x="dom-setTimeout">setTimeout()</code> and <code
data-x="dom-setInterval">setInterval()</code> methods allow authors to schedule timer-based
callbacks.</p>

<dl class="domintro">

<dt><var>handle</var> = <var>window</var> . <code subdfn data-x="dom-windowtimers-setTimeout">setTimeout</code>( <var>handler</var> [, <var>timeout</var> [, <var>arguments</var>... ] ] )</dt>
<dt><var>handle</var> = self . <code subdfn data-x="dom-setTimeout">setTimeout</code>( <var>handler</var> [, <var>timeout</var> [, <var>arguments</var>... ] ] )</dt>

<dd>

Expand All @@ -88289,26 +88298,25 @@ interface <dfn>WindowTimers</dfn> {

</dd>

<dt><var>handle</var> = <var>window</var> . <code data-x="dom-windowtimers-setTimeout">setTimeout</code>( <var>code</var> [, <var>timeout</var> ] )</dt>
<dt><var>handle</var> = self . <code data-x="dom-setTimeout">setTimeout</code>( <var>code</var> [, <var>timeout</var> ] )</dt>

<dd>

<p>Schedules a timeout to compile and run <var>code</var> after <var>timeout</var> milliseconds.</p>

</dd>

<dt><var>window</var> . <code subdfn data-x="dom-windowtimers-clearTimeout">clearTimeout</code>( <var>handle</var> )</dt>
<dt>self . <code subdfn data-x="dom-clearTimeout">clearTimeout</code>( <var>handle</var> )</dt>
<!-- don't mention that the handle is optional, since if omitted, the method does nothing -->

<dd>

<p>Cancels the timeout set with <code data-x="dom-windowtimers-setTimeout">setTimeout()</code>
or <code data-x="dom-windowtimers-setInterval">setInterval()</code> identified by
<var>handle</var>.</p>
<p>Cancels the timeout set with <code data-x="dom-setTimeout">setTimeout()</code> or <code
data-x="dom-setInterval">setInterval()</code> identified by <var>handle</var>.</p>

</dd>

<dt><var>handle</var> = <var>window</var> . <code subdfn data-x="dom-windowtimers-setInterval">setInterval</code>( <var>handler</var> [, <var>timeout</var> [, <var>arguments</var>... ] ] )</dt>
<dt><var>handle</var> = self . <code subdfn data-x="dom-setInterval">setInterval</code>( <var>handler</var> [, <var>timeout</var> [, <var>arguments</var>... ] ] )</dt>

<dd>

Expand All @@ -88317,22 +88325,21 @@ interface <dfn>WindowTimers</dfn> {

</dd>

<dt><var>handle</var> = <var>window</var> . <code data-x="dom-windowtimers-setInterval">setInterval</code>( <var>code</var> [, <var>timeout</var> ] )</dt>
<dt><var>handle</var> = self . <code data-x="dom-setInterval">setInterval</code>( <var>code</var> [, <var>timeout</var> ] )</dt>

<dd>

<p>Schedules a timeout to compile and run <var>code</var> every <var>timeout</var> milliseconds.</p>

</dd>

<dt><var>window</var> . <code subdfn data-x="dom-windowtimers-clearInterval">clearInterval</code>( <var>handle</var> )</dt>
<dt>self . <code subdfn data-x="dom-clearInterval">clearInterval</code>( <var>handle</var> )</dt>
<!-- don't mention that the handle is optional, since if omitted, the method does nothing -->

<dd>

<p>Cancels the timeout set with <code data-x="dom-windowtimers-setInterval">setInterval()
</code> or <code data-x="dom-windowtimers-setTimeout">setTimeout()</code> identified by <var>
handle</var>.</p>
<p>Cancels the timeout set with <code data-x="dom-setInterval">setInterval()</code> or <code
data-x="dom-setTimeout">setTimeout()</code> identified by <var>handle</var>.</p>

</dd>

Expand All @@ -88346,34 +88353,41 @@ interface <dfn>WindowTimers</dfn> {

<div w-nodev>

<p>Objects that implement the <code>WindowTimers</code> interface have a <dfn>list of active
timers</dfn>. Each entry in this lists is identified by a number, which must be unique within the
list for the lifetime of the object that implements the <code>WindowTimers</code> interface.</p>
<p>Objects that implement the <code>WindowOrWorkerGlobalScope</code> mixin have a <dfn>list of
active timers</dfn>. Each entry in this lists is identified by a number, which must be unique
within the list for the lifetime of the object that implements the
<code>WindowOrWorkerGlobalScope</code> mixin.</p>

<hr>

<p>The <dfn><code data-x="dom-windowtimers-setTimeout">setTimeout()</code></dfn> method must return
the value returned by the <span>timer initialisation steps</span>, passing them the method's
arguments, the object on which the method for which the algorithm is running is implemented (a
<code>Window</code> or <code>WorkerGlobalScope</code> object) as the <var>method
context</var>, and the <var>repeat</var> flag set to false.</p>

<p>The <dfn><code data-x="dom-windowtimers-setInterval">setInterval()</code></dfn> method must
return the value returned by the <span>timer initialisation steps</span>, passing them the
method's arguments, the object on which the method for which the algorithm is running is
implemented (a <code>Window</code> or <code>WorkerGlobalScope</code> object) as the <var>method context</var>, and the <var>repeat</var> flag set to true.</p>

<p>The <dfn><code data-x="dom-windowtimers-clearTimeout">clearTimeout()</code></dfn> and <dfn><code data-x="dom-windowtimers-clearInterval">clearInterval()</code></dfn> methods must clear the
entry identified as <var>handle</var> from the <span>list of active timers</span> of the
<code>WindowTimers</code> object on which the method was invoked, if any, where <var>handle</var> is the argument passed to the method. (If <var>handle</var> does
not identify an entry in the <span>list of active timers</span> of the <code>WindowTimers</code>
object on which the method was invoked, the method does nothing.)</p>

<p class="note">Because <code data-x="dom-windowtimers-clearTimeout">clearTimeout()</code> and
<code data-x="dom-windowtimers-clearInterval">clearInterval()</code> clear entries from the same
list, either method can be used to clear timers created by
<code data-x="dom-windowtimers-setTimeout">setTimeout()</code> or
<code data-x="dom-windowtimers-setInterval">setInterval()</code>.</p>
<p>The <dfn data-x="dom-setTimeout"><code
id="dom-windowtimers-setTimeout">setTimeout()</code></dfn> method must return the value returned
by the <span>timer initialisation steps</span>, passing them the method's arguments, the object on
which the method for which the algorithm is running is implemented (a <code>Window</code> or
<code>WorkerGlobalScope</code> object) as the <var>method context</var>, and the <var>repeat</var>
flag set to false.</p>

<p>The <dfn data-x="dom-setInterval"><code
id="dom-windowtimers-setInterval">setInterval()</code></dfn> method must return the value returned
by the <span>timer initialisation steps</span>, passing them the method's arguments, the object on
which the method for which the algorithm is running is implemented (a <code>Window</code> or
<code>WorkerGlobalScope</code> object) as the <var>method context</var>, and the <var>repeat</var>
flag set to true.</p>

<p>The <dfn data-x="dom-clearTimeout"><code
id="dom-windowtimers-clearTimeout">clearTimeout()</code></dfn> and <dfn
data-x="dom-clearInterval"><code id="dom-windowtimers-clearInterval">clearInterval()</code></dfn>
methods must clear the entry identified as <var>handle</var> from the <span>list of active
timers</span> of the <code>WindowOrWorkerGlobalScope</code> object on which the method was
invoked, if any, where <var>handle</var> is the argument passed to the method. (If
<var>handle</var> does not identify an entry in the <span>list of active timers</span> of the
<code>WindowOrWorkerGlobalScope</code> object on which the method was invoked, the method does
nothing.)</p>

<p class="note">Because <code data-x="dom-clearTimeout">clearTimeout()</code> and <code
data-x="dom-clearInterval">clearInterval()</code> clear entries from the same list, either method
can be used to clear timers created by <code data-x="dom-setTimeout">setTimeout()</code> or <code
data-x="dom-setInterval">setInterval()</code>.</p>

<hr>

Expand Down Expand Up @@ -90372,15 +90386,7 @@ dictionary <dfn>ImageBitmapOptions</dfn> {
<span>ImageOrientation</span> <span data-x="dom-ImageBitmapOptions-imageOrientation">imageOrientation</span> = "<span data-x="dom-ImageOrientation-none">none</span>";
<span>PremultiplyAlpha</span> <span data-x="dom-ImageBitmapOptions-premultiplyAlpha">premultiplyAlpha</span> = "<span data-x="dom-PremultiplyAlpha-default">default</span>";
<span>ColorspaceConversion</span> <span data-x="dom-ImageBitmapOptions-colorspaceConversion">colorspaceConversion</span> = "<span data-x="dom-ColorspaceConversion-default">default</span>";
};

[NoInterfaceObject, Exposed=(Window,Worker)]
interface <dfn>ImageBitmapFactories</dfn> {
Promise&lt;<span>ImageBitmap</span>&gt; <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, optional <span>ImageBitmapOptions</span> options);
Promise&lt;<span>ImageBitmap</span>&gt; <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, long sx, long sy, long sw, long sh, optional <span>ImageBitmapOptions</span> options);
};
<span>Window</span> implements <span>ImageBitmapFactories</span>;
<span>WorkerGlobalScope</span> implements <span>ImageBitmapFactories</span>;</pre>
};</pre>

<p>An <code>ImageBitmap</code> object represents a bitmap image that can be painted to a canvas
without undue latency.</p>
Expand All @@ -90392,8 +90398,8 @@ interface <dfn>ImageBitmapFactories</dfn> {

<dl class="domintro">

<dt><var>promise</var> = <var>Window</var> . <code subdfn data-x="dom-createImageBitmap">createImageBitmap</code>(<var>image</var> [, <var>options</var> ])</dt>
<dt><var>promise</var> = <var>Window</var> . <code data-x="dom-createImageBitmap">createImageBitmap</code>(<var>image</var>, <var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var> [, <var>options</var> ])</dt>
<dt><var>promise</var> = self . <code subdfn data-x="dom-createImageBitmap">createImageBitmap</code>(<var>image</var> [, <var>options</var> ])</dt>
<dt><var>promise</var> = self . <code data-x="dom-createImageBitmap">createImageBitmap</code>(<var>image</var>, <var>sx</var>, <var>sy</var>, <var>sw</var>, <var>sh</var> [, <var>options</var> ])</dt>

<dd>

Expand Down

0 comments on commit cdd48e1

Please sign in to comment.