Window Object 1.0

This specification defines the Window object, which provides the global namespace for web scripting languages, access to other documents in a compound document by reference, navigation to other locations, and timers. The Window object is a long-standing de facto standard for HTML user agents. However, it should not be assumed based on this or the name "Window" that it is limited to HTML or to visual user agents.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the 05 April 2006 Working Draft of the Window Object, the first publication of this specification. This document is produced by the Web API WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. The authors of this document are the members of the W3C Web API Working Group.

Web content and browser developers are encouraged to review this draft. Please send comments to public-webapi@w3.org, the W3C's public email list for issues related to Web APIs. Archives of the list are available.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

• 1. Introduction
• • 1.1. Examples of usage
  • 1.2. Not in This Specification
  • 1.3. Definitions
  • 1.4. Conformance
• 2. Browsing Contexts
• • 2.1. The Window Interface, Basic Attributes
  • • 2.1.1. Attributes
    • 2.1.2. Use in scripting
  • 2.2. The DocumentWindow Interface, Basic Attributes
• 3. Navigation
• • 3.1. The Window Interface, Location Attributes
  • • 3.1.1. Attributes
  • 3.2. The DocumentWindow Interface, Location Attributes
  • • 3.2.1. Attributes
  • 3.3. The Location Interface
  • • 3.3.1. Attributes
    • 3.3.2. Methods
• 4. Embedding: Compound Documents by Reference
• • 4.1. The Window Interface, Embedding Attributes
  • 4.2. The EmbeddingElement Interface
• 5. Timers
• • 5.1. The Window Interface, Timer Attributes
  • 5.2. The TimerListener Interface
• 6. Security Considerations

• A. IDL Definitions
• B. ECMAScript Language Binding
• C. Java Language Binding
• D. Acknowledgements
• E. References

1. Introduction

This section is not normative.

The Window Object 1.0 specification defines a subset of the features of the Window object, a widely implemented part of HTML User Agents, with parts also found in non-HTML UAs that offer scripting and DOM access. This specification is intended to be suitable for all implementations that present any sort of DOM document [DOM3Core] to the user.

This specification defines four features of the window object. It describes the use of the Window object as a browsing context: a container that displays a document, or a series of documents in sequence. It describes interfaces for navigation, the ability to go to a new document in the same browsing context. It describes interfaces for embedding, a feature also known as compound document by reference, where one document includes another separate document by external reference. And it specifies methods for using timers.

In addition, for some languages, such as ECMAScript [ECMAScript], the Window interface is implemented by the object that provides the global namespace for script execution. The details of how this works for ECMAScript are specified in ECMAScript Language Binding Appendix.

2. Browsing Contexts

A browsing context is a place where a user agent presents a document or a sequence of documents to the user, using one or more views. Only one document of this sequence is presented at a time. A browsing context is said to navigate when it changes from presenting one document to another, for example by following a hyperlink. More is specified about navigation behavior in the Navigation section.

A visual user agent typically presents a document by rendering it to a display. However, even non-visual agents could have a browsing context. For example, a voice browser also presents documents to the user. This also establishes a browsing context.

An object that implements the Document interface [DOM3Core] and is presented in a browsing context MUST also implement the DocumentWindow interface.

Each view of a Document presented in a browsing context MUST be represented by an object that implements the Window interface. One of these is the default view. The default view is typically the primary mode of presentation to the user, and in interactive user agents, the primary means of interaction for the user.

An object that implements the Window interface is referred to as a Window object. Note: despite the name, a Window object does not necessarily represent an onscreen overlapping window, even in visual user agents.

A document presented in a browsing context may have elements that embed additional documents, forming a Compound Document by Reference. Each such element creates a nested browsing context. This mechanism is described in Embedding: Compound Documents by Reference.

When an event implementing the UIEvent interface [DOM3EV] is dispatched on any node in a Document presented in a browsing context, the value of the view attribute of the event MUST be the Window object where the user originated the event.

interface Window : views::AbstractView {
    // ...

