Window Object 1.0

W3C Editor's Draft 19 Feb 2006

This version:
Latest version:
Previous version:
Maciej Stachowiak (Apple Computer, Inc.) <mjs@apple.com>


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 longstanding 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 document is produced by the Web API WG (part of the Rich Web Clients Activity). This document has no formal standing within the W3C. Please send comments to public-webapi@w3.org, the public email list for issues related to Web APIs.

The patent policy for this document is the 5 February 2004 W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Web API Working Group's patent disclosure page. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as an Editor's 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

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. With this specification, it is recommended for all implementations that present documents to the user or provide the equivalent of a browsing context.

The main purpose of the Window object is to provide the global namespace for script execution. This specification defines four features of the window object, in addition to its use for the global namespace. 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 finally it provides timers.

1.1. Examples of usage

(this section is informative)

1.2. Not in This Specification

(this section is informative)

This specification does not include the following features, which are also found on the Window Object in some implementations. It is possible they will defined by other specifications or found in a future version of this specification.

1.3. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].

Sometimes, for readability, conformance requirements are phrased as requirements on elements, attributes, methods, interfaces, properties or functions. In all cases these are conformance requirements on implementations.

This specification defines two classes of conformance:

conforming implementation
A conforming implementation of the Window Object specification is one that implements all the interfaces in this specification, and satisfies all other MUST, REQUIRED and SHALL level criteria in all parts of this document other than language binding appendices.
conforming ECMAScript implementation
A conforming ECMAScript implementation of the Window Object specification is a conforming implementation that maps all of the interfaces in this specification to ECMAScript, and satisfies the additional requirements in the ECMAScript Language Binding Appendix.

2. Browsing Contexts

2.1. Overview

2.2. The Window Interface

// should this interface be called something else - Global, DOMWindow, DOMGlobal?
// should specify that for ECMAScript execution this provides the global scope
// based on Mozilla and Safari implementations, Win IE docs, Web Apps 1.0 draft
// (some also in SVG Tiny 1.2 draft)
interface Window : views::AbstractView {
    // AbstractView has a document attribute of type DocumentView, should we drop the
    // charade and admit it is a Document?

    // self-reference
    readonly attribute Window window;

    // self-reference - why both? because both are used
    readonly attribute Window self;

2.3. The DocumentWindow Interface

interface DocumentWindow : views::DocumentView {
// the defaultView must be the Window object

3.1. The WindowLocation Interface

interface WindowLocation {
    // Location object representing the current location
    // 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;

3.2. The DocumentLocation Interface

interface DocumentLocation {
    // must be same object as window.location
    // same special JS assignment as window.location
    readonly attribute Location location;

3.3. The Location Interface

interface Location {
    attribute DOMString href;
    // pieces of the URI, per the generic URI syntax
    attribute DOMString hash; // (fragment)
    attribute DOMString host; // hostname:port if port specified,
    attribute DOMString hostname; // just the hostname, no port
    attribute DOMString pathname;
    attribute DOMString port;
    attribute DOMString protocol; // scheme
    attribute DOMString search;  // query

    void assign(in DOMString url); // go to the requested URL
    // does it make sense to spec reload and replace without specifying 
    // history behavior at all?
    void replace(in DOMString url);
    void reload();

    // same value as href; not all implementations have this explicitly 
    // but toString is always available in ECMAScript, and probably this 
    // should be explicit for the sake of Java. Or we could skip it since
    // it matches href.
    DOMString toString();

4. Embedding: Compound Documents by Reference

4.1. The WindowEmbedding Interface

interface WindowEmbedding {
    // name attribute of referencing frame/iframe/object, or name passed to 
    // window.open, does it make sense to spec this without being html-specific 
    // or defining open?
    attribute 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 core::Element frameElement;

4.2. The EmbeddingElement Interface

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

5. Timers

5.1. The WindowTimers Interface

interface WindowTimers {
    // 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);

5.2. The TimerListener Interface

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

6. Security Consideration

A. IDL Definitions

B. ECMAScript Language Binding

C. Acknowledgements

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

D. References

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