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