    // self-references
    readonly attribute Window window;
    readonly attribute Window self;

    // ...
};

interface DocumentWindow : views::DocumentView {
    // ...
};

3. Navigation

interface Window : views::AbstractView {
    // ...

    // assigning this has special behavior in ECMAScript, but it is otherwise
    // read only. specifically, in ES a string URI can be assigned to location,
    // having the same effect as location.assign(URI)
    readonly attribute Location location;

    // ...
};

interface DocumentWindow  : views::DocumentView {
    // ...
    // same special JS assignment as window.location
    readonly attribute Location location;
    // ...
};

interface Location {
    attribute dom::DOMString href;

    // pieces of the URI, per the generic URI syntax
    attribute dom::DOMString hash;
    attribute dom::DOMString host;
    attribute dom::DOMString hostname;
    attribute dom::DOMString pathname;
    attribute dom::DOMString port;
    attribute dom::DOMString protocol;
    attribute dom::DOMString search;

    void assign(in dom::DOMString url);
    void replace(in dom::DOMString url);
    void reload();

    dom::DOMString toString();
};

4. Embedding: Compound Documents by Reference

An element that refers to another document which is then embedded is called an embedding element. A document embedded in such an element is called a child document. Seen from a child document, the embedding element is part of a parent document. When a document has no embedding element that points to it the document is a root document. A document can be both a parent document and child document at the same time.

The value of the frameElement attribute of a Window object MUST be the embedding element, or null if there is no such element. The value of the parent attribute of a Window object MUST be the parent document's Window object or the document's Window object if there is no parent document. The value of the top attribute of a Window object MUST be the root document's Window object.

The name attribute of a Window object MUST be the name assigned by the embedding element, the empty string if there is no such element or a value set by the script author. How this name is extracted from the embedding element is language specific.

For example, if you have <object data="file" id="test"/> in an XHTML document the name DOM attribute within file will be "test".

The value of the contentDocument attribute of an object that implements the EmbeddingElement interface MUST be the child document's Document object or null if there is no such object.

interface Window {
    // name attribute of referencing frame/iframe/object, or name passed to
    // window.open
    attribute dom::DOMString name;

    // global object of containing document
    readonly attribute Window parent;

    // global object of outermost containing document
    readonly attribute Window top;

    // referencing <html:frame>, <html:iframe>, <html:object>, <svg:foreignObject>,
    // <svg:animation> or other embedding point, or null if none
    readonly attribute dom::Element frameElement;
};

// must be on an object that also implements dom::Element
interface EmbeddingElement {
    readonly attribute dom::Document contentDocument;
    readonly attribute Window contentWindow;
};

5. Timers

interface Window {
    // should timers allow more than long, maybe a floating point type?
    // don't think anyone's timers have more precision

    // one-shot timer
    long setTimeout(in TimerListener listener, in long milliseconds);
    void clearTimeout(in long timerID);

    // repeating timer
    long setInterval(in TimerListener listener, in long milliseconds);
    void clearInterval(in long timerID);
};

// behavior is always special in ECMAScript, this is defined only for the benefit
// of other languages
interface TimerListener {
    // what to put here?
};

6. Security Considerations

A. IDL Definitions

B. ECMAScript Language Binding

C. Java Language Binding

D. Acknowledgements

The WebAPI WG would like to thanks the following people for contributing to this specification:

Björn Höhrmann, Jim Ley, Cameron McCormack and Boris Zbarsky.

Special thanks to Anne van Kesteren for writing the Embedding section and many other additions and improvenets.

Special thanks to Ian Hickson for making the first attempt to standardize the Window object in Web Apps 1.0, drafts of which heavily influenced this document. In particular, he coined the term "browsing context".

E. References

DOM2Views

,

DOM3Core

,

DOM3EV

Document Object Model (DOM) Level 3 Events Specification, Philippe Le Hégaret (W3C), and Tom Pixley (Netscape Communications Corporation).

ECMAScript

,

Java

,

RFC2119

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner.

RFC2396

Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, and L. Masinter.