This section describes features that apply most directly to Web browsers. Having said that, except where specified otherwise, the requirements defined in this section do apply to all user agents, whether they are Web browsers or not.
A browsing context is an environment in which Document
objects are
presented to the user.
A tab or window in a Web browser typically contains a browsing
context, as does an iframe
or frame
s in a
frameset
.
Each browsing context has a corresponding WindowProxy
object.
A browsing context has a session history, which lists the
Document
objects that that browsing context has presented, is
presenting, or will present. At any time, one Document
in each browsing
context is designated the active document. A Document
's
browsing context is that browsing context whose session
history contains the Document
, if any. (A Document
created using
an API such as createDocument()
has no
browsing context.)
Each Document
in a browsing context is
associated with a Window
object. A browsing
context's WindowProxy
object forwards everything to the browsing
context's active document's Window
object.
In general, there is a 1-to-1 mapping from the Window
object to the
Document
object. There are two exceptions. First, a Window
can be reused
for the presentation of a second Document
in the same browsing context,
such that the mapping is then 1-to-2. This occurs when a browsing context is navigated from the initial about:blank
Document
to another, with replacement enabled. Second, a Document
can end up
being reused for several Window
objects when the document.open()
method is used, such that the mapping is then
many-to-1.
A Document
does not necessarily have a browsing context
associated with it. In particular, data mining tools are likely to never instantiate browsing
contexts.
A browsing context can have a creator browsing context, the browsing context that was responsible for its creation. If a browsing context has a parent browsing context, then that is its creator browsing context. Otherwise, if the browsing context has an opener browsing context, then that is its creator browsing context. Otherwise, the browsing context has no creator browsing context.
If a browsing context A has a creator browsing
context, then the Document
that was the active document of that
creator browsing context at the time A was created is the
creator Document
.
When a browsing context is first created, it must be created with a single
Document
in its session history, whose address is about:blank
, which is marked as being an HTML document, whose character
encoding is UTF-8, and which is both ready for post-load tasks and
completely loaded immediately. The Document
must have a single child
html
node, which itself has a single child body
node. As soon as this
Document
is created, the user agent must implement the sandboxing for
it. If the browsing context has a creator Document
, then
the browsing context's Document
's referrer must be set to the address
of that creator Document
at the time of the browsing
context's creation.
If the browsing context is created specifically to be immediately navigated, then that initial navigation will have replacement enabled.
The origin and effective script origin of the
about:blank
Document
are set when the Document
is created.
If the new browsing context has a creator browsing context, then the
origin of the about:blank
Document
is an alias to the origin of the creator
Document
and the effective script origin of the
about:blank
Document
is initially an alias to the effective script origin of the
creator Document
. Otherwise, the origin of the
about:blank
Document
is a globally unique identifier assigned when the
new browsing context is created and the effective script origin of the
about:blank
Document
is initially an alias to its origin.
Certain elements (for example, iframe
elements) can instantiate further browsing contexts. These are called nested browsing contexts. If a browsing context P has a
Document
D with an element E that nests
another browsing context C inside it, then C is said to be
nested through D, and E is said to be the browsing context container of C.
If the browsing context container element E is in the Document
D, then P is
said to be the parent browsing context of C and C is said to be a child browsing context of P.
Otherwise, the nested browsing context C has no parent
browsing context.
A browsing context A is said to be an ancestor of a browsing context B if there exists a browsing context A' that is a child browsing context of A and that is itself an ancestor of B, or if the browsing context A is the parent browsing context of B.
A browsing context that is not a nested browsing context has no parent browsing context, and is the top-level browsing context of all the browsing contexts for which it is an ancestor browsing context.
The transitive closure of parent browsing contexts for a nested browsing context gives the list of ancestor browsing contexts.
The list of the descendant browsing contexts of a Document
d is the (ordered) list returned by the following algorithm:
Let list be an empty list.
For each child browsing context of d that is nested through an element that is in the Document
d, in the tree
order of the elements nesting those browsing
contexts, run these substeps:
Append that child browsing context to the list list.
Append the list of the descendant browsing contexts of the active document of that child browsing context to the list list.
Return the constructed list.
A Document
is said to be fully active when it is the active
document of its browsing context, and either its browsing context is a
top-level browsing context, or it has a parent browsing context and the
Document
through which it is
nested is itself fully active.
Because they are nested through an element, child browsing
contexts are always tied to a specific Document
in their parent browsing
context. User agents must not allow the user to interact with child browsing contexts of elements that are in Document
s that are
not themselves fully active.
A nested browsing context can have a seamless browsing context flag
set, if it is embedded through an iframe
element with a seamless
attribute.
A nested browsing context can be put into a delaying load
events mode. This is used when it is navigated, to delay the load event of the browsing
context container iframe
element before the new Document
is
created.
The document family of a browsing context consists of the union of all
the Document
objects in that browsing context's session
history and the document families of all those
Document
objects. The document family of a Document
object
consists of the union of all the document families of the
browsing contexts that are nested through the Document
object.
top
Returns the WindowProxy
for the top-level browsing context.
parent
Returns the WindowProxy
for the parent browsing context.
frameElement
Returns the Element
for the browsing context container.
Returns null if there isn't one.
Throws a SecurityError
exception in cross-origin situations.
The top
IDL attribute on the Window
object
of a Document
in a browsing context b must return
the WindowProxy
object of its top-level browsing context (which would be
its own WindowProxy
object if it was a top-level browsing context
itself), if it has one, or its own WindowProxy
object otherwise (e.g. if it was a
detached nested browsing context).
The parent
IDL attribute on the Window
object of a Document
in a browsing context b must
return the WindowProxy
object of the parent browsing context, if there
is one (i.e. if b is a child browsing context), or the
WindowProxy
object of the browsing context b itself,
otherwise (i.e. if it is a top-level browsing context or a detached nested
browsing context).
The frameElement
IDL attribute on the
Window
object of a Document
d, on getting, must run
the following algorithm:
If d is not a Document
in a nested browsing
context, return null and abort these steps.
If the browsing context container's Document
does not have the
same effective script origin as the entry
script, then throw a SecurityError
exception and abort these steps.
Return the browsing context container for b.
It is possible to create new browsing contexts that are related to a top-level browsing context without being nested through an element. Such browsing contexts are called auxiliary browsing contexts. Auxiliary browsing contexts are always top-level browsing contexts.
An auxiliary browsing context has an opener browsing context, which is the browsing context from which the auxiliary browsing context was created.
The opener
IDL attribute on the Window
object, on getting, must return the WindowProxy
object of the browsing
context from which the current browsing context was created (its opener
browsing context), if there is one, if it is still available, and if the current
browsing context has not disowned its opener; otherwise, it must return null.
On setting, if the new value is null then the current browsing context must disown its opener; if the new value is anything else then the
user agent must ignore the new value.
User agents may support secondary browsing contexts, which are browsing contexts that form part of the user agent's interface, apart from the main content area.
The sidebar
link type uses secondary browsing contexts.
A browsing context A is familiar with a second browsing context B if one of the following conditions is true:
A browsing context A is allowed to navigate a second browsing context B if the following algorithm terminates positively:
If A is not the same browsing context as B, and A is not one of the ancestor browsing contexts of B, and B is not a top-level browsing context, and A's active document's active sandboxing flag set has its sandboxed navigation browsing context flag set, then abort these steps negatively.
Otherwise, if B is a top-level browsing context, and is
one of the ancestor browsing contexts of A, and A's Document
's active sandboxing
flag set has its sandboxed top-level navigation browsing context flag set,
then abort these steps negatively.
Otherwise, if B is a top-level browsing context, and is
not one of the ancestor browsing contexts of A, and A's Document
's active sandboxing
flag set has its sandboxed navigation browsing context flag set, and A is not the one permitted sandboxed navigator of B, then abort these steps negatively.
Otherwise, terminate positively!
An element has a browsing context scope origin if its Document
's
browsing context is a top-level browsing context or if all of its
Document
's ancestor browsing contexts
all have active documents whose origin are the
same origin as the element's Document
's origin. If an
element has a browsing context scope origin, then its value is the
origin of the element's Document
.
Each browsing context is defined as having a list of one or more directly reachable browsing contexts. These are:
The transitive closure of all the browsing contexts that are directly reachable browsing contexts forms a unit of related browsing contexts.
Each unit of related browsing contexts is then further divided into the smallest
number of groups such that every member of each group has an active document with an
effective script origin that, through appropriate manipulation of the document.domain
attribute, could be made to be the same as
other members of the group, but could not be made the same as members of any other group. Each
such group is a unit of related similar-origin browsing contexts.
There is also at most one event loop per unit of related similar-origin browsing contexts (though several units of related similar-origin browsing contexts can have a shared event loop).
Browsing contexts can have a browsing context name. By default, a browsing context has no name (its name is not set).
A valid browsing context name is any string with at least one character that does not start with a U+005F LOW LINE character. (Names starting with an underscore are reserved for special keywords.)
A valid browsing context name or keyword is any string that is either a valid
browsing context name or that is an ASCII case-insensitive match for one of:
_blank
, _self
, _parent
, or _top
.
These values have different meanings based on whether the page is sandboxed or not, as
summarized in the following (non-normative) table. In this table, "current" means the
browsing context that the link or script is in, "parent" means the parent
browsing context of the one the link or script is in, "master" means the nearest
ancestor browsing context of the one the link or script is in that is not itself in a
seamless iframe, "top" means the top-level
browsing context of the one the link or script is in, "new" means a new top-level
browsing context or auxiliary browsing context is to be created, subject to
various user preferences and user agent policies, "none" means that nothing will happen, and
"maybe new" means the same as "new" if the "allow-popups
" keyword is also specified on the
sandbox
attribute (or if the user overrode the
sandboxing), and the same as "none" otherwise.
Keyword | Ordinary effect | Effect in an iframe with...
| ||||
---|---|---|---|---|---|---|
seamless=""
| sandbox=""
| sandbox="" seamless=""
| sandbox="allow-top-navigation"
| sandbox="allow-top-navigation" seamless=""
| ||
none specified, for links and form submissions | current | master | current | master | current | master |
empty string | current | master | current | master | current | master |
_blank
| new | new | maybe new | maybe new | maybe new | maybe new |
_self
| current | current | current | current | current | current |
_parent if there isn't a parent
| current | current | current | current | current | current |
_parent if parent is also top
| parent/top | parent/top | none | none | parent/top | parent/top |
_parent if there is one and it's not top
| parent | parent | none | none | none | none |
_top if top is current
| current | current | current | current | current | current |
_top if top is not current
| top | top | none | none | top | top |
name that doesn't exist | new | new | maybe new | maybe new | maybe new | maybe new |
name that exists and is a descendant | specified descendant | specified descendant | specified descendant | specified descendant | specified descendant | specified descendant |
name that exists and is current | current | current | current | current | current | current |
name that exists and is an ancestor that is top | specified ancestor | specified ancestor | none | none | specified ancestor/top | specified ancestor/top |
name that exists and is an ancestor that is not top | specified ancestor | specified ancestor | none | none | none | none |
other name that exists with common top | specified | specified | none | none | none | none |
name that exists with different top, if familiar and one permitted sandboxed navigator | specified | specified | specified | specified | specified | specified |
name that exists with different top, if familiar but not one permitted sandboxed navigator | specified | specified | none | none | none | none |
name that exists with different top, not familiar | new | new | maybe new | maybe new | maybe new | maybe new |
Most of the restrictions on sandboxed browsing contexts are applied by other algorithms, e.g. the navigation algorithm, not the rules for choosing a browsing context given a browsing context name given below.
An algorithm is allowed to show a popup if any of the following conditions is true:
The task in which the algorithm is running is currently
processing an activation behavior whose click
event
was trusted.
The task in which the algorithm is running is currently running the event listener for a trusted event whose type is in the following list:
change
click
dblclick
mouseup
reset
submit
The task in which the algorithm is running was queued by an algorithm that was allowed to show a popup, and the chain of such algorithms started within a user-agent defined timeframe.
For example, if a user clicked a button, it might be acceptable for a popup to result from that after 4 seconds, but it would likely not be acceptable for a popup to result from that after 4 hours.
The rules for choosing a browsing context given a browsing context name are as follows. The rules assume that they are being applied in the context of a browsing context, as part of the execution of a task.
If the given browsing context name is the empty string or _self
, then
the chosen browsing context must be the current one.
If the given browsing context name is _self
, then this is an
explicit self-navigation override, which overrides the behavior of the
seamless browsing context flag set by the seamless
attribute on iframe
elements.
If the given browsing context name is _parent
, then the chosen
browsing context must be the parent browsing context of the current one,
unless there isn't one, in which case the chosen browsing context must be the current browsing
context.
If the given browsing context name is _top
, then the chosen browsing
context must be the top-level browsing context of the current one, if there is one,
or else the current browsing context.
If the given browsing context name is not _blank
and there exists a
browsing context whose name is the same as the given
browsing context name, and the current browsing context is familiar with that
browsing context, and the user agent determines that the two browsing contexts are related
enough that it is ok if they reach each other, then that browsing context must be the chosen
one. If there are multiple matching browsing contexts, the user agent should select one in some
arbitrary consistent manner, such as the most recently opened, most recently focused, or more
closely related.
If the browsing context is chosen by this step to be the current browsing context, then this is also an explicit self-navigation override.
Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and abilities — it is determined by the rules given for the first applicable option from the following list:
There is no chosen browsing context. The user agent may inform the user that a popup has been blocked.
Typically, there is no chosen browsing context.
The user agent may offer to create a new top-level browsing context or reuse an existing top-level browsing context. If the user picks one of those options, then the designated browsing context must be the chosen one (the browsing context's name isn't set to the given browsing context name). The default behaviour (if the user agent doesn't offer the option to the user, or if the user declines to allow a browsing context to be used) must be that there must not be a chosen browsing context.
If this case occurs, it means that an author has explicitly sandboxed the document that is trying to open a link.
noreferrer
keywordA new top-level browsing context must be created. If the given browsing
context name is not _blank
, then the new top-level browsing context's
name must be the given browsing context name (otherwise, it has no name). The chosen browsing
context must be this new browsing context. The creation of such a browsing context
is a new start for session storage.
If it is immediately navigated, then the navigation will be done with replacement enabled.
noreferrer
keyword doesn't
applyA new auxiliary browsing context must be created, with the opener
browsing context being the current one. If the given browsing context name is not _blank
, then the new auxiliary browsing context's name must be the given
browsing context name (otherwise, it has no name). The chosen browsing context must be this new
browsing context.
If it is immediately navigated, then the navigation will be done with replacement enabled.
The chosen browsing context is the current browsing context.
There must not be a chosen browsing context.
User agent implementors are encouraged to provide a way for users to configure the user agent to always reuse the current browsing context.
If the current browsing context's active document's active sandboxing flag set has the sandboxed navigation browsing context flag set and the chosen browsing context picked above, if any, is a new browsing context (whether top-level or auxiliary), then all the flags that are set in the current browsing context's active document's active sandboxing flag set when the new browsing context is created must be set in the new browsing context's popup sandboxing flag set, and the current browsing context must be set as the new browsing context's one permitted sandboxed navigator.
Window
object[Global] /*sealed*/ interface Window : EventTarget { // the current browsing context [Unforgeable] readonly attribute WindowProxy window; [Replaceable] readonly attribute WindowProxy self; [Unforgeable] readonly attribute Document document; attribute DOMString name; [PutForwards=href, Unforgeable] readonly attribute Location location; readonly attribute History history; [Replaceable] readonly attribute BarProp locationbar; [Replaceable] readonly attribute BarProp menubar; [Replaceable] readonly attribute BarProp personalbar; [Replaceable] readonly attribute BarProp scrollbars; [Replaceable] readonly attribute BarProp statusbar; [Replaceable] readonly attribute BarProp toolbar; attribute DOMString status; void close(); readonly attribute boolean closed; void stop(); void focus(); void blur(); // other browsing contexts [Replaceable] readonly attribute WindowProxy frames; [Replaceable] readonly attribute unsigned long length; [Unforgeable] readonly attribute WindowProxy top; attribute WindowProxy? opener; readonly attribute WindowProxy parent; readonly attribute Element? frameElement; WindowProxy open(optional DOMString url = "about:blank", optional DOMString target = "_blank", optional DOMString features = "", optional boolean replace = false); getter WindowProxy (unsigned long index); getter object (DOMString name); // the user agent readonly attribute Navigator navigator; readonly attribute External external; readonly attribute ApplicationCache applicationCache; // user prompts void alert(optional DOMString message = ""); boolean confirm(optional DOMString message = ""); DOMString? prompt(optional DOMString message = "", optional DOMString default = ""); void print(); any showModalDialog(DOMString url, optional any argument); void postMessage(any message, DOMString targetOrigin, optional sequence<Transferable> transfer); // also has obsolete members }; Window implements GlobalEventHandlers; Window implements WindowEventHandlers;
window
frames
self
These attributes all return window.
document
Returns the Document
associated with window.
defaultView
Returns the Window
object of the active document.
The Window
interface must only be exposed to JavaScript if the
JavaScript global environment is a document environment.
The window
, frames
, and self
IDL attributes must all return the Window
object's browsing context's
WindowProxy
object.
The document
IDL attribute must return
the Window
object's newest Document
object.
The defaultView
IDL attribute of the
Document
interface must return the Document
's browsing
context's WindowProxy
object, if there is one, or null otherwise.
For historical reasons, Window
objects must also have a writable, configurable,
non-enumerable property named HTMLDocument
whose value is the
Document
interface object.
This section describes a security model that is underdefined, imperfect, and does
not match implementations. Work is ongoing to attempt to resolve this, but in the meantime, please
do not rely on this section for precision. Implementors are urged to send their feedback on how
cross-origin cross-global access to Window
and Location
objects should
work.
User agents must throw a SecurityError
exception whenever any
properties of a Window
object are accessed when the incumbent script has
an effective script origin that is not the same as
the Window
object's
Document
's effective script origin, with the following
exceptions:
location
attribute
postMessage()
method
window
attribute
frames
attribute
self
attribute
top
attribute
parent
attribute
opener
attribute
closed
attribute
close()
method
blur()
method
focus()
method
When the incumbent script's effective script origin is different than
a Window
object's
Document
's effective script origin, the user agent must act as if
any changes to that Window
object's properties, getters, setters, etc, were not
present, and as if all the properties of that Window
object had their [[Enumerable]]
attribute set to false.
For members that return objects (including function objects), each distinct effective
script origin that is not the same as the Window
object's
Document
's effective script origin must be provided with a separate set
of objects. These objects must have the prototype chain appropriate for the script for which the
objects are created (not those that would be appropriate for scripts whose script's global
object is the Window
object in question).
For instance, if two frames containing Document
s from different origins access the same Window
object's postMessage()
method, they will get distinct objects that
are not equal.
open
( [ url [, target [, features [, replace ] ] ] ] )Opens a window to show url (defaults to about:blank
), and
returns it. The target argument gives the name of the new window. If a
window exists with that name already, it is reused. The replace attribute,
if true, means that whatever page is currently open in that window will be removed from the
window's session history. The features argument is ignored.
name
[ = value ]Returns the name of the window.
Can be set, to change the name.
close
()Closes the window.
closed
Returns true if the window has been closed, false otherwise.
stop
()Cancels the document load.
The open()
method on Window
objects
provides a mechanism for navigating an existing browsing
context or opening and navigating an auxiliary browsing context.
The method has four arguments, though they are all optional.
The first argument, url, must be a valid non-empty URL for a
page to load in the browsing context. If the first argument is the empty string, then the url argument must be interpreted as "about:blank
". Otherwise, the
argument must be resolved to an absolute URL (or
an error), relative to the entry script's base
URL, when the method is invoked.
The second argument, target, specifies the name of the browsing context that is to be navigated. It must be a valid browsing context name or keyword.
The third argument, features, has no defined effect and is mentioned for historical reasons only. User agents may interpret this argument as instructions to set the size and position of the browsing context, but are encouraged to instead ignore the argument entirely.
The fourth argument, replace, specifies whether or not the new page will replace the page currently loaded in the browsing context, when target identifies an existing browsing context (as opposed to leaving the current page in the browsing context's session history).
When the method is invoked, the user agent must first select a browsing context to navigate by applying the rules for choosing a browsing context given a browsing context name using the target argument as the name and the browsing context of the script as the context in which the algorithm is executed, unless the user has indicated a preference, in which case the browsing context to navigate may instead be the one indicated by the user.
For example, suppose there is a user agent that supports control-clicking a
link to open it in a new tab. If a user clicks in that user agent on an element whose onclick
handler uses the window.open()
API to open a page in an iframe, but, while doing so, holds
the control key down, the user agent could override the selection of the target browsing context
to instead target a new tab.
If applying the rules for choosing a browsing context given a browsing context
name using the target argument would result in there not being a chosen
browsing context, then throw an InvalidAccessError
exception and abort these
steps.
Otherwise, if url is not "about:blank
", the user agent must
navigate the selected browsing context to the
absolute URL obtained from resolving url earlier. If the replace is true or if the browsing
context was just created as part of the rules for choosing a browsing context given a
browsing context name, then replacement must be
enabled. The navigation must be done with the browsing context of the incumbent script as the source browsing
context. If the resolve a URL algorithm failed, then the user agent may either
instead navigate to an inline error page, using the same replacement behavior and
source browsing context behavior as described earlier in this paragraph; or treat the url as "about:blank
", acting as described in the next paragraph.
If url is "about:blank
", and the browsing
context was just created as part of the rules for choosing a browsing context given a
browsing context name, then the user agent must instead queue a task to
fire a simple event named load
at the selected
browsing context's Window
object, but with its target
set to the selected browsing context's Window
object's Document
object
(and the currentTarget
set to the Window
object).
The method must return the WindowProxy
object of the browsing context
that was navigated, or null if no browsing context was navigated.
The name
attribute of the Window
object
must, on getting, return the current name of the
browsing context, and, on setting, set the name of the browsing context to the new value.
The name gets reset when the browsing context is navigated to another domain.
The close()
method on Window
objects should, if all the following conditions are met, close the browsing context A:
A browsing context is script-closable if it is an auxiliary
browsing context that was created by a script (as opposed to by an action of the user), or
if it is a browsing context whose session history contains only one
Document
.
The closed
attribute on Window
objects must return true if the Window
object's browsing context has
been discarded, and false otherwise.
The stop()
method on Window
objects should, if there is an existing attempt to navigate the browsing
context and that attempt is not currently running the unload a document
algorithm, cancel that navigation; then, it must abort the active document of the browsing context of
the Window
object on which it was invoked.
length
Returns the number of child browsing contexts.
Returns the indicated child browsing context.
The length
IDL attribute on the Window
interface must return the number of child browsing
contexts that are nested through
elements that are in the Document
that is the
active document of that Window
object, if that Window
's
browsing context shares the same event loop as the script's
browsing context of the entry script accessing the IDL attribute; otherwise,
it must return zero.
The supported property indices on the Window
object at any instant
are the numbers in the range 0 .. n-1, where n is the number returned by the length
IDL
attribute. If n is zero then there are no supported property
indices.
To determine the value of an indexed property index of a Window
object, the user agent must return the
WindowProxy
object of the indexth child browsing
context of the Document
that is nested through an element that is in the Document
, sorted in the tree order
of the elements nesting those browsing contexts.
These properties are the dynamic nested browsing context properties.
Window
objectReturns the indicated element or collection of elements.
The Window
interface supports named
properties. The supported property names at any moment consist of the
following, in tree order, ignoring later duplicates:
name
content attribute for all a
,
applet
, area
, embed
, form
,
frameset
, img
, and object
elements in the active
document that have a non-empty name
content attribute, andid
content attribute of any HTML element in the active document with a non-empty id
content attribute.To determine the value of a named property name when the Window
object is indexed for property
retrieval, the user agent must return the value obtained using the following steps:
Let objects be the list of named objects with the name name in the active document.
There will be at least one such object, by definition.
If objects contains a nested browsing context, then return
the WindowProxy
object of the nested browsing context corresponding to
the first browsing context container in tree order whose
browsing context is in objects, and abort these steps.
Otherwise, if objects has only one element, return that element and abort these steps.
Otherwise return an HTMLCollection
rooted at the Document
node,
whose filter matches only named objects with
the name name. (By definition, these will all be elements.)
Named objects with the name name, for the purposes of the above algorithm, are those that are either:
a
, applet
, area
, embed
,
form
, frameset
, img
, or object
elements that
have a name
content attribute whose value is name, orid
content attribute
whose value is name.A browsing context has a strong reference to each of its Document
s
and its WindowProxy
object, and the user agent itself has a strong reference to its
top-level browsing contexts.
A Document
has a strong reference to its Window
object.
A Window
object has a strong
reference to its Document
object through its document
attribute. Thus, references from other scripts to either of
those objects will keep both alive. Similarly, both Document
and Window
objects have implied strong references to the
WindowProxy
object.
Each script has a strong reference to its browsing context and its document.
When a browsing context is to discard a Document
, the user
agent must run the following steps:
Set the Document
's salvageable state to false.
Run any unloading document cleanup steps for the Document
that
are defined by this specification and other applicable specifications.
Remove any tasks associated with the
Document
in any task source, without running those tasks.
Discard all the child browsing contexts of the Document
.
Lose the strong reference from the Document
's browsing context
to the Document
.
Whenever a Document
object is discarded, it is also removed from the list of the worker's
Document
s of each worker whose list contains that Document
.
When a browsing context is discarded, the strong reference
from the user agent itself to the browsing context must be severed, and all the
Document
objects for all the entries in the browsing context's session
history must be discarded as well.
User agents may discard top-level browsing contexts at any time (typically, in
response to user requests, e.g. when a user force-closes a window containing one or more top-level browsing contexts). Other browsing contexts must be discarded once their
WindowProxy
object is eligible for garbage collection.
When the user agent is required to close a browsing context, it must run the following steps:
Let specified browsing context be the browsing context being closed.
Prompt to unload the active document of the specified browsing context. If the user refused to allow the document to be unloaded, then abort these steps.
Unload the active document of the specified browsing context with the recycle parameter set to false.
Remove the specified browsing context from the user interface (e.g. close or hide its tab in a tabbed browser).
Discard the specified browsing context.
User agents should offer users the ability to arbitrarily close any top-level browsing context.
To allow Web pages to integrate with Web browsers, certain Web browser interface elements are exposed in a limited way to scripts in Web pages.
Each interface element is represented by a BarProp
object:
interface BarProp { attribute boolean visible; };
locationbar
. visible
Returns true if the location bar is visible; otherwise, returns false.
menubar
. visible
Returns true if the menu bar is visible; otherwise, returns false.
personalbar
. visible
Returns true if the personal bar is visible; otherwise, returns false.
scrollbars
. visible
Returns true if the scroll bars are visible; otherwise, returns false.
statusbar
. visible
Returns true if the status bar is visible; otherwise, returns false.
toolbar
. visible
Returns true if the toolbar is visible; otherwise, returns false.
The visible attribute, on getting, must return either true or a value determined by the user agent to most accurately represent the visibility state of the user interface element that the object represents, as described below. On setting, the new value must be discarded.
The following BarProp
objects exist for each Document
object in a
browsing context. Some of the user interface elements represented by these objects
might have no equivalent in some user agents; for those user agents, except when otherwise
specified, the object must act as if it was present and visible (i.e. its visible
attribute must return true).
BarProp
objectBarProp
objectBarProp
objectBarProp
objectBarProp
objectvisible
attribute may return false).BarProp
objectvisible
attribute may return false).The locationbar
attribute must return
the location bar BarProp
object.
The menubar
attribute must return the
menu bar BarProp
object.
The personalbar
attribute must return
the personal bar BarProp
object.
The scrollbars
attribute must return
the scrollbar BarProp
object.
The statusbar
attribute must return
the status bar BarProp
object.
The toolbar
attribute must return the
toolbar BarProp
object.
For historical reasons, the status
attribute
on the Window
object must, on getting, return the last string it was set to, and on
setting, must set itself to the new value. When the Window
object is created, the
attribute must be set to the empty string. It does not do anything else.
WindowProxy
objectAs mentioned earlier, each browsing context has a
WindowProxy
object. This object is unusual in that all operations that
would be performed on it must be performed on the Window
object of the browsing
context's active document instead. It is thus indistinguishable from that
Window
object in every way until the browsing context is navigated.
There is no WindowProxy
interface object.
The WindowProxy
object allows scripts to act as if each
browsing context had a single Window
object, while still keeping
separate Window
objects for each Document
.
In the following example, the variable x is set to the
WindowProxy
object returned by the window
accessor
on the global object. All of the expressions following the assignment return true, because in
every respect, the WindowProxy
object acts like the underlying Window
object.
var x = window; x instanceof Window; // true x === this; // true