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