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