Annotation of html5/spec/browsers.html, revision 1.687
1.2 mike 1: <!DOCTYPE HTML>
1.258 mike 2: <!-- when publishing, change bits marked ZZZ --><html lang="en-US-x-Hixie"><head><title>6 Web browsers — HTML 5</title><style type="text/css">
1.1 mike 3: pre { margin-left: 2em; white-space: pre-wrap; }
4: h2 { margin: 3em 0 1em 0; }
5: h3 { margin: 2.5em 0 1em 0; }
6: h4 { margin: 2.5em 0 0.75em 0; }
7: h5, h6 { margin: 2.5em 0 1em; }
8: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
9: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
10: p { margin: 1em 0; }
11: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
12: dl, dd { margin-top: 0; margin-bottom: 0; }
13: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
14: dt + dt { margin-top: 0; }
15: dd dt { margin-top: 0.25em; margin-bottom: 0; }
16: dd p { margin-top: 0; }
17: dd dl + p { margin-top: 1em; }
18: dd table + p { margin-top: 1em; }
19: p + * > li, dd li { margin: 1em 0; }
20: dt, dfn { font-weight: bold; font-style: normal; }
21: dt dfn { font-style: italic; }
22: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
23: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
24: pre em { font-weight: bolder; font-style: normal; }
25: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
26: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
27: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
28: table thead { border-bottom: solid; }
29: table tbody th:first-child { border-left: solid; }
1.475 mike 30: table tbody th { text-align: left; }
1.1 mike 31: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
32: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
33:
34: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
35: .matrix, .matrix td { border: none; text-align: right; }
36: .matrix { margin-left: 2em; }
37: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
38: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
39: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
40:
41: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
42: img.extra { float: right; }
43: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
44: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
45: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
46: pre.css:first-line { color: #AAAA50; }
47: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #EEFFEE; }
48: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
49: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
50: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
51: dl.domintro dd p { margin: 0.5em 0; }
52: dl.switch { padding-left: 2em; }
53: dl.switch > dt { text-indent: -1.5em; }
54: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
55: dl.triple { padding: 0 0 0 1em; }
56: dl.triple dt, dl.triple dd { margin: 0; display: inline }
57: dl.triple dt:after { content: ':'; }
58: dl.triple dd:after { content: '\A'; white-space: pre; }
59: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
60: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
61: a .diff-new { border-bottom: 1px blue solid; }
62:
63: h2 { page-break-before: always; }
64: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
65: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
66:
67: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]), li > span:not([title=""]):not([class="XXX"]):not([class="impl"]) { border-bottom: solid #9999CC; }
68:
69: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
70: div.head p { margin: 0; }
71: div.head h1 { margin: 0; }
72: div.head .logo { float: right; margin: 0 1em; }
73: div.head .logo img { border: none } /* remove border from top image */
74: div.head dl { margin: 1em 0; }
1.671 mike 75: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
1.1 mike 76:
77: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
78: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
79: body > .toc > li > * { margin-bottom: 0.5em; }
80: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
81: .toc, .toc li { list-style: none; }
82:
83: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
84: .brief li { margin: 0; padding: 0; }
85: .brief li p { margin: 0; padding: 0; }
86:
87: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
88: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
89: .category-list li { display: inline; }
90: .category-list li:not(:last-child)::after { content: ', '; }
91: .category-list li > span, .category-list li > a { text-transform: lowercase; }
92: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
93:
94: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
95: .XXX > :first-child { margin-top: 0; }
96: p .XXX { line-height: 3em; }
1.159 mike 97: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
98: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
99: .annotation :link, .annotation :visited { color: inherit; }
100: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
101: .annotation span { border: none ! important; }
1.1 mike 102: .note { color: green; background: transparent; font-family: sans-serif; }
103: .warning { color: red; background: transparent; }
104: .note, .warning { font-weight: bolder; font-style: italic; }
105: p.note, div.note { padding: 0.5em 2em; }
106: span.note { padding: 0 2em; }
107: .note p:first-child, .warning p:first-child { margin-top: 0; }
108: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
109: .warning:before { font-style: normal; }
110: p.note:before { content: 'Note: '; }
111: p.warning:before { content: '\26A0 Warning! '; }
112:
113: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
114: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
115: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
116:
117: h4 { position: relative; z-index: 3; }
118: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
119: .element {
120: background: #EEEEFF;
121: color: black;
122: margin: 0 0 1em 0.15em;
123: padding: 0 1em 0.25em 0.75em;
124: border-left: solid #9999FF 0.25em;
125: position: relative;
126: z-index: 1;
127: }
128: .element:before {
129: position: absolute;
130: z-index: 2;
131: top: 0;
132: left: -1.15em;
133: height: 2em;
134: width: 0.9em;
135: background: #EEEEFF;
136: content: ' ';
137: border-style: none none solid solid;
138: border-color: #9999FF;
139: border-width: 0.25em;
140: }
141:
1.149 mike 142: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
143: td > .example:only-child { margin: 0 0 0 0.1em; }
1.1 mike 144:
145: .tall-and-narrow {
146: font-size: 0.6em;
147: column-width: 25em;
148: column-gap: 1em;
149: -moz-column-width: 25em;
150: -moz-column-gap: 1em;
151: -webkit-column-width: 25em;
152: -webkit-column-gap: 1em;
153: }
154:
155: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
156: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
157: ul.domTree li li { list-style: none; }
158: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
159: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
160: ul.domTree span { font-style: italic; font-family: serif; }
161: ul.domTree .t1 code { color: purple; font-weight: bold; }
162: ul.domTree .t2 { font-style: normal; font-family: monospace; }
163: ul.domTree .t2 .name { color: black; font-weight: bold; }
164: ul.domTree .t2 .value { color: blue; font-weight: normal; }
165: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
166: ul.domTree .t7 code, .domTree .t8 code { color: green; }
167: ul.domTree .t10 code { color: teal; }
168:
1.671 mike 169: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
170: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
171: #configUI p label { display: block; }
172: #configUI #updateUI, #configUI .loginUI { text-align: center; }
173: #configUI input[type=button] { display: block; margin: auto; }
1.267 mike 174: </style><style type="text/css">
175:
1.292 mike 176: .applies thead th > * { display: block; }
177: .applies thead code { display: block; }
178: .applies tbody th { whitespace: nowrap; }
179: .applies td { text-align: center; }
180: .applies .yes { background: yellow; }
181:
1.267 mike 182: .matrix, .matrix td { border: none; text-align: right; }
183: .matrix { margin-left: 2em; }
184:
185: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
186: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
187: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
188:
189: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
190: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
191: #table-example-1 caption { padding-bottom: 0.5em; }
192: #table-example-1 thead, #table-example-1 tbody { border: none; }
193: #table-example-1 th, #table-example-1 td { border: solid thin; }
194: #table-example-1 th { font-weight: normal; }
195: #table-example-1 td { border-style: none solid; vertical-align: top; }
196: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
197: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
198: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
199: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
200: #table-example-1 tbody td:first-child::after { content: leader(". "); }
201: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
202: #table-example-1 tbody td:first-child + td { width: 10em; }
203: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
204: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
205:
206: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
207: .apple-table-examples * { font-family: "Times", serif; }
208: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
209: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
210: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
211: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
212: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
213: .apple-table-examples td { text-align: right; vertical-align: top; }
214: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
215: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
216: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
217: .apple-table-examples sup { line-height: 0; }
218:
1.671 mike 219: </style><link href="data:text/css," rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D" rel="alternate stylesheet" title="Highlight implementation requirements"><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script>
220: function getCookie(name) {
221: var params = location.search.substr(1).split("&");
222: for (var index = 0; index < params.length; index++) {
223: if (params[index] == name)
224: return "1";
225: var data = params[index].split("=");
226: if (data[0] == name)
227: return unescape(data[1]);
228: }
229: var cookies = document.cookie.split("; ");
230: for (var index = 0; index < cookies.length; index++) {
231: var data = cookies[index].split("=");
232: if (data[0] == name)
233: return unescape(data[1]);
234: }
235: return null;
236: }
237: function load(script) {
238: var e = document.createElement('script');
239: e.setAttribute('src', 'http://www.whatwg.org/specs/web-apps/current-work/' + script + '?' + encodeURIComponent(location) + '&' + encodeURIComponent(document.referrer));
240: document.body.appendChild(e);
241: }
242: function init() {
243: if (location.search == '?slow-browser')
244: return;
245: var configUI = document.createElement('div');
246: configUI.id = 'configUI';
247: document.body.appendChild(configUI);
248: // load('reviewer.js'); // would need cross-site XHR
249: if (document.getElementById('head'))
250: load('toc.js');
251: load('styler.js');
252: // load('updater.js'); // would need cross-site XHR
253: load('dfn.js');
254: // load('status.js'); // would need cross-site XHR
255: if (getCookie('profile') == '1')
256: document.getElementsByTagName('h2')[0].textContent += '; load: ' + (new Date() - loadTimer) + 'ms';
257: fixBrokenLink();
258: }
259: </script><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css">
1.2 mike 260: <script src="link-fixup.js"></script>
1.51 mike 261: <link href="microdata.html" title="5 Microdata" rel="prev">
1.2 mike 262: <link href="spec.html#contents" title="Table of contents" rel="index">
1.1 mike 263: <link href="offline.html" title="6.9 Offline Web applications" rel="next">
1.671 mike 264: </head><body onload="fixBrokenLink(); init()"><div class="head" id="head">
1.1 mike 265: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
1.183 mike 266: <h1>HTML5</h1>
1.1 mike 267: <h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2>
1.642 mike 268:
1.123 mike 269: </div><nav>
1.51 mike 270: <a href="microdata.html">← 5 Microdata</a> –
1.2 mike 271: <a href="spec.html#contents">Table of contents</a> –
1.1 mike 272: <a href="offline.html">6.9 Offline Web applications →</a>
1.687 ! mike 273: </nav><p>This is revision 1.3575.</p>
1.659 mike 274:
1.1 mike 275:
1.534 mike 276: <h2 id="browsers"><span class="secno">6 </span>Web browsers</h2><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><div class="impl">
1.1 mike 277:
278: <p>This section describes features that apply most directly to Web
1.409 mike 279: browsers. Having said that, except where specified otherwise, the
1.1 mike 280: requirements defined in this section <em>do</em> apply to all user
281: agents, whether they are Web browsers or not.</p>
282:
1.614 mike 283: </div><h3 id="windows"><span class="secno">6.1 </span>Browsing contexts</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>A <dfn id="browsing-context">browsing context</dfn> is an environment in which
1.123 mike 284: <code>Document</code> objects are presented to the user.</p><p class="note">A tab or window in a Web browser typically contains
1.159 mike 285: a <a href="#browsing-context">browsing context</a>, as does an <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code><span class="impl"> or <code><a href="obsolete.html#frame">frame</a></code>s in a
1.123 mike 286: <code><a href="obsolete.html#frameset">frameset</a></code></span>.</p><p>Each <a href="#browsing-context">browsing context</a> has a corresponding
1.364 mike 287: <code><a href="#windowproxy">WindowProxy</a></code> object.</p><p>A <a href="#browsing-context">browsing context</a> has a <a href="history.html#session-history">session
288: history</a>, which lists the <code>Document</code> objects that
289: that <a href="#browsing-context">browsing context</a> has presented, is presenting, or
290: will present. At any time, one <code>Document</code> in each
291: <a href="#browsing-context">browsing context</a> is designated the <dfn id="active-document">active
292: document</dfn>.</p><p>Each <code>Document</code> has a collection of one or more <a href="#view" title="view">views</a>.</p><p>A <dfn id="view">view</dfn> is a user agent interface tied to a particular
1.1 mike 293: media used for the presentation of a particular
294: <code>Document</code> object in some media. A view may be
295: interactive. Each view is represented by an
1.123 mike 296: <code>AbstractView</code> object. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p><p>The main <a href="#view">view</a> through which a user primarily
1.1 mike 297: interacts with a user agent is the <dfn id="default-view">default view</dfn>. The
298: <code>AbstractView</code> object that represents this view <span class="impl">must also implement the <code><a href="#window">Window</a></code> interface,
299: and</span> is referred to as the <code>Document</code>'s
300: <code><a href="#window">Window</a></code> object. <code><a href="#windowproxy">WindowProxy</a></code> objects forward
301: everything to the <a href="#active-document">active document</a>'s <a href="#default-view">default
1.123 mike 302: view</a>'s <code><a href="#window">Window</a></code> object.</p><div class="impl">
1.1 mike 303:
304: <p>The <code title="dom-document-defaultView">defaultView</code>
305: attribute on the <code>Document</code> object's
306: <code>DocumentView</code> interface must return the <a href="#browsing-context">browsing
307: context</a>'s <code><a href="#windowproxy">WindowProxy</a></code> object, not the actual
308: <code>AbstractView</code> object of the <a href="#default-view">default
1.104 mike 309: view</a>. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p>
1.1 mike 310:
1.123 mike 311: </div><p class="note">The <code title="dom-document">document</code>
1.1 mike 312: attribute of an <code>AbstractView</code> object representing a
313: <a href="#view">view</a> gives the view's corresponding
1.123 mike 314: <code>Document</code> object. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p><p class="note">In general, there is a 1-to-1 mapping from the
1.1 mike 315: <code><a href="#window">Window</a></code> object to the <code>Document</code> object. In
316: one particular case, a set of <a href="#view" title="view">views</a> can be
317: reused for the presentation of a second <code>Document</code> in the
318: same <a href="#browsing-context">browsing context</a>, such that the mapping is then
319: 2:1. This occurs when a <a href="#browsing-context">browsing context</a> is <a href="history.html#navigate" title="navigate">navigated</a> from the initial
320: <code><a href="infrastructure.html#about:blank">about:blank</a></code> <code>Document</code> to another, with
1.123 mike 321: <a href="history.html#replacement-enabled">replacement enabled</a>.</p><div class="impl">
1.1 mike 322:
323: <p>Events that use the <code>UIEvent</code> interface are related to
324: a specific <a href="#view">view</a> (the view in which the event happened);
325: when that <a href="#view">view</a> is the <a href="#default-view">default view</a>, the
326: event object's <code title="">view</code> attribute's must return
327: the <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing
328: context</a> of that <a href="#view">view</a>, not the actual
329: <code>AbstractView</code> object of the <a href="#default-view">default
1.104 mike 330: view</a>. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
1.1 mike 331:
1.123 mike 332: </div><p class="note">A typical Web browser has one obvious
1.1 mike 333: <a href="#view">view</a> per <code>Document</code>: the browser's window
334: (screen media). This is typically the <a href="#default-view">default view</a>. If
335: a page is printed, however, a second view becomes evident, that of
336: the print media. The two views always share the same underlying
337: <code>Document</code> object, but they have a different presentation
338: of that object. A speech browser might have a different
1.123 mike 339: <a href="#default-view">default view</a>, using the speech media.</p><p class="note">A <code>Document</code> does not necessarily have a
1.1 mike 340: <a href="#browsing-context">browsing context</a> associated with it. In particular,
341: data mining tools are likely to never instantiate browsing
1.123 mike 342: contexts.</p><hr><p>A <a href="#browsing-context">browsing context</a> can have a <dfn id="creator-browsing-context">creator browsing
1.1 mike 343: context</dfn>, the <a href="#browsing-context">browsing context</a> that was
1.409 mike 344: responsible for its creation. <span class="impl">Except when
345: otherwise specified, a <a href="#browsing-context">browsing context</a> has no
346: <a href="#creator-browsing-context">creator browsing context</a>.</span></p><p>If a <a href="#browsing-context">browsing context</a> <var title="">A</var> has a
1.1 mike 347: <a href="#creator-browsing-context">creator browsing context</a>, then the
348: <code>Document</code> that was the <a href="#active-document">active document</a> of
349: that <a href="#creator-browsing-context">creator browsing context</a> at the time <var title="">A</var> was created is the <dfn id="creator-document">creator
1.123 mike 350: <code>Document</code></dfn>.</p><div class="impl">
1.1 mike 351:
352: <p>When a <a href="#browsing-context">browsing context</a> is first created, it must be
353: created with a single <code>Document</code> in its session history,
354: whose <a href="dom.html#the-document-s-address" title="the document's address">address</a> is
355: <code><a href="infrastructure.html#about:blank">about:blank</a></code>, which is marked as being an <a href="dom.html#html-documents" title="HTML documents">HTML document</a>, and whose <a href="dom.html#document-s-character-encoding" title="document's character encoding">character encoding</a> is
356: UTF-8. The <code>Document</code> must have a single child
1.159 mike 357: <code><a href="semantics.html#the-html-element-0">html</a></code> node, which itself has a single child
358: <code><a href="semantics.html#the-body-element-0">body</a></code> node.</p>
1.1 mike 359:
360: <p class="note">If the <a href="#browsing-context">browsing context</a> is created
361: specifically to be immediately navigated, then that initial
362: navigation will have <a href="history.html#replacement-enabled">replacement enabled</a>.</p>
363:
1.159 mike 364: <p id="about-blank-origin">The <a href="#origin">origin</a> of the
1.1 mike 365: <code><a href="infrastructure.html#about:blank">about:blank</a></code> <code>Document</code> is set when the
366: <code>Document</code> is created. If the new <a href="#browsing-context">browsing
367: context</a> has a <a href="#creator-browsing-context">creator browsing context</a>, then the
1.159 mike 368: <a href="#origin">origin</a> of the <code><a href="infrastructure.html#about:blank">about:blank</a></code>
369: <code>Document</code> is the <a href="#origin">origin</a> of the
1.1 mike 370: <a href="#creator-document">creator <code>Document</code></a>. Otherwise, the
1.159 mike 371: <a href="#origin">origin</a> of the <code><a href="infrastructure.html#about:blank">about:blank</a></code>
1.1 mike 372: <code>Document</code> is a globally unique identifier assigned when
373: the new <a href="#browsing-context">browsing context</a> is created.</p>
374:
1.614 mike 375: </div><h4 id="nested-browsing-contexts"><span class="secno">6.1.1 </span>Nested browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>Certain elements (for example, <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code> elements) can
1.1 mike 376: instantiate further <a href="#browsing-context" title="browsing context">browsing
377: contexts</a>. These are called <dfn id="nested-browsing-context" title="nested browsing
378: context">nested browsing contexts</dfn>. If a browsing context <var title="">P</var> has an element <var title="">E</var> in one of its
379: <code>Document</code>s <var title="">D</var> that nests another
380: browsing context <var title="">C</var> inside it, then <var title="">P</var> is said to be the <dfn id="parent-browsing-context">parent browsing
381: context</dfn> of <var title="">C</var>, <var title="">C</var> is
382: said to be a <dfn id="child-browsing-context">child browsing context</dfn> of <var title="">P</var>, <var title="">C</var> is said to be <dfn id="browsing-context-nested-through" title="browsing context nested through">nested through</dfn> <var title="">D</var>, and <var title="">E</var> is said to be the
1.123 mike 383: <dfn id="browsing-context-container">browsing context container</dfn> of <var title="">C</var>.</p><p>A browsing context <var title="">A</var> is said to be an
1.1 mike 384: ancestor of a browsing context <var title="">B</var> if there exists
385: a browsing context <var title="">A'</var> that is a <a href="#child-browsing-context">child
386: browsing context</a> of <var title="">A</var> and that is itself
387: an ancestor of <var title="">B</var>, or if there is a browsing
388: context <var title="">P</var> that is a <a href="#child-browsing-context">child browsing
389: context</a> of <var title="">A</var> and that is the <a href="#parent-browsing-context">parent
1.123 mike 390: browsing context</a> of <var title="">B</var>.</p><p>The browsing context with no <a href="#parent-browsing-context">parent browsing context</a>
1.1 mike 391: is the <dfn id="top-level-browsing-context">top-level browsing context</dfn> of all the browsing
392: contexts <a href="#nested-browsing-context" title="nested browsing context">nested</a> within
393: it (either directly or indirectly through other nested browsing
1.123 mike 394: contexts).</p><p>The transitive closure of <a href="#parent-browsing-context" title="parent browsing
1.1 mike 395: context">parent browsing contexts</a> for a <a href="#nested-browsing-context">nested browsing
396: context</a> gives the list of <dfn id="ancestor-browsing-context" title="ancestor browsing
1.123 mike 397: context">ancestor browsing contexts</dfn>.</p><p>A <code>Document</code> is said to be <dfn id="fully-active">fully active</dfn>
1.1 mike 398: when it is the <a href="#active-document">active document</a> of its <a href="#browsing-context">browsing
399: context</a>, and either its browsing context is a <a href="#top-level-browsing-context">top-level
400: browsing context</a>, or the <code>Document</code> <a href="#browsing-context-nested-through" title="browsing context nested through">through which</a> that
401: browsing context is <a href="#nested-browsing-context" title="nested browsing
1.123 mike 402: context">nested</a> is itself <a href="#fully-active">fully active</a>.</p><p>Because they are nested through an element, <a href="#child-browsing-context" title="child
1.1 mike 403: browsing context">child browsing contexts</a> are always tied to
404: a specific <code>Document</code> in their <a href="#parent-browsing-context">parent browsing
405: context</a>. User agents must not allow the user to interact with
406: <a href="#child-browsing-context" title="child browsing context">child browsing contexts</a>
407: of elements that are in <code>Document</code>s that are not
1.159 mike 408: themselves <a href="#fully-active">fully active</a>.</p><p>A <a href="#nested-browsing-context">nested browsing context</a> can have a <a href="text-level-semantics.html#seamless-browsing-context-flag">seamless
1.1 mike 409: browsing context flag</a> set, if it is embedded through an
1.614 mike 410: <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code> element with a <code title="attr-iframe-seamless"><a href="text-level-semantics.html#attr-iframe-seamless">seamless</a></code> attribute.</p><h5 id="navigating-nested-browsing-contexts-in-the-dom"><span class="secno">6.1.1.1 </span>Navigating nested browsing contexts in the DOM</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-top"><a href="#dom-top">top</a></code></dt>
1.1 mike 411:
412: <dd>
413:
414: <p>Returns the <code><a href="#windowproxy">WindowProxy</a></code> for the <a href="#top-level-browsing-context">top-level browsing context</a>.</p>
415:
416: </dd>
417:
418: <dt><var title="">window</var> . <code title="dom-parent"><a href="#dom-parent">parent</a></code></dt>
419:
420: <dd>
421:
422: <p>Returns the <code><a href="#windowproxy">WindowProxy</a></code> for the <a href="#parent-browsing-context">parent browsing context</a>.</p>
423:
424: </dd>
425:
426: <dt><var title="">window</var> . <code title="dom-frameElement"><a href="#dom-frameelement">frameElement</a></code></dt>
427:
428: <dd>
429:
430: <p>Returns the <code>Element</code> for the <a href="#browsing-context-container">browsing context container</a>.</p>
431:
432: <p>Returns null if there isn't one.</p>
433:
434: <p>Throws a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception in cross-origin situations.</p>
435:
436: </dd>
437:
438: </dl><div class="impl">
439:
1.192 mike 440: <p>The <dfn id="dom-top" title="dom-top"><code>top</code></dfn> IDL attribute on
1.1 mike 441: the <code><a href="#window">Window</a></code> object of a <code>Document</code> in a
442: <a href="#browsing-context">browsing context</a> <var title="">b</var> must return the
443: <code><a href="#windowproxy">WindowProxy</a></code> object of its <a href="#top-level-browsing-context">top-level browsing
444: context</a> (which would be its own <code><a href="#windowproxy">WindowProxy</a></code>
445: object if it was a <a href="#top-level-browsing-context">top-level browsing context</a>
446: itself).</p>
447:
1.192 mike 448: <p>The <dfn id="dom-parent" title="dom-parent"><code>parent</code></dfn> IDL
1.1 mike 449: attribute on the <code><a href="#window">Window</a></code> object of a
450: <code>Document</code> in a <a href="#browsing-context">browsing context</a> <var title="">b</var> must return the <code><a href="#windowproxy">WindowProxy</a></code> object of
451: the <a href="#parent-browsing-context">parent browsing context</a>, if there is one (i.e. if
452: <var title="">b</var> is a <a href="#child-browsing-context">child browsing context</a>), or
453: the <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing
454: context</a> <var title="">b</var> itself, otherwise (i.e. if it
455: is a <a href="#top-level-browsing-context">top-level browsing context</a>).</p>
456:
457: <p>The <dfn id="dom-frameelement" title="dom-frameElement"><code>frameElement</code></dfn>
1.192 mike 458: IDL attribute on the <code><a href="#window">Window</a></code> object of a
1.1 mike 459: <code>Document</code> <var title="">d</var>, on getting, must run
460: the following algorithm:</p>
461:
462: <ol><li><p>If <var title="">d</var> is not a <code>Document</code> in a
463: <a href="#child-browsing-context">child browsing context</a>, return null and abort these
464: steps.</p></li>
465:
466: <li><p>If the <a href="#parent-browsing-context">parent browsing context</a>'s <a href="#active-document">active
1.582 mike 467: document</a> does not have the <a href="#same-origin" title="same
468: origin">same</a> <a href="#effective-script-origin">effective script origin</a> as the
469: <a href="#first-script">first script</a>, then throw a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code>
470: exception.</p></li>
1.1 mike 471:
472: <li><p>Otherwise, return the <a href="#browsing-context-container">browsing context
473: container</a> for <var title="">b</var>.</p></li>
474:
1.614 mike 475: </ol></div><h4 id="auxiliary-browsing-contexts"><span class="secno">6.1.2 </span>Auxiliary browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>It is possible to create new browsing contexts that are related
1.174 mike 476: to a <a href="#top-level-browsing-context">top-level browsing context</a> without being nested
1.1 mike 477: through an element. Such browsing contexts are called <dfn id="auxiliary-browsing-context" title="auxiliary browsing context">auxiliary browsing
478: contexts</dfn>. Auxiliary browsing contexts are always <a href="#top-level-browsing-context" title="top-level browsing context">top-level browsing
1.123 mike 479: contexts</a>.</p><p>An <a href="#auxiliary-browsing-context">auxiliary browsing context</a> has an <dfn id="opener-browsing-context">opener
1.1 mike 480: browsing context</dfn>, which is the <a href="#browsing-context">browsing context</a>
481: from which the <a href="#auxiliary-browsing-context">auxiliary browsing context</a> was created,
482: and it has a <dfn id="furthest-ancestor-browsing-context">furthest ancestor browsing context</dfn>, which is
483: the <a href="#top-level-browsing-context">top-level browsing context</a> of the <a href="#opener-browsing-context">opener
484: browsing context</a> when the <a href="#auxiliary-browsing-context">auxiliary browsing
1.614 mike 485: context</a> was created.</p><h5 id="navigating-auxiliary-browsing-contexts-in-the-dom"><span class="secno">6.1.2.1 </span>Navigating auxiliary browsing contexts in the DOM</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>The <dfn id="dom-opener" title="dom-opener"><code>opener</code></dfn> IDL
1.1 mike 486: attribute on the <code><a href="#window">Window</a></code> object must return the
487: <code><a href="#windowproxy">WindowProxy</a></code> object of the <a href="#browsing-context">browsing context</a>
488: from which the current <a href="#browsing-context">browsing context</a> was created
489: (its <a href="#opener-browsing-context">opener browsing context</a>), if there is one and it
1.614 mike 490: is still available.</p><h4 id="secondary-browsing-contexts"><span class="secno">6.1.3 </span>Secondary browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>User agents may support <dfn id="secondary-browsing-context" title="secondary browsing
1.1 mike 491: context">secondary browsing contexts</dfn>, which are <a href="#browsing-context" title="browsing context">browsing contexts</a> that form part of
1.123 mike 492: the user agent's interface, apart from the main content area.</p><div class="impl">
1.1 mike 493:
1.614 mike 494: <h4 id="security-1"><span class="secno">6.1.4 </span>Security</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 495:
496: <p>A <a href="#browsing-context">browsing context</a> <var title="">A</var> is
497: <dfn id="allowed-to-navigate">allowed to navigate</dfn> a second <a href="#browsing-context">browsing
498: context</a> <var title="">B</var> if one of the following
499: conditions is true:</p>
500:
1.159 mike 501: <ul><li>Either the <a href="#origin">origin</a> of the <a href="#active-document">active
1.1 mike 502: document</a> of <var title="">A</var> is the <a href="#same-origin" title="same
1.159 mike 503: origin">same</a> as the <a href="#origin">origin</a> of the <a href="#active-document">active
1.1 mike 504: document</a> of <var title="">B</var>, or</li>
505:
506: <li>The browsing context <var title="">A</var> is a <a href="#nested-browsing-context">nested
507: browsing context</a> and its <a href="#top-level-browsing-context">top-level browsing
508: context</a> is <var title="">B</var>, or</li>
509:
510: <li>The browsing context <var title="">B</var> is an
511: <a href="#auxiliary-browsing-context">auxiliary browsing context</a> and <var title="">A</var>
512: is <a href="#allowed-to-navigate">allowed to navigate</a> <var title="">B</var>'s
513: <a href="#opener-browsing-context">opener browsing context</a>, or</li>
514:
515: <li>The browsing context <var title="">B</var> is not a
516: <a href="#top-level-browsing-context">top-level browsing context</a>, but there exists an
517: <a href="#ancestor-browsing-context">ancestor browsing context</a> of <var title="">B</var>
518: whose <a href="#active-document">active document</a> has the <a href="#same-origin" title="same
1.159 mike 519: origin">same</a> <a href="#origin">origin</a> as the <a href="#active-document">active
1.1 mike 520: document</a> of <var title="">A</var> (possibly in fact being
521: <var title="">A</var> itself).</li>
522:
1.414 mike 523: </ul><hr><p>An element has a <dfn id="browsing-context-scope-origin">browsing context scope origin</dfn> if its
524: <code>Document</code>'s <a href="#browsing-context">browsing context</a> is a
525: <a href="#top-level-browsing-context">top-level browsing context</a> or if all of its
526: <code>Document</code>'s <a href="#ancestor-browsing-context" title="ancestor browsing
527: context">ancestor browsing contexts</a> all have <a href="#active-document" title="active document">active documents</a> whose
528: <a href="#origin">origin</a> are the <a href="#same-origin">same origin</a> as the
529: element's <code>Document</code>'s <a href="#origin">origin</a>. If an element
530: has a <a href="#browsing-context-scope-origin">browsing context scope origin</a>, then its value is
531: the <a href="#origin">origin</a> of the element's <code>Document</code>.</p>
532:
533: </div><div class="impl">
1.1 mike 534:
1.614 mike 535: <h4 id="groupings-of-browsing-contexts"><span class="secno">6.1.5 </span>Groupings of browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 536:
537: <p>Each <a href="#browsing-context">browsing context</a> is defined as having a list of
538: zero or more <dfn id="directly-reachable-browsing-contexts">directly reachable browsing contexts</dfn>. These
539: are:</p>
540:
541: <ul><li>All the <a href="#browsing-context">browsing context</a>'s <a href="#child-browsing-context" title="child
542: browsing context">child browsing contexts</a>.</li>
543:
544: <li>The <a href="#browsing-context">browsing context</a>'s <a href="#parent-browsing-context">parent browsing
545: context</a>.</li>
546:
547: <li>All the <a href="#browsing-context" title="browsing context">browsing contexts</a>
548: that have the <a href="#browsing-context">browsing context</a> as their <a href="#opener-browsing-context">opener
549: browsing context</a>.</li>
550:
551: <li>The <a href="#browsing-context">browsing context</a>'s <a href="#opener-browsing-context">opener browsing
552: context</a>.</li>
553:
554: </ul><p>The transitive closure of all the <a href="#browsing-context" title="browsing
555: context">browsing contexts</a> that are <a href="#directly-reachable-browsing-contexts">directly reachable
556: browsing contexts</a> forms a <dfn id="unit-of-related-browsing-contexts">unit of related browsing
557: contexts</dfn>.</p>
558:
559: <p>Each <a href="#unit-of-related-browsing-contexts">unit of related browsing contexts</a> is then
560: further divided into the smallest number of groups such that every
561: member of each group has an <a href="#effective-script-origin">effective script origin</a>
562: that, through appropriate manipulation of the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute, could
563: be made to be the same as other members of the group, but could not
564: be made the same as members of any other group. Each such group is a
565: <dfn id="unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</dfn>.</p>
566:
567: <p>Each <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing
568: contexts</a> can have a <dfn id="first-script">first script</dfn> which is used to
569: obtain, amongst other things, the <a href="#script-s-base-url">script's base URL</a> to
570: <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolve</a> relative <a href="infrastructure.html#url" title="URL">URLs</a> used in scripts running in that <a href="#unit-of-related-similar-origin-browsing-contexts">unit
571: of related similar-origin browsing contexts</a>. Initially, there
572: is no <a href="#first-script">first script</a>.</p>
573:
1.213 mike 574: <p class="note">There is at most one <a href="#event-loop">event loop</a> per
575: <a href="#unit-of-related-similar-origin-browsing-contexts">unit of related similar-origin browsing contexts</a>.</p>
576:
1.614 mike 577: </div><h4 id="browsing-context-names"><span class="secno">6.1.6 </span>Browsing context names</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>Browsing contexts can have a <dfn id="browsing-context-name">browsing context name</dfn>. By
1.123 mike 578: default, a browsing context has no name (its name is not set).</p><p>A <dfn id="valid-browsing-context-name">valid browsing context name</dfn> is any string with at
1.1 mike 579: least one character that does not start with a U+005F LOW LINE
580: character. (Names starting with an underscore are reserved for
1.123 mike 581: special keywords.)</p><p>A <dfn id="valid-browsing-context-name-or-keyword">valid browsing context name or keyword</dfn> is any string
1.1 mike 582: that is either a <a href="#valid-browsing-context-name">valid browsing context name</a> or that is
1.123 mike 583: an <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for one of: <code title="">_blank</code>, <code title="">_self</code>, <code title="">_parent</code>, or <code title="">_top</code>.</p><div class="impl">
1.1 mike 584:
585: <p><dfn id="the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">The rules for choosing a browsing context given a browsing
586: context name</dfn> are as follows. The rules assume that they are
587: being applied in the context of a <a href="#browsing-context">browsing context</a>.</p>
588:
589: <ol><li><p>If the given browsing context name is the empty string or
590: <code title="">_self</code>, then the chosen browsing context must
591: be the current one.</p></li>
592:
593: <li><p>If the given browsing context name is <code title="">_parent</code>, then the chosen browsing context must be
594: the <a href="#parent-browsing-context"><em>parent</em> browsing context</a> of the current
595: one, unless there isn't one, in which case the chosen browsing
596: context must be the current browsing context.</p></li>
597:
598: <li><p>If the given browsing context name is <code title="">_top</code>, then the chosen browsing context must be the
599: most <a href="#top-level-browsing-context">top-level browsing context</a> of the current
600: one.</p></li>
601:
602: <li>
603:
604: <p>If the given browsing context name is not <code title="">_blank</code> and there exists a browsing context whose
605: <a href="#browsing-context-name" title="browsing context name">name</a> is the same as the
606: given browsing context name, and the current browsing context is
607: <a href="#allowed-to-navigate">allowed to navigate</a> that browsing context, and the
608: user agent determines that the two browsing contexts are related
609: enough that it is ok if they reach each other, then that browsing
610: context must be the chosen one. If there are multiple matching
611: browsing contexts, the user agent should select one in some
612: arbitrary consistent manner, such as the most recently opened,
613: most recently focused, or more closely related.</p>
614:
615: </li>
616:
617: <li>
618:
619: <p>Otherwise, a new browsing context is being requested, and what
620: happens depends on the user agent's configuration and/or
621: abilities:</p>
622:
623: <dl><dt id="sandboxWindowOpen">If the current browsing context has
1.159 mike 624: the <a href="text-level-semantics.html#sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</a>
1.1 mike 625: set.</dt>
626:
627: <dd><p>The user agent may offer to create a new <a href="#top-level-browsing-context">top-level
628: browsing context</a> or reuse an existing <a href="#top-level-browsing-context">top-level
629: browsing context</a>. If the user picks one of those options,
630: then the designated browsing context must be the chosen one (the
631: browsing context's name isn't set to the given browsing context
632: name). Otherwise (if the user agent doesn't offer the option to
633: the user, or if the user declines to allow a browsing context to
634: be used) there must not be a chosen browsing context.</p></dd>
635:
636: <dt id="noopener">If the user agent has been configured such that
637: in this instance it will create a new browsing context, and the
638: browsing context is being requested as part of <a href="history.html#following-hyperlinks" title="following hyperlinks">following a hyperlink</a> whose
639: <a href="history.html#linkTypes">link types</a> include the <code title="rel-noreferrer"><a href="history.html#link-type-noreferrer">noreferrer</a></code> keyword</dt>
640:
641: <dd><p>A new <a href="#top-level-browsing-context">top-level browsing context</a> must be
642: created. If the given browsing context name is not <code title="">_blank</code>, then the new top-level browsing context's
643: name must be the given browsing context name (otherwise, it has
644: no name). The chosen browsing context must be this new browsing
645: context.</p>
646:
647: <p class="note">If it is immediately <a href="history.html#navigate" title="navigate">navigated</a>, then the navigation will be
648: done with <a href="history.html#replacement-enabled">replacement enabled</a>.</p></dd>
649:
650: <dt>If the user agent has been configured such that in this
651: instance it will create a new browsing context, and the <code title="rel-noreferrer"><a href="history.html#link-type-noreferrer">noreferrer</a></code> keyword doesn't
652: apply</dt>
653:
654: <dd><p>A new <a href="#auxiliary-browsing-context">auxiliary browsing context</a> must be
655: created, with the <a href="#opener-browsing-context">opener browsing context</a> being the
656: current one. If the given browsing context name is not <code title="">_blank</code>, then the new auxiliary browsing context's
657: name must be the given browsing context name (otherwise, it has
658: no name). The chosen browsing context must be this new browsing
659: context.</p>
660:
661: <p>If it is immediately <a href="history.html#navigate" title="navigate">navigated</a>,
662: then the navigation will be done with <a href="history.html#replacement-enabled">replacement
663: enabled</a>.</p></dd>
664:
665: <dt>If the user agent has been configured such that in this
666: instance it will reuse the current browsing context</dt>
667:
668: <dd><p>The chosen browsing context is the current browsing
669: context.</p></dd>
670:
671: <dt>If the user agent has been configured such that in this
672: instance it will not find a browsing context</dt>
673:
674: <dd><p>There must not be a chosen browsing context.</p></dd>
675:
676: </dl><p>User agent implementors are encouraged to provide a way for
677: users to configure the user agent to always reuse the current
678: browsing context.</p>
679:
680: </li>
681:
1.123 mike 682: </ol></div><div class="impl">
1.1 mike 683:
1.614 mike 684: <h3 id="the-windowproxy-object"><span class="secno">6.2 </span>The <code><a href="#windowproxy">WindowProxy</a></code> object</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 685:
686: <p>As mentioned earlier, each <a href="#browsing-context">browsing context</a> has a
687: <dfn id="windowproxy"><code>WindowProxy</code></dfn> object. This object is unusual
1.468 mike 688: in that all operations that would be performed on it must be
1.583 mike 689: performed on the <code><a href="#window">Window</a></code> object of the <a href="#browsing-context">browsing
1.468 mike 690: context</a>'s <a href="#active-document">active document</a> instead. It is thus
691: indistinguishable from that <code><a href="#window">Window</a></code> object in every way
692: until the <a href="#browsing-context">browsing context</a> is navigated.</p>
693:
694: <p>There is no <code><a href="#windowproxy">WindowProxy</a></code> interface object.</p>
695:
1.548 mike 696: <p class="note">The <code><a href="#windowproxy">WindowProxy</a></code> object allows scripts
697: to act as if each <a href="#browsing-context">browsing context</a> had a single
698: <code><a href="#window">Window</a></code> object, while still keeping separate
699: <code><a href="#window">Window</a></code> objects for each <code>Document</code>.</p>
700:
1.468 mike 701: <div class="example">
702:
703: <p>In the following example, the variable <var title="">x</var> is
1.580 mike 704: set to the <code><a href="#windowproxy">WindowProxy</a></code> object returned by the <code title="dom-window"><a href="#dom-window">window</a></code> accessor on the global object. All
1.468 mike 705: of the expressions following the assignment return true, because in
706: every respect, the <code><a href="#windowproxy">WindowProxy</a></code> object acts like the
707: underlying <code><a href="#window">Window</a></code> object.</p>
708:
709: <pre>var x = window;
710: x instanceof Window; // true
711: x === this; // true</pre>
712:
713: </div>
1.1 mike 714:
1.614 mike 715: </div><h3 id="the-window-object"><span class="secno">6.3 </span>The <code><a href="#window">Window</a></code> object</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><pre class="idl">[OverrideBuiltins]
1.1 mike 716: interface <dfn id="window">Window</dfn> {
717: // the current browsing context
718: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-window" title="dom-window">window</a>;
719: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-self" title="dom-self">self</a>;
720: attribute DOMString <a href="#dom-name" title="dom-name">name</a>;
721: [PutForwards=href] readonly attribute <a href="history.html#location">Location</a> <a href="history.html#dom-location" title="dom-location">location</a>;
1.159 mike 722: readonly attribute <a href="history.html#history-0">History</a> <a href="history.html#dom-history" title="dom-history">history</a>;
1.1 mike 723: readonly attribute <a href="editing.html#undomanager">UndoManager</a> <a href="editing.html#dom-undomanager" title="dom-undoManager">undoManager</a>;
724: <a href="editing.html#selection-0">Selection</a> <a href="editing.html#dom-getselection" title="dom-getSelection">getSelection</a>();
725: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-locationbar" title="dom-window-locationbar">locationbar</a>;
726: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-menubar" title="dom-window-menubar">menubar</a>;
727: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-personalbar" title="dom-window-personalbar">personalbar</a>;
728: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-scrollbars" title="dom-window-scrollbars">scrollbars</a>;
729: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-statusbar" title="dom-window-statusbar">statusbar</a>;
730: [Replaceable] readonly attribute <a href="#barprop">BarProp</a> <a href="#dom-window-toolbar" title="dom-window-toolbar">toolbar</a>;<!--
731: [Replaceable] readonly attribute <span>BarProp</span> <span title="dom-window-directories">directories</span>; // legacy (Gecko-only) -->
732: void <a href="#dom-window-close" title="dom-window-close">close</a>();
733: void <a href="editing.html#dom-window-focus" title="dom-window-focus">focus</a>();
734: void <a href="editing.html#dom-window-blur" title="dom-window-blur">blur</a>();
735:
736: // other browsing contexts
1.190 mike 737: [Replaceable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-frames" title="dom-frames">frames</a>;
738: [Replaceable] readonly attribute unsigned long <a href="#dom-length" title="dom-length">length</a>;
1.1 mike 739: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-top" title="dom-top">top</a>;
740: [Replaceable] readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-opener" title="dom-opener">opener</a>;
741: readonly attribute <a href="#windowproxy">WindowProxy</a> <a href="#dom-parent" title="dom-parent">parent</a>;
742: readonly attribute <span>Element</span> <a href="#dom-frameelement" title="dom-frameElement">frameElement</a>;
1.401 mike 743: <a href="#windowproxy">WindowProxy</a> <a href="#dom-open" title="dom-open">open</a>(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace);
1.87 mike 744: <a href="#dom-window-item" title="dom-window-item">getter</a> <a href="#windowproxy">WindowProxy</a> (in unsigned long index);
745: <a href="#dom-window-nameditem" title="dom-window-namedItem">getter</a> <a href="#windowproxy">WindowProxy</a> (in DOMString name);
1.1 mike 746:
747: // the user agent
748: readonly attribute <a href="#navigator">Navigator</a> <a href="#dom-navigator" title="dom-navigator">navigator</a>; <!-- IE also has window.clientInformation === window.navigator -->
749: readonly attribute <a href="offline.html#applicationcache">ApplicationCache</a> <a href="offline.html#dom-applicationcache" title="dom-applicationCache">applicationCache</a>;
750:
751: // user prompts
752: void <a href="#dom-alert" title="dom-alert">alert</a>(in DOMString message);
753: boolean <a href="#dom-confirm" title="dom-confirm">confirm</a>(in DOMString message);
1.401 mike 754: DOMString <a href="#dom-prompt" title="dom-prompt">prompt</a>(in DOMString message, in optional DOMString default);
1.1 mike 755: void <a href="#dom-print" title="dom-print">print</a>();
1.401 mike 756: any <a href="#dom-showmodaldialog" title="dom-showModalDialog">showModalDialog</a>(in DOMString url, in optional any argument<!--, in optional DOMString features-->);
1.1 mike 757:
758: // <a href="comms.html#crossDocumentMessages">cross-document messaging</a>
759: void <a href="comms.html#dom-window-postmessage-2" title="dom-window-postMessage-2">postMessage</a>(in any message, in DOMString targetOrigin);
760: void <a href="comms.html#dom-window-postmessage-3" title="dom-window-postMessage-3">postMessage</a>(in any message, in <a href="comms.html#messageportarray">MessagePortArray</a> ports, in DOMString targetOrigin);
761:
1.192 mike 762: // <a href="#event-handler-idl-attributes">event handler IDL attributes</a>
1.1 mike 763: attribute <a href="#function">Function</a> <a href="#handler-onabort" title="handler-onabort">onabort</a>;
764: attribute <a href="#function">Function</a> <a href="#handler-window-onafterprint" title="handler-window-onafterprint">onafterprint</a>;
765: attribute <a href="#function">Function</a> <a href="#handler-window-onbeforeprint" title="handler-window-onbeforeprint">onbeforeprint</a>;
766: attribute <a href="#function">Function</a> <a href="#handler-window-onbeforeunload" title="handler-window-onbeforeunload">onbeforeunload</a>;
767: attribute <a href="#function">Function</a> <a href="#handler-window-onblur" title="handler-window-onblur">onblur</a>;
768: attribute <a href="#function">Function</a> <a href="#handler-oncanplay" title="handler-oncanplay">oncanplay</a>;
769: attribute <a href="#function">Function</a> <a href="#handler-oncanplaythrough" title="handler-oncanplaythrough">oncanplaythrough</a>;
770: attribute <a href="#function">Function</a> <a href="#handler-onchange" title="handler-onchange">onchange</a>;
771: attribute <a href="#function">Function</a> <a href="#handler-onclick" title="handler-onclick">onclick</a>;
772: attribute <a href="#function">Function</a> <a href="#handler-oncontextmenu" title="handler-oncontextmenu">oncontextmenu</a>;
773: attribute <a href="#function">Function</a> <a href="#handler-ondblclick" title="handler-ondblclick">ondblclick</a>;
774: attribute <a href="#function">Function</a> <a href="#handler-ondrag" title="handler-ondrag">ondrag</a>;
775: attribute <a href="#function">Function</a> <a href="#handler-ondragend" title="handler-ondragend">ondragend</a>;
776: attribute <a href="#function">Function</a> <a href="#handler-ondragenter" title="handler-ondragenter">ondragenter</a>;
777: attribute <a href="#function">Function</a> <a href="#handler-ondragleave" title="handler-ondragleave">ondragleave</a>;
778: attribute <a href="#function">Function</a> <a href="#handler-ondragover" title="handler-ondragover">ondragover</a>;
779: attribute <a href="#function">Function</a> <a href="#handler-ondragstart" title="handler-ondragstart">ondragstart</a>;
780: attribute <a href="#function">Function</a> <a href="#handler-ondrop" title="handler-ondrop">ondrop</a>;
781: attribute <a href="#function">Function</a> <a href="#handler-ondurationchange" title="handler-ondurationchange">ondurationchange</a>;
782: attribute <a href="#function">Function</a> <a href="#handler-onemptied" title="handler-onemptied">onemptied</a>;
783: attribute <a href="#function">Function</a> <a href="#handler-onended" title="handler-onended">onended</a>;
784: attribute <a href="#function">Function</a> <a href="#handler-window-onerror" title="handler-window-onerror">onerror</a>;
785: attribute <a href="#function">Function</a> <a href="#handler-window-onfocus" title="handler-window-onfocus">onfocus</a>;
786: attribute <a href="#function">Function</a> <a href="#handler-onformchange" title="handler-onformchange">onformchange</a>;
787: attribute <a href="#function">Function</a> <a href="#handler-onforminput" title="handler-onforminput">onforminput</a>;
788: attribute <a href="#function">Function</a> <a href="#handler-window-onhashchange" title="handler-window-onhashchange">onhashchange</a>;
789: attribute <a href="#function">Function</a> <a href="#handler-oninput" title="handler-oninput">oninput</a>;
790: attribute <a href="#function">Function</a> <a href="#handler-oninvalid" title="handler-oninvalid">oninvalid</a>;
791: attribute <a href="#function">Function</a> <a href="#handler-onkeydown" title="handler-onkeydown">onkeydown</a>;
792: attribute <a href="#function">Function</a> <a href="#handler-onkeypress" title="handler-onkeypress">onkeypress</a>;
793: attribute <a href="#function">Function</a> <a href="#handler-onkeyup" title="handler-onkeyup">onkeyup</a>;
794: attribute <a href="#function">Function</a> <a href="#handler-window-onload" title="handler-window-onload">onload</a>;
795: attribute <a href="#function">Function</a> <a href="#handler-onloadeddata" title="handler-onloadeddata">onloadeddata</a>;
796: attribute <a href="#function">Function</a> <a href="#handler-onloadedmetadata" title="handler-onloadedmetadata">onloadedmetadata</a>;
797: attribute <a href="#function">Function</a> <a href="#handler-onloadstart" title="handler-onloadstart">onloadstart</a>;
798: attribute <a href="#function">Function</a> <a href="#handler-window-onmessage" title="handler-window-onmessage">onmessage</a>;
799: attribute <a href="#function">Function</a> <a href="#handler-onmousedown" title="handler-onmousedown">onmousedown</a>;
800: attribute <a href="#function">Function</a> <a href="#handler-onmousemove" title="handler-onmousemove">onmousemove</a>;
801: attribute <a href="#function">Function</a> <a href="#handler-onmouseout" title="handler-onmouseout">onmouseout</a>;
802: attribute <a href="#function">Function</a> <a href="#handler-onmouseover" title="handler-onmouseover">onmouseover</a>;
803: attribute <a href="#function">Function</a> <a href="#handler-onmouseup" title="handler-onmouseup">onmouseup</a>;
804: attribute <a href="#function">Function</a> <a href="#handler-onmousewheel" title="handler-onmousewheel">onmousewheel</a>;
805: attribute <a href="#function">Function</a> <a href="#handler-window-onoffline" title="handler-window-onoffline">onoffline</a>;
806: attribute <a href="#function">Function</a> <a href="#handler-window-ononline" title="handler-window-ononline">ononline</a>;
807: attribute <a href="#function">Function</a> <a href="#handler-onpause" title="handler-onpause">onpause</a>;
808: attribute <a href="#function">Function</a> <a href="#handler-onplay" title="handler-onplay">onplay</a>;
809: attribute <a href="#function">Function</a> <a href="#handler-onplaying" title="handler-onplaying">onplaying</a>;
1.569 mike 810: attribute <a href="#function">Function</a> <a href="#handler-window-onpagehide" title="handler-window-onpagehide">onpagehide</a>;
811: attribute <a href="#function">Function</a> <a href="#handler-window-onpageshow" title="handler-window-onpageshow">onpageshow</a>;
1.1 mike 812: attribute <a href="#function">Function</a> <a href="#handler-window-onpopstate" title="handler-window-onpopstate">onpopstate</a>;
813: attribute <a href="#function">Function</a> <a href="#handler-onprogress" title="handler-onprogress">onprogress</a>;
814: attribute <a href="#function">Function</a> <a href="#handler-onratechange" title="handler-onratechange">onratechange</a>;
815: attribute <a href="#function">Function</a> <a href="#handler-onreadystatechange" title="handler-onreadystatechange">onreadystatechange</a>;
816: attribute <a href="#function">Function</a> <a href="#handler-window-onredo" title="handler-window-onredo">onredo</a>;
817: attribute <a href="#function">Function</a> <a href="#handler-window-onresize" title="handler-window-onresize">onresize</a>;
818: attribute <a href="#function">Function</a> <a href="#handler-onscroll" title="handler-onscroll">onscroll</a>;
819: attribute <a href="#function">Function</a> <a href="#handler-onseeked" title="handler-onseeked">onseeked</a>;
820: attribute <a href="#function">Function</a> <a href="#handler-onseeking" title="handler-onseeking">onseeking</a>;
821: attribute <a href="#function">Function</a> <a href="#handler-onselect" title="handler-onselect">onselect</a>;
822: attribute <a href="#function">Function</a> <a href="#handler-onshow" title="handler-onshow">onshow</a>;
823: attribute <a href="#function">Function</a> <a href="#handler-onstalled" title="handler-onstalled">onstalled</a>;
824: attribute <a href="#function">Function</a> <a href="#handler-window-onstorage" title="handler-window-onstorage">onstorage</a>;
825: attribute <a href="#function">Function</a> <a href="#handler-onsubmit" title="handler-onsubmit">onsubmit</a>;
826: attribute <a href="#function">Function</a> <a href="#handler-onsuspend" title="handler-onsuspend">onsuspend</a>;
827: attribute <a href="#function">Function</a> <a href="#handler-ontimeupdate" title="handler-ontimeupdate">ontimeupdate</a>;
828: attribute <a href="#function">Function</a> <a href="#handler-window-onundo" title="handler-window-onundo">onundo</a>;
829: attribute <a href="#function">Function</a> <a href="#handler-window-onunload" title="handler-window-onunload">onunload</a>;
830: attribute <a href="#function">Function</a> <a href="#handler-onvolumechange" title="handler-onvolumechange">onvolumechange</a>;
831: attribute <a href="#function">Function</a> <a href="#handler-onwaiting" title="handler-onwaiting">onwaiting</a>;
1.343 mike 832: };
1.421 mike 833: <a href="#window">Window</a> implements <span>EventTarget</span>;</pre><!-- for more features to add here, look here:
1.1 mike 834: http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_window.asp
835: http://www.mozilla.org/docs/dom/domref/dom_window_ref.html
836: http://lxr.mozilla.org/mozilla/source/dom/public/idl/base/nsIDOMWindow.idl - scrollBy, etc
837: http://lxr.mozilla.org/mozilla/source/dom/public/idl/base/nsIDOMWindowInternal.idl - DOM level 0
1.123 mike 838: --><dl class="domintro"><dt><var title="">window</var> . <code title="dom-window"><a href="#dom-window">window</a></code></dt>
1.1 mike 839: <dt><var title="">window</var> . <code title="dom-frames"><a href="#dom-frames">frames</a></code></dt>
840: <dt><var title="">window</var> . <code title="dom-self"><a href="#dom-self">self</a></code></dt>
841:
842: <dd>
843:
844: <p>These attributes all return <var title="">window</var>.</p>
845:
846: </dd>
847:
848: </dl><div class="impl">
849:
1.192 mike 850: <p>The <dfn id="dom-window" title="dom-window"><code>window</code></dfn>, <dfn id="dom-frames" title="dom-frames"><code>frames</code></dfn>, and <dfn id="dom-self" title="dom-self"><code>self</code></dfn> IDL attributes must all
1.1 mike 851: return the <code><a href="#window">Window</a></code> object's <a href="#browsing-context">browsing
852: context</a>'s <code><a href="#windowproxy">WindowProxy</a></code> object.</p>
853:
1.123 mike 854: </div><div class="impl">
1.1 mike 855:
1.614 mike 856: <h4 id="security-2"><span class="secno">6.3.1 </span>Security</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 857:
858: <p>User agents must raise a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception
859: whenever any of the members of a <code><a href="#window">Window</a></code> object are
860: accessed by scripts whose <a href="#effective-script-origin">effective script origin</a> is
861: not the same as the <code><a href="#window">Window</a></code> object's
862: <code>Document</code>'s <a href="#effective-script-origin">effective script origin</a>, with
863: the following exceptions:</p>
864:
865: <ul><li>The <code title="dom-location"><a href="history.html#dom-location">location</a></code> object
866:
867: </li><li>The <code title="dom-window-postMessage-2"><a href="comms.html#dom-window-postmessage-2">postMessage()</a></code>
868: method with two arguments
869:
870: </li><li>The <code title="dom-window-postMessage-3"><a href="comms.html#dom-window-postmessage-3">postMessage()</a></code>
871: method with three arguments
872:
873: </li><li>The <code title="dom-frames"><a href="#dom-frames">frames</a></code> attribute
874:
875: </li><li>The <a href="#dynamic-nested-browsing-context-properties">dynamic nested browsing context properties</a>
876:
1.138 mike 877: </li></ul><p>When a script whose <a href="#effective-script-origin">effective script origin</a> is not
878: the same as the <code><a href="#window">Window</a></code> object's <code>Document</code>'s
879: <a href="#effective-script-origin">effective script origin</a> attempts to access that
880: <code><a href="#window">Window</a></code> object's methods or attributes, the user agent
881: must act as if any changes to the <code><a href="#window">Window</a></code> object's
882: properties, getters, setters, etc, were not present.</p>
883:
884: <p>For members that return objects (including function objects),
885: each distinct <a href="#effective-script-origin">effective script origin</a> that is not the
886: same as the <code><a href="#window">Window</a></code> object's <code>Document</code>'s
887: <a href="#effective-script-origin">effective script origin</a> must be provided with a
888: separate set of objects. These objects must have the prototype chain
889: appropriate for the script for which the objects are created (not
890: those that would be appropriate for scripts whose <a href="#script-s-global-object">script's
891: global object</a> is the <code><a href="#window">Window</a></code> object in
892: question).</p>
893:
894: <div class="example">
895:
896: <p>For instance, if two frames containing <code>Document</code>s
1.159 mike 897: from different <a href="#origin" title="origin">origins</a> access the same
1.138 mike 898: <code><a href="#window">Window</a></code> object's <code title="dom-window-postMessage-2"><a href="comms.html#dom-window-postmessage-2">postMessage()</a></code> method, they
899: will get distinct objects that are not equal.</p>
900:
901: </div>
1.1 mike 902:
1.614 mike 903: </div><h4 id="apis-for-creating-and-navigating-browsing-contexts-by-name"><span class="secno">6.3.2 </span>APIs for creating and navigating browsing contexts by name</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> = <var title="">window</var> . <code title="dom-open"><a href="#dom-open">open</a></code>( [ <var title="">url</var> [, <var title="">target</var> [, <var title="">features</var> [, <var title="">replace</var> ] ] ] ] )</dt>
1.1 mike 904:
905: <dd>
906:
907: <p>Opens a window to show <var title="">url</var> (defaults to
908: <code><a href="infrastructure.html#about:blank">about:blank</a></code>), and returns it. The <var title="">target</var> argument gives the name of the new
909: window. If a window exists with that name already, it is
910: reused. The <var title="">replace</var> attribute, if true, means
911: that whatever page is currently open in that window will be
912: removed from the window's session history. The <var title="">features</var> argument is ignored.</p>
913:
914: </dd>
915:
916: <dt><var title="">window</var> . <code title="dom-name"><a href="#dom-name">name</a></code> [ = <var title="">value</var> ]</dt>
917:
918: <dd>
919:
920: <p>Returns the name of the window.</p>
921:
922: <p>Can be set, to change the name.</p>
923:
924: </dd>
925:
926: <dt><var title="">window</var> . <code title="dom-close">close</code>()</dt>
927:
928: <dd>
929:
930: <p>Closes the window.</p>
931:
932: </dd>
933:
934: </dl><div class="impl">
935:
936: <p>The <dfn id="dom-open" title="dom-open"><code>open()</code></dfn> method on
937: <code><a href="#window">Window</a></code> objects provides a mechanism for <a href="history.html#navigate" title="navigate">navigating</a> an existing <a href="#browsing-context">browsing
938: context</a> or opening and navigating an <a href="#auxiliary-browsing-context">auxiliary browsing
939: context</a>.</p>
940:
941: <p>The method has four arguments, though they are all optional.</p>
942:
943: <p>The first argument, <var title="">url</var>, must be a
944: <a href="infrastructure.html#valid-url">valid URL</a> for a page to load in the browsing
945: context. If no arguments are provided, or if the first argument is
946: the empty string, then the <var title="">url</var> argument defaults
947: to "<code><a href="infrastructure.html#about:blank">about:blank</a></code>". The argument must be <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolved</a> to an <a href="infrastructure.html#absolute-url">absolute
948: URL</a> (or an error), relative to the <a href="#first-script">first
949: script</a>'s <a href="#script-s-base-url" title="script's base URL">base URL</a>,
950: when the method is invoked.</p>
951:
952: <p>The second argument, <var title="">target</var>, specifies the
953: <a href="#browsing-context-name" title="browsing context name">name</a> of the browsing
954: context that is to be navigated. It must be a <a href="#valid-browsing-context-name-or-keyword">valid browsing
955: context name or keyword</a>. If fewer than two arguments are
956: provided, then the <var title="">name</var> argument defaults to the
957: value "<code>_blank</code>".</p>
958:
959: <p>The third argument, <var title="">features</var>, has no effect
960: and is supported for historical reasons only.</p>
961:
962: <p>The fourth argument, <var title="">replace</var>, specifies
963: whether or not the new page will <a href="history.html#replacement-enabled" title="replacement
964: enabled">replace</a> the page currently loaded in the browsing
965: context, when <var title="">target</var> identifies an existing
966: browsing context (as opposed to leaving the current page in the
967: browsing context's <a href="history.html#session-history">session history</a>). When three or
968: fewer arguments are provided, <var title="">replace</var> defaults
969: to false.</p>
970:
971: <p>When the method is invoked, the user agent must first select a
972: <a href="#browsing-context">browsing context</a> to navigate by applying <a href="#the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">the
973: rules for choosing a browsing context given a browsing context
974: name</a> using the <var title="">target</var> argument as the
975: name and the <a href="#browsing-context">browsing context</a> of the script as the
976: context in which the algorithm is executed, unless the user has
977: indicated a preference, in which case the browsing context to
978: navigate may instead be the one indicated by the user.</p>
979:
980: <p class="example">For example, suppose there is a user agent that
981: supports control-clicking a link to open it in a new tab. If a user
982: clicks in that user agent on an element whose <code title="handler-onclick"><a href="#handler-onclick">onclick</a></code> handler uses the <code title="dom-open"><a href="#dom-open">window.open()</a></code> API to open a page in an
983: iframe, but, while doing so, holds the control key down, the user
984: agent could override the selection of the target browsing context to
985: instead target a new tab.</p>
986:
987: <p>Then, the user agent must <a href="history.html#navigate">navigate</a> the selected
988: <a href="#browsing-context">browsing context</a> to the <a href="infrastructure.html#absolute-url">absolute URL</a> (or
989: error) obtained from <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolving</a>
990: <var title="">url</var> earlier. If the <var title="">replace</var>
991: is true, then <a href="history.html#replacement-enabled" title="replacement enabled">replacement must be
992: enabled</a>; otherwise, it must not be enabled unless the
1.671 mike 993: <a href="#browsing-context">browsing context</a> was just created as part of
1.1 mike 994: <a href="#the-rules-for-choosing-a-browsing-context-given-a-browsing-context-name">the rules for choosing a browsing context given a browsing
995: context name</a>. The navigation must be done with the <a href="#script-s-browsing-context" title="script's browsing context">browsing context</a> of the
996: <a href="#first-script">first script</a> as the <a href="history.html#source-browsing-context">source browsing
997: context</a>.</p>
998:
999: <p>The method must return the <code><a href="#windowproxy">WindowProxy</a></code> object of the
1000: <a href="#browsing-context">browsing context</a> that was navigated, or null if no
1001: browsing context was navigated.</p>
1002:
1003: <hr><p>The <dfn id="dom-name" title="dom-name"><code>name</code></dfn> attribute of
1004: the <code><a href="#window">Window</a></code> object must, on getting, return the current
1005: name of the <a href="#browsing-context">browsing context</a>, and, on setting, set the
1006: name of the <a href="#browsing-context">browsing context</a> to the new value.</p>
1007:
1008: <p class="note">The name <a href="history.html#resetBCName">gets reset</a> when
1009: the browsing context is navigated to another domain.</p>
1010:
1011: <hr><p>The <dfn id="dom-window-close" title="dom-window-close"><code>close()</code></dfn>
1012: method on <code><a href="#window">Window</a></code> objects should, if the corresponding
1013: <a href="#browsing-context">browsing context</a> <var title="">A</var> is an
1014: <a href="#auxiliary-browsing-context">auxiliary browsing context</a> that was created by a script
1015: (as opposed to by an action of the user), and if the <a href="#script-s-browsing-context" title="script's browsing context">browsing context</a> of the
1016: <a href="#concept-script" title="concept-script">script</a> that invokes the method
1017: is <a href="#allowed-to-navigate">allowed to navigate</a> the <a href="#browsing-context">browsing
1018: context</a> <var title="">A</var>, close the <a href="#browsing-context">browsing
1019: context</a> <var title="">A</var> (and may <a href="#a-browsing-context-is-discarded" title="a
1020: browsing context is discarded">discard</a> it too).</p>
1021:
1.614 mike 1022: </div><h4 id="accessing-other-browsing-contexts"><span class="secno">6.3.3 </span>Accessing other browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-length"><a href="#dom-length">length</a></code></dt>
1.1 mike 1023:
1024: <dd>
1025:
1026: <p>Returns the number of <a href="#child-browsing-context" title="child browsing
1027: context">child browsing contexts</a>.</p>
1028:
1029: </dd>
1030:
1031: <dt><var title="">window</var>[<var title="">index</var>]</dt>
1032:
1033: <dd>
1034:
1035: <p>Returns the indicated <a href="#child-browsing-context">child browsing context</a>.</p>
1036:
1037: </dd>
1038:
1039: </dl><div class="impl">
1040:
1.192 mike 1041: <p>The <dfn id="dom-length" title="dom-length"><code>length</code></dfn> IDL
1.1 mike 1042: attribute on the <code><a href="#window">Window</a></code> interface must return the
1043: number of <a href="#child-browsing-context" title="child browsing context">child browsing
1.177 mike 1044: contexts</a> of the <a href="#active-document">active document</a> of that
1045: <code><a href="#window">Window</a></code> object, if that <code><a href="#window">Window</a></code>'s
1046: <a href="#browsing-context">browsing context</a> shares the same <a href="#event-loop">event
1047: loop</a> as the <a href="#script-s-browsing-context">script's browsing context</a> of the
1.192 mike 1048: <a href="#first-script">first script</a> accessing the IDL attribute; otherwise, it
1.177 mike 1049: must return zero.</p>
1050:
1051: <!-- in other words, frames are only accessible to same-thread processes -->
1.1 mike 1052:
1053: <p>The <span>indices of the supported indexed properties</span> on
1054: the <code><a href="#window">Window</a></code> object at any instant are the numbers in the
1.192 mike 1055: range 0 .. <span title=""><var title="">n</var>-1</span>, where <var title="">n</var> is the number returned by the <code title="dom-length"><a href="#dom-length">length</a></code> IDL attribute. If <var title="">n</var> is zero then there are no <span>supported indexed
1.177 mike 1056: properties</span>.</p>
1.1 mike 1057:
1058: <p>When a <code><a href="#window">Window</a></code> object is <dfn id="dom-window-item" title="dom-window-item">indexed to retrieve an indexed
1059: property</dfn> <var title="">index</var>, the value returned must be
1060: the <var title="">index</var>th <a href="#child-browsing-context">child browsing context</a>
1061: of the <code>Document</code>, sorted in the <a href="infrastructure.html#tree-order">tree order</a>
1062: of the elements nesting those <a href="#browsing-context" title="browsing
1063: context">browsing contexts</a>.</p>
1064:
1065: <p>These properties are the <dfn id="dynamic-nested-browsing-context-properties">dynamic nested browsing context
1066: properties</dfn>.</p>
1067:
1.614 mike 1068: </div><h4 id="named-access-on-the-window-object"><span class="secno">6.3.4 </span>Named access on the <code><a href="#window">Window</a></code> object</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var>[<var title="">name</var>]</dt>
1.1 mike 1069:
1070: <dd>
1071:
1072: <p>Returns the indicated <a href="#child-browsing-context">child browsing context</a>.</p>
1073:
1074: </dd>
1075:
1076: </dl><div class="impl">
1077:
1078: <p>The <code><a href="#window">Window</a></code> interface <span title="support named
1079: properties">supports named properties</span>. The <span>names of the
1080: supported named properties</span> at any moment consist of:</p>
1081:
1082: <ul><li>The value of the <code title="">name</code> content attribute
1.5 mike 1083: for all <code><a href="text-level-semantics.html#the-a-element">a</a></code>, <code><a href="obsolete.html#the-applet-element">applet</a></code>, <code><a href="the-canvas-element.html#the-area-element">area</a></code>,
1.159 mike 1084: <code><a href="text-level-semantics.html#the-embed-element">embed</a></code>, <code><a href="obsolete.html#frame">frame</a></code>, <code><a href="obsolete.html#frameset">frameset</a></code>,
1085: <code><a href="forms.html#the-form-element">form</a></code>, <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code>, <code><a href="text-level-semantics.html#the-img-element">img</a></code>, and
1086: <code><a href="text-level-semantics.html#the-object-element">object</a></code> elements in the <a href="#active-document">active document</a>
1.1 mike 1087: that have a <code title="">name</code> content attribute, and,</li>
1088:
1089: <li>The value of the <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> content
1090: attribute of any <a href="infrastructure.html#html-elements" title="HTML elements">HTML element</a> in
1091: the <a href="#active-document">active document</a> with an <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> content attribute.</li>
1092:
1093: </ul><p>When <dfn id="dom-window-nameditem" title="dom-window-namedItem">the <code>Window</code>
1094: object is indexed for property retrieval</dfn> using a name <var title="">name</var>, then the user agent must return the value
1095: obtained using the following steps:</p>
1096:
1097: <ol><li>
1098:
1099: <p>Let <var title="">elements</var> be the list of <a href="#dom-window-nameditem-filter" title="dom-window-namedItem-filter">named elements</a> with the
1100: name <var title="">name</var> in the <a href="#active-document">active document</a>.
1101:
1102: </p><p class="note">There will be at least one such element, by
1103: definition.<!-- (If there wasn't, then this algorithm wouldn't
1104: have been invoked by Web IDL.) --></p>
1105:
1106: </li>
1107:
1108: <li>
1109:
1.159 mike 1110: <p>If <var title="">elements</var> contains an <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code>
1.1 mike 1111: element, then return the <code><a href="#windowproxy">WindowProxy</a></code> object of the
1112: <a href="#nested-browsing-context">nested browsing context</a> represented by the first such
1.159 mike 1113: <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code> element in <a href="infrastructure.html#tree-order">tree order</a>, and abort
1.1 mike 1114: these steps.</p>
1115:
1116: </li>
1117:
1118: <li>
1119:
1120: <p>Otherwise, if <var title="">elements</var> has only one
1121: element, return that element and abort these steps.</p>
1122:
1123: </li>
1124:
1125: <li>
1126:
1.159 mike 1127: <p>Otherwise return an <code><a href="infrastructure.html#htmlcollection">HTMLCollection</a></code> rooted at the
1.1 mike 1128: <code>Document</code> node, whose filter matches only <a href="#dom-window-nameditem-filter" title="dom-window-namedItem-filter">named elements</a> with
1129: the name <var title="">name</var>.</p> <!-- the same one each time
1130: is returned, because of the rule under collections -->
1131:
1132: </li>
1133:
1134: </ol><p><dfn id="dom-window-nameditem-filter" title="dom-window-nameditem-filter">Named elements</dfn>
1135: with the name <var title="">name</var>, for the purposes of the
1136: above algorithm, are those that are either:</p>
1137:
1.5 mike 1138: <ul><li><code><a href="text-level-semantics.html#the-a-element">a</a></code>, <code><a href="obsolete.html#the-applet-element">applet</a></code>, <code><a href="the-canvas-element.html#the-area-element">area</a></code>,
1.159 mike 1139: <code><a href="text-level-semantics.html#the-embed-element">embed</a></code>, <code><a href="forms.html#the-form-element">form</a></code>, <code><a href="obsolete.html#frame">frame</a></code>,
1140: <code><a href="obsolete.html#frameset">frameset</a></code>, <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code>, <code><a href="text-level-semantics.html#the-img-element">img</a></code>, or
1141: <code><a href="text-level-semantics.html#the-object-element">object</a></code> elements that have a <code title="attr-name">name</code> content attribute whose value is <var title="">name</var>, or</li>
1.1 mike 1142:
1143: <li><a href="infrastructure.html#html-elements">HTML elements</a> elements that have an <code title="attr-id"><a href="dom.html#the-id-attribute">id</a></code> content attribute whose value is <var title="">name</var>.</li>
1144:
1.123 mike 1145: </ul></div><div class="impl">
1.1 mike 1146:
1.614 mike 1147: <h4 id="garbage-collection-and-browsing-contexts"><span class="secno">6.3.5 </span>Garbage collection and browsing contexts</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1148:
1149: <p>A <a href="#browsing-context">browsing context</a> has a strong reference to each of
1150: its <code>Document</code>s and its <code><a href="#windowproxy">WindowProxy</a></code> object,
1151: and the user agent itself has a strong reference to its <a href="#top-level-browsing-context" title="top-level browsing context">top-level browsing
1152: contexts</a>.</p>
1153:
1154: <p>A <code>Document</code> has a strong reference to each of its
1155: <a href="#view" title="view">views</a> and their <code>AbstractView</code>
1156: objects.</p>
1157:
1158: <p>When a <a href="#browsing-context">browsing context</a> is to <dfn id="discard-a-document">discard a
1159: <code>Document</code></dfn>, that means that it is to lose the
1160: strong reference from the <code>Document</code>'s <a href="#browsing-context">browsing
1161: context</a> to the <code>Document</code>, and that any <a href="#concept-task" title="concept-task">tasks</a> associated with the
1162: <code>Document</code> in any <a href="#task-source">task source</a> must be
1163: removed without being run.</p>
1164:
1165: <p class="note">The <a href="#browsing-context">browsing context</a>'s <a href="#default-view">default
1166: view</a>'s <code><a href="#window">Window</a></code> object <a href="infrastructure.html#implied-strong-reference" title="implied strong
1167: reference">has a strong reference</a> to its
1168: <code>Document</code> object through the <code title="dom-document">document</code> attribute of the
1169: <code>AbstractView</code> interface. Thus, references from other
1.104 mike 1170: scripts to either of those objects will keep both alive. <a href="references.html#refsDOMVIEWS">[DOMVIEWS]</a></p>
1.1 mike 1171:
1172: <p class="note">Whenever a <code>Document</code> object is <a href="#discard-a-document" title="discard a Document">discarded</a>, it is also removed from
1173: the list of <span>the worker's <code>Document</code>s</span> of each
1174: worker whose list contains that <code>Document</code>.</p>
1175:
1176: <p>When <dfn id="a-browsing-context-is-discarded">a <em><span>browsing context</span></em> is
1177: discarded</dfn>, the strong reference from the user agent itself to
1178: the <a href="#browsing-context">browsing context</a> must be severed, and all the
1179: <code>Document</code> objects for all the entries in the
1180: <a href="#browsing-context">browsing context</a>'s session history must be <a href="#discard-a-document" title="discard a document">discarded</a> as well.</p>
1181:
1182: <p>User agents may <a href="#a-browsing-context-is-discarded" title="a browsing context is
1183: discarded">discard</a> <a href="#top-level-browsing-context" title="top-level browsing
1184: context">top-level browsing contexts</a> at any time (typically,
1185: in response to user requests, e.g. when a user closes a window
1186: containing one or more <a href="#top-level-browsing-context" title="top-level browsing
1187: context">top-level browsing contexts</a>). Other <a href="#browsing-context" title="browsing context">browsing contexts</a> must be discarded
1188: once their <code><a href="#windowproxy">WindowProxy</a></code> object is eligible for garbage
1189: collection.</p>
1190:
1.614 mike 1191: </div><h4 id="browser-interface-elements"><span class="secno">6.3.6 </span>Browser interface elements</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>To allow Web pages to integrate with Web browsers, certain Web
1.1 mike 1192: browser interface elements are exposed in a limited way to scripts
1.123 mike 1193: in Web pages.</p><p>Each interface element is represented by a <code><a href="#barprop">BarProp</a></code>
1194: object:</p><pre class="idl">interface <dfn id="barprop">BarProp</dfn> {
1.1 mike 1195: attribute boolean <a href="#dom-barprop-visible" title="dom-BarProp-visible">visible</a>;
1.123 mike 1196: };</pre><dl class="domintro"><dt><var title="">window</var> . <code title="dom-window-locationbar"><a href="#dom-window-locationbar">locationbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1.1 mike 1197: <dd>
1198: <p>Returns true if the location bar is visible; otherwise, returns false.</p>
1199: </dd>
1200:
1201: <dt><var title="">window</var> . <code title="dom-window-menubar"><a href="#dom-window-menubar">menubar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1202: <dd>
1203: <p>Returns true if the menu bar is visible; otherwise, returns false.</p>
1204: </dd>
1205:
1206: <dt><var title="">window</var> . <code title="dom-window-personalbar"><a href="#dom-window-personalbar">personalbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1207: <!--<dt><var title="">window</var> . <code title="dom-window-directories">directories</code> . <code title="dom-BarProp-visible">visible</code></dt>-->
1208: <dd>
1209: <p>Returns true if the personal bar is visible; otherwise, returns false.</p>
1210: </dd>
1211:
1212: <dt><var title="">window</var> . <code title="dom-window-scrollbars"><a href="#dom-window-scrollbars">scrollbars</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1213: <dd>
1214: <p>Returns true if the scroll bars are visible; otherwise, returns false.</p>
1215: </dd>
1216:
1217: <dt><var title="">window</var> . <code title="dom-window-statusbar"><a href="#dom-window-statusbar">statusbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1218: <dd>
1219: <p>Returns true if the status bar is visible; otherwise, returns false.</p>
1220: </dd>
1221:
1222: <dt><var title="">window</var> . <code title="dom-window-toolbar"><a href="#dom-window-toolbar">toolbar</a></code> . <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code></dt>
1223: <dd>
1.391 mike 1224: <p>Returns true if the toolbar is visible; otherwise, returns false.</p>
1.1 mike 1225: </dd>
1226:
1227: </dl><div class="impl">
1228:
1229: <p>The <dfn id="dom-barprop-visible" title="dom-BarProp-visible">visible</dfn> attribute, on
1230: getting, must return either true or a value determined by the user
1231: agent to most accurately represent the visibility state of the user
1232: interface element that the object represents, as described below. On
1233: setting, the new value must be discarded.</p>
1234:
1235: <p>The following <code><a href="#barprop">BarProp</a></code> objects exist for each
1236: <code>Document</code> object in a <a href="#browsing-context">browsing
1237: context</a>. Some of the user interface elements represented by
1238: these objects might have no equivalent in some user agents; for
1.409 mike 1239: those user agents, except when otherwise specified, the object must
1240: act as if it was present and visible (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code> attribute must return
1.1 mike 1241: true).</p>
1242:
1243: <dl><dt><dfn id="the-location-bar-barprop-object">The location bar <code>BarProp</code> object</dfn></dt>
1244:
1245: <dd>Represents the user interface element that contains a control
1246: that displays the <a href="infrastructure.html#url">URL</a> of the <a href="#active-document">active
1247: document</a>, or some similar interface concept.</dd>
1248:
1249: <dt><dfn id="the-menu-bar-barprop-object">The menu bar <code>BarProp</code> object</dfn></dt>
1250:
1251: <dd>Represents the user interface element that contains a list of
1252: commands in menu form, or some similar interface concept.</dd>
1253:
1254: <dt><dfn id="the-personal-bar-barprop-object">The personal bar <code>BarProp</code> object</dfn></dt>
1255:
1256: <dd>Represents the user interface element that contains links to
1257: the user's favorite pages, or some similar interface concept.</dd>
1258:
1259: <dt><dfn id="the-scrollbar-barprop-object">The scrollbar <code>BarProp</code> object</dfn></dt>
1260:
1261: <dd>Represents the user interface element that contains a scrolling
1262: mechanism, or some similar interface concept.</dd>
1263:
1264: <dt><dfn id="the-status-bar-barprop-object">The status bar <code>BarProp</code> object</dfn></dt>
1265:
1266: <dd>Represents a user interface element found immediately below or
1267: after the document, as appropriate for the <a href="#default-view">default
1268: view</a>'s media. If the user agent has no such user interface
1269: element, then the object may act as if the corresponding user
1270: interface element was absent (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code> attribute may return
1271: false).</dd>
1272:
1.391 mike 1273: <dt><dfn id="the-toolbar-barprop-object">The toolbar <code>BarProp</code> object</dfn></dt>
1.1 mike 1274:
1275: <dd>Represents the user interface element found immediately above
1276: or before the document, as appropriate for the <a href="#default-view">default
1277: view</a>'s media. If the user agent has no such user interface
1278: element, then the object may act as if the corresponding user
1279: interface element was absent (i.e. its <code title="dom-BarProp-visible"><a href="#dom-barprop-visible">visible</a></code> attribute may return
1280: false).</dd>
1281:
1282: </dl><p>The <dfn id="dom-window-locationbar" title="dom-window-locationbar"><code>locationbar</code></dfn>
1283: attribute must return <a href="#the-location-bar-barprop-object">the location bar <code>BarProp</code>
1284: object</a>.</p>
1285:
1286: <p>The <dfn id="dom-window-menubar" title="dom-window-menubar"><code>menubar</code></dfn>
1287: attribute must return <a href="#the-menu-bar-barprop-object">the menu bar <code>BarProp</code>
1288: object</a>.</p>
1289:
1290: <p>The <dfn id="dom-window-personalbar" title="dom-window-personalbar"><code>personalbar</code></dfn>
1291: attribute must return <a href="#the-personal-bar-barprop-object">the personal bar <code>BarProp</code>
1292: object</a>.</p>
1293:
1294: <p>The <dfn id="dom-window-scrollbars" title="dom-window-scrollbars"><code>scrollbars</code></dfn>
1295: attribute must return <a href="#the-scrollbar-barprop-object">the scrollbar <code>BarProp</code>
1296: object</a>.</p>
1297:
1298: <p>The <dfn id="dom-window-statusbar" title="dom-window-statusbar"><code>statusbar</code></dfn> attribute
1299: must return <a href="#the-status-bar-barprop-object">the status bar <code>BarProp</code>
1300: object</a>.</p>
1301:
1302: <p>The <dfn id="dom-window-toolbar" title="dom-window-toolbar"><code>toolbar</code></dfn>
1.391 mike 1303: attribute must return <a href="#the-toolbar-barprop-object">the toolbar <code>BarProp</code>
1.1 mike 1304: object</a>.</p>
1305:
1306: <!--
1307: <p>For legacy reasons, the <dfn
1308: title="dom-window-directories"><code>directories</code></dfn>
1309: attribute must also return <span>the personal bar
1310: <code>BarProp</code> object</span>.</p>
1311: -->
1312:
1.123 mike 1313: </div><div class="impl">
1.1 mike 1314:
1.614 mike 1315: <h3 id="origin-0"><span class="secno">6.4 </span>Origin</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1316: <!-- Hallowed are the Ori -->
1317:
1.159 mike 1318: <p>The <dfn id="origin">origin</dfn> of a resource and the <dfn id="effective-script-origin">effective script
1.1 mike 1319: origin</dfn> of a resource are both either opaque identifiers or
1320: tuples consisting of a scheme component, a host component, a port
1321: component, and optionally extra data.</p>
1322:
1323: <p class="note">The extra data could include the certificate of the
1324: site when using encrypted connections, to ensure that if the site's
1325: secure certificate changes, the origin is considered to change as
1326: well.</p>
1327:
1328: <p>These characteristics are defined as follows:</p>
1329:
1330: <dl><dt>For URLs</dt>
1331:
1332: <dd>
1333:
1.159 mike 1334: <p>The <a href="#origin">origin</a> and <a href="#effective-script-origin">effective script
1.1 mike 1335: origin</a> of the <a href="infrastructure.html#url">URL</a> is whatever is returned by
1336: the following algorithm:</p>
1337:
1338: <ol><li><p>Let <var title="">url</var> be the <a href="infrastructure.html#url">URL</a> for
1.159 mike 1339: which the <a href="#origin">origin</a> is being determined.</p></li>
1.1 mike 1340:
1341: <li><p><a href="infrastructure.html#parse-a-url" title="parse a url">Parse</a> <var title="">url</var>.</p></li>
1342:
1343: <li><p>If <var title="">url</var> identifies a resource that is
1344: its own trust domain (e.g. it identifies an e-mail on an IMAP
1345: server or a post on an NNTP server) then return a globally unique
1346: identifier specific to the resource identified by <var title="">url</var>, so that if this algorithm is invoked again
1.174 mike 1347: for <a href="infrastructure.html#url" title="URL">URLs</a> that identify the same resource,
1.1 mike 1348: the same identifier will be returned.</p></li>
1349:
1350: <li><p>If <var title="">url</var> does not use a server-based
1351: naming authority, or if parsing <var title="">url</var> failed,
1352: or if <var title="">url</var> is not an <a href="infrastructure.html#absolute-url">absolute
1353: URL</a>, then return a new globally unique
1354: identifier.</p></li>
1355:
1356: <li><p>Let <var title="">scheme</var> be the <a href="infrastructure.html#url-scheme" title="url-scheme"><scheme></a> component of <var title="">url</var>, <a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>.</p></li>
1357:
1358: <li><p>If the UA doesn't support the protocol given by <var title="">scheme</var>, then return a new globally unique
1359: identifier.</p></li>
1360:
1361: <li><p>If <var title="">scheme</var> is "<code title="">file</code>", then the user agent may return a
1362: UA-specific value.</p></li>
1363:
1364: <li><p>Let <var title="">host</var> be the <a href="infrastructure.html#url-host" title="url-host"><host></a> component of <var title="">url</var>.</p></li>
1365:
1366: <li>
1367:
1368: <p>Apply the IDNA ToASCII algorithm to <var title="">host</var>,
1369: with both the AllowUnassigned and UseSTD3ASCIIRules flags
1370: set. Let <var title="">host</var> be the result of the ToASCII
1371: algorithm.</p>
1372:
1373: <p>If ToASCII fails to convert one of the components of the
1374: string, e.g. because it is too long or because it contains
1375: invalid characters, then return a new globally unique
1.104 mike 1376: identifier. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1377:
1378: </li>
1379:
1380: <li><p>Let <var title="">host</var> be the result of converting
1381: <var title="">host</var> <a href="infrastructure.html#converted-to-ascii-lowercase" title="converted to ASCII lowercase">to
1382: ASCII lowercase</a>.</p></li>
1383:
1384: <li><p>If there is no <a href="infrastructure.html#url-port" title="url-port"><port></a>
1385: component, then let <var title="">port</var> be the default port
1386: for the protocol given by <var title="">scheme</var>. Otherwise,
1387: let <var title="">port</var> be the <a href="infrastructure.html#url-port" title="url-port"><port></a> component of <var title="">url</var>.</p></li>
1388:
1389: <li><p>Return the tuple (<var title="">scheme</var>, <var title="">host</var>, <var title="">port</var>).</p></li>
1390:
1391: </ol><p>In addition, if the <a href="infrastructure.html#url">URL</a> is in fact associated with
1392: a <code>Document</code> object that was created by parsing the
1393: resource obtained from fetching <a href="infrastructure.html#url">URL</a>, and this was
1394: done over a secure connection, then the server's secure
1395: certificate may be added to the origin as additional data.</p>
1396:
1397: </dd>
1398:
1399: <dt>For scripts</dt>
1400:
1401: <dd>
1402:
1.159 mike 1403: <p>The <a href="#origin">origin</a> and <a href="#effective-script-origin">effective script
1.1 mike 1404: origin</a> of a script are determined from another resource,
1405: called the <i>owner</i>:</p>
1406:
1407: <dl class="switch"><dt>If a script is in a <code><a href="semantics.html#script">script</a></code> element</dt>
1408:
1409: <dd>The owner is the <code>Document</code> to which the
1410: <code><a href="semantics.html#script">script</a></code> element belongs.</dd>
1411:
1412:
1413: <dt>If a script is in an <a href="#event-handler-content-attributes" title="event handler content
1414: attributes">event handler content attribute</a></dt>
1415:
1416: <dd>The owner is the <code>Document</code> to which the
1417: attribute node belongs.</dd>
1418:
1419:
1420: <dt>If a script is a function or other code reference created by
1421: another script</dt>
1422:
1423: <dd>The owner is the script that created it.</dd>
1424:
1425:
1426: <dt>If a script is a <a href="#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> that was returned as the
1427: location of an HTTP redirect (<a href="infrastructure.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a> in
1428: other protocols)</dt>
1429:
1430: <dd>The owner is the <a href="infrastructure.html#url">URL</a> that redirected to the
1431: <a href="#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a>.</dd>
1432:
1433:
1434: <dt>If a script is a <a href="#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> in an attribute</dt>
1435:
1436: <dd>The owner is the <code>Document</code> of the element on
1437: which the attribute is found.</dd>
1438:
1439:
1440: <dt>If a script is a <a href="#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> in a style sheet</dt>
1441:
1442: <dd>The owner is the <a href="infrastructure.html#url">URL</a> of the style sheet.</dd>
1443:
1444:
1445: <dt>If a script is a <a href="#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
1446: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
1447: the URL having been provided by the user (e.g. by using a
1448: <i>bookmarklet</i>)</dt>
1449:
1450: <dd>The owner is the <code>Document</code> of the <a href="#browsing-context">browsing
1451: context</a>'s <a href="#active-document">active document</a>.</dd>
1452:
1453:
1454: <dt>If a script is a <a href="#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
1455: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
1456: the URL having been declared in markup</dt>
1457:
1458: <dd>The owner is the <code>Document</code> of the element
1459: (e.g. an <code><a href="text-level-semantics.html#the-a-element">a</a></code> or <code><a href="the-canvas-element.html#the-area-element">area</a></code> element) that
1460: declared the URL.</dd>
1461:
1462:
1463: <dt>If a script is a <a href="#javascript-protocol" title="javascript protocol"><code title="">javascript:</code> URL</a> to which a <a href="#browsing-context">browsing
1464: context</a> is being <a href="history.html#navigate" title="navigate">navigated</a>,
1465: the URL having been provided by script</dt>
1466:
1467: <dd>The owner is the script that provided the URL.</dd>
1468:
1.159 mike 1469: </dl><p>The <a href="#origin">origin</a> of the script is then equal to the
1470: <a href="#origin">origin</a> of the owner, and the <a href="#effective-script-origin">effective script
1.1 mike 1471: origin</a> of the script is equal to the <a href="#effective-script-origin">effective script
1472: origin</a> of the owner.</p>
1473:
1474: </dd>
1475:
1476: <dt>For <code>Document</code> objects and images</dt>
1477:
1478: <dd>
1479:
1480: <dl class="switch"><dt id="sandboxOrigin">If a <code>Document</code> is in a
1.159 mike 1481: <a href="#browsing-context">browsing context</a> whose <a href="text-level-semantics.html#sandboxed-origin-browsing-context-flag">sandboxed origin
1.1 mike 1482: browsing context flag</a> was set when the
1483: <code>Document</code> was created</dt>
1484:
1.159 mike 1485: <dd>The <a href="#origin">origin</a> is a globally unique identifier
1.1 mike 1486: assigned when the <code>Document</code> is created.</dd>
1487:
1488:
1489: <dt>If a <code>Document</code> or image was returned by the
1490: <code>XMLHttpRequest</code> API</dt>
1491:
1.409 mike 1492: <dd>The <a href="#origin">origin</a> is equal to the <span>XMLHttpRequest
1493: origin</span> of the <code>XMLHttpRequest</code> object. <a href="references.html#refsXHR">[XHR]</a></dd>
1.1 mike 1494:
1495:
1496: <dt>If a <code>Document</code> or image was generated from a
1497: <a href="#javascript-protocol" title="javascript protocol"><code>javascript:</code>
1498: URL</a></dt>
1499:
1.159 mike 1500: <dd>The <a href="#origin">origin</a> is equal to the <a href="#origin">origin</a>
1.1 mike 1501: of the script of that <a href="#javascript-protocol" title="javascript
1502: protocol"><code>javascript:</code> URL</a>.</dd>
1503:
1504:
1505: <dt>If a <code>Document</code> or image was served over the
1506: network and has an address that uses a URL scheme with a
1507: server-based naming authority</dt>
1508:
1.159 mike 1509: <dd>The <a href="#origin">origin</a> is the <a href="#origin">origin</a> of the
1.1 mike 1510: <a href="dom.html#the-document-s-address" title="the document's address">address</a> of the
1511: <code>Document</code> or the <a href="infrastructure.html#url">URL</a> of the image, as
1512: appropriate.</dd>
1513:
1514:
1515: <dt>If a <code>Document</code> or image was generated from a
1516: <code title="">data:</code> URL that was returned as the location
1517: of an HTTP redirect (<a href="infrastructure.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a> in
1518: other protocols)</dt>
1519:
1.159 mike 1520: <dd>The <a href="#origin">origin</a> is the <a href="#origin">origin</a> of the
1.1 mike 1521: <a href="infrastructure.html#url">URL</a> that redirected to the <code title="">data:</code> URL.</dd>
1522:
1523:
1524: <dt>If a <code>Document</code> or image was generated from a
1525: <code title="">data:</code> URL found in another
1526: <code>Document</code> or in a script</dt>
1527:
1.159 mike 1528: <dd>The <a href="#origin">origin</a> is the <a href="#origin">origin</a> of the
1.1 mike 1529: <code>Document</code> or script in which the <code title="">data:</code> URL was found.</dd>
1530:
1531:
1532: <dt>If a <code>Document</code> has the <a href="dom.html#the-document-s-address" title="the
1533: document's address">address</a>
1534: "<code><a href="infrastructure.html#about:blank">about:blank</a></code>"</dt>
1535:
1.159 mike 1536: <dd>The <a href="#origin">origin</a> of the <code>Document</code> is <a href="#about-blank-origin">the <span>origin</span> it was
1.1 mike 1537: assigned when its browsing context was created</a>.</dd>
1538:
1539:
1540: <dt>If a <code>Document</code> or image was obtained in some
1541: other manner (e.g. a <code title="">data:</code> URL typed in by
1.557 mike 1542: the user, a <code>Document</code> created using the <code title="dom-DOMImplementation-createDocument">createDocument()</code>
1543: API, etc)</dt>
1.1 mike 1544:
1.159 mike 1545: <dd>The <a href="#origin">origin</a> is a globally unique identifier
1.1 mike 1546: assigned when the <code>Document</code> or image is created.</dd>
1547:
1.409 mike 1548: </dl><p>When a <code>Document</code> is created, its <a href="#effective-script-origin">effective
1549: script origin</a> is initialized to the <a href="#origin">origin</a> of
1550: the <code>Document</code>. However, the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute can
1.1 mike 1551: be used to change it.</p>
1552:
1553: </dd>
1554:
1555: <dt>For <code><a href="video.html#audio">audio</a></code> and <code><a href="video.html#video">video</a></code> elements</dt>
1556:
1557: <dd>
1558:
1559: <p>If value of the <a href="video.html#media-element">media element</a>'s <code title="dom-media-currentSrc"><a href="video.html#dom-media-currentsrc">currentSrc</a></code> attribute is the
1.159 mike 1560: empty string, the <a href="#origin">origin</a> is the same as the
1561: <a href="#origin">origin</a> of the element's <code>Document</code>'s
1562: <a href="#origin">origin</a>.</p>
1.1 mike 1563:
1.159 mike 1564: <p>Otherwise, the <a href="#origin">origin</a> is equal to the
1565: <a href="#origin">origin</a> of the <a href="infrastructure.html#absolute-url">absolute URL</a> given by the
1.1 mike 1566: <a href="video.html#media-element">media element</a>'s <code title="dom-media-currentSrc"><a href="video.html#dom-media-currentsrc">currentSrc</a></code> attribute.</p>
1567:
1568: </dd>
1569:
1570: </dl><p>The <dfn id="unicode-serialization-of-an-origin">Unicode serialization of an origin</dfn> is the string
1571: obtained by applying the following algorithm to the given
1.159 mike 1572: <a href="#origin">origin</a>:</p>
1.1 mike 1573:
1.159 mike 1574: <ol><li><p>If the <a href="#origin">origin</a> in question is not a
1.1 mike 1575: scheme/host/port tuple, then return the literal string "<code title="">null</code>" and abort these steps.</p></li>
1576:
1577: <li><p>Otherwise, let <var title="">result</var> be the scheme part
1.159 mike 1578: of the <a href="#origin">origin</a> tuple.</p></li>
1.1 mike 1579:
1580: <li><p>Append the string "<code title="">://</code>" to <var title="">result</var>.</p></li>
1581:
1582: <li><p>Apply the IDNA ToUnicode algorithm to each component of the
1.159 mike 1583: host part of the <a href="#origin">origin</a> tuple, and append the results
1.1 mike 1584: — each component, in the same order, separated by U+002E FULL
1.464 mike 1585: STOP characters (.) — to <var title="">result</var>. <a href="references.html#refsRFC3490">[RFC3490]</a></p></li>
1.1 mike 1586:
1.159 mike 1587: <li><p>If the port part of the <a href="#origin">origin</a> tuple gives a port
1.1 mike 1588: that is different from the default port for the protocol given by
1.159 mike 1589: the scheme part of the <a href="#origin">origin</a> tuple, then append a
1.464 mike 1590: U+003A COLON character (:) and the given port, in base ten, to
1.1 mike 1591: <var title="">result</var>.</p></li>
1592:
1593: <li><p>Return <var title="">result</var>.</p></li>
1594:
1595: </ol><p>The <dfn id="ascii-serialization-of-an-origin">ASCII serialization of an origin</dfn> is the string
1596: obtained by applying the following algorithm to the given
1.159 mike 1597: <a href="#origin">origin</a>:</p>
1.1 mike 1598:
1.159 mike 1599: <ol><li><p>If the <a href="#origin">origin</a> in question is not a
1.1 mike 1600: scheme/host/port tuple, then return the literal string "<code title="">null</code>" and abort these steps.</p></li>
1601:
1602: <li><p>Otherwise, let <var title="">result</var> be the scheme part
1.159 mike 1603: of the <a href="#origin">origin</a> tuple.</p></li>
1.1 mike 1604:
1605: <li><p>Append the string "<code title="">://</code>" to <var title="">result</var>.</p></li>
1606:
1607: <li>
1608:
1609: <p>Apply the IDNA ToASCII algorithm the host part of the
1.159 mike 1610: <a href="#origin">origin</a> tuple, with both the AllowUnassigned and
1.1 mike 1611: UseSTD3ASCIIRules flags set, and append the results <var title="">result</var>.</p>
1612:
1613: <p>If ToASCII fails to convert one of the components of the
1614: string, e.g. because it is too long or because it contains invalid
1.104 mike 1615: characters, then return the empty string and abort these steps. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1616:
1617: </li>
1618:
1.159 mike 1619: <li><p>If the port part of the <a href="#origin">origin</a> tuple gives a port
1.1 mike 1620: that is different from the default port for the protocol given by
1.159 mike 1621: the scheme part of the <a href="#origin">origin</a> tuple, then append a
1.464 mike 1622: U+003A COLON character (:) and the given port, in base ten, to
1.1 mike 1623: <var title="">result</var>.</p></li>
1624:
1625: <li><p>Return <var title="">result</var>.</p></li>
1626:
1.159 mike 1627: </ol><p>Two <a href="#origin" title="origin">origins</a> are said to be the
1.1 mike 1628: <dfn id="same-origin">same origin</dfn> if the following algorithm returns true:</p>
1629:
1.159 mike 1630: <ol><li><p>Let <var title="">A</var> be the first <a href="#origin">origin</a>
1.1 mike 1631: being compared, and <var title="">B</var> be the second
1.159 mike 1632: <a href="#origin">origin</a> being compared.</p></li>
1.1 mike 1633:
1634: <li><p>If <var title="">A</var> and <var title="">B</var> are both
1635: opaque identifiers, and their value is equal, then return
1636: true.</p></li>
1637:
1638: <li><p>Otherwise, if either <var title="">A</var> or <var title="">B</var> or both are opaque identifiers, return
1639: false.</p></li>
1640:
1641: <li><p>If <var title="">A</var> and <var title="">B</var> have
1642: scheme components that are not identical, return false.</p></li>
1643:
1644: <li><p>If <var title="">A</var> and <var title="">B</var> have host
1645: components that are not identical, return false.</p></li>
1646:
1647: <li><p>If <var title="">A</var> and <var title="">B</var> have port
1648: components that are not identical, return false.</p></li>
1649:
1650: <li><p>If either <var title="">A</var> or <var title="">B</var>
1651: have additional data, but that data is not identical for both,
1652: return false.</p></li>
1653:
1654: <li><p>Return true.</p></li>
1655:
1.614 mike 1656: </ol></div><h4 id="relaxing-the-same-origin-restriction"><span class="secno">6.4.1 </span>Relaxing the same-origin restriction</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">document</var> . <code title="dom-document-domain"><a href="#dom-document-domain">domain</a></code> [ = <var title="">domain</var> ]</dt>
1.1 mike 1657:
1658: <dd>
1659:
1660: <p>Returns the current domain used for security checks.</p>
1661:
1662: <p>Can be set to a value that removes subdomains, to allow pages
1663: on other subdomains of the same domain (if they do the same thing)
1664: to access each other.</p>
1665:
1666: </dd>
1667:
1668: </dl><div class="impl">
1669:
1670: <p>The <dfn id="dom-document-domain" title="dom-document-domain"><code>domain</code></dfn>
1671: attribute on <code>Document</code> objects must be initialized to
1672: <a href="#the-document-s-domain">the document's domain</a>, if it has one, and the empty
1673: string otherwise. If the value is an IPv6 address, then the square
1674: brackets from the host portion of the <a href="infrastructure.html#url-host" title="url-host"><host></a> component must be omitted from
1675: the attribute's value.</p>
1676:
1677: <p>On getting, the attribute must return its current
1678: value, unless the document was created by
1679: <code>XMLHttpRequest</code>, in which case it must throw an
1680: <code><a href="infrastructure.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception.</p>
1681:
1682: <p>On setting, the user agent must run the following algorithm:</p>
1683:
1684: <ol><li>
1685:
1686: <p>If the document was created by <code>XMLHttpRequest</code>,
1687: throw an <code><a href="infrastructure.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
1688: steps.</p>
1689:
1690: </li>
1691:
1692: <li>
1693:
1694: <p>If the new value is an IP address, let <var title="">new
1695: value</var> be the new value. Otherwise, apply the IDNA ToASCII
1696: algorithm to the new value, with both the AllowUnassigned and
1697: UseSTD3ASCIIRules flags set, and let <var title="">new value</var>
1698: be the result of the ToASCII algorithm.</p>
1699:
1700: <p>If ToASCII fails to convert one of the components of the
1701: string, e.g. because it is too long or because it contains invalid
1702: characters, then throw a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort
1.104 mike 1703: these steps. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1704:
1705: </li>
1706:
1707: <li>
1708:
1709: <p>If <var title="">new value</var> is not exactly equal to the
1710: current value of the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute, then
1711: run these substeps:</p>
1712:
1713: <ol><li>
1714:
1715: <p>If the current value is an IP address, throw a
1716: <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort these steps.</p>
1717:
1718: </li>
1719:
1720: <li>
1721:
1722: <p>If <var title="">new value</var>, prefixed by a U+002E FULL
1.464 mike 1723: STOP (.), does not exactly match the end of the current value,
1.1 mike 1724: throw a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort these
1725: steps.</p>
1726:
1727: </li>
1728:
1729: <li>
1730:
1731: <p>If <var title="">new value</var> matches a suffix in the
1732: Public Suffix List, or, if <var title="">new value</var>,
1.464 mike 1733: prefixed by a U+002E FULL STOP (.), matches the end of a
1.1 mike 1734: suffix in the Public Suffix List, then throw a
1.104 mike 1735: <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception and abort these steps. <a href="references.html#refsPSL">[PSL]</a></p>
1.1 mike 1736:
1737: <p>Suffixes must be compared after applying the IDNA ToASCII
1738: algorithm to them, with both the AllowUnassigned and
1739: UseSTD3ASCIIRules flags set, in an <a href="infrastructure.html#ascii-case-insensitive">ASCII
1.104 mike 1740: case-insensitive</a> manner. <a href="references.html#refsRFC3490">[RFC3490]</a></p>
1.1 mike 1741:
1742: </li>
1743:
1744: </ol></li>
1745:
1.318 mike 1746: <li><p>Release the <a href="#storage-mutex">storage mutex</a>.</p></li>
1747:
1.1 mike 1748: <li>
1749:
1750: <p>Set the attribute's value to <var title="">new value</var>.</p>
1751:
1752: </li>
1753:
1754: <li>
1755:
1756: <p>Set the host part of the <a href="#effective-script-origin">effective script origin</a>
1757: tuple of the <code>Document</code> to <var title="">new
1758: value</var>.</p>
1759:
1760: </li>
1761:
1762: <li>
1763:
1764: <p>Set the port part of the <a href="#effective-script-origin">effective script origin</a>
1765: tuple of the <code>Document</code> to "manual override" (a value
1766: that, for the purposes of <a href="#same-origin" title="same origin">comparing
1767: origins</a>, is identical to "manual override" but not
1768: identical to any other value).</p>
1769:
1770: </li>
1771:
1772: </ol><p>The <dfn id="the-document-s-domain" title="the document's domain">domain</dfn> of a
1773: <code>Document</code> is the host part of the document's
1.159 mike 1774: <a href="#origin">origin</a>, if that is a scheme/host/port tuple. If it
1.1 mike 1775: isn't, then the document does not have a domain.</p>
1776:
1.123 mike 1777: </div><p class="note">The <code title="dom-document-domain"><a href="#dom-document-domain">domain</a></code>
1.1 mike 1778: attribute is used to enable pages on different hosts of a domain to
1.320 mike 1779: access each others' DOMs.</p><p class="warning">Do not use the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute when
1780: using shared hosting. If an untrusted third party is able to host an
1781: HTTP server at the same IP address but on a different port, then the
1782: same-origin protection that normally protects two different sites on
1783: the same host will fail, as the ports are ignored when comparing
1784: origins after the <code title="dom-document-domain"><a href="#dom-document-domain">document.domain</a></code> attribute has
1.614 mike 1785: been used.</p><h3 id="scripting"><span class="secno">6.5 </span>Scripting</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><h4 id="introduction-2"><span class="secno">6.5.1 </span>Introduction</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>Various mechanisms can cause author-provided executable code to
1.1 mike 1786: run in the context of a document. These mechanisms include, but are
1.123 mike 1787: probably not limited to:</p><ul><li>Processing of <code><a href="semantics.html#script">script</a></code> elements.</li>
1.1 mike 1788:
1789: <li>Processing of inline <code title="javascript
1.159 mike 1790: protocol"><a href="#javascript-protocol">javascript:</a></code> URLs (e.g. the <code title="attr-img-src"><a href="text-level-semantics.html#attr-img-src">src</a></code> attribute of <code><a href="text-level-semantics.html#the-img-element">img</a></code>
1.1 mike 1791: elements, or an <code title="">@import</code> rule in a CSS
1792: <code><a href="semantics.html#the-style-element">style</a></code> element block).</li>
1793:
1794: <li>Event handlers, whether registered through the DOM using <code title="">addEventListener()</code>, by explicit <a href="#event-handler-content-attributes">event handler
1.192 mike 1795: content attributes</a>, by <a href="#event-handler-idl-attributes">event handler IDL
1.1 mike 1796: attributes</a>, or otherwise.</li>
1797:
1798: <li>Processing of technologies like XBL or SVG that have their own
1799: scripting features.</li>
1800:
1801: </ul><div class="impl">
1802:
1.614 mike 1803: <h4 id="enabling-and-disabling-scripting"><span class="secno">6.5.2 </span>Enabling and disabling scripting</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1804:
1805: <p><dfn id="concept-bc-script" title="concept-bc-script">Scripting is enabled</dfn> in a
1806: <em><a href="#browsing-context">browsing context</a></em> when all of the
1807: following conditions are true:</p>
1808:
1809: <ul><li>The user agent supports scripting.</li>
1810:
1811: <li>The user has not disabled scripting for this <a href="#browsing-context">browsing
1812: context</a> at this time. (User agents may provide users with
1813: the option to disable scripting globally, or in a finer-grained
1814: manner, e.g. on a per-origin basis.)</li>
1815:
1816: <li id="sandboxScriptBlocked">The <a href="#browsing-context">browsing context</a>
1.159 mike 1817: does not have the <a href="text-level-semantics.html#sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context
1.1 mike 1818: flag</a> set.</li>
1819:
1820: </ul><p><dfn id="concept-bc-noscript" title="concept-bc-noscript">Scripting is disabled</dfn> in a
1821: <a href="#browsing-context">browsing context</a> when any of the above conditions are
1822: false (i.e. when scripting is not <a href="#concept-bc-script" title="concept-bc-script">enabled</a>).</p>
1823:
1824: <hr><p><dfn id="concept-n-script" title="concept-n-script">Scripting is enabled</dfn> for a
1825: <em>node</em> if the <code>Document</code> object of the node (the
1826: node itself, if it is itself a <code>Document</code> object) has an
1827: associated <a href="#browsing-context">browsing context</a>, and <a href="#concept-bc-script" title="concept-bc-script">scripting is enabled</a> in that
1828: <a href="#browsing-context">browsing context</a>.</p>
1829:
1830: <p><dfn id="concept-n-noscript" title="concept-n-noscript">Scripting is disabled</dfn> for a
1831: node if there is no such <a href="#browsing-context">browsing context</a>, or if <a href="#concept-bc-noscript" title="concept-bc-noscript">scripting is disabled</a> in that
1832: <a href="#browsing-context">browsing context</a>.</p>
1833:
1.123 mike 1834: </div><div class="impl">
1.1 mike 1835:
1836: <!-- SCRIPT EXEC (marks areas related to creation of scripts) -->
1.614 mike 1837: <h4 id="processing-model-1"><span class="secno">6.5.3 </span>Processing model</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1838:
1.614 mike 1839: <h5 id="definitions-0"><span class="secno">6.5.3.1 </span>Definitions</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1840:
1841: <p>A <dfn id="concept-script" title="concept-script">script</dfn> has:</p>
1842:
1843: <dl><dt>A <dfn id="script-execution-environment">script execution environment</dfn></dt>
1844:
1845: <dd>
1846:
1847: <p>The characteristics of the script execution environment depend
1848: on the language, and are not defined by this specification.</p>
1849:
1850: <p class="example">In JavaScript, the script execution environment
1851: consists of the interpreter, the stack of <i>execution
1852: contexts</i>, the <i>global code</i> and <i>function code</i> and
1853: the Function objects resulting, and so forth.</p>
1854:
1855: </dd>
1856:
1857: <dt>A <dfn id="list-of-code-entry-points">list of code entry-points</dfn></dt>
1858:
1859: <dd>
1860:
1861: <p>Each code entry-point represents a block of executable code
1862: that the script exposes to other scripts and to the user
1863: agent.</p>
1864:
1865: <p class="example">Each Function object in a JavaScript
1866: <a href="#script-execution-environment">script execution environment</a> has a corresponding code
1867: entry-point, for instance.</p>
1868:
1869: <p>The main program code of the script, if any, is the
1870: <dfn id="initial-code-entry-point"><i>initial code entry-point</i></dfn>. Typically, the code
1871: corresponding to this entry-point is executed immediately after
1872: the script is parsed.</p>
1873:
1874: <p class="example">In JavaScript, this corresponds to the
1875: execution context of the global code.</p>
1876:
1877: </dd>
1878:
1879: <dt>A relationship with the <dfn id="script-s-global-object">script's global object</dfn></dt>
1880:
1881: <dd>
1882:
1883: <p>An object that provides the APIs that the code can use.</p>
1884:
1885: <p class="example">This is typically a <code><a href="#window">Window</a></code>
1886: object. In JavaScript, this corresponds to the <i>global
1887: object</i>.</p>
1888:
1889: <p class="note">When a <a href="#script-s-global-object">script's global object</a> is an
1890: empty object, it can't do anything that interacts with the
1891: environment.</p>
1892:
1893: <p>If the <a href="#script-s-global-object">script's global object</a> is a
1894: <code><a href="#window">Window</a></code> object, then in JavaScript, the <code title="">this</code> keyword in the global scope must return the
1895: <code><a href="#window">Window</a></code> object's <code><a href="#windowproxy">WindowProxy</a></code> object.</p>
1896:
1897: <p class="note">This is a <a href="introduction.html#willful-violation">willful violation</a> of the
1898: JavaScript specification current at the time of writing
1899: (ECMAScript edition 3). The JavaScript specification requires that
1900: the <code title="">this</code> keyword in the global scope return
1901: the global object, but this is not compatible with the security
1.104 mike 1902: design prevalent in implementations as specified herein. <a href="references.html#refsECMA262">[ECMA262]</a></p>
1.1 mike 1903:
1904: </dd>
1905:
1906: <dt>A relationship with the <dfn id="script-s-browsing-context">script's browsing context</dfn></dt>
1907:
1908: <dd>
1909:
1910: <p>A <a href="#browsing-context">browsing context</a> that is assigned responsibility
1911: for actions taken by the script.</p>
1912:
1913: <p class="example">When a script creates and <a href="history.html#navigate" title="navigate">navigates</a> a new <a href="#top-level-browsing-context">top-level browsing
1914: context</a>, the <code title="dom-opener"><a href="#dom-opener">opener</a></code>
1915: attribute of the new <a href="#browsing-context">browsing context</a>'s
1916: <code><a href="#window">Window</a></code> object will be set to the <a href="#script-s-browsing-context">script's
1917: browsing context</a>'s <code><a href="#windowproxy">WindowProxy</a></code> object.</p>
1918:
1919: </dd>
1920:
1921: <dt>A <dfn id="script-s-url-character-encoding" title="script's URL character encoding">URL character encoding</dfn></dt>
1922:
1923: <dd>
1924:
1925: <p>A character encoding, set when the script is created, used to
1926: encode URLs. <span id="sce-not-copy">If the character encoding is
1927: set from another source, e.g. a <a href="dom.html#document-s-character-encoding">document's character
1928: encoding</a>, then the <a href="#script-s-url-character-encoding">script's URL character
1929: encoding</a> must follow the source, so that if the source's
1930: changes, so does the script's.</span></p>
1931:
1932: </dd>
1933:
1934: <dt>A <dfn id="script-s-base-url" title="script's base URL">base URL</dfn></dt>
1935:
1936: <dd>
1937:
1938: <p>A <a href="infrastructure.html#url">URL</a>, set when the script is created, used to
1939: resolve relative URLs. <span id="sbu-not-copy">If the base URL is
1940: set from another source, e.g. a <a href="infrastructure.html#document-base-url">document base URL</a>,
1941: then the <a href="#script-s-base-url">script's base URL</a> must follow the source, so
1942: that if the source's changes, so does the script's.</span></p>
1943:
1944: </dd>
1945:
1.123 mike 1946: </dl></div><div class="impl">
1.1 mike 1947:
1.614 mike 1948: <h5 id="calling-scripts"><span class="secno">6.5.3.2 </span>Calling scripts</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1949:
1950: <p>When a user agent is to <dfn id="jump-to-a-code-entry-point">jump to a code entry-point</dfn> for
1951: a <a href="#concept-script" title="concept-script">script</a>, for example to invoke
1952: an event listener defined in that <a href="#concept-script" title="concept-script">script</a>, the user agent must run the
1953: following steps:</p>
1954:
1955: <ol><li><p>If the <a href="#script-s-global-object">script's global object</a> is a
1956: <code><a href="#window">Window</a></code> object whose <code>Document</code> object is
1957: not <a href="#fully-active">fully active</a>, then abort these steps without doing
1958: anything. The callback is not fired.</p>
1959:
1960: </li><li><p>Set the <a href="#first-script">first script</a> to be the <a href="#concept-script" title="concept-script">script</a> being invoked.</p></li>
1961:
1962: <li><p>Make the <a href="#script-execution-environment" title="script execution environment">script
1963: execution environment</a> for the <a href="#concept-script" title="concept-script">script</a> execute the code for the given
1964: code entry-point.</p></li>
1965:
1966: <li><p>Set the <a href="#first-script">first script</a> back to whatever it was
1967: when this algorithm started.</p></li>
1968:
1969: </ol><p>This algorithm is not invoked by one script calling another.</p>
1970:
1.123 mike 1971: </div><div class="impl">
1.1 mike 1972:
1.614 mike 1973: <h5 id="creating-scripts"><span class="secno">6.5.3.3 </span>Creating scripts</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 1974:
1975: <p>When the specification says that a <a href="#concept-script" title="concept-script">script</a> is to be <dfn id="create-a-script" title="create a
1976: script">created</dfn>, given some script source, its scripting
1.532 mike 1977: language, a global object, a browsing context, a URL character
1978: encoding, and a base URL, the user agent must run the following
1979: steps:</p>
1.1 mike 1980:
1981: <ol><li><p>If <a href="#concept-bc-noscript" title="concept-bc-noscript">scripting is
1982: disabled</a> for <a href="#browsing-context">browsing context</a> passed to this
1983: algorithm, then abort these steps, as if the script did nothing but
1984: return void.</p>
1985:
1986: </li><li><p>Set up a <a href="#script-execution-environment">script execution environment</a> as
1987: appropriate for the scripting language.</p></li>
1988:
1989: <li><p>Parse/compile/initialize the source of the script using the
1990: <a href="#script-execution-environment">script execution environment</a>, as appropriate for the
1991: scripting language, and thus obtain the <a href="#list-of-code-entry-points">list of code
1992: entry-points</a> for the script. If the semantics of the
1993: scripting language and the given source code are such that there is
1994: executable code to be immediately run, then the <i><a href="#initial-code-entry-point">initial code
1995: entry-point</a></i> is the entry-point for that code.</p></li>
1996:
1997: <li><p>Set up the <a href="#script-s-global-object">script's global object</a>, the
1998: <a href="#script-s-browsing-context">script's browsing context</a>, the <a href="#script-s-url-character-encoding">script's URL
1999: character encoding</a>, and the <a href="#script-s-base-url">script's base URL</a>
2000: from the settings passed to this algorithm.</p></li>
2001:
2002: <li><p><a href="#jump-to-a-code-entry-point" title="jump to a code entry-point">Jump</a> to the
2003: <a href="#concept-script" title="concept-script">script</a>'s <i><a href="#initial-code-entry-point">initial code
2004: entry-point</a></i>.</p></li>
2005:
2006: </ol><hr><p>When the user agent is to <dfn id="create-an-impotent-script">create an impotent script</dfn>,
2007: given some script source, its scripting language, and a browsing
2008: context, the user agent must <a href="#create-a-script">create a script</a>, using the
2009: given script source and scripting language, using a new empty object
2010: as the global object, and using the given browsing context as the
1.532 mike 2011: browsing context. The URL character encoding and base URL for the
1.1 mike 2012: resulting <a href="#concept-script" title="concept-script">script</a> are not
2013: important as no APIs are exposed to the script.</p>
2014:
2015: <hr><p>When the specification says that a <a href="#concept-script" title="concept-script">script</a> is to be <dfn id="create-a-script-from-a-node" title="create a
2016: script from a node">created from a node</dfn> <var title="">node</var>, given some script source and its scripting
2017: language, the user agent must <a href="#create-a-script">create a script</a>, using
2018: the given script source and scripting language, and using <a href="#the-script-settings-determined-from-the-node">the
2019: script settings determined from the node</a> <var title="">node</var>.</p>
2020:
2021: <p><dfn id="the-script-settings-determined-from-the-node">The script settings determined from the node</dfn> <var title="">node</var> are computed as follows:</p>
2022:
2023: <ol><li><p>Let <var title="">document</var> be the
2024: <code>Document</code> of <var title="">node</var> (or <var title="">node</var> itself if it is a
2025: <code>Document</code>).</p></li>
2026:
2027: <li><p>The browsing context is the <a href="#browsing-context">browsing context</a> of
2028: <var title="">document</var>.</p>
2029:
2030: </li><li><p>The global object is the <code><a href="#window">Window</a></code> object of
2031: <var title="">document</var>.</p></li>
2032:
1.449 mike 2033: <li><p>The URL character encoding is the <a href="dom.html#document-s-character-encoding" title="document's
1.1 mike 2034: character encoding">character encoding</a> of <var title="">document</var>. (<a href="#sce-not-copy">This is a
2035: reference, not a copy</a>.)</p></li>
2036:
2037: <li><p>The base URL is the <a href="infrastructure.html#document-base-url" title="document base URL">base
2038: URL</a> of <var title="">document</var>. (<a href="#sbu-not-copy">This is a reference, not a copy</a>.)</p></li>
2039:
1.123 mike 2040: </ol></div><div class="impl">
1.1 mike 2041:
1.614 mike 2042: <h5 id="killing-scripts"><span class="secno">6.5.3.4 </span>Killing scripts</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2043:
2044: <p>User agents may impose resource limitations on scripts, for
2045: example CPU quotas, memory limits, total execution time limits, or
2046: bandwidth limitations. When a script exceeds a limit, the user agent
2047: may either throw a <code><a href="infrastructure.html#quota_exceeded_err">QUOTA_EXCEEDED_ERR</a></code> exception, abort
2048: the script without an exception, prompt the user, or throttle script
2049: execution.</p>
2050:
2051: <div class="example">
2052:
2053: <p>For example, the following script never terminates. A user agent
2054: could, after waiting for a few seconds, prompt the user to either
2055: terminate the script or let it continue.</p>
2056:
2057: <pre><script>
2058: while (true) { /* loop */ }
2059: </script></pre>
2060:
2061: </div>
2062:
2063: <p>User agents are encouraged to allow users to disable scripting
2064: whenever the user is prompted either by a script (e.g. using the
2065: <code title="dom-alert"><a href="#dom-alert">window.alert()</a></code> API) or because of a
2066: script's actions (e.g. because it has exceeded a time limit).</p>
2067:
2068: <p>If scripting is disabled while a script is executing, the script
2069: should be terminated immediately.</p>
2070:
1.123 mike 2071: </div><div class="impl">
1.1 mike 2072:
1.614 mike 2073: <h4 id="event-loops"><span class="secno">6.5.4 </span>Event loops</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2074:
1.614 mike 2075: <h5 id="definitions-1"><span class="secno">6.5.4.1 </span>Definitions</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2076:
2077: <p>To coordinate events, user interaction, scripts, rendering,
2078: networking, and so forth, user agents must use <dfn id="event-loop" title="event
2079: loop">event loops</dfn> as described in this section.</p>
2080:
2081: <p>There must be at least one <a href="#event-loop">event loop</a> per user
2082: agent, and at most one <a href="#event-loop">event loop</a> per <a href="#unit-of-related-similar-origin-browsing-contexts">unit of
2083: related similar-origin browsing contexts</a>.</p>
2084:
2085: <p>An <a href="#event-loop">event loop</a> always has at least one <a href="#browsing-context">browsing
2086: context</a>. If an <a href="#event-loop">event loop</a>'s <a href="#browsing-context" title="browsing context">browsing contexts</a> all go away, then
2087: the <a href="#event-loop">event loop</a> goes away as well. A <a href="#browsing-context">browsing
2088: context</a> always has an <a href="#event-loop">event loop</a> coordinating
2089: its activities.</p>
2090:
1.669 mike 2091:
1.1 mike 2092: <p class="note">Other specifications can define new kinds of event
1.240 mike 2093: loops that aren't associated with browsing contexts; in particular,
2094: the Web Workers specification does so.</p>
1.669 mike 2095:
1.1 mike 2096:
2097: <p>An <a href="#event-loop">event loop</a> has one or more <dfn id="task-queue" title="task
2098: queue">task queues</dfn>. A <a href="#task-queue">task queue</a> is an ordered
2099: list of <dfn id="concept-task" title="concept-task">tasks</dfn>, which can be:</p>
2100:
2101: <dl><dt>Events</dt>
2102:
2103: <dd>
2104:
2105: <p>Asynchronously dispatching an <code>Event</code> object at a
2106: particular <code>EventTarget</code> object is a task.</p>
2107:
2108: <p class="note">Not all events are dispatched using the <a href="#task-queue">task
2109: queue</a>, many are dispatched synchronously during other
2110: tasks.</p>
2111:
2112: </dd>
2113:
2114:
2115: <dt>Parsing</dt>
2116:
2117: <dd><p>The <a href="syntax.html#html-parser">HTML parser</a> tokenizing a single byte, and
2118: then processing any resulting tokens, is a task.</p></dd>
2119:
2120:
2121: <dt>Callbacks</dt>
2122:
2123: <dd><p>Calling a callback asynchronously is a task.</p></dd>
2124:
2125:
2126: <dt>Using a resource</dt>
2127:
2128: <dd><p>When an algorithm <a href="infrastructure.html#fetch" title="fetch">fetches</a> a
2129: resource, if the fetching occurs asynchronously then the processing
2130: of the resource once some or all of the resource is available is a
2131: task.</p></dd>
2132:
2133:
2134: <dt>Reacting to DOM manipulation</dt>
2135:
2136: <dd><p>Some elements have tasks that trigger in response to DOM
2137: manipulation, e.g. when that element is <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an
2138: element into a document">inserted into the document</a>.</p>
2139:
2140: </dd></dl><p>When a user agent is to <dfn id="queue-a-task">queue a task</dfn>, it must add the
2141: given task to one of the <a href="#task-queue" title="task queue">task queues</a>
2142: of the relevant <a href="#event-loop">event loop</a>. All the tasks from one
2143: particular <dfn id="task-source">task source</dfn> (e.g. the callbacks generated by
2144: timers, the events dispatched for mouse movements, the tasks queued
2145: for the parser) must always be added to the same <a href="#task-queue">task
2146: queue</a>, but tasks from different <a href="#task-source" title="task
2147: source">task sources</a> may be placed in different <a href="#task-queue" title="task queue">task queues</a>.</p>
2148:
2149: <p class="example">For example, a user agent could have one
2150: <a href="#task-queue">task queue</a> for mouse and key events (the <a href="#user-interaction-task-source">user
2151: interaction task source</a>), and another for everything
2152: else. The user agent could then give keyboard and mouse events
2153: preference over other tasks three quarters of the time, keeping the
2154: interface responsive but not starving other task queues, and never
2155: processing events from any one <a href="#task-source">task source</a> out of
2156: order.</p>
2157:
2158: <p>Each <a href="#concept-task" title="concept-task">task</a> that is <a href="#queue-a-task" title="queue a task">queued</a> onto a <a href="#task-queue">task queue</a> of
2159: an <a href="#event-loop">event loop</a> defined by this specification is
2160: associated with a <code>Document</code>; if the task was queued in
2161: the context of an element, then it is the element's
2162: <code>Document</code>; if the task was queued in the context of a
2163: <a href="#browsing-context">browsing context</a>, then it is the <a href="#browsing-context">browsing
2164: context</a>'s <a href="#active-document">active document</a> at the time the task
2165: was queued; if the task was queued by or for a <a href="#concept-script" title="concept-script">script</a> then the document is the
2166: <a href="#script-s-browsing-context">script's browsing context</a>'s <a href="#active-document">active
2167: document</a> at the time the task was queued.</p>
2168:
2169: <p>A user agent is required to have one <dfn id="storage-mutex">storage
2170: mutex</dfn>. This mutex is used to control access to shared state
2171: like cookies. At any one point, the <a href="#storage-mutex">storage mutex</a> is
2172: either free, or owned by a particular <a href="#event-loop">event loop</a> or
2173: instance of the <a href="infrastructure.html#fetch" title="fetch">fetching</a> algorithm.</p>
2174:
2175: <p>Whenever a <a href="#concept-script" title="concept-script">script</a> calls into
2176: a <a href="infrastructure.html#plugin">plugin</a>, and whenever a <a href="infrastructure.html#plugin">plugin</a> calls into
2177: a <a href="#concept-script" title="concept-script">script</a>, the user agent must
2178: release the <a href="#storage-mutex">storage mutex</a>.</p>
2179:
2180:
1.614 mike 2181: <h5 id="processing-model-2"><span class="secno">6.5.4.2 </span>Processing model</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2182:
2183: <p>An <a href="#event-loop">event loop</a> must continually run through the
2184: following steps for as long as it exists:</p>
2185:
2186: <ol><li><p>Run the oldest <a href="#concept-task" title="concept-task">task</a> on one
2187: of the <a href="#event-loop">event loop</a>'s <a href="#task-queue" title="task queue">task
2188: queues</a>, ignoring tasks whose associated
2189: <code>Document</code>s are not <a href="#fully-active">fully active</a>. The user
2190: agent may pick any <a href="#task-queue">task queue</a>.</p></li>
2191:
2192: <li><p>If the <a href="#storage-mutex">storage mutex</a> is now owned by the
2193: <a href="#event-loop">event loop</a>, release it so that it is once again
2194: free.</p>
2195:
2196: </li><li><p>Remove that task from its <a href="#task-queue">task queue</a>.</p></li>
2197:
1.16 mike 2198: <li><p>If any asynchronously-running algorithms are <dfn id="await-a-stable-state" title="await a stable state">awaiting a stable state</dfn>, then
2199: run their <dfn id="synchronous-section">synchronous section</dfn> and then resume running
2200: their asynchronous algorithm.</p>
2201:
2202: <p class="note">A <a href="#synchronous-section">synchronous section</a> never mutates
1.564 mike 2203: the DOM, runs any script, or has any other side-effects.</p>
1.16 mike 2204:
2205: <p class="note">Steps in <a href="#synchronous-section" title="synchronous
2206: section">synchronous sections</a> are marked with
2207: ⌛.</p></li>
2208:
1.1 mike 2209: <li><p>If necessary, update the rendering or user interface of any
2210: <code>Document</code> or <a href="#browsing-context">browsing context</a> to reflect
2211: the current state.</p></li>
2212:
2213: <li><p>Return to the first step of the <a href="#event-loop">event
2214: loop</a>.</p></li>
2215:
1.484 mike 2216: </ol><hr><p>When an algorithm says to <dfn id="spin-the-event-loop">spin the event loop</dfn> until
2217: a condition <var title="">goal</var> is met, the user agent must run
2218: the following steps:</p>
2219:
2220: <ol><li><p>Let <var title="">task source</var> be the <a href="#task-source">task
2221: source</a> of the currently running <a href="#concept-task" title="concept-task">task</a>.</p></li>
2222:
2223: <li><p>Stop the currently running <a href="#concept-task" title="concept-task">task</a>, allowing the <a href="#event-loop">event
2224: loop</a> to resume, but continue these steps
2225: asynchronously.</p></li>
2226:
2227: <li><p>Wait until the condition <var title="">goal</var> is
2228: met.</p></li>
2229:
2230: <li><p><a href="#queue-a-task">Queue a task</a> to continue running these steps,
2231: using the <a href="#task-source">task source</a> <var title="">task
2232: source</var>. Wait until this task runs before continuing these
2233: steps.</p></li>
2234:
2235: <li><p>Return to the caller.</p></li>
2236:
1.1 mike 2237: </ol><hr><p>Some of the algorithms in this specification, for historical
2238: reasons, require the user agent to <dfn id="pause">pause</dfn> while running a
2239: <a href="#concept-task" title="concept-task">task</a> until some condition has been
2240: met. While a user agent has a paused <a href="#concept-task" title="concept-task">task</a>, the corresponding <a href="#event-loop">event
2241: loop</a> must not run further <a href="#concept-task" title="concept-task">tasks</a>, and any script in the currently
2242: running <a href="#concept-task" title="concept-task">task</a> must block. User
2243: agents should remain responsive to user input while paused, however,
2244: albeit in a reduced capacity since the <a href="#event-loop">event loop</a> will
2245: not be doing anything.</p>
2246:
2247: <hr><p>When a user agent is to <dfn id="obtain-the-storage-mutex">obtain the storage mutex</dfn> as
2248: part of running a <a href="#concept-task" title="concept-task">task</a>, it must
2249: run through the following steps:</p>
2250:
2251: <ol><li><p>If the <a href="#storage-mutex">storage mutex</a> is already owned by this
2252: <a href="#concept-task" title="concept-task">task</a>'s <a href="#event-loop">event loop</a>,
2253: then abort these steps.</p></li>
2254:
2255: <li><p>Otherwise, <a href="#pause">pause</a> until the <a href="#storage-mutex">storage
2256: mutex</a> can be taken by the <a href="#event-loop">event loop</a>.</p></li>
2257:
2258: <li><p>Take ownership of the <a href="#storage-mutex">storage mutex</a>.</p></li>
2259:
1.123 mike 2260: </ol></div><div class="impl">
1.1 mike 2261:
1.614 mike 2262: <h5 id="generic-task-sources"><span class="secno">6.5.4.3 </span>Generic task sources</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2263:
2264: <p>The following <a href="#task-source" title="task source">task sources</a> are
2265: used by a number of mostly unrelated features in this and other
2266: specifications.</p>
2267:
2268: <dl><dt>The <dfn id="dom-manipulation-task-source">DOM manipulation task source</dfn></dt>
2269:
2270: <dd>
2271:
2272: <p>This <a href="#task-source">task source</a> is used for features that react
2273: to DOM manipulations, such as things that happen asynchronously
2274: when an element is <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a
2275: document">inserted into the document</a>.</p>
2276:
2277: <!--
2278: <p>Asynchronous mutation events must be dispatched using <span
2279: title="concept-task">tasks</span> <span title="queue a
2280: task">queued</span> with the <span>DOM manipulation task
1.104 mike 2281: source</span>. <a href="#refsDOMEVENTS">[DOMEVENTS]</a></p>
1.1 mike 2282: -->
2283:
2284: </dd>
2285:
2286: <dt>The <dfn id="user-interaction-task-source">user interaction task source</dfn></dt>
2287:
2288: <dd>
2289:
2290: <p>This <a href="#task-source">task source</a> is used for features that react
2291: to user interaction, for example keyboard or mouse input.</p>
2292:
2293: <p>Asynchronous events sent in response to user input (e.g. <span title="event-click">click</span> events) must be dispatched using
2294: <a href="#concept-task" title="concept-task">tasks</a> <a href="#queue-a-task" title="queue a
2295: task">queued</a> with the <a href="#user-interaction-task-source">user interaction task
1.104 mike 2296: source</a>. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
1.1 mike 2297:
2298: </dd>
2299:
2300: <dt>The <dfn id="networking-task-source">networking task source</dfn></dt>
2301:
2302: <dd>
2303:
2304: <p>This <a href="#task-source">task source</a> is used for features that trigger
2305: in response to network activity.</p>
2306:
2307: <!-- XHR should use this -->
2308:
2309: </dd>
2310:
1.123 mike 2311: </dl></div><div class="impl">
1.1 mike 2312:
2313: <!-- SCRIPT EXEC -->
1.614 mike 2314: <h4 id="javascript-protocol"><span class="secno">6.5.5 </span><dfn title="javascript protocol">The <code title="">javascript:</code> protocol</dfn></h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2315:
2316: <p>When a <a href="infrastructure.html#url">URL</a> using the <code title="">javascript:</code> protocol is <dfn id="concept-js-deref" title="concept-js-deref">dereferenced</dfn>, the user agent must run
2317: the following steps:</p>
2318:
2319: <ol><li><p>Let the script source be the string obtained using the
1.104 mike 2320: content retrieval operation defined for <code title="">javascript:</code> URLs. <a href="references.html#refsJSURL">[JSURL]</a></p></li>
1.1 mike 2321:
2322: <li>
2323:
2324: <p>Use the appropriate step from the following list:</p>
2325:
2326: <dl><dt>If a <a href="#browsing-context">browsing context</a> is being <a href="history.html#navigate" title="navigate">navigated</a> to a <code>javascript:</code>
2327: URL, and the <a href="#active-document">active document</a> of that browsing
2328: context has the <a href="#same-origin">same origin</a> as the script given by
2329: that URL</dt>
2330:
2331: <dd>
2332:
2333: <!-- http://www.hixie.ch/tests/adhoc/html/navigation/javascript-url/ -->
2334:
2335: <p>Let <var title="">address</var> be the <a href="dom.html#the-document-s-address" title="the
2336: document's address">address</a> of the <a href="#active-document">active
2337: document</a> of the <a href="#browsing-context">browsing context</a> being
2338: navigated.</p>
2339:
2340: <p>If <var title="">address</var> is <code><a href="infrastructure.html#about:blank">about:blank</a></code>,
2341: and the <a href="#browsing-context">browsing context</a> being navigated has a
2342: <a href="#creator-browsing-context">creator browsing context</a>, then let <var title="">address</var> be the <a href="dom.html#the-document-s-address" title="the document's
2343: address">address</a> of the <a href="#creator-document">creator
2344: <code>Document</code></a> instead.</p>
2345:
2346: <p><a href="#create-a-script-from-a-node" title="create a script from a node">Create a
2347: script</a> from the <code>Document</code> node of the
2348: <a href="#active-document">active document</a>, using the aforementioned script
2349: source, and assuming the scripting language is JavaScript.</p>
2350:
2351: <p>Let <var title="">result</var> be the return value of the
2352: <i><a href="#initial-code-entry-point">initial code entry-point</a></i> of this <a href="#concept-script" title="concept-script">script</a>. If an exception was
2353: raised, let <var title="">result</var> be void instead. (The
2354: result will be void also if <a href="#concept-bc-noscript" title="concept-bc-noscript">scripting is disabled</a>.)</p>
2355:
2356: <p>When it comes time to <a href="history.html#set-the-document-s-address">set the document's address</a>
2357: in the <a href="history.html#navigate" title="navigate">navigation algorithm</a>, use
2358: <var title="">address</var> as the <a href="history.html#override-url">override
2359: URL</a>.</p>
2360:
2361: </dd>
2362:
2363: <dt>If the <code>Document</code> object of the element,
2364: attribute, or style sheet from which the <code>javascript:</code>
2365: URL was reached has an associated <a href="#browsing-context">browsing
2366: context</a></dt>
2367:
2368: <dd>
2369:
2370: <p><a href="#create-an-impotent-script">Create an impotent script</a> using the
2371: aforementioned script source, with the scripting language set to
2372: JavaScript, and with the <code>Document</code>'s object's
2373: <a href="#browsing-context">browsing context</a> as the browsing context.</p>
2374:
2375: <p>Let <var title="">result</var> be the return value of the
2376: <i><a href="#initial-code-entry-point">initial code entry-point</a></i> of this <a href="#concept-script" title="concept-script">script</a>. If an exception was
2377: raised, let <var title="">result</var> be void instead. (The
2378: result will be void also if <a href="#concept-bc-noscript" title="concept-bc-noscript">scripting is disabled</a>.)</p>
2379:
2380: </dd>
2381:
2382: <dt>Otherwise</dt>
2383:
2384: <dd>
2385:
2386: <p>Let <var title="">result</var> be void.</p>
2387:
2388: </dd>
2389:
2390: </dl></li>
2391:
2392: <li>
2393:
2394: <p>If the result of executing the script is void (there is no
2395: return value), then the URL must be treated in a manner equivalent
2396: to an HTTP resource with an HTTP 204 No Content response.</p>
2397:
2398: <p>Otherwise, the URL must be treated in a manner equivalent to an
1.83 mike 2399: HTTP resource with a 200 OK response whose <a href="infrastructure.html#content-type" title="Content-Type">Content-Type metadata</a> is
1.605 mike 2400: <code><a href="iana.html#text-html">text/html</a></code> and whose response body is the return value
1.83 mike 2401: converted to a string value.</p>
1.1 mike 2402:
1.159 mike 2403: <p class="note">Certain contexts, in particular <code><a href="text-level-semantics.html#the-img-element">img</a></code>
1.1 mike 2404: elements, ignore the <a href="infrastructure.html#content-type" title="Content-Type">Content-Type
2405: metadata</a>.</p>
2406:
2407: </li>
2408:
2409: </ol><div class="example">
2410:
2411: <p>So for example a <code title="">javascript:</code> URL for a
1.159 mike 2412: <code title="attr-img-src"><a href="text-level-semantics.html#attr-img-src">src</a></code> attribute of an
2413: <code><a href="text-level-semantics.html#the-img-element">img</a></code> element would be evaluated in the context of an
1.1 mike 2414: empty object as soon as the attribute is set; it would then be
2415: sniffed to determine the image type and decoded as an image.</p>
2416:
2417: <p>A <code title="">javascript:</code> URL in an <code title="attr-hyperlink-href"><a href="history.html#attr-hyperlink-href">href</a></code> attribute of an <code><a href="text-level-semantics.html#the-a-element">a</a></code>
2418: element would only be evaluated when the link was <a href="history.html#following-hyperlinks" title="following hyperlinks">followed</a>.</p>
2419:
1.159 mike 2420: <p>The <code title="attr-iframe-src"><a href="text-level-semantics.html#attr-iframe-src">src</a></code> attribute of an
2421: <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code> element would be evaluated in the context of
2422: the <code><a href="text-level-semantics.html#the-iframe-element">iframe</a></code>'s own <a href="#browsing-context">browsing context</a>; once
1.1 mike 2423: evaluated, its return value (if it was not void) would replace that
2424: <a href="#browsing-context">browsing context</a>'s document, thus changing the
2425: variables visible in that <a href="#browsing-context">browsing context</a>.</p>
2426:
2427: </div>
2428:
1.159 mike 2429: </div><h4 id="events"><span class="secno">6.5.6 </span>Events</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><div class="impl">
1.1 mike 2430:
1.614 mike 2431: <h5 id="event-handler-attributes"><span class="secno">6.5.6.1 </span>Event handlers</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2432:
1.416 mike 2433: </div><!--test: <a href="http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C!DOCTYPE%20html%3E%0A...%3Cscript%3E%0Aw(a%3Ddocument.implementation.createDocument(null%2C%20null%2C%20null))%3B%0Aw(a.appendChild(a.createElementNS('https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttp%2Fwww.w3.org%2F1999%2Fxhtml'%2C%20'html')))%3B%0Aw(b%3Da.firstChild.appendChild(a.createElementNS('https%3A%2F%2F2.zoppoz.workers.dev%3A443%2Fhttp%2Fwww.w3.org%2F1999%2Fxhtml'%2C%20'body')))%3B%0Aw(b.test%20%3D%20w)%3B%0Aw(b.setAttribute('onclick'%2C%20'test(%22fire%3A%20%22%20%2B%20event)'))%3B%0Aw(b.onclick)%3B%0Aw(e%3Da.createEvent('Event'))%3B%0Aw(e.initEvent('click'%2C%20false%2C%20false))%3B%0Aw(b.dispatchEvent(e))%3B%0A%3C%2Fscript%3E">test</a>--><p>Many objects can have <dfn id="event-handlers">event handlers</dfn> specified. These
2434: act as bubbling event listeners for the object on which they are
2435: specified.</p><p>An <a href="#event-handlers" title="event handlers">event handler</a> can either
2436: have the value null or be set to a <code><a href="#function">Function</a></code>
2437: object. <span class="impl">Initially, event handlers must be set to
2438: null.</span></p><p>Event handlers are exposed in one or two ways.</p><p>The first way, common to all event handlers, is as an <a href="#event-handler-idl-attributes" title="event handler IDL attributes">event handler IDL
1.123 mike 2439: attribute</a>.</p><p>The second way is as an <a href="#event-handler-content-attributes" title="event handler content
1.416 mike 2440: attributes">event handler content attribute</a>. Event handlers
2441: on <a href="infrastructure.html#html-elements">HTML elements</a> and some of the event handlers on
1.123 mike 2442: <code><a href="#window">Window</a></code> objects are exposed in this way.</p><div class="impl">
1.1 mike 2443:
1.192 mike 2444: <hr><p><dfn id="event-handler-idl-attributes">Event handler IDL attributes</dfn>, on setting, must set the
1.416 mike 2445: corresponding event handler to their new value, and on
1.1 mike 2446: getting, must return whatever the current value of the corresponding
1.416 mike 2447: event handler is (possibly null).</p>
1.1 mike 2448:
1.192 mike 2449: <p>If an <a href="#event-handler-idl-attributes" title="event handler IDL attributes">event handler
1.416 mike 2450: IDL attribute</a> exposes an <a href="#event-handlers" title="event handlers">event
2451: handler</a> of an object that doesn't exist, it must always
2452: return null on getting and must do nothing on setting.</p>
1.1 mike 2453:
1.192 mike 2454: <p class="note">This can happen in particular for <a href="#event-handler-idl-attributes" title="event
2455: handler IDL attributes">event handler IDL attribute</a> on
1.159 mike 2456: <code><a href="semantics.html#the-body-element-0">body</a></code> elements that do not have corresponding
1.1 mike 2457: <code><a href="#window">Window</a></code> objects.</p>
2458:
1.192 mike 2459: <p class="note">Certain event handler IDL attributes have additional
1.1 mike 2460: requirements, in particular the <code title="handler-MessagePort-onmessage"><a href="comms.html#handler-messageport-onmessage">onmessage</a></code> attribute of
2461: <code><a href="comms.html#messageport">MessagePort</a></code> objects.</p>
2462:
1.123 mike 2463: <hr></div><p><dfn id="event-handler-content-attributes">Event handler content attributes</dfn>, when specified, must
2464: contain valid JavaScript code matching the <code title="">FunctionBody</code> production. <a href="references.html#refsECMA262">[ECMA262]</a></p><div class="impl">
1.1 mike 2465:
2466: <!-- SCRIPT EXEC -->
2467: <p>When an event handler content attribute is set, if the element is
2468: owned by a <code>Document</code> that is in a <a href="#browsing-context">browsing
2469: context</a>, and <a href="#concept-bc-script" title="concept-bc-script">scripting is
2470: enabled</a> for that <a href="#browsing-context">browsing context</a>, the user
2471: agent must run the following steps to create a <a href="#concept-script" title="concept-script">script</a> after setting the content
2472: attribute to its new value:</p>
2473:
2474: <ol><li><p>Set up a <a href="#script-execution-environment">script execution environment</a> for
2475: JavaScript.</p></li>
2476:
2477: <li>
2478:
2479: <p>Using this script execution environment, interpret the
2480: attribute's new value as the body of an anonymous function, with
2481: the function's arguments set as follows:</p>
2482:
2483: <dl class="switch"><dt>If the attribute is the <code title="handler-window-onerror"><a href="#handler-window-onerror">onerror</a></code> attribute of the
2484: <code><a href="#window">Window</a></code> object</dt>
2485:
2486: <dd>Let the function have three arguments, named <code title="">event</code>, <code title="">source</code>, and <code title="">fileno</code>.</dd>
2487:
2488: <dt>Otherwise</dt>
2489:
2490: <dd>Let the function have a single argument called <code title="">event</code>.</dd>
2491:
2492: </dl><p>Link the new function's scope chain from the activation object
2493: of the handler, to the element's object, to the element's
2494: <a href="forms.html#form-owner">form owner</a>, if it has one, to the element's
2495: <code>Document</code> object, to the <code><a href="#window">Window</a></code> object of
2496: that <code>Document</code>. Set the function's <code>this</code>
2497: parameter to the <code>Element</code> object representing the
2498: element. Let this function be the only entry in the script's
2499: <a href="#list-of-code-entry-points">list of code entry-points</a>.</p>
2500:
2501: <p class="note">See ECMA262 Edition 3, sections 10.1.6 and 10.2.3,
1.104 mike 2502: for more details on activation objects. <a href="references.html#refsECMA262">[ECMA262]</a></p>
1.1 mike 2503:
2504: </li>
2505:
2506: <li><p>If the previous steps failed to compile the script, then set
1.416 mike 2507: the corresponding <a href="#event-handlers" title="event handlers">event handler</a>
2508: to null and abort these steps.</p></li>
1.1 mike 2509:
2510: <li><p>Set up the <a href="#script-s-global-object">script's global object</a>, the
2511: <a href="#script-s-browsing-context">script's browsing context</a>, the <a href="#script-s-url-character-encoding">script's URL
2512: character encoding</a>, and the <a href="#script-s-base-url">script's base URL</a>
2513: from <a href="#the-script-settings-determined-from-the-node">the script settings determined from the node</a> on
2514: which the attribute is being set.</p></li>
2515:
1.416 mike 2516: <li><p>Set the corresponding <a href="#event-handlers" title="event handlers">event
2517: handler</a> to the aforementioned function.</p></li>
1.1 mike 2518:
1.443 mike 2519: </ol><p>When an event handler content attribute is removed, the user
2520: agent must set the corresponding <a href="#event-handlers" title="event handlers">event
2521: handler</a> to null.</p>
2522: <!--
2523: http://software.hixie.ch/utilities/js/live-dom-viewer/saved/245 onload
2524: http://software.hixie.ch/utilities/js/live-dom-viewer/saved/247 onclick
2525: see http://www.w3.org/Bugs/Public/show_bug.cgi?id=7626#c5 for reasoning
2526: -->
2527:
2528: </div><p class="note">When an <a href="#event-handler-content-attributes" title="event handler content
1.1 mike 2529: attributes">event handler content attribute</a> is set on an
2530: element owned by a <code>Document</code> that is not in a
1.417 mike 2531: <a href="#browsing-context">browsing context</a>, the corresponding event handler is
1.443 mike 2532: not changed.</p><!-- v2: we should probably support HTML4's Content-Script-Type header here. --><div class="impl">
1.1 mike 2533:
1.416 mike 2534: <hr><p>All <a href="#event-handlers">event handlers</a> on an element, whether
1.1 mike 2535: set to null or to a <code><a href="#function">Function</a></code> object, must be registered
2536: as event listeners on the element, as if the <code title="dom-EventTarget-addEventListenerNS">addEventListenerNS()</code>
2537: method on the <code>Element</code> object's <code>EventTarget</code>
1.416 mike 2538: interface had been invoked when the event handler's
1.1 mike 2539: element or object was created, with the event type (<var title="dom-event-type">type</var> argument) equal to the type
1.416 mike 2540: corresponding to the event handler (the <dfn id="event-handler-event-type">event handler
1.1 mike 2541: event type</dfn>), the namespace (<var title="dom-event-namespaceURI">namespaceURI</var> argument) set to
2542: null, the listener set to be a target and bubbling phase listener
2543: (<var title="dom-event-useCapture">useCapture</var> argument set to
2544: false), the event group set to the default group (<var title="dom-event-evtGroup">evtGroup</var> argument set to null), and
2545: the event listener itself (<var title="dom-event-listener">listener</var> argument) set to do
1.416 mike 2546: nothing while the event handler's value is not a
1.1 mike 2547: <code><a href="#function">Function</a></code> object, and set to invoke the <code title="dom-function-call"><a href="#dom-function-call">call()</a></code> callback of the
1.416 mike 2548: <code><a href="#function">Function</a></code> object associated with the event handler otherwise.</p>
1.1 mike 2549:
2550: <p class="note">The <var title="dom-event-listener">listener</var>
1.416 mike 2551: argument is emphatically <em>not</em> the <a href="#event-handlers" title="event
2552: handlers">event handler</a> itself.</p>
1.1 mike 2553:
2554: <p class="note">The interfaces implemented by the event object do
1.416 mike 2555: not affect whether an <a href="#event-handlers" title="event handlers">event
2556: handler</a> is used or not.</p>
1.1 mike 2557:
1.416 mike 2558: <p>When an <a href="#event-handlers" title="event handlers">event handler</a>'s
1.1 mike 2559: <code><a href="#function">Function</a></code> object is invoked, its <code title="dom-function-call"><a href="#dom-function-call">call()</a></code> callback must be invoked
2560: with one argument, set to the <code>Event</code> object of the event
2561: in question.</p>
2562:
2563: <p>The handler's return value must then be processed as follows:</p>
2564:
2565: <dl class="switch"><dt>If the event type is <code class="event-mouseover">mouseover</code></dt>
2566:
2567: <dd><p>If the return value is a boolean with the value true, then
2568: the event must be canceled.</p></dd>
2569:
2570: <dt>If the event object is a <code><a href="history.html#beforeunloadevent">BeforeUnloadEvent</a></code> object</dt>
2571:
2572: <dd><p>If the return value is a string, and the event object's
2573: <code title="dom-BeforeUnloadEvent-returnValue"><a href="history.html#dom-beforeunloadevent-returnvalue">returnValue</a></code>
2574: attribute's value is the empty string, then set the <code title="dom-BeforeUnloadEvent-returnValue"><a href="history.html#dom-beforeunloadevent-returnvalue">returnValue</a></code>
2575: attribute's value to the return value.</p></dd>
2576:
2577: <dt>Otherwise</dt>
2578:
2579: <dd><p>If the return value is a boolean with the value false, then
2580: the event must be canceled.</p></dd>
2581:
2582: </dl><!-- IE actually uncancels the event if the function returns true --><hr><p>The <code><a href="#function">Function</a></code> interface represents a function in the
2583: scripting language being used. It is represented in IDL as
2584: follows:</p>
2585:
2586: <pre class="idl">[Callback=FunctionOnly, NoInterfaceObject]
2587: interface <dfn id="function">Function</dfn> {
1.87 mike 2588: any <a href="#dom-function-call" title="dom-function-call">call</a>(in any... arguments);
1.1 mike 2589: };</pre>
2590:
2591: <p>The <dfn id="dom-function-call" title="dom-function-call"><code>call(...)</code></dfn>
2592: method is the object's callback.</p>
2593:
2594: <p class="note">In JavaScript, any <code title="">Function</code>
2595: object implements this interface.</p>
2596:
1.123 mike 2597: </div><div class="impl">
1.1 mike 2598:
1.416 mike 2599: <h5 id="event-handlers-on-elements-document-objects-and-window-objects"><span class="secno">6.5.6.2 </span>Event handlers on elements, <code>Document</code> objects, and <code><a href="#window">Window</a></code> objects</h5>
1.1 mike 2600:
1.416 mike 2601: <p>The following are the <a href="#event-handlers">event handlers</a> (and their
2602: corresponding <a href="#event-handler-event-type" title="event handler event type">event handler
2603: event types</a>) that must be supported by all <a href="infrastructure.html#html-elements">HTML
1.192 mike 2604: elements</a>, as both content attributes and IDL attributes, and
2605: on <code>Document</code> and <code><a href="#window">Window</a></code> objects, as IDL
1.1 mike 2606: attributes.</p>
2607:
1.416 mike 2608: <table><thead><tr><th><a href="#event-handlers" title="event handlers">Event handler</a> </th><th><a href="#event-handler-event-type">Event handler event type</a>
1.394 mike 2609: </th></tr></thead><tbody><tr><td><dfn id="handler-onabort" title="handler-onabort"><code>onabort</code></dfn> </td><td> <code title="event-abort">abort</code>
1.476 mike 2610: </td></tr><tr><td><dfn id="handler-oncanplay" title="handler-oncanplay"><code>oncanplay</code></dfn> </td><td> <code title="event-media-canplay"><a href="video.html#event-media-canplay">canplay</a></code>
2611: </td></tr><tr><td><dfn id="handler-oncanplaythrough" title="handler-oncanplaythrough"><code>oncanplaythrough</code></dfn> </td><td> <code title="event-media-canplaythrough"><a href="video.html#event-media-canplaythrough">canplaythrough</a></code>
1.1 mike 2612: </td></tr><tr><td><dfn id="handler-onchange" title="handler-onchange"><code>onchange</code></dfn> </td><td> <code title="event-change">change</code> <!-- widely used -->
2613: </td></tr><tr><td><dfn id="handler-onclick" title="handler-onclick"><code>onclick</code></dfn> </td><td> <code title="event-click">click</code> <!-- widely used -->
2614: </td></tr><tr><td><dfn id="handler-oncontextmenu" title="handler-oncontextmenu"><code>oncontextmenu</code></dfn> </td><td> <code title="event-contextmenu">contextmenu</code> <!-- widely used -->
2615: </td></tr><tr><td><dfn id="handler-ondblclick" title="handler-ondblclick"><code>ondblclick</code></dfn> </td><td> <code title="event-dblclick">dblclick</code> <!-- widely used -->
2616: </td></tr><tr><td><dfn id="handler-ondrag" title="handler-ondrag"><code>ondrag</code></dfn> </td><td> <code title="event-drag"><a href="editing.html#event-drag">drag</a></code>
2617: </td></tr><tr><td><dfn id="handler-ondragend" title="handler-ondragend"><code>ondragend</code></dfn> </td><td> <code title="event-dragend"><a href="editing.html#event-dragend">dragend</a></code>
2618: </td></tr><tr><td><dfn id="handler-ondragenter" title="handler-ondragenter"><code>ondragenter</code></dfn> </td><td> <code title="event-dragenter"><a href="editing.html#event-dragenter">dragenter</a></code>
2619: </td></tr><tr><td><dfn id="handler-ondragleave" title="handler-ondragleave"><code>ondragleave</code></dfn> </td><td> <code title="event-dragleave"><a href="editing.html#event-dragleave">dragleave</a></code>
2620: </td></tr><tr><td><dfn id="handler-ondragover" title="handler-ondragover"><code>ondragover</code></dfn> </td><td> <code title="event-dragover"><a href="editing.html#event-dragover">dragover</a></code>
2621: </td></tr><tr><td><dfn id="handler-ondragstart" title="handler-ondragstart"><code>ondragstart</code></dfn> </td><td> <code title="event-dragstart"><a href="editing.html#event-dragstart">dragstart</a></code> <!-- widely used -->
2622: </td></tr><tr><td><dfn id="handler-ondrop" title="handler-ondrop"><code>ondrop</code></dfn> </td><td> <code title="event-drop"><a href="editing.html#event-drop">drop</a></code>
1.476 mike 2623: </td></tr><tr><td><dfn id="handler-ondurationchange" title="handler-ondurationchange"><code>ondurationchange</code></dfn> </td><td> <code title="event-media-durationchange"><a href="video.html#event-media-durationchange">durationchange</a></code>
2624: </td></tr><tr><td><dfn id="handler-onemptied" title="handler-onemptied"><code>onemptied</code></dfn> </td><td> <code title="event-media-emptied"><a href="video.html#event-media-emptied">emptied</a></code>
2625: </td></tr><tr><td><dfn id="handler-onended" title="handler-onended"><code>onended</code></dfn> </td><td> <code title="event-media-ended"><a href="video.html#event-media-ended">ended</a></code>
1.1 mike 2626: </td></tr><tr><td><dfn id="handler-onformchange" title="handler-onformchange"><code>onformchange</code></dfn> </td><td> <code title="event-formchange">formchange</code>
2627: </td></tr><tr><td><dfn id="handler-onforminput" title="handler-onforminput"><code>onforminput</code></dfn> </td><td> <code title="event-forminput">forminput</code>
2628: </td></tr><tr><td><dfn id="handler-oninput" title="handler-oninput"><code>oninput</code></dfn> </td><td> <code title="event-input">input</code>
2629: </td></tr><tr><td><dfn id="handler-oninvalid" title="handler-oninvalid"><code>oninvalid</code></dfn> </td><td> <code title="event-invalid">invalid</code>
2630: </td></tr><tr><td><dfn id="handler-onkeydown" title="handler-onkeydown"><code>onkeydown</code></dfn> </td><td> <code title="event-keydown">keydown</code> <!-- widely used -->
2631: </td></tr><tr><td><dfn id="handler-onkeypress" title="handler-onkeypress"><code>onkeypress</code></dfn> </td><td> <code title="event-keypress">keypress</code> <!-- widely used -->
2632: </td></tr><tr><td><dfn id="handler-onkeyup" title="handler-onkeyup"><code>onkeyup</code></dfn> </td><td> <code title="event-keyup">keyup</code> <!-- widely used -->
1.476 mike 2633: </td></tr><tr><td><dfn id="handler-onloadeddata" title="handler-onloadeddata"><code>onloadeddata</code></dfn> </td><td> <code title="event-media-loadeddata"><a href="video.html#event-media-loadeddata">loadeddata</a></code>
2634: </td></tr><tr><td><dfn id="handler-onloadedmetadata" title="handler-onloadedmetadata"><code>onloadedmetadata</code></dfn> </td><td> <code title="event-media-loadedmetadata"><a href="video.html#event-media-loadedmetadata">loadedmetadata</a></code>
2635: </td></tr><tr><td><dfn id="handler-onloadstart" title="handler-onloadstart"><code>onloadstart</code></dfn> </td><td> <code title="event-media-loadstart"><a href="video.html#event-media-loadstart">loadstart</a></code>
1.1 mike 2636: </td></tr><tr><td><dfn id="handler-onmousedown" title="handler-onmousedown"><code>onmousedown</code></dfn> </td><td> <code title="event-mousedown">mousedown</code> <!-- widely used -->
2637: </td></tr><tr><td><dfn id="handler-onmousemove" title="handler-onmousemove"><code>onmousemove</code></dfn> </td><td> <code title="event-mousemove">mousemove</code> <!-- widely used -->
2638: </td></tr><tr><td><dfn id="handler-onmouseout" title="handler-onmouseout"><code>onmouseout</code></dfn> </td><td> <code title="event-mouseout">mouseout</code> <!-- widely used -->
2639: </td></tr><tr><td><dfn id="handler-onmouseover" title="handler-onmouseover"><code>onmouseover</code></dfn> </td><td> <code title="event-mouseover">mouseover</code> <!-- widely used -->
2640: </td></tr><tr><td><dfn id="handler-onmouseup" title="handler-onmouseup"><code>onmouseup</code></dfn> </td><td> <code title="event-mouseup">mouseup</code> <!-- widely used -->
2641: </td></tr><tr><td><dfn id="handler-onmousewheel" title="handler-onmousewheel"><code>onmousewheel</code></dfn> </td><td> <code title="event-mousewheel">mousewheel</code> <!-- widely used -->
1.476 mike 2642: </td></tr><tr><td><dfn id="handler-onpause" title="handler-onpause"><code>onpause</code></dfn> </td><td> <code title="event-media-pause"><a href="video.html#event-media-pause">pause</a></code>
2643: </td></tr><tr><td><dfn id="handler-onplay" title="handler-onplay"><code>onplay</code></dfn> </td><td> <code title="event-media-play"><a href="video.html#event-media-play">play</a></code>
2644: </td></tr><tr><td><dfn id="handler-onplaying" title="handler-onplaying"><code>onplaying</code></dfn> </td><td> <code title="event-media-playing"><a href="video.html#event-media-playing">playing</a></code>
2645: </td></tr><tr><td><dfn id="handler-onprogress" title="handler-onprogress"><code>onprogress</code></dfn> </td><td> <code title="event-media-progress"><a href="video.html#event-media-progress">progress</a></code>
2646: </td></tr><tr><td><dfn id="handler-onratechange" title="handler-onratechange"><code>onratechange</code></dfn> </td><td> <code title="event-media-ratechange"><a href="video.html#event-media-ratechange">ratechange</a></code>
1.1 mike 2647: </td></tr><tr><td><dfn id="handler-onreadystatechange" title="handler-onreadystatechange"><code>onreadystatechange</code></dfn> </td><td> <code title="event-readystatechange">readystatechange</code>
2648: </td></tr><tr><td><dfn id="handler-onscroll" title="handler-onscroll"><code>onscroll</code></dfn> </td><td> <code title="event-scroll">scroll</code> <!-- widely used --> <!-- [CSSOM] -->
1.476 mike 2649: </td></tr><tr><td><dfn id="handler-onseeked" title="handler-onseeked"><code>onseeked</code></dfn> </td><td> <code title="event-media-seeked"><a href="video.html#event-media-seeked">seeked</a></code>
2650: </td></tr><tr><td><dfn id="handler-onseeking" title="handler-onseeking"><code>onseeking</code></dfn> </td><td> <code title="event-media-seeking"><a href="video.html#event-media-seeking">seeking</a></code>
1.1 mike 2651: </td></tr><tr><td><dfn id="handler-onselect" title="handler-onselect"><code>onselect</code></dfn> </td><td> <code title="event-select">select</code> <!-- widely used --> <!-- [CSSOM] -->
2652: </td></tr><tr><td><dfn id="handler-onshow" title="handler-onshow"><code>onshow</code></dfn> </td><td> <code title="event-show">show</code>
1.476 mike 2653: </td></tr><tr><td><dfn id="handler-onstalled" title="handler-onstalled"><code>onstalled</code></dfn> </td><td> <code title="event-media-stalled"><a href="video.html#event-media-stalled">stalled</a></code>
1.1 mike 2654: </td></tr><tr><td><dfn id="handler-onsubmit" title="handler-onsubmit"><code>onsubmit</code></dfn> </td><td> <code title="event-submit">submit</code> <!-- widely used -->
1.476 mike 2655: </td></tr><tr><td><dfn id="handler-onsuspend" title="handler-onsuspend"><code>onsuspend</code></dfn> </td><td> <code title="event-media-suspend"><a href="video.html#event-media-suspend">suspend</a></code>
2656: </td></tr><tr><td><dfn id="handler-ontimeupdate" title="handler-ontimeupdate"><code>ontimeupdate</code></dfn> </td><td> <code title="event-media-timeupdate"><a href="video.html#event-media-timeupdate">timeupdate</a></code>
2657: </td></tr><tr><td><dfn id="handler-onvolumechange" title="handler-onvolumechange"><code>onvolumechange</code></dfn> </td><td> <code title="event-media-volumechange"><a href="video.html#event-media-volumechange">volumechange</a></code>
2658: </td></tr><tr><td><dfn id="handler-onwaiting" title="handler-onwaiting"><code>onwaiting</code></dfn> </td><td> <code title="event-media-waiting"><a href="video.html#event-media-waiting">waiting</a></code>
1.1 mike 2659:
2660: <!-- not supported, use dnd: -->
2661: <!--<tr><td><dfn title="handler-onbeforecopy"><code>onbeforecopy</code></dfn> <td> <code title="event-beforecopy">beforecopy</code>--> <!-- widely used -->
2662: <!--<tr><td><dfn title="handler-oncopy"><code>oncopy</code></dfn> <td> <code title="event-copy">copy</code>--> <!-- widely used -->
2663: <!--<tr><td><dfn title="handler-onpaste"><code>onpaste</code></dfn> <td> <code title="event-paste">paste</code>--> <!-- widely used -->
2664: <!-- not supported yet (v2?): -->
2665: <!--<tr><td><dfn title="handler-onselectstart"><code>onselectstart</code></dfn> <td> <code title="event-selectstart">selectstart</code>--> <!-- widely used -->
1.416 mike 2666: </td></tr></tbody></table><hr><p>The following are the <a href="#event-handlers">event handlers</a> (and their
2667: corresponding <a href="#event-handler-event-type" title="event handler event type">event handler
2668: event types</a>) that must be supported by all <a href="infrastructure.html#html-elements">HTML
1.159 mike 2669: elements</a> other than <code><a href="semantics.html#the-body-element-0">body</a></code>, as both content
1.192 mike 2670: attributes and IDL attributes, and on <code>Document</code> objects,
2671: as IDL attributes:</p>
1.1 mike 2672:
1.416 mike 2673: <table><thead><tr><th><a href="#event-handlers" title="event handlers">Event handler</a> </th><th><a href="#event-handler-event-type">Event handler event type</a>
1.1 mike 2674: </th></tr></thead><tbody><tr><td><dfn id="handler-onblur" title="handler-onblur"><code>onblur</code></dfn> </td><td> <code title="event-blur">blur</code> <!-- widely used -->
1.394 mike 2675: </td></tr><tr><td><dfn id="handler-onerror" title="handler-onerror"><code>onerror</code></dfn> </td><td> <code title="event-error">error</code>
1.1 mike 2676: </td></tr><tr><td><dfn id="handler-onfocus" title="handler-onfocus"><code>onfocus</code></dfn> </td><td> <code title="event-focus">focus</code> <!-- widely used -->
1.394 mike 2677: </td></tr><tr><td><dfn id="handler-onload" title="handler-onload"><code>onload</code></dfn> </td><td> <code title="event-load">load</code>
1.416 mike 2678: </td></tr></tbody></table><hr><p>The following are the <a href="#event-handlers">event handlers</a> (and their
2679: corresponding <a href="#event-handler-event-type" title="event handler event type">event handler
2680: event types</a>) that must be supported by <code><a href="#window">Window</a></code>
2681: objects, as IDL attributes on the <code><a href="#window">Window</a></code> object, and
2682: with corresponding content attributes and IDL attributes exposed on
2683: the <code><a href="semantics.html#the-body-element-0">body</a></code> and <code><a href="obsolete.html#frameset">frameset</a></code> elements:</p>
1.1 mike 2684:
1.416 mike 2685: <table><thead><tr><th><a href="#event-handlers" title="event handlers">Event handler</a> </th><th><a href="#event-handler-event-type">Event handler event type</a>
1.1 mike 2686: </th></tr></thead><tbody><tr><td><dfn id="handler-window-onafterprint" title="handler-window-onafterprint"><code>onafterprint</code></dfn> </td><td> <code title="event-afterprint">afterprint</code>
2687: </td></tr><tr><td><dfn id="handler-window-onbeforeprint" title="handler-window-onbeforeprint"><code>onbeforeprint</code></dfn> </td><td> <code title="event-beforeprint">beforeprint</code>
2688: </td></tr><tr><td><dfn id="handler-window-onbeforeunload" title="handler-window-onbeforeunload"><code>onbeforeunload</code></dfn> </td><td> <code title="event-beforeunload">beforeunload</code>
2689: </td></tr><tr><td><dfn id="handler-window-onblur" title="handler-window-onblur"><code>onblur</code></dfn> </td><td> <code title="event-blur">blur</code>
1.394 mike 2690: </td></tr><tr><td><dfn id="handler-window-onerror" title="handler-window-onerror"><code>onerror</code></dfn> </td><td> <code title="event-error">error</code>
1.1 mike 2691: </td></tr><tr><td><dfn id="handler-window-onfocus" title="handler-window-onfocus"><code>onfocus</code></dfn> </td><td> <code title="event-focus">focus</code>
2692: </td></tr><tr><td><dfn id="handler-window-onhashchange" title="handler-window-onhashchange"><code>onhashchange</code></dfn> </td><td> <code title="event-hashchange">hashchange</code> <!-- new -->
1.394 mike 2693: </td></tr><tr><td><dfn id="handler-window-onload" title="handler-window-onload"><code>onload</code></dfn> </td><td> <code title="event-load">load</code> <!-- widely used -->
1.1 mike 2694: </td></tr><tr><td><dfn id="handler-window-onmessage" title="handler-window-onmessage"><code>onmessage</code></dfn> </td><td> <code title="event-message"><a href="comms.html#event-message">message</a></code> <!-- new for postMessage -->
2695: </td></tr><tr><td><dfn id="handler-window-onoffline" title="handler-window-onoffline"><code>onoffline</code></dfn> </td><td> <code title="event-offline"><a href="offline.html#event-offline">offline</a></code> <!-- new -->
2696: </td></tr><tr><td><dfn id="handler-window-ononline" title="handler-window-ononline"><code>ononline</code></dfn> </td><td> <code title="event-online"><a href="offline.html#event-online">online</a></code> <!-- new -->
1.569 mike 2697: </td></tr><tr><td><dfn id="handler-window-onpagehide" title="handler-window-onpagehide"><code>onpagehide</code></dfn> </td><td> <code title="event-pagehide">pagehide</code> <!-- new -->
2698: </td></tr><tr><td><dfn id="handler-window-onpageshow" title="handler-window-onpageshow"><code>onpageshow</code></dfn> </td><td> <code title="event-pageshow">pageshow</code> <!-- new -->
1.1 mike 2699: </td></tr><tr><td><dfn id="handler-window-onpopstate" title="handler-window-onpopstate"><code>onpopstate</code></dfn> </td><td> <code title="event-popstate"><a href="history.html#event-popstate">popstate</a></code> <!-- new -->
2700: </td></tr><tr><td><dfn id="handler-window-onredo" title="handler-window-onredo"><code>onredo</code></dfn> </td><td> <code title="event-redo"><a href="editing.html#event-redo">redo</a></code> <!-- new -->
2701: </td></tr><tr><td><dfn id="handler-window-onresize" title="handler-window-onresize"><code>onresize</code></dfn> </td><td> <code title="event-resize">resize</code> <!-- widely used --> <!-- [CSSOM] -->
2702: </td></tr><tr><td><dfn id="handler-window-onstorage" title="handler-window-onstorage"><code>onstorage</code></dfn> </td><td> <code title="event-storage">storage</code> <!-- new -->
2703: </td></tr><tr><td><dfn id="handler-window-onundo" title="handler-window-onundo"><code>onundo</code></dfn> </td><td> <code title="event-undo"><a href="editing.html#event-undo">undo</a></code> <!-- new -->
2704: </td></tr><tr><td><dfn id="handler-window-onunload" title="handler-window-onunload"><code>onunload</code></dfn> </td><td> <code title="event-unload">unload</code> <!-- widely used -->
2705: </td></tr></tbody></table><p class="note">The <code title="handler-window-onerror"><a href="#handler-window-onerror">onerror</a></code>
2706: handler is also used for <a href="#runtime-script-errors">reporting script errors</a>.</p>
2707:
1.123 mike 2708: </div><div class="impl">
1.1 mike 2709:
1.614 mike 2710: <h5 id="event-firing"><span class="secno">6.5.6.3 </span>Event firing</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2711:
2712: <p>Certain operations and methods are defined as firing events on
2713: elements. For example, the <code title="dom-click"><a href="editing.html#dom-click">click()</a></code>
2714: method on the <code><a href="dom.html#htmlelement">HTMLElement</a></code> interface is defined as
2715: firing a <code title="event-click">click</code> event on the
1.104 mike 2716: element. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
1.1 mike 2717:
1.651 mike 2718: <p><dfn id="fire-a-click-event" title="fire a click event">Firing a <code title="event-click">click</code> event</dfn> means that a <code title="event-click">click</code> event, which bubbles and is
2719: cancelable, and which uses the <code>MouseEvent</code> interface,
2720: must be dispatched at the given target. The event object must have
2721: its <code title="">screenX</code>, <code title="">screenY</code>,
2722: <code title="">clientX</code>, <code title="">clientY</code>, and
2723: <code title="">button</code> attributes set to 0, its <code title="">ctrlKey</code>, <code title="">shiftKey</code>, <code title="">altKey</code>, and <code title="">metaKey</code> attributes
1.1 mike 2724: set according to the current state of the key input device, if any
2725: (false for any keys that are not available), its <code title="">detail</code> attribute set to 1, and its <code title="">relatedTarget</code> attribute set to null. The <code title="">getModifierState()</code> method on the object must return
2726: values appropriately describing the state of the key input device at
2727: the time the event is created.</p>
2728:
1.651 mike 2729: <p><dfn id="fire-a-simple-event" title="fire a simple event">Firing a simple event named <var title="">e</var></dfn> means that an event with the name <var title="">e</var>, which does not bubble (except where otherwise
2730: stated) and is not cancelable (except where otherwise stated), and
2731: which uses the <code>Event</code> interface, must be dispatched at
2732: the given target.</p>
1.1 mike 2733:
1.507 mike 2734: <!--
2735: <p><dfn title="fire a progress event">Firing a progress event named
1.155 mike 2736: <var title="">e</var></dfn>, optionally in the context of a
1.507 mike 2737: particular instance of the <span title="fetch">fetching
2738: algorithm</span>, means that an event with the name <var
1.651 mike 2739: title="">e</var>, which does not bubble (except where otherwise
2740: stated) and is not cancelable (except where otherwise stated), and
2741: which uses the <code>ProgressEvent</code> interface, must be
2742: dispatched at the given target element. If there is a <span
2743: title="fetch">fetching algorithm</span>, and the <span>URL</span>
2744: being <span title="fetch">fetched</span> has the <span>same
2745: origin</span> as the <code>Document</code> of the target element,
2746: then the <code
1.507 mike 2747: title="dom-ProgressEvents-lengthComputable">lengthComputable</code>
2748: attribute must be set to true if the <span title="fetch">fetching
2749: algorithm</span>'s subject has a known <span
2750: title="concept-fetch-total">size</span>; the <code
2751: title="dom-ProgressEvents-total">total</code> attribute must be set
2752: to the subject's <span title="concept-fetch-total">size</span> if it
2753: is known and zero otherwise; and the <code
2754: title="dom-ProgressEvents-loaded">loaded</code> attribute must be
2755: set to the <span title="concept-fetch-loaded">number of bytes
2756: downloaded</span>, excluding HTTP headers <span
2757: title="concept-http-equivalent-headers">or
2758: equivalent</span>. Otherwise, the <code
2759: title="dom-ProgressEvents-lengthComputable">lengthComputable</code>
2760: attribute must be set to false, and the <code
2761: title="dom-ProgressEvents-total">total</code> and the <code
2762: title="dom-ProgressEvents-loaded">loaded</code> attributes must be
1.531 mike 2763: set to zero. <a href="#r-e-f-sPROGRESS">[PROGRESS]</a></p>
2764: (also fix reference in line above)-->
1.1 mike 2765:
1.409 mike 2766: <p>The default action of these event is to do nothing where where
1.1 mike 2767: otherwise stated.</p>
2768:
1.123 mike 2769: </div><div class="impl">
1.1 mike 2770:
1.614 mike 2771: <h5 id="events-and-the-window-object"><span class="secno">6.5.6.4 </span>Events and the <code><a href="#window">Window</a></code> object</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2772:
2773: <p>When an event is dispatched at a DOM node in a
2774: <code>Document</code> in a <a href="#browsing-context">browsing context</a>, if the
1.394 mike 2775: event is not a <code title="event-load">load</code> event, the user
1.1 mike 2776: agent must also dispatch the event to the <code><a href="#window">Window</a></code>, as
2777: follows:</p>
2778:
1.92 mike 2779: <ol><li>In the capture phase, the event must propagate to the
2780: <code><a href="#window">Window</a></code> object before propagating to any of the nodes,
2781: as if the <code><a href="#window">Window</a></code> object was the parent of the
2782: <code>Document</code> in the dispatch chain.</li>
1.1 mike 2783:
1.92 mike 2784: <li>In the bubble phase, the event must propagate up to the
1.1 mike 2785: <code><a href="#window">Window</a></code> object at the end of the phase, unless bubbling
1.92 mike 2786: has been prevented, again as if the <code><a href="#window">Window</a></code> object was
2787: the parent of the <code>Document</code> in the dispatch chain.</li>
1.1 mike 2788:
1.123 mike 2789: </ol></div><div class="impl">
1.1 mike 2790:
1.614 mike 2791: <h5 id="runtime-script-errors"><span class="secno">6.5.6.5 </span>Runtime script errors</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 2792:
2793: <p><i>This section only applies to user agents that support
2794: scripting in general and JavaScript in particular.</i></p>
2795:
2796: <p>Whenever an uncaught runtime script error occurs in one of the
2797: scripts associated with a <code>Document</code>, the user agent must
1.416 mike 2798: <a href="#report-the-error">report the error</a> using the <code title="handler-window-onerror"><a href="#handler-window-onerror">onerror</a></code> <a href="#event-handlers" title="event
2799: handlers">event handler</a> of the <a href="#script-s-global-object">script's global
2800: object</a>. If the error is still <i title="concept-error-nothandled"><a href="#concept-error-nothandled">not handled</a></i> after this, then
1.1 mike 2801: the error should be reported to the user.</p>
2802:
2803: <hr><p>When the user agent is required to <dfn id="report-the-error" title="report the
2804: error">report an error</dfn> <var title="">error</var> using the
1.416 mike 2805: <a href="#event-handlers" title="event handlers">event handler</a> <var title="">onerror</var>, it must run these steps, after which the
2806: error is either <dfn id="concept-error-handled" title="concept-error-handled"><i>handled</i></dfn> or <dfn id="concept-error-nothandled" title="concept-error-nothandled"><i>not handled</i></dfn>:</p>
1.1 mike 2807:
2808: <dl class="switch"><dt>If the value of <var title="">onerror</var> is a
2809: <code><a href="#function">Function</a></code></dt>
2810:
2811: <dd>
2812:
2813: <p>The function must be invoked with three arguments. The three
2814: arguments passed to the function are all <code>DOMString</code>s;
2815: the first must give the message that the UA is considering
2816: reporting, the second must give the <a href="infrastructure.html#absolute-url">absolute URL</a> of
2817: the resource in which the error occurred, and the third must give
2818: the line number in that resource on which the error occurred.</p>
2819:
2820: <p>If the function returns false, then the error is <i title="concept-error-handled"><a href="#concept-error-handled">handled</a></i>. Otherwise, the error is
2821: <i title="concept-error-nothandled"><a href="#concept-error-nothandled">not handled</a></i>.</p>
2822:
2823: <p>Any uncaught exceptions thrown or errors caused by this
2824: function must be reported to the user immediately after the error
2825: that the function was called for, without using the <a href="#report-the-error" title="report the error">report an error</a> algorithm
2826: again.</p>
2827:
2828: </dd>
2829:
2830: <dt>Otherwise</dt>
2831:
2832: <dd>
2833:
2834: <p>The error is <i title="concept-error-nothandled"><a href="#concept-error-nothandled">not handled</a></i>.</p>
2835:
2836: </dd>
2837:
1.614 mike 2838: </dl></div><h3 id="timers"><span class="secno">6.6 </span>Timers</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>The <code title="dom-windowtimers-setTimeout"><a href="#dom-windowtimers-settimeout">setTimeout()</a></code>
1.1 mike 2839: and <code title="dom-windowtimers-setInterval"><a href="#dom-windowtimers-setinterval">setInterval()</a></code>
1.123 mike 2840: methods allow authors to schedule timer-based callbacks.</p><pre class="idl">[Supplemental, NoInterfaceObject]
1.87 mike 2841: interface <dfn id="windowtimers">WindowTimers</dfn> {
1.401 mike 2842: long <a href="#dom-windowtimers-settimeout" title="dom-windowtimers-setTimeout">setTimeout</a>(in any handler, in optional any timeout, in any... args);
1.1 mike 2843: void <a href="#dom-windowtimers-cleartimeout" title="dom-windowtimers-clearTimeout">clearTimeout</a>(in long handle);
1.401 mike 2844: long <a href="#dom-windowtimers-setinterval" title="dom-windowtimers-setInterval">setInterval</a>(in any handler, in optional any timeout, in any... args);
1.1 mike 2845: void <a href="#dom-windowtimers-clearinterval" title="dom-windowtimers-clearInterval">clearInterval</a>(in long handle);
1.87 mike 2846: };
1.123 mike 2847: <a href="#window">Window</a> implements <a href="#windowtimers">WindowTimers</a>;</pre><dl class="domintro"><dt><var title="">handle</var> = <var title="">window</var> . <code title="dom-windowtimers-setTimeout"><a href="#dom-windowtimers-settimeout">setTimeout</a></code>( <var title="">handler</var> [, <var title="">timeout</var> [, <var title="">arguments</var> ] ] )</dt>
1.1 mike 2848:
2849: <dd>
2850:
2851: <p>Schedules a timeout to run <var title="">handler</var> after
2852: <var title="">timeout</var> milliseconds. Any <var title="">arguments</var> are passed straight through to the <var title="">handler</var>.</p>
2853:
2854: </dd>
2855:
2856: <dt><var title="">handle</var> = <var title="">window</var> . <code title="dom-windowtimers-setTimeout"><a href="#dom-windowtimers-settimeout">setTimeout</a></code>( <var title="">code</var> [, <var title="">timeout</var> ] )</dt>
2857:
2858: <dd>
2859:
2860: <p>Schedules a timeout to compile and run <var title="">code</var>
2861: after <var title="">timeout</var> milliseconds.</p>
2862:
2863: </dd>
2864:
1.103 mike 2865: <dt><var title="">window</var> . <code title="dom-windowtimers-clearTimeout"><a href="#dom-windowtimers-cleartimeout">clearTimeout</a></code>( <var title="">handle</var> )</dt>
2866:
2867: <dd>
2868:
2869: <p>Cancels the timeout set with <code title="dom-windowtimers-setTimeout"><a href="#dom-windowtimers-settimeout">setTimeout()</a></code> identified by <var title="">handle</var>.</p>
2870:
2871: </dd>
2872:
1.1 mike 2873: <dt><var title="">handle</var> = <var title="">window</var> . <code title="dom-windowtimers-setInterval"><a href="#dom-windowtimers-setinterval">setInterval</a></code>( <var title="">handler</var> [, <var title="">timeout</var> [, <var title="">arguments</var> ] ] )</dt>
2874:
2875: <dd>
2876:
2877: <p>Schedules a timeout to run <var title="">handler</var> every
2878: <var title="">timeout</var> milliseconds. Any <var title="">arguments</var> are passed straight through to the <var title="">handler</var>.</p>
2879:
2880: </dd>
2881:
2882: <dt><var title="">handle</var> = <var title="">window</var> . <code title="dom-windowtimers-setInterval"><a href="#dom-windowtimers-setinterval">setInterval</a></code>( <var title="">code</var> [, <var title="">timeout</var> ] )</dt>
2883:
2884: <dd>
2885:
2886: <p>Schedules a timeout to compile and run <var title="">code</var>
2887: every <var title="">timeout</var> milliseconds.</p>
2888:
2889: </dd>
2890:
1.103 mike 2891: <dt><var title="">window</var> . <code title="dom-windowtimers-clearInterval"><a href="#dom-windowtimers-clearinterval">clearInterval</a></code>( <var title="">handle</var> )</dt>
2892:
2893: <dd>
2894:
2895: <p>Cancels the timeout set with <code title="dom-windowtimers-setInterval"><a href="#dom-windowtimers-setinterval">setInterval()</a></code> identified by <var title="">handle</var>.</p>
2896:
2897: </dd>
2898:
1.1 mike 2899: </dl><p class="note">This API does not guarantee that timers will fire
2900: exactly on schedule. Delays due to CPU load, other tasks, etc, are
1.123 mike 2901: to be expected.</p><div class="impl">
1.1 mike 2902:
1.174 mike 2903: <p class="note">The <code><a href="#windowtimers">WindowTimers</a></code> interface adds to the
1.87 mike 2904: <code><a href="#window">Window</a></code> interface and the <code>WorkerUtils</code>
2905: interface (part of Web Workers).</p>
1.1 mike 2906:
2907: <p>Each object that implements the <code><a href="#windowtimers">WindowTimers</a></code>
2908: interface has a <dfn id="list-of-active-timeouts">list of active timeouts</dfn> and a <dfn id="list-of-active-intervals">list
2909: of active intervals</dfn>. Each entry in these lists is identified
2910: by a number, which must be unique within its list for the lifetime
2911: of the object that implements the <code><a href="#windowtimers">WindowTimers</a></code>
2912: interface.</p>
2913:
2914: <hr><p>The <dfn id="dom-windowtimers-settimeout" title="dom-windowtimers-setTimeout"><code>setTimeout()</code></dfn>
2915: method must run the following steps:
2916:
2917: </p><ol><li><p><a href="#get-the-timed-task">Get the timed task</a>, and let <var title="">task</var> be the result.</p></li>
2918:
2919: <li><p><a href="#get-the-timeout">Get the timeout</a>, and let <var title="">timeout</var> be the result.</p></li>
2920:
2921: <li><p>If the currently running <a href="#concept-task" title="concept-task">task</a> is a task that was created by
2922: either the <code title="dom-windowtimers-setTimeout"><a href="#dom-windowtimers-settimeout">setTimeout()</a></code> method, and
2923: <var title="">timeout</var> is less than 4, then increase <var title="">timeout</var> to 4.</p></li>
2924:
2925: <li><p>Add an entry to the <a href="#list-of-active-timeouts">list of active timeouts</a>,
1.174 mike 2926: identified by a user-agent-defined integer that is greater than
1.1 mike 2927: zero.</p></li>
2928:
2929: <li><p>Return the number identifying the newly added entry in the
2930: <a href="#list-of-active-timeouts">list of active timeouts</a>, and then continue running
2931: this algorithm asynchronously.</p></li>
2932:
2933: <li>
2934:
2935: <p>If <var title="">context</var> is a <code><a href="#window">Window</a></code> object,
2936: wait until the <code>Document</code> associated with <var title="">context</var> has been <a href="#fully-active">fully active</a> for a
2937: further <var title="">timeout</var> milliseconds (not necessarily
2938: consecutively).</p>
2939:
2940: <p>Otherwise, if <var title="">context</var> is a
2941: <code>WorkerUtils</code> object, wait until <var title="">timeout</var> milliseconds have passed with the worker
2942: not suspended (not necessarily consecutively).</p>
2943:
2944: <p>Otherwise, act as described in the specification that defines
2945: that the <code><a href="#windowtimers">WindowTimers</a></code> interface is implemented by
2946: some other object.</p>
2947:
2948: </li>
2949:
2950: <li><p>Wait until any invocations of this algorithm started before
2951: this one whose <var title="">timeout</var> is equal to or less than
2952: this one's have completed.</p></li>
2953:
2954: <li><p>If the entry in the <a href="#list-of-active-timeouts">list of active timeouts</a>
2955: that was added in the earlier step has been cleared, then abort
2956: this algorithm.</p></li>
2957:
2958: <li><p><a href="#queue-a-task" title="queue a task">Queue</a> the <var title="">task</var> <a href="#concept-task" title="concept-task">task</a>.</p></li>
2959:
2960: </ol><p>The <dfn id="dom-windowtimers-cleartimeout" title="dom-windowtimers-clearTimeout"><code>clearTimeout()</code></dfn>
2961: method must clear the entry identified as <var title="">handle</var>
2962: from the <a href="#list-of-active-timeouts">list of active timeouts</a> of the
2963: <code><a href="#windowtimers">WindowTimers</a></code> object on which the method was invoked,
2964: where <var title="">handle</var> is the argument passed to the
2965: method.</p>
2966:
2967: <hr><p>The <dfn id="dom-windowtimers-setinterval" title="dom-windowtimers-setInterval"><code>setInterval()</code></dfn>
2968: method must run the following steps:
2969:
2970: </p><ol><li><p><a href="#get-the-timed-task">Get the timed task</a>, and let <var title="">task</var> be the result.</p></li>
2971:
2972: <li><p><a href="#get-the-timeout">Get the timeout</a>, and let <var title="">timeout</var> be the result.</p></li>
2973:
2974: <li><p>If <var title="">timeout</var> is less than 10, then
2975: increase <var title="">timeout</var> to 10.</p></li> <!-- (but see
2976: note below about IE) -->
2977:
2978: <li><p>Add an entry to the <a href="#list-of-active-intervals">list of active intervals</a>,
1.174 mike 2979: identified by a user-agent-defined integer that is greater than
1.1 mike 2980: zero.</p></li>
2981:
2982: <li><p>Return the number identifying the newly added entry in the
2983: <a href="#list-of-active-intervals">list of active intervals</a>, and then continue running
2984: this algorithm asynchronously.</p></li>
2985:
2986: <!-- Note: IE doesn't actually run intervals with duration zero, it
2987: aborts roughly here in the algorithm for them. -->
2988:
2989: <li>
2990:
2991: <p><i>Wait</i>: If <var title="">context</var> is a
2992: <code><a href="#window">Window</a></code> object, wait until the <code>Document</code>
2993: associated with <var title="">context</var> has been <a href="#fully-active">fully
2994: active</a> for a further <var title="">interval</var>
2995: milliseconds (not necessarily consecutively).</p>
2996:
2997: <p>Otherwise, if <var title="">context</var> is a
2998: <code>WorkerUtils</code> object, wait until <var title="">interval</var> milliseconds have passed with the worker
2999: not suspended (not necessarily consecutively).</p>
3000:
3001: <p>Otherwise, act as described in the specification that defines
3002: that the <code><a href="#windowtimers">WindowTimers</a></code> interface is implemented by
3003: some other object.</p>
3004:
3005: </li>
3006:
3007: <li><p>If the entry in the <a href="#list-of-active-intervals">list of active intervals</a>
3008: that was added in the earlier step has been cleared, then abort
3009: this algorithm.</p></li>
3010:
3011: <li><p><a href="#queue-a-task" title="queue a task">Queue</a> the <var title="">task</var> <a href="#concept-task" title="concept-task">task</a>.</p></li>
3012:
3013: <li><p>Return to the step labeled <i>wait</i>.</p></li>
3014:
3015: </ol><p>The <dfn id="dom-windowtimers-clearinterval" title="dom-windowtimers-clearInterval"><code>clearInterval()</code></dfn>
3016: method must clear the entry identified as <var title="">handle</var>
3017: from the <a href="#list-of-active-intervals">list of active intervals</a> of the
3018: <code><a href="#windowtimers">WindowTimers</a></code> object on which the method was invoked,
3019: where <var title="">handle</var> is the argument passed to the
3020: method.</p>
3021:
3022: <hr><p>When the above methods are to <dfn id="get-the-timed-task">get the timed task</dfn>, they
3023: must run the following steps:</p>
3024:
3025: <ol><li>
3026:
3027: <p>If the first argument to the method is an object that has an
3028: internal [[Call]] method, then return a <a href="#concept-task" title="concept-task">task</a> that calls that [[Call]] method
3029: with as its arguments the third and subsequent arguments to the
3030: method (if any), and abort these steps.</p>
3031:
3032: <p>Otherwise, continue with the remaining steps.</p>
3033:
3034: </li>
3035:
3036: <li><p>Apply the ToString() conversion operator to the first
3037: argument to the method, and let <var title="">script source</var>
3038: be the result.</p></li>
3039:
3040: <li><p>Let <var title="">script language</var> be
3041: JavaScript.</p></li>
3042:
3043: <li><p>Let <var title="">context</var> be the object on which the
3044: method is implemented (a <code><a href="#window">Window</a></code> or
3045: <code>WorkerUtils</code> object).</p></li>
3046:
3047: <li>
3048:
3049: <p>If <var title="">context</var> is a <code><a href="#window">Window</a></code> object,
3050: let <var title="">global object</var> be <var title="">context</var>, let <var title="">browsing context</var>
3051: be the <a href="#browsing-context">browsing context</a> with which <var title="">global object</var> is associated, let <var title="">character encoding</var> be the <a href="dom.html#document-s-character-encoding" title="document's
3052: character encoding">character encoding</a> of the
3053: <code>Document</code> associated with <var title="">global
3054: object</var> (<a href="#sce-not-copy">this is a reference, not a
3055: copy</a>), and let <var title="">base URL</var> be the <a href="infrastructure.html#document-base-url" title="document base URL">base URL</a> of the
3056: <code>Document</code> associated with <var title="">global
3057: object</var> (<a href="#sbu-not-copy">this is a reference, not a
3058: copy</a>).</p>
3059:
3060: <p>Otherwise, if <var title="">context</var> is a
3061: <code>WorkerUtils</code> object, let <var title="">global
3062: object</var>, <var title="">browsing context</var>, <var title="">character encoding</var>, and <var title="">base
3063: URL</var> be the <a href="#script-s-global-object">script's global object</a>,
3064: <a href="#script-s-browsing-context">script's browsing context</a>, <a href="#script-s-url-character-encoding">script's URL
3065: character encoding</a>, and <a href="#script-s-base-url">script's base URL</a>
3066: (respectively) of the <a href="#concept-script" title="concept-script">script</a>
3067: that the <span>run a worker</span> algorithm created when it
3068: created <var title="">context</var>.</p>
3069:
3070: <p>Otherwise, act as described in the specification that defines
3071: that the <code><a href="#windowtimers">WindowTimers</a></code> interface is implemented by
3072: some other object.</p>
3073:
3074: </li>
3075:
1.532 mike 3076: <li><p>Return a <a href="#concept-task" title="concept-task">task</a> that <a href="#create-a-script" title="create a script">creates a script</a> using <var title="">script source</var> as the script source, <var title="">scripting language</var> as the scripting language, <var title="">global object</var> as the global object, <var title="">browsing context</var> as the browsing context, <var title="">character encoding</var> as the URL character encoding,
3077: and <var title="">base URL</var> as the base URL.</p></li>
1.1 mike 3078:
3079: </ol><p>When the above methods are to <dfn id="get-the-timeout">get the timeout</dfn>, they
3080: must run the following steps:</p>
3081:
3082: <ol><li><p>Let <var title="">timeout</var> be the second argument to
3083: the method, or zero if the argument was omitted.</p></li>
3084:
3085: <li><p>Apply the ToString() conversion operator to <var title="">timeout</var>, and let <var title="">timeout</var>
3086: be the result.</p></li>
3087:
3088: <li><p>Apply the ToNumber() conversion operator to <var title="">timeout</var>, and let <var title="">timeout</var> be the
3089: result.</p></li>
3090:
1.66 mike 3091: <li><p>If <var title="">timeout</var> is an Infinity value, a
3092: Not-a-Number (NaN) value, or negative, let <var title="">timeout</var> be zero.</p></li>
1.1 mike 3093:
3094: <li><p>Round <var title="">timeout</var> down to the nearest
3095: integer, and let <var title="">timeout</var> be the
3096: result.</p></li>
3097:
3098: <li><p>Return <var title="">timeout</var>.</p></li>
3099:
1.407 mike 3100: </ol><hr><p>The <a href="#task-source">task source</a> for these <a href="#concept-task" title="concept-task">tasks</a> is the <dfn id="timer-task-source">timer task
1.228 mike 3101: source</dfn>.</p>
1.1 mike 3102:
1.614 mike 3103: </div><h3 id="user-prompts"><span class="secno">6.7 </span>User prompts</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><!--
1.1 mike 3104: v2 ideas:
3105: * in-window modal dialogs
3106: - escape/enter handling
3107: - dragging the window out of the tab
3108: * in-window non-modal palettes
3109: - with a solution for the mobile space
1.614 mike 3110: --><h4 id="simple-dialogs"><span class="secno">6.7.1 </span>Simple dialogs</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-alert"><a href="#dom-alert">alert</a></code>(<var title="">message</var>)</dt>
1.1 mike 3111: <dd>
3112:
3113: <p>Displays a modal alert with the given message, and waits for the user to dismiss it.</p>
3114:
1.185 mike 3115: <p>A call to the <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">navigator.yieldForStorageUpdates()</a></code>
1.1 mike 3116: method is implied when this method is invoked.</p>
3117:
3118: </dd>
3119:
3120: <dt><var title="">result</var> = <var title="">window</var> . <code title="dom-confirm"><a href="#dom-confirm">confirm</a></code>(<var title="">message</var>)</dt>
3121: <dd>
3122:
3123: <p>Displays a modal OK/Cancel prompt with the given message, waits
3124: for the user to dismiss it, and returns true if the user clicks OK
3125: and false if the user clicks Cancel.</p>
3126:
1.185 mike 3127: <p>A call to the <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">navigator.yieldForStorageUpdates()</a></code>
1.1 mike 3128: method is implied when this method is invoked.</p>
3129:
3130: </dd>
3131:
3132: <dt><var title="">result</var> = <var title="">window</var> . <code title="dom-prompt"><a href="#dom-prompt">prompt</a></code>(<var title="">message</var> [, <var title="">default</var>] )</dt>
3133: <dd>
3134:
3135: <p>Displays a modal text field prompt with the given message,
3136: waits for the user to dismiss it, and returns the value that the
3137: user entered. If the user cancels the prompt, then returns null
3138: instead. If the second argument is present, then the given value
3139: is used as a default.</p>
3140:
1.185 mike 3141: <p>A call to the <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">navigator.yieldForStorageUpdates()</a></code>
1.1 mike 3142: method is implied when this method is invoked.</p>
3143:
3144: </dd>
3145:
3146: </dl><div class="impl">
3147:
3148: <p>The <dfn id="dom-alert" title="dom-alert"><code>alert(<var title="">message</var>)</code></dfn> method, when invoked, must
3149: release the <a href="#storage-mutex">storage mutex</a> and show the given <var title="">message</var> to the user. The user agent may make the
3150: method wait for the user to acknowledge the message before
3151: returning; if so, the user agent must <a href="#pause">pause</a> while the
3152: method is waiting.</p>
3153:
3154: <p>The <dfn id="dom-confirm" title="dom-confirm"><code>confirm(<var title="">message</var>)</code></dfn> method, when invoked, must
3155: release the <a href="#storage-mutex">storage mutex</a> and show the given <var title="">message</var> to the user, and ask the user to respond with
3156: a positive or negative response. The user agent must then
3157: <a href="#pause">pause</a> as the method waits for the user's response. If
3158: the user responds positively, the method must return true, and if
3159: the user responds negatively, the method must return false.</p>
3160:
3161: <p>The <dfn id="dom-prompt" title="dom-prompt"><code>prompt(<var title="">message</var>, <var title="">default</var>)</code></dfn>
3162: method, when invoked, must release the <a href="#storage-mutex">storage mutex</a>,
3163: show the given <var title="">message</var> to the user, and ask the
3164: user to either respond with a string value or abort. The user agent
3165: must then <a href="#pause">pause</a> as the method waits for the user's
3166: response. The second argument is optional. If the second argument
3167: (<var title="">default</var>) is present, then the response must be
3168: defaulted to the value given by <var title="">default</var>. If the
3169: user aborts, then the method must return null; otherwise, the method
3170: must return the string that the user responded with.</p>
3171:
1.614 mike 3172: </div><h4 id="printing"><span class="secno">6.7.2 </span>Printing</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-print"><a href="#dom-print">print</a></code>()</dt>
1.1 mike 3173:
3174: <dd>
3175:
3176: <p>Prompts the user to print the page.</p>
3177:
1.185 mike 3178: <p>A call to the <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">navigator.yieldForStorageUpdates()</a></code>
1.1 mike 3179: method is implied when this method is invoked.</p>
3180:
3181: </dd>
3182:
3183: </dl><div class="impl">
3184:
3185: <p>The <dfn id="dom-print" title="dom-print"><code>print()</code></dfn> method,
3186: when invoked, must run the <a href="#printing-steps">printing steps</a>.</p>
3187:
3188: <p>User agents should also run the <a href="#printing-steps">printing steps</a>
3189: whenever the user asks for the opportunity to <a href="the-xhtml-syntax.html#obtain-a-physical-form">obtain a
3190: physical form</a> (e.g. printed copy), or the representation of a
3191: physical form (e.g. PDF copy), of a document.</p>
3192:
3193: <p>The <dfn id="printing-steps">printing steps</dfn> are as follows:</p>
3194:
3195: <ol><li>
3196:
3197: <p>The user agent may display a message to the user and/or may
3198: abort these steps.</p>
3199:
3200: <p class="example">For instance, a kiosk browser could silently
3201: ignore any invocations of the <code title="dom-print"><a href="#dom-print">print()</a></code> method.</p>
3202:
3203: <p class="example">For instance, a browser on a mobile device
3204: could detect that there are no printers in the vicinity and
3205: display a message saying so before continuing to offer a "save to
3206: PDF" option.</p>
3207:
3208: </li>
3209:
3210: <li>
3211:
1.460 mike 3212: <p>The user agent must <a href="#fire-a-simple-event">fire a simple event</a> named
1.1 mike 3213: <code title="event-beforeprint">beforeprint</code> at the
3214: <code><a href="#window">Window</a></code> object of the <code>Document</code> that is
3215: being printed, as well as any <a href="#nested-browsing-context" title="nested browsing
3216: context">nested browsing contexts</a> in it.</p>
3217:
3218: <p class="example">The <code title="event-beforeprint">beforeprint</code> event can be used
3219: to annotate the printed copy, for instance adding the time at
3220: which the document was printed.</p>
3221:
3222: </li>
3223:
3224: <li>
3225:
3226: <p>The user agent must release the <a href="#storage-mutex">storage mutex</a>.</p>
3227:
3228: </li>
3229:
3230: <li>
3231:
3232: <p>The user agent should offer the user the opportunity to
3233: <a href="the-xhtml-syntax.html#obtain-a-physical-form">obtain a physical form</a> (or the representation of a
3234: physical form) of the document. The user agent may wait for the
3235: user to either accept or decline before returning; if so, the user
3236: agent must <a href="#pause">pause</a> while the method is waiting. Even if
3237: the user agent doesn't wait at this point, the user agent must use
3238: the state of the relevant documents as they are at this point in
3239: the algorithm if and when it eventually creates the alternate
3240: form.</p>
3241:
3242: </li>
3243:
3244: <li>
3245:
1.460 mike 3246: <p>The user agent must <a href="#fire-a-simple-event">fire a simple event</a> named
1.1 mike 3247: <code title="event-afterprint">afterprint</code> at the
3248: <code><a href="#window">Window</a></code> object of the <code>Document</code> that is
3249: being printed, as well as any <a href="#nested-browsing-context" title="nested browsing
3250: context">nested browsing contexts</a> in it.</p>
3251:
3252: <p class="example">The <code title="event-afterprint">afterprint</code> event can be used
3253: to revert annotations added in the earlier event, as well as
3254: showing post-printing UI. For instance, if a page is walking the
3255: user through the steps of applying for a home loan, the script
3256: could automatically advance to the next step after having printed
3257: a form or other.</p>
3258:
3259: </li>
3260:
1.614 mike 3261: </ol></div><h4 id="dialogs-implemented-using-separate-documents"><span class="secno">6.7.3 </span>Dialogs implemented using separate documents</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">result</var> = <var title="">window</var> . <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog</a></code>(<var title="">url</var> [, <var title="">argument</var>] )</dt>
1.1 mike 3262:
3263: <dd>
3264:
3265: <p>Prompts the user with the given page, waits for that page to
3266: close, and returns the return value.</p>
3267:
1.185 mike 3268: <p>A call to the <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">navigator.yieldForStorageUpdates()</a></code>
1.1 mike 3269: method is implied when this method is invoked.</p>
3270:
3271: </dd>
3272:
3273: </dl><div class="impl">
3274:
3275: <p>The <dfn id="dom-showmodaldialog" title="dom-showModalDialog"><code>showModalDialog(<var title="">url</var>, <var title="">argument</var><!--, <var
3276: title="">features</var>-->)</code></dfn> method, when invoked, must
3277: cause the user agent to run the following steps:</p>
3278:
3279: <ol><li>
3280:
3281: <p><a href="infrastructure.html#resolve-a-url" title="resolve a url">Resolve</a> <var title="">url</var> relative to the <a href="#first-script">first script</a>'s
3282: <a href="#script-s-base-url" title="script's base URL">base URL</a>.</p>
3283:
3284: <p>If this fails, then throw a <code><a href="infrastructure.html#syntax_err">SYNTAX_ERR</a></code> exception
3285: and abort these steps.</p>
3286:
3287: </li>
3288:
3289: <li>
3290:
3291: <p>Release the <a href="#storage-mutex">storage mutex</a>.</p>
3292:
3293: </li>
3294:
3295: <li>
3296:
3297: <p>If the user agent is configured such that this invocation of
3298: <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code> is
3299: somehow disabled, then return the empty string and abort these
3300: steps.</p>
3301:
3302: <p class="note">User agents are expected to disable this method in
3303: certain cases to avoid user annoyance (e.g. as part of their popup
3304: blocker feature). For instance, a user agent could require that a
3305: site be white-listed before enabling this method, or the user
3306: agent could be configured to only allow one modal dialog at a
3307: time.</p>
3308:
3309: </li>
3310:
3311: <li>
3312:
3313: <p>Let <var title="">the list of background browsing
3314: contexts</var> be a list of all the browsing contexts that:</p>
3315:
3316: <ul><li>are part of the same <a href="#unit-of-related-browsing-contexts">unit of related browsing
3317: contexts</a> as the browsing context of the
3318: <code><a href="#window">Window</a></code> object on which the <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code> method was
3319: called, and that</li>
3320:
3321: <li>have an <a href="#active-document">active document</a> whose
1.159 mike 3322: <a href="#origin">origin</a> is the <a href="#same-origin" title="same origin">same</a>
3323: as the <a href="#origin">origin</a> of the <a href="#concept-script" title="concept-script">script</a> that called the <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code> method at
1.1 mike 3324: the time the method was called,</li> <!-- Note that changing
3325: document.domain to talk to another domain doesn't make you able
3326: to block that domain -->
3327:
3328: </ul><p>...as well as any browsing contexts that are nested inside any
3329: of the browsing contexts matching those conditions.</p>
3330:
3331: </li>
3332:
3333: <li>
3334:
3335: <p>Disable the user interface for all the browsing contexts in
3336: <var title="">the list of background browsing contexts</var>. This
3337: should prevent the user from navigating those browsing contexts,
3338: causing events to be sent to those browsing context, or editing
3339: any content in those browsing contexts. However, it does not
3340: prevent those browsing contexts from receiving events from sources
3341: other than the user, from running scripts, from running
3342: animations, and so forth.</p>
3343:
3344: </li>
3345:
3346: <li>
3347:
3348: <p>Create a new <a href="#auxiliary-browsing-context">auxiliary browsing context</a>, with the
3349: <a href="#opener-browsing-context">opener browsing context</a> being the browsing context of
3350: the <code><a href="#window">Window</a></code> object on which the <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code> method was
3351: called. The new auxiliary browsing context has no name.</p>
3352:
3353: <p class="note">This <a href="#browsing-context">browsing context</a>'s
3354: <code>Document</code>s' <code><a href="#window">Window</a></code> objects all implement
3355: the <code><a href="#windowmodal">WindowModal</a></code> interface.</p>
3356:
3357: </li>
3358:
3359: <li>
3360:
3361: <p>Let the <a href="#dialog-arguments">dialog arguments</a> of the new browsing
3362: context be set to the value of <var title="">argument</var>, or
3363: the 'undefined' value if the argument was omitted.</p>
3364:
3365: </li>
3366:
3367: <li>
3368:
3369: <p>Let the <a href="#dialog-arguments-origin">dialog arguments' origin</a> be the
1.159 mike 3370: <a href="#origin">origin</a> of the <a href="#concept-script" title="concept-script">script</a> that called the <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code> method.</p>
1.1 mike 3371:
3372: </li>
3373:
3374: <li>
3375:
3376: <p><a href="history.html#navigate">Navigate</a> the new <a href="#browsing-context">browsing context</a> to
3377: the <a href="infrastructure.html#absolute-url">absolute URL</a> that resulted from <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolving</a> <var title="">url</var>
3378: earlier, with <a href="history.html#replacement-enabled">replacement enabled</a>, and with the <a href="#script-s-browsing-context" title="script's browsing context">browsing context</a> of the
3379: <a href="#concept-script" title="concept-script">script</a> that invoked the method
3380: as the <a href="history.html#source-browsing-context">source browsing context</a>.</p>
3381:
3382: </li>
3383:
3384: <li>
3385:
1.558 mike 3386: <p><a href="#spin-the-event-loop">Spin the event loop</a> until the new <a href="#browsing-context">browsing
3387: context</a> is closed. (The user agent must allow the user to
3388: indicate that the <a href="#browsing-context">browsing context</a> is to be
1.1 mike 3389: closed.)</p>
3390:
3391: </li>
3392:
3393: <li>
3394:
3395: <p>Reenable the user interface for all the browsing contexts in
3396: <var title="">the list of background browsing contexts</var>.</p>
3397:
3398: </li>
3399:
3400: <li>
3401:
3402: <p>Return the <a href="#auxiliary-browsing-context">auxiliary browsing context</a>'s
3403: <a href="#return-value">return value</a>.</p>
3404:
3405: </li>
3406:
3407: </ol><p>The <code><a href="#window">Window</a></code> objects of <code>Document</code>s hosted
3408: by <a href="#browsing-context" title="browsing context">browsing contexts</a> created
1.87 mike 3409: by the above algorithm must all have the <code><a href="#windowmodal">WindowModal</a></code>
3410: interface added to their <code><a href="#window">Window</a></code> interface:</p>
1.1 mike 3411:
1.123 mike 3412: </div><pre class="idl">[Supplemental, NoInterfaceObject] interface <dfn id="windowmodal">WindowModal</dfn> {
1.1 mike 3413: readonly attribute any <a href="#dom-windowmodal-dialogarguments" title="dom-WindowModal-dialogArguments">dialogArguments</a>;
3414: attribute DOMString <a href="#dom-windowmodal-returnvalue" title="dom-WindowModal-returnValue">returnValue</a>;
1.87 mike 3415: };
1.123 mike 3416: <a href="#window">Window</a> implements <a href="#windowmodal">WindowModal</a>; /* sometimes */</pre><dl class="domintro"><dt><var title="">window</var> . <code title="dom-WindowModal-dialogArguments"><a href="#dom-windowmodal-dialogarguments">dialogArguments</a></code></dt>
1.1 mike 3417:
3418: <dd>
3419:
3420: <p>Returns the <var title="">argument</var> argument that was
3421: passed to the <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code> method.</p>
3422:
3423: </dd>
3424:
3425: <dt><var title="">window</var> . <code title="dom-WindowModal-returnValue"><a href="#dom-windowmodal-returnvalue">returnValue</a></code> [ = <var title="">value</var> ]</dt>
3426:
3427: <dd>
3428:
3429: <p>Returns the current return value for the window.</p>
3430:
3431: <p>Can be set, to change the value that will be returned by the
3432: <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code>
3433: method.</p>
3434:
3435: </dd>
3436:
3437: </dl><div class="impl">
3438:
3439: <p>Such browsing contexts have associated <dfn id="dialog-arguments">dialog
3440: arguments</dfn>, which are stored along with the <dfn id="dialog-arguments-origin">dialog
3441: arguments' origin</dfn>. These values are set by the <code title="dom-showModalDialog"><a href="#dom-showmodaldialog">showModalDialog()</a></code> method in the
3442: algorithm above, when the browsing context is created, based on the
3443: arguments provided to the method.</p>
3444:
3445: <p>The <dfn id="dom-windowmodal-dialogarguments" title="dom-WindowModal-dialogArguments"><code>dialogArguments</code></dfn>
1.192 mike 3446: IDL attribute, on getting, must check whether its browsing context's
1.159 mike 3447: <a href="#active-document">active document</a>'s <a href="#origin">origin</a> is the <a href="#same-origin" title="same origin">same</a> as the <a href="#dialog-arguments-origin">dialog arguments'
1.1 mike 3448: origin</a>. If it is, then the browsing context's <a href="#dialog-arguments">dialog
3449: arguments</a> must be returned unchanged. Otherwise, if the
3450: <a href="#dialog-arguments">dialog arguments</a> are an object, then the empty string
3451: must be returned, and if the <a href="#dialog-arguments">dialog arguments</a> are not
3452: an object, then the stringification of the <a href="#dialog-arguments">dialog
3453: arguments</a> must be returned.
3454:
3455: </p><p>These browsing contexts also have an associated <dfn id="return-value">return
3456: value</dfn>. The <a href="#return-value">return value</a> of a browsing context
3457: must be initialized to the empty string when the browsing context is
3458: created.</p>
3459:
3460: <p>The <dfn id="dom-windowmodal-returnvalue" title="dom-WindowModal-returnValue"><code>returnValue</code></dfn>
1.192 mike 3461: IDL attribute, on getting, must return the <a href="#return-value">return value</a>
1.1 mike 3462: of its browsing context, and on setting, must set the <a href="#return-value">return
3463: value</a> to the given new value.</p>
3464:
1.123 mike 3465: </div><p class="note">The <code title="dom-window-close"><a href="#dom-window-close">window.close()</a></code> method can be used to
1.486 mike 3466: close the browsing context.</p><h3 id="system-state-and-capabilities"><span class="secno">6.8 </span>System state and capabilities</h3><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><div class="impl">
1.1 mike 3467:
3468: <p>The <dfn id="dom-navigator" title="dom-navigator"><code>navigator</code></dfn>
3469: attribute of the <code><a href="#window">Window</a></code> interface must return an
3470: instance of the <code><a href="#navigator">Navigator</a></code> interface, which represents
3471: the identity and state of the user agent (the client), and allows
3472: Web pages to register themselves as potential protocol and content
3473: handlers:</p>
3474:
1.123 mike 3475: </div><pre class="idl">interface <dfn id="navigator">Navigator</dfn> {
1.1 mike 3476: // objects implementing this interface also implement the interfaces given below
3477: };
1.87 mike 3478: <a href="#navigator">Navigator</a> implements <a href="#navigatorid">NavigatorID</a>;
3479: <a href="#navigator">Navigator</a> implements <a href="#navigatoronline">NavigatorOnLine</a>;
3480: <a href="#navigator">Navigator</a> implements <a href="#navigatorabilities">NavigatorAbilities</a>;
1.1 mike 3481:
1.87 mike 3482: [Supplemental, NoInterfaceObject]
3483: interface <dfn id="navigatorid">NavigatorID</dfn> {<!--
1.1 mike 3484: readonly attribute DOMString <span title="dom-navigator-appCodeName">appCodeName</span>;-->
3485: readonly attribute DOMString <a href="#dom-navigator-appname" title="dom-navigator-appName">appName</a>;
3486: readonly attribute DOMString <a href="#dom-navigator-appversion" title="dom-navigator-appVersion">appVersion</a>;
3487: readonly attribute DOMString <a href="#dom-navigator-platform" title="dom-navigator-platform">platform</a>;
3488: readonly attribute DOMString <a href="#dom-navigator-useragent" title="dom-navigator-userAgent">userAgent</a>;
3489: };
3490:
1.87 mike 3491: [Supplemental, NoInterfaceObject]
3492: interface <dfn id="navigatoronline">NavigatorOnLine</dfn> {
1.1 mike 3493: readonly attribute boolean <a href="offline.html#dom-navigator-online" title="dom-navigator-onLine">onLine</a>;
3494: };
3495:
1.87 mike 3496: [Supplemental, NoInterfaceObject]
3497: interface <dfn id="navigatorabilities">NavigatorAbilities</dfn> {
1.1 mike 3498: // content handler registration
3499: void <a href="#dom-navigator-registerprotocolhandler" title="dom-navigator-registerProtocolHandler">registerProtocolHandler</a>(in DOMString scheme, in DOMString url, in DOMString title);
3500: void <a href="#dom-navigator-registercontenthandler" title="dom-navigator-registerContentHandler">registerContentHandler</a>(in DOMString mimeType, in DOMString url, in DOMString title);
1.185 mike 3501: void <a href="#dom-navigator-yieldforstorageupdates" title="dom-navigator-yieldForStorageUpdates">yieldForStorageUpdates</a>();
1.1 mike 3502: <!-- v2: cookieEnabled geolocator javaEnabled mozIsLocallyAvailable preference
3503: readonly attribute <span>MimeTypeArray</span> <span title="dom-navigator-mimeTypes">mimeTypes</span>;
3504: readonly attribute <span>PluginArray</span> <span title="dom-navigator-plugins">plugins</span>;
3505: (the latter is used in a <video> element demo now, so we might need to pull this forward from v2!)
1.123 mike 3506: -->};</pre><div class="impl">
1.1 mike 3507:
1.343 mike 3508: <p>These interfaces are defined separately so that other
3509: specifications can re-use parts of the <code><a href="#navigator">Navigator</a></code>
3510: interface.</p>
1.1 mike 3511:
3512: <!-- v2: also, see window.external.AddSearchProvider() and similar DOM APIs from IE -->
3513:
3514: <!-- v2: also, could expose languages:
3515: <dt><dfn title="dom-navigator-browserLanguage"><code>browserLanguage</code></dfn></dt> <!- - Opera and IE only - ->
3516: <dd><p>Must return either null or a language code representing the language the browser uses in its interface.</p></dd>
3517: <dt><dfn title="dom-navigator-userLanguage"><code>userLanguage</code></dfn></dt> <!- - Opera and IE only - ->
3518: <dt><dfn title="dom-navigator-language"><code>language</code></dfn></dt> <!- - Opera, Safari, and Mozilla only - ->
3519: <dd><p>Must return either null or a language code representing the user's preferred language.</p></dd>
3520: -->
3521:
1.614 mike 3522: </div><h4 id="client-identification"><span class="secno">6.8.1 </span>Client identification</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>In certain cases, despite the best efforts of the entire
1.1 mike 3523: industry, Web browsers have bugs and limitations that Web authors
1.123 mike 3524: are forced to work around.</p><p>This section defines a collection of attributes that can be used
1.1 mike 3525: to determine, from script, the kind of user agent in use, in order
1.123 mike 3526: to work around these issues.</p><p>Client detection should always be limited to detecting known
1.1 mike 3527: current versions; future versions and unknown versions should always
1.123 mike 3528: be assumed to be fully compliant.</p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-appName"><a href="#dom-navigator-appname">appName</a></code></dt>
1.1 mike 3529: <dd>
3530: <p>Returns the name of the browser.</p>
3531: </dd>
3532:
3533: <dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-appVersion"><a href="#dom-navigator-appversion">appVersion</a></code></dt>
3534: <dd>
3535: <p>Returns the version of the browser.</p>
3536: </dd>
3537:
3538: <dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-platform"><a href="#dom-navigator-platform">platform</a></code></dt>
3539: <dd>
3540: <p>Returns the name of the platform.</p>
3541: </dd>
3542:
3543: <dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-userAgent"><a href="#dom-navigator-useragent">userAgent</a></code></dt>
3544: <dd>
3545: <p>Returns the complete User-Agent header.</p>
3546: </dd>
3547:
3548: </dl><div class="impl">
3549:
3550: <dl><!-- redundant
3551: <dt><dfn title="dom-navigator-appCodeName"><code>appCodeName</code></dfn></dt>
3552: <dd><p>Must return the string "<code title="">Mozilla</code>".</p></dd>
3553: --><!-- appMinorVersion: IE only. In IE8b1, returns " Beta" (with the space) --><dt><dfn id="dom-navigator-appname" title="dom-navigator-appName"><code>appName</code></dfn></dt>
3554: <dd><p>Must return either the string "<code title="">Netscape</code>" or the full name of the browser, e.g. "<code title="">Mellblom Browsernator</code>".</p></dd>
3555:
3556: <dt><dfn id="dom-navigator-appversion" title="dom-navigator-appVersion"><code>appVersion</code></dfn></dt>
3557: <dd><p>Must return either the string "<code title="">4.0</code>" or a string representing the version of the browser in detail, e.g. "<code title="">1.0 (VMS; en-US) Mellblomenator/9000</code>".</p></dd>
3558:
3559: <!-- buildID: Mozilla only -->
3560:
3561: <!-- oscpu: Mozilla only -->
3562:
3563: <dt><dfn id="dom-navigator-platform" title="dom-navigator-platform"><code>platform</code></dfn></dt>
3564: <dd><p>Must return either the empty string or a string representing the platform on which the browser is executing, e.g. "<code title="">MacIntel</code>", "<code title="">Win32</code>", "<code title="">FreeBSD i386</code>", "<code title="">WebTV OS</code>".</p></dd>
3565:
3566: <!-- product: Mozilla and Safari only; always returns "Gecko" -->
3567:
3568: <!-- productSub: Mozilla and Safari only; returns same as buildID in Mozilla, and returns the fixed string "20030107" in Safari -->
3569:
3570: <!-- securityPolicy: Mozilla only; always returns "" -->
3571:
3572: <!-- taintEnabled(): Opera, IE and Mozilla have this function as one that always returns false -->
3573:
3574: <dt><dfn id="dom-navigator-useragent" title="dom-navigator-userAgent"><code>userAgent</code></dfn></dt>
3575: <dd><p>Must return the string used for the value of the "<code title="">User-Agent</code>" header in HTTP requests, or the empty string if no such header is ever sent.</p></dd>
3576:
3577: <!-- vendor: Mozilla and Safari only; always returns "" in Mozilla, and returns the fixed string "Apple Computer, Inc." in Safari -->
3578:
3579: <!-- vendorSub: Mozilla and Safari only; always returns "" -->
3580:
1.486 mike 3581: </dl></div><h4 id="custom-handlers"><span class="secno">6.8.2 </span>Custom scheme and content handlers</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><p>The <dfn id="dom-navigator-registerprotocolhandler" title="dom-navigator-registerProtocolHandler"><code>registerProtocolHandler()</code></dfn>
1.1 mike 3582: method allows Web sites to register themselves as possible handlers
3583: for particular schemes. For example, an online fax service could
1.104 mike 3584: register itself as a handler of the <code>fax:</code> scheme (<a href="references.html#refsRFC2806">[RFC2806]</a>), so that if the user clicks on
1.1 mike 3585: such a link, he is given the opportunity to use that Web
3586: site. Analogously, the <dfn id="dom-navigator-registercontenthandler" title="dom-navigator-registerContentHandler"><code>registerContentHandler()</code></dfn>
3587: method allows Web sites to register themselves as possible handlers
1.104 mike 3588: for content in a particular <a href="infrastructure.html#mime-type">MIME type</a>. For example, the same online
1.1 mike 3589: fax service could register itself as a handler for
1.104 mike 3590: <code>image/g3fax</code> files (<a href="references.html#refsRFC1494">[RFC1494]</a>), so that if the user has no
1.1 mike 3591: native application capable of handling G3 Facsimile byte streams,
3592: his Web browser can instead suggest he use that site to view the
1.123 mike 3593: image.</p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-registerProtocolHandler"><a href="#dom-navigator-registerprotocolhandler">registerProtocolHandler</a></code>(<var title="">scheme</var>, <var title="">url</var>, <var title="">title</var>)</dt>
1.1 mike 3594: <dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-registerContentHandler"><a href="#dom-navigator-registercontenthandler">registerContentHandler</a></code>(<var title="">mimeType</var>, <var title="">url</var>, <var title="">title</var>)</dt>
3595:
3596: <dd>
3597:
3598: <p>Registers a handler for the given scheme or content type, at
3599: the given URL, with the given title.</p>
3600:
3601: <p>The string "<code title="">%s</code>" in the URL is used as a
3602: placeholder for where to put the URL of the content to be
3603: handled.</p>
3604:
3605: <p>Throws a <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exception if the user agent
3606: blocks the registration (this might happen if trying to register
3607: as a handler for "http", for instance).</p>
3608:
3609: <p>Throws a <code><a href="infrastructure.html#syntax_err">SYNTAX_ERR</a></code> if the "<code title="">%s</code>" string is missing in the URL.</p>
3610:
3611: </dd>
3612:
3613: </dl><div class="impl">
3614:
3615: <p>User agents may, within the constraints described in this
3616: section, do whatever they like when the methods are called. A UA
3617: could, for instance, prompt the user and offer the user the
3618: opportunity to add the site to a shortlist of handlers, or make the
3619: handlers his default, or cancel the request. UAs could provide such
3620: a UI through modal UI or through a non-modal transient notification
3621: interface. UAs could also simply silently collect the information,
3622: providing it only when relevant to the user.</p>
3623:
3624: <p>User agents should keep track of which sites have registered
3625: handlers (even if the user has declined such registrations) so that
3626: the user is not repeatedly prompted with the same request.</p>
3627:
3628: <p>The arguments to the methods have the following meanings and
3629: corresponding implementation requirements:</p>
3630:
3631: <dl><dt><var title="">protocol</var> (<code title="dom-navigator-registerProtocolHandler"><a href="#dom-navigator-registerprotocolhandler">registerProtocolHandler()</a></code> only)</dt>
3632:
3633: <dd>
3634:
3635: <p>A scheme, such as <code>ftp</code> or <code>fax</code>. The
3636: scheme must be compared in an <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a>
3637: manner by user agents for the purposes of comparing with the
3638: scheme part of URLs that they consider against the list of
3639: registered handlers.</p>
3640:
3641: <p>The <var title="">scheme</var> value, if it contains a colon
3642: (as in "<code>ftp:</code>"), will never match anything, since
3643: schemes don't contain colons.</p>
3644:
3645: <p class="note">This feature is not intended to be used with
3646: non-standard protocols.</p>
3647:
3648: </dd>
3649:
3650: <dt><var title="">mimeType</var> (<code title="dom-navigator-registerContentHandler"><a href="#dom-navigator-registercontenthandler">registerContentHandler()</a></code> only)</dt>
3651:
3652: <dd>
3653:
1.104 mike 3654: <p>A <a href="infrastructure.html#mime-type">MIME type</a>, such as <code>model/vrml</code> or
3655: <code>text/richtext</code>. The <a href="infrastructure.html#mime-type">MIME type</a> must be
3656: compared in an <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> manner by user
3657: agents for the purposes of comparing with MIME types of documents
3658: that they consider against the list of registered handlers.</p>
1.1 mike 3659:
3660: <p>User agents must compare the given values only to the MIME
3661: type/subtype parts of content types, not to the complete type
3662: including parameters. Thus, if <var title="">mimeType</var> values
3663: passed to this method include characters such as commas or
3664: whitespace, or include MIME parameters, then the handler being
3665: registered will never be used.</p>
3666:
1.104 mike 3667: <p class="note">The type is compared to the <a href="infrastructure.html#mime-type">MIME type</a> used by the
1.1 mike 3668: user agent <em>after</em> the sniffing algorithms have been
3669: applied.</p>
3670:
3671: </dd>
3672:
3673:
3674: <dt><var title="">url</var></dt>
3675:
3676: <dd>
3677:
3678: <p>The <a href="infrastructure.html#url">URL</a> of the page that will handle the
3679: requests.</p>
3680:
3681: <p>When the user agent uses this URL, it must replace the first
3682: occurrence of the exact literal string "<code title="">%s</code>"
3683: with an escaped version of the <a href="infrastructure.html#absolute-url">absolute URL</a> of the
3684: content in question (as defined below), then <a href="infrastructure.html#resolve-a-url" title="resolve
3685: a url">resolve</a> the resulting URL, relative to the <a href="#script-s-base-url" title="script's base URL">base URL</a> of the <a href="#first-script">first
3686: script</a> at the time the <code title="dom-navigator-registerContentHandler"><a href="#dom-navigator-registercontenthandler">registerContentHandler()</a></code>
3687: or <code title="dom-navigator-registerProtocolHandler"><a href="#dom-navigator-registerprotocolhandler">registerProtocolHandler()</a></code>
3688: methods were invoked, and then <a href="history.html#navigate">navigate</a> an
3689: appropriate <a href="#browsing-context">browsing context</a> to the resulting URL
3690: using the GET method (<a href="infrastructure.html#concept-http-equivalent-get" title="concept-http-equivalent-get">or
3691: equivalent</a> for non-HTTP URLs).</p>
3692:
3693: <p>To get the escaped version of the <a href="infrastructure.html#absolute-url">absolute URL</a> of
3694: the content in question, the user agent must replace every
3695: character in that <a href="infrastructure.html#absolute-url">absolute URL</a> that doesn't match the
3696: <query> production defined in RFC 3986 by the
1.104 mike 3697: percent-encoded form of that character. <a href="references.html#refsRFC3986">[RFC3986]</a></p>
1.1 mike 3698:
3699: <div class="example">
3700:
3701: <p>If the user had visited a site at <code title="">http://example.com/</code> that made the following
3702: call:</p>
3703:
3704: <pre>navigator.registerContentHandler('application/x-soup', 'soup?url=%s', 'SoupWeb™')</pre>
3705:
3706: <p>...and then, much later, while visiting <code title="">http://www.example.net/</code>, clicked on a link such
3707: as:</p>
3708:
3709: <pre><a href="chickenkïwi.soup">Download our Chicken Kïwi soup!</a></pre>
3710:
3711: <p>...then, assuming this <code>chickenkïwi.soup</code> file
1.104 mike 3712: was served with the <a href="infrastructure.html#mime-type">MIME type</a> <code>application/x-soup</code>,
1.1 mike 3713: the UA might navigate to the following URL:</p>
3714:
3715: <pre>http://example.com/soup?url=http://www.example.net/chickenk%C3%AFwi.soup</pre>
3716:
3717: <p>This site could then fetch the <code>chickenkïwi.soup</code>
3718: file and do whatever it is that it does with soup (synthesize it
3719: and ship it to the user, or whatever).</p>
3720:
3721: </div>
3722:
3723: </dd>
3724:
3725: <dt><var title="">title</var></dt>
3726:
3727: <dd>
3728:
3729: <p>A descriptive title of the handler, which the UA might use to
3730: remind the user what the site in question is.</p>
3731:
3732: </dd>
3733:
3734: </dl><p>User agents should raise <code><a href="infrastructure.html#security_err">SECURITY_ERR</a></code> exceptions if
3735: the methods are called with <var title="">scheme</var> or <var title="">mimeType</var> values that the UA deems to be
3736: "privileged". For example, a site attempting to register a handler
1.605 mike 3737: for <code>http</code> URLs or <code><a href="iana.html#text-html">text/html</a></code> content in a
1.1 mike 3738: Web browser would likely cause an exception to be raised.</p>
3739:
3740: <p>User agents must raise a <code><a href="infrastructure.html#syntax_err">SYNTAX_ERR</a></code> exception if the
3741: <var title="">url</var> argument passed to one of these methods does
3742: not contain the exact literal string "<code>%s</code>", or if <a href="infrastructure.html#resolve-a-url" title="resolve a url">resolving</a> the <var title="">url</var>
3743: argument with the first occurrence of the string "<code title="">%s</code>" removed, relative to the <a href="#first-script">first
3744: script</a>'s <a href="#script-s-base-url" title="script's base URL">base URL</a>, is
3745: not successful.</p>
3746:
3747: <p>User agents must not raise any other exceptions (other than
3748: binding-specific exceptions, such as for an incorrect number of
3749: arguments in an JavaScript implementation).</p>
3750:
3751: <p>This section does not define how the pages registered by these
3752: methods are used, beyond the requirements on how to process the <var title="">url</var> value (see above). To some extent, the <a href="history.html#navigate" title="navigate">processing model for navigating across
3753: documents</a> defines some cases where these methods are
3754: relevant, but in general UAs may use this information wherever they
3755: would otherwise consider handing content to native plugins or helper
3756: applications.</p>
3757:
3758: <p>UAs must not use registered content handlers to handle content
3759: that was returned as part of a non-GET transaction (or rather, as
3760: part of any non-idempotent transaction), as the remote site would
3761: not be able to fetch the same data.</p>
3762:
1.123 mike 3763: </div><div class="impl">
1.1 mike 3764:
1.614 mike 3765: <h5 id="security-and-privacy"><span class="secno">6.8.2.1 </span>Security and privacy</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 3766:
3767: <p>These mechanisms can introduce a number of concerns, in
3768: particular privacy concerns.</p>
3769:
3770: <p><strong>Hijacking all Web usage.</strong> User agents should not
3771: allow schemes that are key to its normal operation, such as
3772: <code>http</code> or <code>https</code>, to be rerouted through
3773: third-party sites. This would allow a user's activities to be
3774: trivially tracked, and would allow user information, even in secure
3775: connections, to be collected.</p>
3776:
3777: <p><strong>Hijacking defaults.</strong> It is strongly recommended
3778: that user agents do not automatically change any defaults, as this
3779: could lead the user to send data to remote hosts that the user is
3780: not expecting. New handlers registering themselves should never
3781: automatically cause those sites to be used.</p>
3782:
3783: <p><strong>Registration spamming.</strong> User agents should
3784: consider the possibility that a site will attempt to register a
3785: large number of handlers, possibly from multiple domains (e.g. by
3786: redirecting through a series of pages each on a different domain,
3787: and each registering a handler for <code>video/mpeg</code> —
3788: analogous practices abusing other Web browser features have been
3789: used by pornography Web sites for many years). User agents should
3790: gracefully handle such hostile attempts, protecting the user.</p>
3791:
3792: <p><strong>Misleading titles.</strong> User agents should not rely
3793: wholly on the <var title="">title</var> argument to the methods when
3794: presenting the registered handlers to the user, since sites could
3795: easily lie. For example, a site <code>hostile.example.net</code>
3796: could claim that it was registering the "Cuddly Bear Happy Content
3797: Handler". User agents should therefore use the handler's domain in
3798: any UI along with any title.</p>
3799:
3800: <p><strong>Hostile handler metadata.</strong> User agents should
3801: protect against typical attacks against strings embedded in their
3802: interface, for example ensuring that markup or escape characters in
3803: such strings are not executed, that null bytes are properly handled,
3804: that over-long strings do not cause crashes or buffer overruns, and
3805: so forth.</p>
3806:
3807: <p><strong>Leaking Intranet URLs.</strong> The mechanism described
3808: in this section can result in secret Intranet URLs being leaked, in
3809: the following manner:</p>
3810:
3811: <ol><li>The user registers a third-party content handler as the default
3812: handler for a content type.</li>
3813:
3814: <li>The user then browses his corporate Intranet site and accesses
3815: a document that uses that content type.</li>
3816:
3817: <li>The user agent contacts the third party and hands the third
3818: party the URL to the Intranet content.</li>
3819:
3820: </ol><p>No actual confidential file data is leaked in this manner, but
3821: the URLs themselves could contain confidential information. For
3822: example, the URL could be
3823: <code>http://www.corp.example.com/upcoming-aquisitions/the-sample-company.egf</code>,
3824: which might tell the third party that Example Corporation is
3825: intending to merge with The Sample Company. Implementors might wish
3826: to consider allowing administrators to disable this feature for
3827: certain subdomains, content types, or schemes.</p>
3828:
3829: <p><strong>Leaking secure URLs.</strong> User agents should not send
3830: HTTPS URLs to third-party sites registered as content handlers, in
3831: the same way that user agents do not send <code title="http-referer">Referer</code> (sic) HTTP headers from secure
3832: sites to third-party sites.</p>
3833:
3834: <p><strong>Leaking credentials.</strong> User agents must never send
3835: username or password information in the URLs that are escaped and
3836: included sent to the handler sites. User agents may even avoid
3837: attempting to pass to Web-based handlers the URLs of resources
3838: that are known to require authentication to access, as such sites
3839: would be unable to access the resources in question without
3840: prompting the user for credentials themselves (a practice that would
3841: require the user to know whether to trust the third-party handler, a
3842: decision many users are unable to make or even understand).</p>
3843:
1.123 mike 3844: </div><div class="impl">
1.1 mike 3845:
1.614 mike 3846: <h5 id="sample-handler-impl"><span class="secno">6.8.2.2 </span>Sample user interface</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
1.1 mike 3847:
3848: <p><i>This section is non-normative.</i></p>
3849:
3850: <p>A simple implementation of this feature for a desktop Web browser
3851: might work as follows.</p>
3852:
3853: <p>The <code title="dom-navigator-registerContentHandler"><a href="#dom-navigator-registercontenthandler">registerContentHandler()</a></code>
3854: method could display a modal dialog box:</p>
3855:
3856: <pre>||[ Content Handler Registration ]||||||||||||||||||||||||||||
3857: | |
3858: | This Web page: |
3859: | |
3860: | Kittens at work |
3861: | http://kittens.example.org/ |
3862: | |
3863: | ...would like permission to handle files of type: |
3864: | |
3865: | application/x-meowmeow |
3866: | |
3867: | using the following Web-based application: |
3868: | |
3869: | Kittens-at-work displayer |
3870: | http://kittens.example.org/?show=%s |
3871: | |
3872: | Do you trust the administrators of the "kittens.example. |
3873: | org" domain? |
3874: | |
3875: | ( Trust kittens.example.org ) (( Cancel )) |
3876: |____________________________________________________________|</pre>
3877:
3878: <p>...where "Kittens at work" is the title of the page that invoked
3879: the method, "http://kittens.example.org/" is the URL of that page,
3880: "application/x-meowmeow" is the string that was passed to the <code title="dom-navigator-registerContentHandler"><a href="#dom-navigator-registercontenthandler">registerContentHandler()</a></code>
3881: method as its first argument (<var title="">mimeType</var>),
3882: "http://kittens.example.org/?show=%s" was the second argument (<var title="">url</var>), and "Kittens-at-work displayer" was the third
3883: argument (<var title="">title</var>).</p>
3884:
3885: <p>If the user clicks the Cancel button, then nothing further
3886: happens. If the user clicks the "Trust" button, then the handler is
3887: remembered.</p>
3888:
3889: <p>When the user then attempts to fetch a URL that uses the
1.104 mike 3890: "application/x-meowmeow" <a href="infrastructure.html#mime-type">MIME type</a>, then it might display a dialog
1.1 mike 3891: as follows:</p>
3892:
3893: <pre>||[ Unknown File Type ]|||||||||||||||||||||||||||||||||||||||
3894: | |
3895: | You have attempted to access: |
3896: | |
3897: | data:application/x-meowmeow;base64,S2l0dGVucyBhcmUgd |
3898: | GhlIGN1dGVzdCE%3D |
3899: | |
3900: | How would you like FerretBrowser to handle this resource? |
3901: | |
3902: | (o) Contact the FerretBrowser plugin registry to see if |
3903: | there is an official way to handle this resource. |
3904: | |
3905: | ( ) Pass this URL to a local application: |
3906: | [ /no application selected/ ] ( Choose ) |
3907: | |
3908: | ( ) Pass this URL to the "Kittens-at-work displayer" |
3909: | application at "kittens.example.org". |
3910: | |
3911: | [ ] Always do this for resources using the "application/ |
3912: | x-meowmeow" type in future. |
3913: | |
3914: | ( Ok ) (( Cancel )) |
3915: |____________________________________________________________|</pre>
3916:
3917: <p>...where the third option is the one that was primed by the site
3918: registering itself earlier.</p>
3919:
3920: <p>If the user does select that option, then the browser, in
3921: accordance with the requirements described in the previous two
3922: sections, will redirect the user to
3923: "http://kittens.example.org/?show=data%3Aapplication/x-meowmeow;base64,S2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%253D".</p>
3924:
3925: <p>The <code title="dom-navigator-registerProtocolHandler"><a href="#dom-navigator-registerprotocolhandler">registerProtocolHandler()</a></code>
3926: method would work equivalently, but for schemes instead of unknown
3927: content types.</p>
3928:
1.614 mike 3929: </div><h4 id="manually-releasing-the-storage-mutex"><span class="secno">6.8.3 </span>Manually releasing the storage mutex</h4><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><dl class="domintro"><dt><var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">yieldForStorageUpdates</a></code>()</dt>
1.1 mike 3930:
3931: <dd>
3932:
3933: <p>If a script uses the <code title="dom-document-cookie"><a href="dom.html#dom-document-cookie">document.cookie</a></code> API, or the
3934: <code title="dom-localStorage">localStorage</code> API, the
3935: browser will block other scripts from accessing cookies or storage
3936: until the first script finishes.</p>
3937:
1.185 mike 3938: <p>Calling the <code title="dom-navigator-yieldForStorageUpdates"><a href="#dom-navigator-yieldforstorageupdates">navigator.yieldForStorageUpdates()</a></code>
1.1 mike 3939: method tells the user agent to unblock any other scripts that may
3940: be blocked, even though the script hasn't returned.</p>
3941:
3942: <p>Values of cookies and items in the <code>Storage</code> objects
3943: of <code title="dom-localStorage">localStorage</code> attributes
3944: can change after calling this method, whence its name.</p>
3945:
3946: </dd>
3947:
3948: </dl><div class="impl">
3949:
1.185 mike 3950: <p>The <dfn id="dom-navigator-yieldforstorageupdates" title="dom-navigator-yieldForStorageUpdates"><code>yieldForStorageUpdates()</code></dfn>
1.1 mike 3951: method, when invoked, must, if the <a href="#storage-mutex">storage mutex</a> is
3952: owned by the <a href="#event-loop">event loop</a> of the <a href="#concept-task" title="concept-task">task</a> that resulted in the method being
3953: called, release the <a href="#storage-mutex">storage mutex</a> so that it is once
3954: again free. Otherwise, it must do nothing.</p>
3955:
1.123 mike 3956: </div></body></html>
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to browsers.html CVS log ![[TXT]](/https/dev.w3.org/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/https/dev.w3.org/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / html5 / spec