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