Annotation of html5/spec/browsers.html, revision 1.119

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

Webmaster