Web Applications 1.0

Working Draft — 1 March 2005

This version:
http://www.whatwg.org/specs/web-apps/current-work/
Latest version:
http://www.whatwg.org/specs/web-apps/current-work/
Editor:
Ian Hickson, Opera Software, ian@hixie.ch

Abstract

This specification introduces features to HTML and the DOM that ease the authoring of Web-based applications. Additions include the context menus, a direct-mode graphics canvas, inline popup windows, server-sent events, and more.

Status of this document

This is a work in progress! This document is changing on a daily if not hourly basis in response to comments and as a general part of its development process. Comments are very welcome, please send them to whatwg@whatwg.org. Thank you.

It is very wrong to cite this as anything other than a work in progress. Do not implement this in a production product. It is not ready yet! At all!

This document is the result of a loose collaboration between interested parties in the context of the Web Hypertext Application Technology Working Group. To become involved in the development of this document, please send comments to the address given above. Your input will be taken into consideration.

This is a working draft and may therefore be updated, replaced or rendered obsolete by other documents at any time. It is inappropriate to use Working Drafts as reference material or to cite them as other than "work in progress".

This draft may contain namespaces that use the uuid: URI scheme. These are temporary and will be changed before this specification is ready to be implemented.

To find the latest version of this working draft, please follow the "Latest version" link above.

Table of contents


1. Introduction

The World Wide Web's markup language has always been HTML. HTML was primarily designed as a language for semantically describing scientific documents, although its general design and adaptations over the years has enabled it to be used to describe a number of other types of documents.

The main area that has not been adequately addressed by HTML is a vague subject referred to as Web Applications. This specification attempts to rectify this, while at the same time updating the HTML specifications to address issues raised in the past few years.

1.1. Scope

This specification is limited to providing a semantic-level markup language and associated semantic-level scripting APIs.

The scope of this specification does not include addressing presentation concerns.

The scope of this specification does not include documenting every HTML or DOM feature supporting by Web browsers. Browsers support many features that are considered to be very bad for accessibility or that are otherwise inappropriate. For example, the blink element is clearly presentational and authors wishing to cause text to blink should instead use CSS.

The scope of this specification is not to describe an entire operating system. In particular, office productivity applications, image manipulation, and other applications that users would be expected to use with high-end workstations on a daily basis are out of scope. In terms of applications, this specification is targetted specifically at applications that would be expected to be used by users on an occasional basis, or regularly but from disparate locations. For instance online purchasing systems, searching systems, games (especially multiplayer online games), public telephone books or address books, communications software (e-mail clients, instant messaging clients, discussion software), etc.

For sophisticated cross-platform applications, there already exist several proprietary solutions (such as Mozilla's XUL and Macromedia's Flash). These solutions are evolving faster than any standards process could follow, and the requirements are evolving even faster. These systems are also significantly more complicated to specify, and are orders of magnitude more difficult to achieve interoperability with, than the solutions described in this document. Platform-specific solutions for such sophisticated applications (for example the MacOS X Core APIs) are even further ahead.

1.2. Requirements and ideas

HTML, CSS, DOM, and JavaScript provide enough power that Web developers have managed to base entire businesses on them. What is required are extensions to these technologies to provide much-needed features such as:

Some less important features would be good to have as well:

Several of the features in these two lists have been supported in non-standard ways by some user agents for some time.

1.3. Relationship to HTML 4.01, XHTML 1.1, and DOM2 HTML

This specification represents a new version of HTML4 and XHTML1, along with a new version of the associated DOM2 HTML API. Migration from HTML4 or XHTML1 to the format and APIs described in this specification should in most cases be straightforward, as care has been taken to ensure that backwards-compatibility is retained.

1.4. Relationship to XHTML2

XHTML2 [XHTML2] updates HTML with better features for hyperlinks, multimedia content, annotating document edits, and introduces elements for better describing the semantics of human literary works such as poems.

Unfortunately, it lacks elements to express the semantics of many of the non-document types of content most often seen on the Web. For instance, the very popular forum sites, auction sites, search engines, online shops, and the like, do not fit the document metaphor well.

This specification aims to extend HTML so that it is more suitable in these contexts.

XHTML2 and this specification use different namespaces and therefore can both be implemented in the same XML processor.

1.5. Relationship to Web Forms 2.0

This specification is designed to complement Web Forms 2.0. [WF2] Where Web Forms concentrates on input controls, data validation, and form submission, this specification concentrates on client-side user interface features needed to create modern applications.

1.6. Relationship to CSS3 UI

The CSS3 UI specification [CSS3UI] introduces a number of properties suitable for Web-based application development. This specification expands on those properties and specifies their interaction with scripting-based environments and the DOM.

1.7. Relationship to XUL, Avalon/XAML, and other proprietary UI languages

This specification is independent of the various proprietary UI languages that various vendors provide.

1.8. Conformance requirements

As well as sections marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in [RFC2119]. For readability, these words do not appear in all uppercase letters in this specification.

This specification describes the conformance criteria for user agents (implementations and their implementors) and documents (and their authors).

Conformance requirements phrased as requirements on elements, attributes, methods or objects are conformance requirements on user agents.

User agents fall into several (overlapping) categories with different conformance requirements.

Web browsers and other interactive user agents

Web browsers that support XHTML must process elements and attributes from the XHTML namespace found in XML documents as described in this specification, so that users can interact with them, unless the semantics of those elements have been overridden by other specifications.

A conforming XHTML processor would, upon finding an XHTML script element in an XML document, execute the script contained in that element. However, if the element is found within an XSLT transformation sheet (assuming the UA also supports XSLT), then the processor would instead simply treat the script element as an opaque element that forms part of the transform.

Web browsers that support HTML must process documents labelled as text/html as described in this specification, so that users can interact with them.

Non-interactive presentation user agents

User agents that process HTML and XHTML documents purely to render non-interactive versions of them must comply to the same conformance criteria as Web browsers, except that they are exempt from requirements regarding user interaction.

Typical examples of non-interactive presentation user agents are printers (static UAs) and overhead displays (dynamic UAs). It is expected that most static non-interactive presentation user agents will also opt to lack scripting support.

A non-interactive but dynamic presentation UA would still execute scripts, allowing forms to be dynamically submitted, and so forth. However, since the concept of "focus" is irrelevant when the user cannot interact with the document, the UA would not need to support any of the focus-related DOM APIs.

User agents with no scripting support

Implementations that do not support scripting (or which have their scripting features disabled) are exempt from supporting the events and DOM interfaces mentioned in this specification. For the parts of this specification that are defined in terms of an events model or in terms of the DOM, such user agents must still act as if events and the DOM were supported.

Scripting can form an integral part of an application. Web browsers that do not support scripting, or that have scripting disabled, might be unable to fully convey the author's intent.

Conformance checkers

Conformance checkers must verify that a document conforms to the applicable conformance criteria described in this specification. Conformance checkers are exempt from detecting errors that require interpretation of the author's intent (for example, while a document is non-conformant if the content of a blockquote element is not a quote, conformance checkers do not have to check that blockquote elements only contain quoted material).

The term "validation" specifically refers to a subset of conformance checking that only verifies that a document complies with the requirements given by an SGML or XML DTD. Conformance checkers that only perform validation are non-conformant, as there are many conformance requirements described in this specification that cannot be checked by SGML or XML DTDs.

Data mining tools

Applications and tools that process HTML and XHTML documents for reasons other than to either render the documents or check them for conformance should act in accordance to the semantics of the documents that they process.

A tool that generates document outlines but increases the nesting level for each paragraph and does not increase the nesting level for each section would not be conformant.

Authoring tools and markup generators

Authoring tools and markup generators must generate conformant documents. Conformance criteria that apply to authors also apply to authoring tools, where appropriate.

For compatibility with existing content and prior specifications, this specification describes two authoring formats: one based on XML (referred to as XHTML), and one nominally based on SGML (referred to as HTML). Implementations may support only one of these two formats, although supporting both is encouraged.

XML documents using elements from the XHTML namespace that use the new features described in this specification and that are served over the wire (e.g. by HTTP) must be sent using an XML MIME type such as application/xml or application/xhtml+xml and must not be served as text/html. [RFC3023]

These XML documents may contain a DOCTYPE if desired, but this is not required to conform to this specification.

HTML documents that use the new features described in this specification and that are served over the wire (e.g. by HTTP) must be sent as text/html and must start with the following DOCTYPE: <!DOCTYPE html PUBLIC "-//WHATWG//NONSGML HTML5//EN">.

1.9. Terminology

This specification refers to both HTML and XML attributes and DOM attributes, often in the same context. When it is not clear which is being referred to, they are referred to as content attributes for HTML and XML attributes, and DOM attributes for those from the DOM. Similarly, the term "properties" is used for both ECMAScript object properties and CSS properties. When these are ambiguous they are qualified as object properties and CSS properties respectively.

To ease migration from HTML to XHTML, UAs conforming to this specification must place elements in HTML in the http://www.w3.org/1999/xhtml namespace, at least for the purposes of the DOM and CSS. The term "elements in the HTML namespace", when used in this specification, thus refers to both HTML and XHTML elements.

Unless otherwise stated, all elements defined in this specification are in the http://www.w3.org/1999/xhtml namespace, and all attributes defined in this specification have no namespace (they are in the per-element partition).

Generally, when the specification states that a feature applies to HTML or XHTML, it also includes the other. When a feature specifically only applies to one of the two languages, it is called out by explicitly stating that it does not apply to the other format, as in "for HTML, ... (this does not apply to XHTML)".

The readability, the term URI is used to refer to both ASCII URIs and Unicode IRIs, as those terms are defined by [RFC3986] and [RFC3987] respectively. On the rare occasions where IRIs are not allowed but ASCII URIs are, this is called out explicitly.

1.10. Miscellaneous

As the specification evolves, these conformance requirements will most likely be moved to more appropriate places.

When a UA needs to convert a string to a number, algorithms equivalent to those specified in ECMA262 sections 9.3.1 ("ToNumber Applied to the String Type") and 8.5 ("The Number type") should be used (possibly after suitably altering the algorithms to handle numbers of the range that the UA can support). [ECMA262]

The alt attribute on images must not be shown in a tooltip in visual browsers.

DOM mutation events must not fire for changes caused by the UA parsing the document. (Conceptually, the parser is not mutating the DOM, it is constructing it.) This includes the parsing of any content inserted using document.write() and document.writeln() calls. Other changes, including fragment insertions involving innerHTML and similar attributes, must fire mutation events. [DOM3EVENTS]

The default value of Content-Style-Type and the default value of the type attribute of the style element is is text/css.

The default value of Content-Script-Type and the default value of the type attribute of the script element is the ECMAScript MIME type.

2. Semantics and structure of HTML elements

2.1. Introduction

To ease migration from HTML to XHTML, UAs must assign the http://www.w3.org/1999/xhtml namespace to elements in that are parsed in documents labelled as text/html, at least for the purposes of the DOM and CSS.

Authors must only use elements from the HTML namespace in the contexts where they are allowed, as defined for each element. For XML compound documents, these contexts could be inside elements from other namespaces, if those elements are defined as providing the relevant contexts.

The SVG specification defines the SVG foreignObject element as allowing foreign namespaces to be included, thus allowing compound documents to be created by inserting subdocument content under that element. This specification defines the XHTML html element as being allowed where subdocument fragments are allowed in a compound document. Together, these two definitions mean that placing an XHTML html element as a child of an SVG foreignObject element is conformant.

Whitespace (U+0020, U+000A, U+000D) is always allowed between elements. User agents must always parse whitespace between elements in the source markup into DOM text nodes.

2.1.1. The DOM

The Document Object Model (DOM) is a representation — a model — of the document and its content. [DOM3CORE] The DOM is not just an API; operations on the in-memory document are defined, in this specifiation, in terms of the DOM.

HTML elements in the DOM, including XHTML elements in XML documents, even when those documents are in another context (e.g. inside an XSLT transform), must implement, and expose to scripts, the interface listed for them in the relevant section of this specification.

The basic interface, from which all the HTML elements' interfaces inherit, and which is used by elements that have no additional requirements, is the HTMLElement interface (defined below).

In HTML documents, for HTML elements, the DOM APIs must return tag names and attributes names in uppercase, regardless of the case with which they were created. This does not apply to XML documents; in XML documents, the DOM APIs must always return tag names and attribute names in the original case used to create those nodes.

Some DOM attributes are defined to reflect a particular content attribute. This means that on getting, the DOM attribute returns the current value of the content attribute, and on setting, the DOM attribute changes the value of the content attribute to the given value.

If a reflecting DOM attribute is a DOMString attribute, then the getting and setting is done in a case-sensitive manner, except if the content attribute is defined to only allow a specific set of values. In this latter case, the attribute's value is first converted to lowercase before being returned. If the content attribute is absent, the DOM attribute must return the default value, if the content attribute has one, or else the empty string.

If a reflecting DOM attribute is a boolean attribute, then the DOM attribute returns true if the attribute is set, and false if it is absent. On setting, the content attribute is removed if the DOM attribute is set to false, and is set to have the same value as its name if the DOM attribute is set to true.

If a reflecting DOM attribute is a numeric type (long int) then the content attribute must be converted to a numeric type first (truncating any fractional part). If that fails, or if the attribute is absent, the default value should be returned instead, or 0 if there is no default value. On setting, the given value is converted to a string representing the number in base ten and then that string should be used as the new content attribute value.

Some elements are defined in terms of their DOM textContent attribute. This is an attribute defined on the Node interface in DOM3 Core. [DOM3CORE]

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTML" and "5.0" (respectively) to determine whether or not this module is supported by the implementation. [DOM3CORE] In addition to the feature string "HTML", the feature string "XHTML" (with version string "5.0") can be used to check if the implementation supports XHTML. User agents should respond with a true value when the the hasFeature method is queried with these values. Authors are cautioned, however, that UAs returning true might not be perfectly compliant, and that UAs returning false might well have support for features in this specification; in general, therefore, use of this method is discouraged.

2.2. Global attributes

User agents must support the following five common attributes on all elements in the HTML namespace (including elements that are not defined to exist by this specification).

id

The element's unique identifier. The value must be unique in the document and must contain at least one character.

If the value is not the empty string, user agents must associate the element with the given value (exactly) for the purposes of ID matching (e.g. for selectors in CSS or for the getElementById() method in the DOM).

Identifiers are opaque strings. Particular meanings should not be derived from the value of the id attribute.

Authors should not use the id attribute in XML documents. Authors should instead use the xml:id attribute. [XMLID]

When an element has an ID set through multiple methods (for example, if it has both id and xml:id attributes simultaneously), then the element has multiple identifiers. User agents must use all of an HTML element's identifiers for the purposes of ID matching.

title

Advisory information for the element, such as would be appropriate for a tooltip. On a link, this could be the title or a description of the target resource; on an image, it could be the caption or a description of the image; on a paragraph, it could be a footnote or commentary on the text; on a citation, it could be further information about the source; and so forth. The value is text.

If this attribute is omitted from an element, then it implies that the title attribute of the nearest ancestor with a title attribute set is also relevant to this element. Setting the attribute overrides this, explicitly stating that the advisory information of any ancestors is not relevant to this element. Setting the attribute to the empty string indicates that the element has no advisory information.

The link and style elements define their own title attributes instead of using the global title attribute.

lang

The primary language for the element's contents and for any of the element's attributes that contain text. The value must be a valid RFC 3066 language code, or the empty string. RFC3066

If this attribute is omitted from an element, then it implies that the language of this element is the same as the language of the parent element. Setting the attribute to the empty string indicates that the primary language is unknown.

If no explicit language is given for the root element, then language information from a higher-level protocol (such as HTTP) must be used if available.

User agents may use the element's language to determine proper processing or rendering (e.g. in the selection of appropriate fonts or pronounciations, or for dictionary selection).

Authors should not use the lang attribute in XML documents. Authors should instead use the xml:lang attribute. [XML]

If both the xml:lang attribute and the lang attribute are set, the xml:lang attribute takes precedence and the lang attribute is ignored for the purposes of determining the element's language.

dir

The element's text directionality. The attribute, if specified, must have either the literal value ltr or the literal value rtl.

If the attribute has the literal value ltr, the element's directionality is left-to-right. If the attribute has the literal value rtl, the element's directionality is right-to-left. If the attribute is omitted or has another value, then the directionality is unchanged.

The processing of this attribute depends on the presentation layer. For example, CSS 2.1 defines a mapping from this attribute to the CSS 'direction' and 'unicode-bidi' properties, and defines rendering in terms of those property.

class

The element's classes. The value must be a list of zero or more words (consisting of one or more non-space characters) separated separated by one or more spaces.

User agents must assign all the given classes to the element, for the purposes of class matching (e.g. for selectors in CSS or for the getElementsByClassName() method in the DOM).

Unless defined by one of the URIs given in the profile attribute, classes are opaque strings. Particular meanings must not be derived from undefined values in the class attribute.

Authors should bear in mind that using the class attribute does not convey any additional meaning to the element (unless using classes defined by a profile). There is no semantic difference between an element with a class attribute and one without. Authors that use classes that are not defined in a profile should make sure, therefore, that their documents make as much sense once all class attributes have been removed as they do with the attributes present.

The following DOM interface, common to all HTML elements, provides scripts with convenient access to the content attributes listed above:

interface HTMLElement : Element {
           attribute DOMString id;
           attribute DOMString title;
           attribute DOMString lang;
           attribute DOMString dir;
           attribute DOMString className;
};

The id attribute must reflect the content id attribute.

The title attribute must reflect the content title attribute.

The lang attribute must reflect the content lang attribute.

The dir attribute must reflect the content dir attribute.

The className attribute must reflect the content class attribute.

2.3. The global structure of a document or document fragment

2.3.1. The html element

Contexts in which this element may be used:
As the root element.
Wherever a subdocument fragment is allowed in a compound document.
Content model:
A head element followed by a body element.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The html element represents the root of an HTML document.

2.3.2. The head element

Contexts in which this element may be used:
As the first element in an html element.
Content model:
In any order, exactly one title element, optionally one base element (HTML only), and zero or more of the following elements: link, meta, script, style
Element-specific attributes:
profile
DOM interface:
interface HTMLHeadElement : HTMLElement {
           attribute DOMString profile;
};

The head element collects the document's metadata.

The profile attribute must, if specified, contain a list of zero or more URIs (or IRIs) representing definitions of classes, metadata names, and link relations. These URIs are opaque strings, like namespaces; user agents are not expected to determine any useful information from the resources that they reference.

Each time a class, metadata, or link relationship name that is not defined by this specification is found in a document, the UA must check whether any of the URIs in the profile attribute are known (to the UA) to define that name. The class, metadata, or link relationship shall then be interpreted using the semantics given by the first URI that is known to define the name. If the name is not defined by this specification and none of the specified URIs defines the name either, then the class, metadata, or link relationship is meaningless and the UA must not assign special meaning to that name.

If two profiles define the same name, then the semantic is given by the first URI specified in the profile attribute. There is no way to use the names from both profiles in one document.

User agents must ignore all the URIs given in the profile attribute that follow a URI that the UA does not recognise. (Otherwise, if a name is defined in two profiles, UAs would assign meanings to the document differently based on which profiles they supported.)

If a profile's definition changes over time, documents that use multiple profiles can change defined meaning over time. So as to avoid this problem, authors are encouraged to avoid using multiple profiles.

The profile DOM attribute must reflect the profile content attribute on getting and setting.

2.3.3. The body element

Contexts in which this element may be used:
As the second element in an html element.
Content model:
Zero or more block-level elements.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The body element consists of the main content of the document.

2.4. Document metadata

2.4.1. The title element

Contexts in which this element may be used:
In a head element containing no other title elements.
Content model:
Text (for details, see prose).
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The title element represents the document's title or name. Authors should use titles that identify their documents even when they are used out of context, for example in a user's history or bookmarks, or in search results.

In HTML (as opposed to XHTML), the title element must not contain content other than text and entities; user agents must parse the element so that entities are recognised and processed, but all other markup is interpreted as literal text.

In XHTML, the title element must not contain any elements.

User agents must concatenate the contents of all the text nodes and CDATA nodes that are direct children of the title element (ignoring any other nodes such as comments or elements), in tree order, to get the string to use as the document's title. User agents should use the document's title when referring to the document in their user interface.

2.4.2. The base element

Contexts in which this element may be used:
In a head element, before any elements that use relative URIs, and only if there are no other base elements anywhere in the document. Only in HTML documents (never in XML documents).
Content model:
Empty.
Element-specific attributes:
href
DOM interface:
interface HTMLBaseElement : HTMLElement {
           attribute DOMString href;
};

The base element allows authors to specify the document's base URI for the purposes of resolving relative URIs.

The href content attribute, if specified, must contain a URI (or IRI).

User agents must use the value of the href attribute on the first base element in the document as the document entity's base URI for the purposes of section 5.1.1 of RFC 2396 ("Establishing a Base URI": "Base URI within Document Content"). [RFC2396] User agents must then follow the rules given by XML Base to resolve relative URIs in HTML and XHTML fragments. [XMLBASE] Note that the base URI from RFC 2396 is referred to by the algorithm given in XML Base.

If the base URI given by this attribute is a relative URI, it must be resolved relative to the higher-level base URIs (i.e. the base URI from the encapsulating entity or the URI used to retrieve the entity) to obtain an absolute base URI.

The href content attribute must be reflected by the DOM href attribute.

Authors must not use the base element in XML documents. Authors should instead use the xml:base attribute. [XMLBASE]

Contexts in which this element may be used:
In a head element.
Content model:
Empty.
Element-specific attributes:
href
rel
media
hreflang
type
title
DOM interface:
interface HTMLLinkElement : HTMLElement {
           attribute boolean disabled;
           attribute DOMString href;
           attribute DOMString hreflang;
           attribute DOMString media;
           attribute DOMString rel;
           attribute DOMString type;
};

The LinkStyle interface defined in DOM2 Style must also be implemented by this element. [DOM2STYLE]

The link element allows authors to indicate explicit relationships between their document and other resources.

The destination of the link is given by the href attribute, which must be a URI (or IRI). If the href attribute is absent, then the element does not define a link.

The type of link indicated (the relationship) is given by the value of the rel attribute. The allowed values and their meanings are defined in a later section. If the rel attribute is absent, or if the value used is not allowed according to the definitions in this specification, then the element does not define a link.

Two categories of links can be created using the link element. Links to external resources are links to resources that are to be used to augment the current document, and hyperlinks are links to other documents. The link types section defines whether a particular link type is an external resource or a hyperlink. One element can create multiple links (of which some might be external resource links and some might be hyperlinks). User agents should process the links on a per-link basis, not a per-element basis.

The exact behaviour for links to external resources depends on the exact relationship, as defined for the relevant link type. Some of the attributes control whether or not the external resource is to be applied (as defined below). For external resources that are represented in the DOM (for example, style sheets), the DOM representation must be made available even if the resource is not applied. (However, user agents may opt to only fetch such resources when they are needed, instead of pro-actively downloading all the external resources that are not applied.)

Interactive user agents should provide users with access to the hyperlinks created using the link element, somewhere within their user interface. The exact interface is not defined by this specification, but it should include the following information (obtained from the element's attributes, again as defined below), in some form or another (possibly simplified), for each hyperlink created with this element:

User agents may also include other information, such as the type of the resource (as given by the type attribute).

The media attribute says which media the resource applies to. The value must be a valid media query. [MQ]

If the link is a hyperlink then the media attribute is purely advisory, and describes for which media the document in question was designed.

However, if the link is an external resource link, then the media attribute is prescriptive. The user agent must only apply the external resource to views while their state match the listed media.

The default, if the media attribute is omitted, is all, meaning that by default links apply to all media.

The hreflang attribute gives the language of the linked resource. It is purely advisory. The value must be a valid RFC 3066 language code. RFC3066 User agents must not consider this attribute authoritative — upon fetching the resource, user agents must only use language information associated with the resource to determine its language, not metadata included in the link to the resource.

The type attribute gives the MIME type of the linked resource. It is purely advisory. The value must be a valid MIME type, optionally with parameters. [RFC2046]

For external resource links, user agents may use the type given in this attribute to decide whether or not to consider using the resource at all. If the UA does not support the given MIME type for the given link relationship, then the UA may opt not to download and apply the resource.

User agents must not consider the type attribute authoritative — upon fetching the resource, user agents must only use the Content-Type information associated with the resource to determine its type, not metadata included in the link to the resource.

If the attribute is omitted, then the UA must fetch the resource to determine its type and thus determine if it supports (and can apply) that external resource.

If a document contains three style sheet links labelled as follows:

<link rel="stylesheet" href="A" type="text/css">
<link rel="stylesheet" href="B" type="text/plain">
<link rel="stylesheet" href="C">

...then a compliant UA that supported only CSS style sheets would fetch the A and C files, and skip the B file (since text/plain is not the MIME type for CSS style sheets). For these two files, it would then check the actual types returned by the UA. For those that are sent as text/css, it would apply the styles, but for those labelled as text/plain, or any other type, it would not.

For external resource links, user agents may use the character encoding given in this attribute to decide whether or not to consider using the resource at all. If the UA does not support the given encoding for the given link relationship, then the UA may opt not to download and apply the resource.

However, once the resource has been fetched, user agents must follow the rules for that resource type when determining the actual character encoding.

The title attribute gives the title of the link. With one exception, it is purely advisory. The value is text. The exception is for style sheet links, where the title attribute defines alternate style sheet sets.

The title attribute on link elements differs from the global title attribute of all the other elements in that a link without a title does not inherit the title of the parent element: it merely has no title.

Some versions of HTTP defined a Link: header, to be processed like a series of link elements. When processing links, those must be taken into consideration as well. For the purposes of ordering, links defined by HTTP headers must be assumed to come before any links in the document, in the order that they were given in the HTTP entity header. Relative URIs in these headers must be resolved according to the rules given in HTTP, not relative to base URIs set by the document (e.g. using a base element or xml:base attributes). [RFC2616] [RFC2068]

The DOM attributes href, hreflang, media, rel, and type each reflect the respective content attributes of the same name.

The DOM attribute disabled only applies to style sheet links. When the link element defines a style sheet link, then the disabled attribute behaves as defined for the alternate stylesheets DOM. For all other link elements it must always return false and must do nothing on setting.

2.4.4. The meta element

Contexts in which this element may be used:
In a head element.
Content model:
Empty.
Element-specific attributes:
name
http-equiv (HTML only)
content
DOM interface:
interface HTMLMetaElement : HTMLElement {
           attribute DOMString content;
           attribute DOMString name;
};

The meta element allows authors to specify document metadata that cannot be expressed using the title, base, link, script, and style elements. The metadata is expressed in terms of name/value pairs: the name attribute on the meta element gives the name, and the content attribute on the same element gives the value.

To set metadata with meta elements, authors must first specify a profile that defines metadata names, using the profile attribute. The value of the name attribute must be defined by one of the profiles, and the value of the content attribute must conform to the syntax given by the profile.

How user agents handle metadata set in this way depends on the definitions of the profiles involved.

If a meta element has no name attribute, it does not set document metadata. If a meta element has no content attribute, then the value part of the metadata name/value pair is the empty string.

The DOM attributes name and content reflect the respective content attributes of the same name.

2.4.4.1. Specifying and establishing the document's character encoding

The meta element may also be used, in HTML only (not in XHTML) to provide UAs with character encoding information for the file. To do this, the meta element must be the first element in the head element, it must have the http-equiv attribute set to the literal value Content-Type, and must have the content attribute set to the literal value text/html; charset= immediately followed by the character encoding, which must be a valid character encoding name. [IANACHARSET] When the meta element is used in this way, there must be no other attributes set on the element. Other than for giving the document's character encoding in this way, the http-equiv attribute must not be used.

In XHTML, the XML declaration should be used for inline character encoding information.

Authors should avoid including inline character encoding information. Character encoding information should instead be included at the transport level (e.g. using the HTTP Content-Type header).

For HTML, user agents must use the following algorithm in determining the character encoding of a document:

  1. If the transport layer specifies an encoding, use that.
  2. Otherwise, if the user agent can find a meta element that specifies character encoding information (as described above), then use that.
  3. Otherwise, if the user agent can autodetect the character encoding from applying frequency analysis or other algorithms to the data stream, then use that.
  4. Otherwise, use an implementation-defined or user-specified default character encoding (ISO-8859-1, windows-1252, and UTF-8) are recommended as defaults, and can in many cases be identified by inspection as they have different ranges of valid bytes).

For XML documents, the algorithm user agents must use to determine the character encoding is given by the XML specification. [XML]

2.4.5. The script element

Contexts in which this element may be used:
Anywhere (unless specified otherwise).
Content model:
If there is no src attribute, depends on the value of the type attribute.
If there is a src attribute, the element must be empty.
Element-specific attributes:
src
type
DOM interface:
interface HTMLScriptElement : HTMLElement {
           attribute DOMString text;
           attribute DOMString src;
           attribute DOMString type;
};

The script element allows authors to include dynamic script in their documents.

User agents that support scripting must execute scripts (written in languages that they support) immediately upon parsing a script element's end tag, and immediately upon having a dynamically created script element inserted into the DOM. Once a script element has been executed, it must be flagged as such and never re-executed again. When an element with this flag set is cloned, the new element must not have the flag set.

When the src attribute is set, the script element refers to an external file, which must (if it uses a supported scripting language) be downloaded and executed. The user agent must delay the execution of other scripts associated with the page that are invoked during the download (e.g. event handlers) until after the external script has been downloaded and executed.

The language of the script is given by the type attribute. The value must be a valid MIME type, optionally with parameters. [RFC2046]

For script elements that have the src attribute set, user agents may use the type given in this attribute to decide whether or not to consider using the resource at all. If the UA does not support the given MIME type as a scripting language, then the UA may opt not to download the script.

User agents must not consider the type attribute authoritative, however — upon fetching the script, user agents must only use the Content-Type information associated with it to determine whether or not to execute it; user agents must not use the type attribute in the document to determine the actual type of the script.

If the type attribute is omitted but the src attribute is set, then the UA must fetch the resource to determine its type and thus determine if it supports (and can execute) that external script.

If the src attribute is not set, then the script is given by the contents of the element. The language is given by the type attribute. If it is omitted, then the default is the ECMAScript MIME type.

When examining types to determine if they support the language, user agents must not ignore unknown MIME parameters — types with unknown parameters must be assumed to be unsupported.

For scripting languages that consist of pure text, user agents must use the value of the DOM text attribute (defined below) as the script to execute. For XML-based scripting languages, user agents must use all the children nodes of the script element as the script.

The DOM attributes src and type each reflect the respective content attributes of the same name.

The DOM attribute text must return a concatenation of the contents of all the text nodes and CDATA nodes that are direct children of the script element (ignoring any other nodes such as comments or elements), in tree order. On setting, it must act the same way as the textContent DOM attribute.

2.4.5.1. Script languages

The following lists some MIME types and the languages to which they refer:

text/javascript
ECMAScript. [ECMA262]
text/javascript;e4x=1
ECMAScript with ECMAScript for XML. [ECMA357]

2.4.6. The style element

Contexts in which this element may be used:
In a head element.
Content model:
Depends on the value of the type attribute.
Element-specific attributes:
type
media
title
DOM interface:
interface HTMLStyleElement : HTMLElement {
           attribute boolean disabled;
           attribute DOMString media;
           attribute DOMString type;
};

The LinkStyle interface defined in DOM2 Style must also be implemented by this element. [DOM2STYLE]

The style element allows authors to embed style information in their documents.

If the type attribute is given, it must contain a MIME type, optionally with parameters, that designates a styling language. If the attribute is absent, the type defaults to text/css.

value must be a valid MIME type, optionally with parameters. [RFC2046]

If the UA supports the given styling language, then the UA must use the given styles as appropriate for that language.

When examining types to determine if they support the language, user agents must not ignore unknown MIME parameters — types with unknown parameters must be assumed to be unsupported.

The media attribute says which media the styles apply to. The value must be a valid media query. [MQ] User agents must only apply the styles to views while their state match the listed media.

The default, if the media attribute is omitted, is all, meaning that by default styles apply to all media.

The title attribute on style elements defines alternate style sheetsets.

For styling languages that consist of pure text, user agents must use a concatenation of the contents of all the text nodes and CDATA nodes that are direct children of the style element (ignoring any other nodes such as comments or elements), in tree order. For XML-based styling languages, user agents must use all the children nodes of the style element as the style.

The DOM attributes media and type each reflect the respective content attributes of the same name.

The disabled attribute behaves as defined for the alternate stylesheets DOM.

2.5. Block-level elements

Authors must use elements for their appropriate semantic purposes.

For example, the following document is non-conformant, despite being syntactically correct:

<!DOCTYPE html PUBLIC "-//WHATWG//NONSGML HTML5//EN">
<html lang="en-GB">
 <head> <title> Demonstration </title> </head>
 <body>
  <table>
   <tr> <td> My favourite animal is the cat. </td> </tr>
   <tr>
    <td>
     —<a href="http://example.org/~ernest/"><cite>Ernest</cite></a>,
     in an essay from 1992
    </td>
   </tr>
  </table>
 </body>
</html>

...because the data placed in the cells is clearly not tabular data. A corrected version of this document might be:

<!DOCTYPE html PUBLIC "-//WHATWG//NONSGML HTML5//EN">
<html lang="en-GB">
 <head> <title> Demonstration </title> </head>
 <body>
  <blockquote>
   <p> My favourite animal is the cat. </p>
  </blockquote>
  <p>
   —<a href="http://example.org/~ernest/"><cite>Ernest</cite></a>,
   in an essay from 1992
  </p>
 </body>
</html>

This next document fragment, intended to represent the heading of a corporate site, is similarly non-conformant because the second line is not the heading of a subsection, but merely a subtitle. The header element should be used in these kinds of situations.

<body>
 <h1>ABC Company</h1>
 <h2>Leading the way in widget design since 1432</h2>
 ...

2.5.1. The p element

Contexts in which this element may be used:
Where block-level elements are expected.
Content model:
Inline-level content, but there must be either one piece of non-whitespace text or at least one replaced element as a descendent.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The p element represents a paragraph.

A paragraph is typically a block of text with one or more sentences that discuss a particular topic, as in typography, but can also be used for more general thematic grouping. For instance, an address is also a paragraph, as is a part of a form, a byline, or a stanza in a poem.

The following examples are conformant HTML fragments:

Please someone come up with better examples. Please please please. I beg of you.

<p>The little kitten gently seated himself on a piece of
carpet. Later in his life, this would be refered to as the time the
cat sat on the mat.</p>
<fieldset>
 <legend>Personal information</legend>
 <p><label>Name: <input name="n"></label></p>
 <p><label>Address: <textarea name="a"></textarea></label></p>
</fieldset>
<p>There was once an example from Femley,<br>
Whose markup was of dubious quality.<br>
The validator complained,<br>
So the author was pained,<br>
To move the error from the markup to the rhyming.</p>

2.5.2. The dl, dt, and dd elements

The dl element introduces an association list consisting of zero or more name-value groups. Each group must consist of one or more names (dt elements) followed by one or more values (dd elements). dl elements must not contain non-whitespace text nodes or elements other than dt and dd elements.

Name-value groups may be terms and definitions, speakers and words, metadata topics and values, or any other groups of name-value data.

The following are all conformant HTML fragments.

In this first one, the groups represent lines in a play, with the groups' names (the dt elements) representing the character names, and the groups' values (the dd elements) representing what they say.

<dl>
 <dt> John </dt>
 <dd> Joan! Let's go back home. </dd>
 <dt> Joan </dt>
 <dd> Ok, if you want. </dd>
</dl>

In the following example, one entry ("Authors") is linked to two values ("John" and "Luke").

<dl>
 <dt> Authors
 <dd> John
 <dd> Luke
 <dt> Editor
 <dd> Frank
</dl>

In the following example, one definition is linked to two terms.

<dl>
 <dt lang="en-US"> color </dt>
 <dt lang="en-GB"> colour </dt>
 <dd> A sensation which (in humans) derives from the ability of
 the fine structure of the eye to distinguish three differently
 filtered analyses of a view. </dd>
</dl>

The following example illustrates the use of the dl element to mark up metadata of sorts. At the end of the example, one group has two metadata labels ("Authors" and "Editors") and two values ("Robert Rothman" and "Daniel Jackson").

<dl>
 <dt> Last modified time </dt>
 <dd> 2004-12-23T23:33Z </dd>
 <dt> Recommended update interval </dt>
 <dd> 60s </dd>
 <dt> Authors </dt>
 <dt> Editors </dt>
 <dd> Robert Rothman </dd>
 <dd> Daniel Jackson </dd>
</dl>

If a dl element is empty, it contains no groups.

If a dl element contains non-whitespace text nodes, or elements other than dt and dd, then those elements or text nodes do not form part of any groups in that dl, and the document is non-conformant.

If a dl element contains only dt elements, then it consists of one group with names but no values, and the document is non-conformant.

If a dl element contains only dd elements, then it consists of one group with values but no names, and the document is non-conformant.

2.6. Inline-level content

All inline-level content (including text) in a document conforming to this specification must have at least one of the elements from the list of block-level elements as an ancestor, or at least one element from another specification that states that the element's content model includes inline content and accepts inline elements from other namespaces.

Documents that place inline-level content in inappropriate contexts are non-conformant.

2.6.1. Text

Text nodes...

2.6.2. The em and strong elements

We should define exactly what these mean, if anyone can come to an agreement.

2.6.3. The q element

Need to deal with the quotemark problem without adding verbose markup, breaking existing documents, or adding redundant elements.

2.6.4. The br element

Need some text here that basically says that br must only be used for the line breaks in poems and addresses, and that it is quite blatently not appropriate for markup like:

<p><a ...>34 comments</a>.<br>
<a ...>Add a comment.<a></p>

2.7. Interactive elements

Certain elements in HTML can be activated, for instance a elements, button elements, or input elements when their type attribute is set to radio. Activation of those elements can happen in various ways, for instance via the mouse or keyboard.

When activation is performed via some method other than clicking the pointing device, the default action of the event that triggers the activation must, instead of being activating the element directly, be the dispatching of a new event on the same element, click, with the mouse-specific fields (button, screenX, etc) set to zero, and the key fields set according to the current state of the key input device, if any (false for any keys that are not available). [DOM3EVENTS]

The default action of this click event, or of the real click event if the element was activated by clicking a pointing device, shall be to dispatch yet another event, namely DOMActivate. It is the default action of that event that then performs the actual action.

For certain form controls, this process is complicated further by changes that must happen around the click event. [WF2]

This section might at some future point list a small set of link relationship types and more exactly define their semantics than HTML4. This section (or indeed this specification in general) is unlikely to specify anything related to the profile attribute and how to extend the link types in HTML. Work in this area is currently being done by GMPG and others.

3. Sections

This section is not finished. The content models of the various elements defined here need work, and in particular the handling of headers is very broken right now. Feel free to comment on this section, but be aware that the current state does not represent anything more than a step along the way to what this section will eventually become.

3.1. Document sections

The section element represents a section of a document, such as a chapter.

The section element is a block level element that must contain either nothing, block level content, or inline level content. User agents must support all of the common attributes and event handlers on the section element, as well as the active attribute (for use with mutually exclusive sections).

In CSS-aware user agents, the default presentation of this element should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|section { display: block; margin: 1em 0; }

3.1.1. Section headers

The semantics of h1 ... h6 elements that have ancestor section elements are all the same: they simply specify the header of that section.

For h1 elements, CSS-aware visual user agents should derive the size of the header from the level of section nesting. This effect should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|section xh|h1 { /* same styles as h2 */ }
xh|section xh|section xh|h1 { /* same styles as h3 */ }
xh|section xh|section xh|section xh|h1 { /* same styles as h4 */ }
xh|section xh|section xh|section xh|section xh|h1 { /* same styles as h5 */ }
xh|section xh|section xh|section xh|section xh|section xh|h1 { /* same styles as h6 */ }

Authors should use h1 elements to denote headers in sections. Authors may instead use h2 ... h6 elements, for backwards compatibility with user agents that do not support section elements.

3.1.2. Section footers

Need to clarify that the address element is purely for a section's contact information and not for any arbitrary address.

3.2. Specific section types

The following elements define sections with specific semantics as described:

navigation
A block of navigation links. User agents may offer users the option to skip past such blocks, for example speech user agents typically would not read out navigation sections unless specifically requested to do so by the user.
header
The page header if the header element has no ancestor section elements, otherwise, the header for the nearest ancestor section.

The highest-level header in the header element is the title of the page or section. Heading elements with lower levels represent subtitles, not titles of lower level sections.

When presenting outlines, or otherwise extracting header information from documents, the contents of the first highest-level header descendant of a header element must be considered as being equivalent to an h1 element replacing the entire header element.

Here are some examples of valid headers. In each case, the emphasised text represents the text that would be used as the header in an application extracting header data and ignoring subtitles.

<header>
 <h1>The reality dysfunction</h1>
 <h2>Space is not the only void</h2>
</header>
<header>
 <p>Welcome to...</p>
 <h1>Voidwars!</h1>
</header>
<header>
 <h1>Scalable Vector Graphics (SVG) 1.2</h1>
 <h2>W3C Working Draft 27 October 2004</h2>
 <dl>
  <dt>This version:</dt>
  <dd><a href="http://www.w3.org/TR/2004/WD-SVG12-20041027/">http://www.w3.org/TR/2004/WD-SVG12-20041027/</a></dd>
  <dt>Previous version:</dt>
  <dd><a href="http://www.w3.org/TR/2004/WD-SVG12-20040510/">http://www.w3.org/TR/2004/WD-SVG12-20040510/</a></dd>
  <dt>Latest version of SVG 1.2:</dt>
  <dd><a href="http://www.w3.org/TR/SVG12/">http://www.w3.org/TR/SVG12/</a></dd>
  <dt>Latest SVG Recommendation:</dt>
  <dd><a href="http://www.w3.org/TR/SVG/">http://www.w3.org/TR/SVG/</a></dd>
  <dt>Editor:</dt>
  <dd>Dean Jackson, W3C, <<a href="mailto:dean@w3.org">dean@w3.org</a>></dd>
  <dt>Authors:</dt>
  <dd>See <a href="#authors">Author List</a></dd>
 </dl>
 <p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright"> Copyright</a> ©2004 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p> 
</header>

header elements must only be used where h1 elements would be allowed.

footer
The footer for the nearest ancestor section element, or if none, for the page.
article
An article, for instance a Web log post, a magazine article, or a forum post. The first header element (h1 to h6) in a depth first search of the article element represents the article header. The first a element with a rel attribute having as one of its values the keyword bookmark in a depth first search of the article element is the article's permalink.

Articles that contain further articles, as for example a Web log post that contains comments on that post, should be represented by nesting article elements inside the main article element.

sidebar
A section that is not directly part of the main flow of text, but is on a related topic.

All of these elements are block level element that must contain either nothing, block level content, or inline level content. User agents must support all of the common attributes and event handlers on these elements.

In CSS-aware user agents, the default presentation of these elements should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|navigation, xh|header, xh|footer, xh|article, xh|sidebar
  { display: block; margin: 0; }

The rendering of h1 elements according to the UA style sheet should not be affected by these elements.

3.3. Section groups (tabs)

Unless someone can come up with a better name, we'll probably rename "tabbox" to "group".

A group of related, order-neutral sections may be denoted using the tabbox element. The default presentation in a visual media (as described below) is to render each section as a separate tab in a tab box, allowing the user to switch between them. Sections can also be represented by links to other documents, instead of them being included literally in the markup.

The tabbox element is a block level element that should only contain section, fieldset, and a elements.

Authors should only use a elements that cause the user agent to change the active page to a page with a similar structure. Other behaviours are likely to be highly confusing to users.

Each section, fieldset, and a child can have a title. If the element is a section element, then the title is taken from the title attribute of the element, if specified, or, if absent, from the textContent DOM attribute of the first element child of the section element, if that is an h1 ... h6 element. (If it is taken from a header child, then that child is hidden from the rendering.) If the element is a fieldset element, then the title is taken from the the textContent DOM attribute of the first element child of the fieldset element, if that is an legend element. If the element is an a element, then the title is taken from the textContent DOM attribute of the element. (Titles may be the empty string.)

The titles obtained in this way, and the section, fieldset, and a elements from which they were derived, represent the list of sections in the tabbox. This list is live, in that dynamic changes to the DOM immediately affect the representation of the tabbox element.

All the other child nodes of the tabbox shall be ignored for the purposes of rendering the tabbox. Authors may use this in order to obtain acceptable renderings even in UAs that do not support tabbox.

In CSS-aware user agents, the default presentation of the tabbox element should, in part, be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|tabbox { display: block; }
xh|tabbox > xh|section:not([title]) > xh|h1:first-child,
xh|tabbox > xh|section:not([title]) > xh|h2:first-child,
xh|tabbox > xh|section:not([title]) > xh|h3:first-child,
xh|tabbox > xh|section:not([title]) > xh|h4:first-child,
xh|tabbox > xh|section:not([title]) > xh|h5:first-child,
xh|tabbox > xh|section:not([title]) > xh|h6:first-child,
xh|tabbox > xh|fieldset > xh|legend:first-child { display: none; }

These rules do not come even close to fully describing the full behaviour of a tabbox element, however.

The behaviour of the tabbox should be to provide quick access to any of the children of the tabbox that have a title (as described above). UAs may keep track of which section is the selected section, and report this information to the user.

When the user specifies a section to access, the relevant element must have a click event dispatched to it, whose default action is to further dispatch a DOMActivate event to the element.

For section and fieldset elements, the default action of DOMActivate events is to display, or jump to, the relevant section. For a elements, the default action is the normal default action for a elements (activating the link, command, or whatever). In addition to these default actions, when a child of a tabbox is accessed, it becomes the selected section.

If the DOMActivate event is cancelled (or if the click event is cancelled, causing the DOMActivate event to never be fired in the first place), then the selected section does not change.

If an a element has a command attribute, it can be disabled. In such cases, the UA should not allow the user to select that section.

The initially selected section shall be the first element from the tabbox element's child list that is:

  1. an a element whose href attribute matches the URI of the current document, if there is one,
  2. otherwise, the first a element whose href attribute matches the URI given by the href attribute of the first link element in the document that has a rel attribute whose value contains the keyword up (treating that attribute as a space-separated list), if there is one,
  3. otherwise, the first section or fieldset element that has a title, if there is one.

If no elements match, then initially no section shall be selected.

In the above algorithm, URI comparisons should be done after canonicalisation, and should ignore fragment identifiers unless the a element in question has one.

In non-interactive or non-spatial media (such as in print, on braille systems, or with speech synthesis) the UA may automatically switch the selected section to the next section once the selected section has been rendered.

Which section is selected if the element representing the currently selected section is dynamically removed from the document is up to the UA.

In interactive visual media, the tabbox element should be rendered as a tab box, with the section titles listed as the tabs, and the selected section (if it is a section or fieldset element) displayed in the tab panel area. When the selected section is an a element, the tab panel area should be empty.

This specification does not describe how CSS properties apply to tabbox elements when the UA uses this rendering, but the children rendered in the tab panel area must be styled using CSS, as if the tab panel area defined a new containing block and new block formatting context.

User agents must support all of the common attributes and event handlers on the tabbox element.

Here is an example of a tabbox used to allow the user to read three different parts of the document:

<tabbox>
 <section>
  <h2>About</h2>
  <p><img src="logo" alt=""></p>
  <p>The Application.</p>
  <p>© copyright 2004 by The First Team.</p>
 </section>
 <section>
  <h2>Credits</h2>
  <ul>
   <li>Jack O'Neill</li>
   <li>Samantha Carter</li>
   <li>Daniel Jackson</li>
   <li>Teal'c</li>
   <li>Jonas Quinn</li>
  </ul>
 </section>
</tabbox>

Next, an example of a form that has been split into little groups of controls:

<tabbox>
 <fieldset>
  <legend>Identity</legend>
  <p><label>First name: <input name="fn"></label></p>
  <p><label>Last name: <input name="ln"></label></p>
  <p><label>Date of Birth: <input name="dob" type="date"></label></p>
 </fieldset>
 <fieldset>
  <legend>Food</legend>
  <p><label>Favourite appetizer: <input name="fa"></label></p>
  <p><label>Favourite meal: <input name="fm"></label></p>
  <p><label>Favourite desert: <input name="fd"></label></p>
 </fieldset>
</tabbox>

Finally, an example of a page using a tabbox to point to sections outside the document. Note the use of fallback content (elements and text in the tabbox element that are not fieldset, section, or a elements) for backwards compatibility.

<div>
 <tabbox>
  <strong>Navigation:</strong>
  <a href="/"><span>Home</span></a>,
  <a href="/news/"><span>News</span></a>,
  <a href="/games/"><span>Games</span></a>,
  <a href="/help/"><span>Help</span></a>,
  <a href="/contact/"><span>Contact</span></a>.
 </tabbox>
</div>

This would be semantically equivalent to the following:

<tabbox>
 <section><h2>Home</h2> ...content... </section>
 <section><h2>News</h2> ...content... </section>
 <section><h2>Games</h2> ...content... </section>
 <section><h2>Help</h2> ...content... </section>
 <section><h2>Contact</h2> ...content... </section>
</tabbox>

3.4. Mutually exclusive sections

The switch element represents a block of mutually exclusive sections.

For example, in an application for an online mutiplayer game, there could be four mutually exclusive sections: one for the login page, one for the network status page displayed while the user is logging in, one for a "lobby" where players get together to organise a game, and one for the actual game. The different sections are the various states that the application can reach.

The switch element must contain only block-level elements. User agents must support all of the common attributes and event handlers on the switch element.

All child elements of a switch element shall be hidden except those that have active attributes (or, for non-XHTML elements, active attributes in the XHTML namespace).

In CSS-aware user agents, the default presentation of this element should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|switch { display: block; }
xh|switch xh|*:not([active]) { display: none; }
xh|switch *:not([xh|active]) { display: none; }

3.4.1. Using switch and section

interface HTMLSwitchElement : HTMLElement {
  readonly attribute Element           activeElement;
  void setActive(in Element element);
};

interface HTMLSectionElement : HTMLElement {
  readonly attribute boolean           active;
  void setActive();
};

...

When an element is added to a switch element as a child (whether during parsing, or later), the element is examined. If the element has an active attribute (or, if it is a non-XHTML element, if it has an active attribute in the XHTML namespace), or, if the switch element's activeElement DOM attribute is null, then the switch element's setActive method is called with that element as the argument. This causes the element to be made the active element for the switch, and causes any other elements to be deactivated if needed.

A side-effect of this definition is that the first element in a switch element is the default element if none have been explicitly marked as active.

4. Structured data

This entire section will need serious fleshing out in due course. Currently it is pending the completion of specifications from Technorati.

4.1. Calendars: event data

The calendar element may be used for indicating hCalendar fragments that should be processed and rendered, e.g. as inline calendars.

The calendar element is a block-level element whose content model is any block-level content. User agents must support all the common attributes and event handlers on calendar elements.

Web browsers should render the calendar element by replacing the element by a representation of the calendar data contained within it.

4.1.1. Intepreting calendar data

UAs must process the contents of calendar data as described in the hCalendar specification. [HCALENDAR]

4.1.2. Rendering examples

These examples will need updating to track hCalendar as it evolves.

The following fragment:

<calendar>
 <div class="vcalendar">
  <span class="prodid">-//hCalendar//EN</span>
  <span class="version">2.0</span> 
  <p class="vevent">
   <a href="http://www.web2con.com/">
    <span class="dtstart">20041005</span>-
    <span class="dtend">20041007</span> 
    <span class="summary">Web 2.0 Conference</span>
   </a>
  </p>
 </div>
</calendar>

...might render as the following:

A calendar control with the 5th of October being a link.

4.2. Business cards: personal data

The card element may be used for indicating hCard fragments that should be processed and rendered, e.g. as inline business cards.

The card element is a block-level element whose content model is any block-level content. User agents must support all the common attributes and event handlers on card elements.

Web browsers should render the card element by replacing the element by a representation of the personal data contained within it.

4.2.1. Intepreting card data

UAs must process the contents of card data as described in the hCard specification. [HCARD]

4.2.2. Rendering examples

These examples will need updating to track hCard as it evolves.

The following fragment:

<card>
 <p class="vcard"> 
  <a class="fn n" href="http://tantek.com/">
   <span class="Given-Name">Tantek</span> 
   <span class="Family-Name">Çelik</span>
  </a>
 </p>
</card>

...might render as the following:

A business card with contact information for Tantek
    Çelik.

4.3. Inline data

This section is a place-holder for where elements such as <date> or <time> might be defined. This might also just be merged with the "Semantics and structure of HTML elements" section above, or dropped, based on demand.

5. Widgets

This section merely indicates what new widgets are expected to be introduced in due course.

5.1. Gauges

The gauge element is an inline element that represents a fractional value, such as the relative relevance of a search result, the fraction of a user's quota that is used, or the fraction of a voting population to have selected a particular candidate.

User agents must support all of the common attributes and event handlers on the gauge element, plus the following attributes:

...

The value should come from parsing the .textContent attribute and taking the first string of digits (possibly with a single dot) as the numerator and the second string of digits (possibly with another single dot) as the denominator, defaulting the denominator to 100 if it is absent, treating zero denominators as 100, and using the resulting fraction as the value, in the range 0 to 1, for the gauge. If the numerator is absent, default to 0.

Do we want something to say that "above 0.75 is bad"? "below 0.2 is bad"?

5.2. Progress meters

Similar to gauge, but renders as a progress bar. If the numerator is absent, default to an indeterminate progress bar (barber pole, bouncing blue box, etc).

5.3. Data grids

5.4. Data trees

6.1. Tutorial

This section still needs to be written. For now, here are some markup snippets to show how this should work:

<menubar>
 <li>
  <a href="#file">File</a>
  <menu id="file">
   <li><button type="button" onclick="fnew()">New...</button></li>
   <li><button type="button" onclick="fopen()">Open...</button></li>
   <li><button type="button" onclick="fsave()" id="save">Save</button></li>
   <li><button type="button" onclick="fsaveas()">Save as...</button></li>
  </menu>
 </li>
 <li>
  <a href="#edit">Edit</a>
  <menu id="edit">
   <li><button type="button" onclick="ecopy()">Copy</button></li>
   <li><button type="button" onclick="ecut()">Cut</button></li>
   <li><button type="button" onclick="epaste()">Paste</button></li>
  </menu>
 </li>
 <li>
  <a href="#help">Help</a>
  <menu id="help">
   <li><a href="help.html">Help</a></li>
   <li><a href="about.html">About</a></li>
  </menu>
 </li>
</menubar>

...

<input command="save"/> <!-- This will act exactly like the
                             Save button above, including reflecting
                             its disabled state dynamically -->

Here's a way of doing something similar. This menu bar would not display inline in the page, but could be made to display in the browser's menu bar or as the window's only menu bar if the application is running standalone. How to do that hasn't yet been decided.

<menubar id="appmenu">
 <menulabel label="File"/>
 <menu>
  <command label="New..." onclick="fnew()"/>
  <command label="Open..." onclick="fopen()"/>
  <command label="Save" onclick="fsave()" id="save"/>
  <command label="Save as..." onclick="fsaveas()"/>
 </menu>
 <menulabel label="Edit"/>
 <menu>
  <command label="Copy" onclick="ecopy()"/>
  <command label="Cut" onclick="ecut()"/>
  <command label="Paste" onclick="epaste()"/>
 </menu>
 <menulabel label="Help"/>
 <menu>
  <a href="help.html">Help</a>
  <a href="about.html">About</a>
 </menu>
</menubar>

Here's some markup that falls back on the traditional abuse of the select element as a navigation menu, but which is implemented as a semi-correct menu using the new techniques of this document:

<form action="redirect.cgi">
 <menubar>
  <menulabel><label for="goto">Go to...</label></menulabel>
  <menu>
   <select id="goto"
           onchange="if (this.options[this.selectedIndex].value)
                     window.location = this.options[this.selectedIndex].value">
    <option value="" selected="selected"> Select site: </option>
    <option value="http://www.apple.com/"> Apple </option>
    <option value="http://www.mozilla.org/"> Mozilla </option>
    <option value="http://www.opera.com/"> Opera </option>
   </select>
   <span><input type="submit" value="Go"></span>
  </menu>
 </menubar>
</form>

6.2. Commands

A command is the abstraction behind menu items, buttons, and keyboard shortcuts. Once a command is defined, it can be referred to by menu items, buttons, keyboard shortcut declarations, script, and so forth. The advantage of this is that it allows many access points to a single feature to share features such as their disabled state.

Commands have the following facets:

Type
The kind of command: "command", meaning it is a normal command; "radio", meaning that triggering the command will, amongst other things, set the Checked State to true (and probably uncheck some other commands); or "checkbox", meaning that triggering the command will, amongst other things, toggle the value of the Checked State.
ID
The name of the command, for referring to the command from the markup or from script. If a command has no ID, it is an anonymous command.
Label
The name of the command as seen by the user.
Hint
A helpful or descriptive string that can be shown to the user.
Icon
A graphical image that represents the action.
Action
The actual effect that triggering the command will have. This could be a scripted event handler, a URI to which to navigate, or a form submission.
Hidden State
Whether the command is hidden or not (basically, whether it should be shown in menus).
Disabled State
Whether the command can be triggered or not. If the Hidden State is true (hidden) then the Disabled state will be true (disabled) regardless.
Checked State
Whether the command is checked or not.
Triggers
The list of elements that can trigger the command. The element defining a command is always in the list of elements that can trigger the command. For anonymous commands, only the element defining the command is on the list, since other elements have no way to refer to it.

The distinction between Disabled State and Hidden State is subtle. A command should be Disabled if, in the same context, it could be enabled if only certain aspects of the situation were changed. A command should be marked as Hidden if, in that situation, the command will never be enabled. For example, in the context menu for a water faucet, the command "open" might be Disabled if the faucet is already open, but the command "eat" would be marked Hidden since the faucet could never be eaten.

In the DOM, the following interface is used to represent a command. (The comments describing each member of this interface are normative.)

interface Command {

  // The command's ID, null if the element defines an anonymous command.
  readonly attribute DOMString               id;

  // The command's Label, null if the element does not specify one.
  readonly attribute DOMString               label;

  // The command's Hint, null if the element does not specify one.
  readonly attribute DOMString               title;

  // The absolute URI to the command's Icon, or, if the element
  // defining the command has no explicit icon, the computed value
  // of the CSS 'icon' property on that element. [CSS3UI]
  // Null if the element does not specify an icon and the computed
  // value of the CSS 'icon' property is 'auto'.
  readonly attribute DOMString               icon;

  // The Hidden State of the command. True if the element is
  // hidden, false otherwise.
  readonly attribute boolean                 hidden;

  // The Disabled State of the command. True if the element is
  // disabled or hidden, false otherwise.
  readonly attribute boolean                 disabled;              

  // The Checked State of the command. True if the element is
  // checked, false otherwise.
  readonly attribute boolean                 checked;              

  // The type of command. Either "command", "radio", or "checkbox".
  // Null if the element does not define a command.
  readonly attribute DOMString               commandType;          

  // The Action of the command: a method that triggers the action for
  // the command. Has no effect if the element does not define a command.
  void triggerCommand();

  // The list of elements that can trigger this command (the Triggers
  // for the command), null if the element does not define a command.
  readonly attribute HTMLCollection          triggers;

  // The element referred to by the command attribute (if
  // specified), which is the element that actually defines the
  // command for this element. (See: the command attribute.)
  // If the element defines a command, this must point to the element
  // itself (as in commandElement.command == commandElement).
  // Null if the element does not have a command attribute and
  // does not define a command.
  readonly attribute Command                 command;

};

The Command interface is implemented by any element capable of defining a command. All the attributes of the Command interface are readonly. Elements implementing this interface may implement other interfaces that have attributes with identical names but that are writable; in bindings that simply flatten all supported interfaces on the object, the writable attributes have priority over the readonly attributes defined above.

All the commands defined in a document that have IDs are listed in the document.commands attribute:

interface DocumentCommands {
  readonly attribute HTMLCollection          commands;
}

The collection represented by this attribute is live. As commands are defined in or removed from the document, the attribute is updated.

The following elements may define commands: a, button, input, option, command.

6.2.1. The command attribute

Any element that can define a command can also, instead, have a command attribute that specifies the ID of a command that the element should defer to. In this case the element does not define a command, but, in the absence of attributes to the contrary, reflects the state of the element specified.

If the command attribute specifies an ID that is not the ID of an element that defines a command, then the command DOM attribute is set to the null value, and the element acts as if it was linked to an element that defined a command with no Label, no Hint, no Icon, no Action, that was not Hidden, not Disabled, not Checked, and that was of Type "command".

6.2.2. The a element and commands

6.2.2.1. Using the a element to define a command

To define a command, an a element must have an appropriate href attribute, and must not have a command attribute. An appropriate href attribute is one whose URI does not contain a fragment identifier that points to a menu element in the same document as the a element.

An a element with an href attribute that points to a menu element in the same file can be used to open a menu.

The Type of the command is "command".

The ID of the command is the ID of the a element, if present. Otherwise it is an anonymous command.

The Label of the command is the string given by the element's textContent DOM attribute. [DOM3CORE]

The Hint of the command is the string given by the title attribute, if any, and the empty string if the attribute is absent.

The Icon of the command is the absolute URI of the first image in the a element. Specifically, in a depth-first search of the children of the element, the first element that is either an img element with a src attribute, or an object element with a data attribute. If it is an img element then the URI is taken from the src attribute. If it is an object element then the URI is taken from the data attribute. Relative URIs must be resolved.

The Action of the command is that a {"http://www.w3.org/2001/xml-events", "click"} event is fired on the a element.

The Hidden State and Disabled State facets of the command are always false. (The command is always enabled.)

The Checked State of the command is always false. (The command is never checked.)

6.2.2.2. Using the a element with the command attribute

If an a element has a command attribute, then:

If the element's title attribute is absent, then when the UA attempts to display the element's hint, it must instead use the specified command's Hint.

Even if the element's href attribute is absent, the element must still match the CSS :link or :visited pseudo-classes. It must match the :visited pseudo-class if the command's action is to follow a link that has already been visited by the user, and must match the :link pseudo-class otherwise.

If a DOMActivate event is dispatched on the element and is not cancelled, and the event has no other default action, and the command's Disabled State is false (enabled), then the command's Action must be triggered as the default action.

The DOMActivate event is fired as the default action of the click event.

If the command's Disabled State is true (disabled) then the element must be disabled and must therefore match the :disabled pseudo-class. UAs should style disabled links in such a way as to clearly convey their disabled state.

The Label, Icon, Checked State and Type facets of the command are ignored by the a element (except for matching CSS pseudo-classes).

6.2.3. The button element and commands

6.2.3.1. Using the button element to define a command

To define a command, a button element must not have a command attribute.

The Type of the command is "command".

The ID of the command is the ID of the button element, if present. Otherwise it is an anonymous command.

The Label, Hint, Icon, and Action facets of the command are determined as for a elements.

The Hidden State of the command is always false.

The Disabled State of the command mirrors the disabled state of the button. Typically this is given by the element's disabled attribute, but certain button types become disabled at other times too — for example, the Web Forms 2.0 move-up button type is disabled when it would have no effect. [WF2]

The Checked State of the command is always false.

6.2.3.2. Using the button element with the command attribute

If a button element has a command attribute, then:

If the element's title attribute is absent, then when the UA attempts to display the element's hint, it must instead use the specified command's Hint.

If a DOMActivate event is dispatched on the element and is not cancelled, and the event has no other default action, and the command's Disabled State is false (enabled), and the button's disabled attribute is absent, then the command's Action must be triggered as the default action.

The DOMActivate event is fired as the default action of the click event.

If the command's Disabled State is true (disabled) then the element must be disabled. The button element must also be disabled if the element's disabled attribute is set.

The Label, Icon, Checked State and Type facets of the command are ignored by the button element (except for matching CSS pseudo-classes).

6.2.4. The input element and commands

6.2.4.1. Using the input element to define a command

To define a command, an input element must have a type attribute specifying a button, radio button, or check box type (In HTML4: submit, reset, button, radio, checkbox (but not image); in WF2: move-up, move-down, add, remove), and must not have a command attribute.

The Type of the command is "radio" if the type attribute has the value radio, "checkbox" if the type attribute has the value checkbox, and "command" otherwise.

The ID of the command is the ID of the input element, if present. Otherwise it is an anonymous command.

The Label of the command depends on the Type of the command. If the Type is "command", then it is the string given by the value attribute, if any, and a UA-dependent value that the UA uses to label the button itself if the attribute is absent.

If the Type is "radio" or "checkbox", then, if the element has a label element associated with it, the textContent of the first such element is used as the Label (in DOM terms, this.labels[0].textContent [WF2] [DOM3CORE]). Otherwise, the value of the value attribute, if present, used is as the Label. Otherwise, the Label is the empty string.

The Hint of the command is the string given by the title attribute, if any, and the empty string if the attribute is absent.

There is no Icon for the command.

The Action of the command is that a {"http://www.w3.org/2001/xml-events", "click"} event is fired on the input element.

The Hidden State and Disabled State facets of the command are as determined for button elements.

The Checked State of the command is true if the command is of Type "radio" or "checkbox" and the element has a checked attribute, and false otherwise.

6.2.4.2. Using the input element with the command attribute

If an input element has no type attribute and no name attribute, and it has a command attribute, then:

If the command is of Type "command" then the element must generally be styled and behave as if it was of type button; if the Type of the command is "radio" then the element must generally be styled and behave as if it was of type radio; and if the Type of the command is "checkbox" then the element must generally be styled and behave as if it was of type checkbox.

If the command is of Type "command" and the element's value attribute is absent, then when the UA attempts to display the element's caption, it must instead use the specified command's Label. The Label facet is ignored if the command is not of Type "command".

The UA may use the Icon facet of the command to render an icon in the control, if appropriate for the UI used.

If the element's title attribute is absent, then when the UA attempts to display the element's hint, it must instead use the specified command's Hint.

If a DOMActivate event is dispatched on the element and is not cancelled, and the event has no other default action, and the command's Disabled State is false (enabled), and the element's disabled attribute is absent, then the command's Action must be triggered as the default action.

The DOMActivate event is fired as the default action of the click event.

If the command's Disabled State is true (disabled) then the element must be disabled. The input element must also be disabled if the element's disabled attribute is set.

If the command's Checked State is true (checked) then the element must be checked. The input element must also be checked if the element's checked attribute is set.

6.2.5. The option element and commands

6.2.5.1. Using the option element to define a command

To define a command, an option element must have an ancestor select element and either no value attribute or a value attribute that is not the empty string.

The Type of the command is "radio" if the option's select element has no multiple attribute, and "checkbox" if it does.

The ID of the command is the ID of the option element, if present. Otherwise it is an anonymous command.

The Label of the command is the value of the option element's label attribute, if there is one, or the value of the option element's textContent DOM attribute if it doesn't.

The Hint of the command is the string given by the title attribute, if any, and the empty string if the attribute is absent.

There is no Icon for the command.

The Action of the command is that the element be selected in its select element. If the command is of Type "radio" then this must unselect all the other options, otherwise it must toggle the selection state of the current option. Once the selection has changed, a change event must be fired on the select element, as if the selection had been changed directly.

The Hidden State facet of the command is always false (shown).

The Disabled State of the command is true (disabled) when the option element is disabled, and false otherwise.

The Checked State of the command is true (checked) when the element is selected in its select element.

6.2.5.2. Using the option element with the command attribute

The command attribute cannot be used with option elements.

6.2.6. The command element and commands

6.2.6.1. Using the command element to define a command

The most direct way to represent a command is by using the command element. A command element defines a command if it does not have a command attribute.

...
 <command id="c_stop" label="Emergency Stop" onclick="dostop()"/>
 <command id="c_go" label="Go" onclick="dogo()"/>
 <command id="c_lamp" label="Headlamps" onclick="dof2()" disabled="disabled"/>
...

This element should not be directly displayed. In CSS-aware user agents, this should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|command { display: none; }

The command element, in addition to the core and internationalisation attributes, may have the following attributes specified:

type
The command's Type. If present, this attribute must either have the value radio, in which case the command is of Type "radio", or the value checkbox, in which case the command is (amazingly) of Type "checkbox". Any other value, or the absence of the attribute altogether, means that the command is of Type "command".
id
The command's ID. If this attribute is not specified, then the command is anonymous.
label
The command's Label. If the attribute is not specified, the command's Label is given by the element's textContent DOM attribute.
title
The command's Hint. If the attribute is not specified, the command's Hint is the empty string.
icon
A URI to the command's Icon. If the attribute is not specified, then the command has no Icon.
onclick
An event handler attribute that listens for click events.
hide
The command's Hidden State. If the attribute is present, the command is hidden (and also disabled, regardless of the value of the disabled attribute), otherwise, the command is shown. If the attribute is present, it should have the value "hide".
disabled
The command's Disabled State. If the attribute is present, the command is disabled, otherwise, the command is enabled. If the attribute is present, it should have the value "disabled".
checked
The command's Checked State. If the attribute is present, the command is checked, otherwise, the command is not. If the attribute is present, it should have the value "checked".
radiogroup
An attribute indicating the name of the group of commands that will be toggled when the command itself is toggled. (Described below.)
default
An attribute indicating whether the command is the default command. If the attribute is present, the command is the default command, otherwise it is not. If it is set, it should have the value default. Used by context menus to indicate what the default option would be. The :default pseudo-class matches command elements with this attribute.

In addition, command elements may also have a command attribute, as described below.

The Type, ID, Label, Hint, Icon, Hidden State, Disabled State, and Checked State of the command defined by a command element are as described above. The Action of a command element is that a {"http://www.w3.org/2001/xml-events", "click"} event is fired on the element.

If the Type of the command is "checkbox", when a click event is dispatched on the element, user agents must toggle the value of the checked attribute before the event is dispatched in the document. (If the attribute is absent, then it is set to the value checked, and if the attribute is present, it is removed.) If the default action of the event is canceled, the value of the attribute must be changed back to the value it had before the event was dispatched.

If the Type of the command is "radio", when a click event is dispatched on the element, user agents must set the value of the checked attribute on the element to checked, and remove the attribute from any command elements with type set to radio and the same parent element and same radiogroup attribute, before the event is dispatched in the document. (If the element has no radiogroup attribute, then the elements "with the same radiogroup attribute" are those elements with no radiogroup attribute.) If the default action of the event is canceled, the value of the attributes that were changed must be changed back to the values they had before the event was dispatched.

In HTML the command element is an empty element with no end tag.

Authors should put command elements inside the head element, inside any element that may contain block-level or inline-level elements, or inside commandset elements.

Authors should not put elements or text inside command elements.

6.2.6.2. Using the command element with the command attribute

If a command element has a command attribute, then:

If the element's label attribute is absent, then when the UA attempts to display the element's caption, it must instead use the specified command's Label.

If the element's icon attribute is absent, then when the UA attempts to display the element's icon, it must instead use the specified command's Icon.

If the element's title attribute is absent, then when the UA attempts to display the element's hint, it must instead use the specified command's Hint.

If a click event is dispatched on the element and is not canceled, and the command's Disabled State is false (enabled), and the element's own disabled attribute is absent, then the command's Action must be triggered as the default action.

If the command's Disabled State is true (disabled) then the element must be disabled. The command element must also be disabled if the element's disabled attribute is set.

If the command's Checked State is true (checked) then the element must be checked. The command element must also be checked if the element's checked attribute is set.

When a command element has a command attribute, any type and radiogroup attribute is ignored.

6.2.6.3. Command Sets

Authors may place related commands together inside a commandset element.

Apart from the core and internationalisation attributes, commandset elements have no attributes.

Authors may use commandset elements wherever command elements are allowed. commandset elements may contain any number of command and commandset elements.

6.2.7. The 'icon' property

UAs should use the command's Icon as the default generic icon provided by the user agent when the 'icon' property computes to 'auto' on an element that either defines a command or refers to one using the command attribute.

6.2.8. CSS pseudo-classes and commands

When an element uses the command attribute, any UI pseudo-classes from the following list that apply to the element defining the command also apply to the elements that refer to that command.

:enabled, :disabled
Matches commands whose Disabled State facet is False and True respectively.
:checked
Matches commands whose Type facet is either "radio" or "checkbox", and whose Checked State facet is true.

This section is horrible. Feel free to coment on this section, but be aware that the current state does not represent anything more than a step along the way to what this section will eventually become.

6.3.1. The menu element

Menus are defined using the menu element. The semantic of the menu element is a structured list of navigation links and commands. The element can be used either as a list or as a block-level container. User agents must support all the common attributes and event handlers, plus the label attribute, on menu elements.

menu elements with explicit label attributes, and menu elements following menulabel elements, should be hidden. In CSS-aware UAs, this effect should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|menu[label], xh|menulabel + xh|menu { display: none; }

All other menu elements should be rendered identically to ul elements. In CSS-aware UAs, this effect may be achieved by including rules similar to the following in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|menu { display: block; margin: 0 0 0 40px; list-style: disc; }

The label attribute sets the label of the menu.

If the attribute is not specified, and the element immediately preceding the menu element (with the same parent node, ignoring sibling nodes that are not elements) is a menulabel element, then that element provides the label.

Otherwise, if the menu element has no label attribute and the element that immediately precedes it is not a menulabel element, not an hr element, not a commandset element, not a select element, and not an element that defines or refers to a command, then the label of the menu is the value of the textContent DOM attribute of that previous sibling element.

Otherwise, the menu element has no label.

6.3.1.1.1. The menulabel element

Menus may be labelled by menulabel elements. The semantic of the menulabel element is that it labels its following sibling element, which must be a menu element. It must only contain inline elements. User agents must support all the common attributes and event handlers, plus the label attribute, on the menulabel element.

A menulabel whose next sibling element is not a menu element is semantically meanginless.

The label of menulabel elements with explicit label attributes is given by that attribute; the label of menulabel elements with no label attribute is given by the DOM textContent attribute.

The default rendering of menulabel elements in visual UAs should be a block. In CSS-aware UAs, this effect should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|menulabel { display: block; }

Menu bars cause menulabel elements to be styled further.

6.3.1.2. Content model of menus

When used as a list, a menu element must only contain li elements. When used in this way, each li element represents at most one item in the menu. What kind of item is represented depends on the children of the li.

When used as a block-level container, a menu element must only contain block-level markup. Each child element represents at most one item in the menu, depending on which kind of element it is.

Each item in a menu is either a group of commands, a single command, a separator, a submenu, or legacy fallback content. A menu is built up from these items.

6.3.1.3. Using optgroups as menus

When an optgroup element is a descendent of a menu element, and the optgroup element has a label attribute, then it defines a submenu. The label of such a menu is given by the label attribute.

When defining a submenu, an optgroup element must be a child node of either a select element or another optgroup element, must only contain option elements or other optgroup elements. Despite this, however, the processing model for constructing menus, as described in the next section, is the same whether the menu is defined by a menu element or an optgroup element.

6.3.1.4. Building menus

Menus shall be built up from the children of their menu (or optgroup) element by processing each child node of that element as follows:

  1. If the node is not an element node, it is ignored. (Fallback content.)
  2. If the node is an element node but is not in the XHTML namespace, it is ignored. (Fallback content.)
  3. If the node is an li element, then:
    1. If the first element node defines or refers to a command, or if the first element node is a menu element, an hr element, a commandset element, a select element, or an optgroup element, then continue the steps as if the li was actually this element.
    2. Otherwise, if the first element node is an a element with an href attribute, then continue the steps as if the li was actually that menu element. (This can only happen if the a element is a menu link, otherwise it would have defined a command and be processed in the first item in this list.)
    3. Otherwise, if the second element node is a menu element, then continue the steps as if the li was actually that element. (The first element will probably be used to get the label of the menu.)
    4. Otherwise, this li element is ignored.
    Non-element child nodes of the li element must be ignored. (Fallback content.)
  4. If the node is a command of some sort, then add that command to the menu. The item can be further annotated as follows:
    1. If the node is a command element with a default attribute, then the command is a default command and this should be reflected in the resulting interface.

      For example, on Windows, context menus can have one menu item marked as being the default item. That item is usually highlighted in bold.

    2. Each of the Triggers for the command must be checked in turn (in document order). If any of these triggers has an access key then the first such access key should be used as the shortcut key shown in the menu.
  5. If the node is an a element with an href attribute whose URI points to the current document and contains a fragment identifier that points to a menu element that is not the menu element for which the menu is currently being built, nor any of the menu elements for which any of the higher-level menus were created, then continue the steps as if the a was actually that menu element. If that menu element does not have a label then for the purposes of the current menu's creation, the a element's textContent is used as the label instead.
  6. If the node is a menu element, then, if it has a label, add that menu to the menu as a submenu. Otherwise, if it is an unlabelled menu element, ignore the node. (Note that a temporary label that applies just for this step may have been assigned by the previous step.)
  7. If the node is an optgroup element and it has a label attribute, then add that menu to the menu as a submenu.
  8. If the node is a commandset element or a select element, then add a separator to the menu, process all the children nodes of the element as if they were children of the menu element, then add another separator.
  9. If the node is an hr element, then add a separator to the menu.
  10. If the node is an option element that does not define a command, that is disabled, and whose label (either from its label attribute, or, if it doesn't have one, from its textContent DOM attribute) consists of nothing but one or more hyphens (U+002D), then add a separator to the menu.
  11. Otherwise, ignore the node. (Fallback content.)

Once all the nodes have been processed in this way, any separators at the top of the menu and at the bottom of the menu shall be removed, and any consecutive separators shall be collapsed to just a single separator.

Commands of Type "radio" or "checkbox" should be represented appropriately. Commands whose Hidden State is true (hidden) must not be shown in the menu at all. Similarly, the Label, Icon, Hint, Disabled State and Checked State facets of the command should be appropriately reflected in the user interface created for the menu. The default state and access key for each menu item, if any, should similarly be reflected in the UI.

Menus are live: changes to the underlying document structure must be reflected in the menu visible to the user immediately.

Immediately prior to a menu or submenu being opened or made visible, a click event that cannot be canceled must be fired on the menu's menu (or optgroup) element. This event allows menus and submenus to be populated dynamically if needed.

When commands are selected from the menu, their associated Action should be triggered.

6.3.1.5. Displaying menus

When a menu element is activated, the associated menu should be constructed and shown. (For details on how a menu element can be activated, see the sections on menu links and menu bars.)

The styles applied to each element in the menu element, as well as the element itself, may be applied when constructing a menu. UAs are recommended to not apply styling to context menus and menus for application menu bars, and to only use styles for in-page menus.

If user agents support styling of menus, they should only support the 'background', 'color', 'border', 'padding' and 'font' properties on menus and menu items. (This list might be incomplete; in general, properties that merely affect the appearance of the element should work, but properties that affect the layout should not.)

As the user interacts with a menu, the elements from which the menu was created should have appropriate pseudo-classes (:hover, :focus, :active) applied.

The menu items must only consider the computed styles of the elements from which they were derived, not other elements.

For example, take this menu:

<menu>
<li><command label="a"/></li>
<menu>

The menu has one menu item, labelled "a".

Styles applied to the li element in this menu would have no effect on the rendered menu, except in so far as styles inherit from that element to the command element.

Styles applied to the command element could affect the menu. While the user is hovering over the menu item, the :hover pseudo-class matches the command element and any appropriate newly matching rules could be applied.

When activated from a menu link, a menu must be placed in an Appropriate Place. Specifically, if the a element is displayed as a vertically-stacked box (as is typically seen for elements with 'display: block', 'list-item', or 'table'), then the menu should appear vertically below the element, anchored so that one of its top corners coincides with a bottom corner of the box so that the menu and the box each have a horizontal sides in common (or a bottom corner of the menu coincides with a top corner of the box, if there isn't enough room for the menu to drop down); otherwise, if the element is displayed as a horizontally stacked box ('display: inline', 'table-cell', etc), the menu should appear to the side of the box in an analogous way. If the element is on the right of the page, the menu should drop to the left, and vice versa.

UAs should implement the drop-down behaviour in more platform-appropriate ways if the platform conventions differ from the behaviour described above.

Menu bars are defined using the menubar element. The semantic of the menubar element is a structured list of menus. The element can be used either as a list or as a menu container. User agents must support all the common attributes and event handlers on menubar elements.

When used as a list, a menubar element must only contain li elements. When used in this way, each li element represents at most one item in the menu bar. What kind of item is represented depends on the children of the li.

When used as a menu container, a menubar element must only contain elements that define commands, menulabel and menu elements, hr elements, commandset elements, plus any other inline content needed for fallback. Each child element represents at most one item in the menu, depending on which kind of element it is.

6.3.2.1. Displaying menu bars inline

Do we even want to allow this? We could instead define menu bars as being always rendered "natively", with styling done as for menus.

When a menubar is displayed inline in the content of the document in a style-sheet-capable UA, it should be rendered according to the rules of the appropriate style sheet language.

Any a elements with href attributes that are children of menubar elements or children of li elements that are themselves children of menubar elements should be rendered in a way that indicates that they are not normal links, but can show menus, just like menulabel elements. Any menu elements that are children of menubar elements or children of li elements that are themselves children of menubar elements should be hidden until they are activated.

In a CSS-aware UA this could be achieved with rules such as:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|menubar > xh|menu, xh|menubar > xh|li > xh|menu { display: none; }
xh|menubar > xh|a[href], xh|menubar > xh|li > xh|a[href],
xh|menulabel { /* styling */ }
6.3.2.2. Displaying menu bars as menu bars

If the UA does not render a menubar element using a style sheet language's rendering model, then it should use the rendering model described in this section.

This model should also be used when a menubar element is to be shown as an actual menu bar in native UI.

First, menu bars shall be built up from the children of their menubar element by processing each child node of that element as follows:

  1. If the node is not an element node, it is ignored. (Fallback content.)
  2. If the node is an element node but is not in the XHTML namespace, it is ignored. (Fallback content.)
  3. If the node is an li element, then if the first element node in that element is one of the following: ...then then continue the steps as if the li was that element. Otherwise, this li element is ignored. Non-element child nodes of the li element must be ignored. (Fallback content.)
  4. If the node is a command of type Command, and the command's Hidden State is not hidden, then add that command to the menu.
  5. If the node is an a element with an href attribute whose URI points to the current document and contains a fragment identifier that points to a menu element, then add that menu to the menu bar as a submenu, using the contents of the textContent DOM attribute of the a element as the menu label.
  6. If the node is a menulabel element whose next sibling element is a menu element, then add that menu to the menu bar as a submenu, using the contents of the menulabel element's label attribute (if there is one) or of its textContent DOM attribute (if there isn't) as the menu label.
  7. If the node is a commandset element, then add a separator to the menu, process all the children nodes of the element as if they were children of the menu element, then add another separator.
  8. If the node is an hr element, then add a separator to the menu.
  9. Otherwise, ignore the node. (Fallback content.)

This processing model, while similar to the processing model for constructing menus, is intentionally different in many respects.

Once all the nodes have been processed in this way, any separators at the top of the menu and at the bottom of the menu shall be removed, and any consecutive separators shall be collapsed to just a single separator. If the menu is to be rendered in a way that does not support separators, then all separators should be dropped.

The Label, Icon, Hint, and Disabled State facets of the command should be appropriately reflected in the user interface created for the menu bar. (Checkbox and Radio commands cannot be added to a menu bar, so the Checked facet is ignored.)

Menu bars are live: changes to the underlying document structure must be reflected in the menu visible to the user immediately.

When commands are selected from the menu bar, their associated Action should be triggered.

The default action of the DOMActivate event of a elements that do not define or refer to commands is as follows:

  1. If the a element has an href attribute, and that attribute points to the a element's document, and contains a fragment identifier that points to a menu element, then activate the menu element.
  2. Otherwise, if the a element has an href attribute, then follow that link, taking into account any other relevant attributes on the element as appropriate.

Thus, any a element can be made to activate a menu by making it point to a menu element in the same document.

By default, such a elements look like links, not like buttons or menus, unless they are placed inside menubar elements.

6.3.4. Context menus

This section will probably describe a context-menu attribute (or similar) which would be a common attribute and would refer to a menu element, allowing any element to get a context menu. This section would have to define how the context menu commands determine which element the menu was triggered on. It would also have to ensure that UAs can show their own context menu alongside the author-provided menu (or at least, give access to it).

6.4. Keyboard shortcuts

Support for the accesskey attribute is optional. User agents may use the attribute as a suggestion for a suitable shortcut key, or may ignore the attribute altogether. User agents should avoid letting author-specified access keys prevent users from accessing the UA's features.

Or should we just deprecate it? People do use this attribute usefully in certain cases.

Interactive user agents that support keyboard input devices should allow users to conveniently access or activate hyperlinks, form controls, and other interactive parts of Web content using the keyboard, without having to cycle through all such content.

The accesskey attribute has numerous problems, such as not being discoverable by users, not being consistent with the interface on certain platforms, clashing with the user agent's own access keys or requiring unusual modifiers, being unable to handle the differing needs of platforms with varying keyboard types, etc. Authors are discouraged from relying on this feature.

It is unclear what new features will be supported in Web Apps with respect to key handling, if any. Some sort of declarative way of listing key listeners that would take effect while a particular element has focus is possible, maybe with the key being given in a style sheet instead of the markup, allowing for a model where the user has final say, and allowing for per-device style sheets to be used to change the key based on the available input device(s).

7. Editing

This section will be based on the contentEditable attribute.

The contentEditable attribute is a common attribute. User agents must support this attribute on all HTML elements.

If an HTML element has a contentEditable attribute set to exactly the literal value true, or if its nearest ancestor with the contentEditable attribute set has its attribute set to exactly the literal value true, then the UA must treat the element as editable (as described below).

If an HTML element has a contentEditable attribute set but the value of the attribute is not exactly the literal value true, or if its nearest ancestor with the contentEditable attribute set is not editable, or if it has no ancestor with the contentEditable attribute set, then the element is not editable.

Authors must only use the values true and false with the contentEditable attribute.

If an element is editable and its parent element is not, then the element is an editing host. Editable elements can be nested, meaning the user can edit through them (see below). User agents must make editing hosts focusable (which typicially means it enters the tab order). An editing host can contain non-editable sections, these are handled as described below. An editing host can contain non-editable sections that contain further editing hosts. These nested editing hosts are not handled any differently to top-level editing hosts — they ...

How editable elements act depends on their CSS 'display' type. (For non-CSS user agents, analogous rules should be followed.)

If an editable element is an inline box ('display' has the value 'inline' or 'run-in' and the result is an inline box),

If an editable host is a block box ('display' has the value 'block', 'list-item', 'inline-block', 'table-cell', 'table-caption', or 'run-in' and the result is a block box), then the user agent must place 'table', 'inline-table', 'table-row-group', 'table-header-group', 'table-footer-group', 'table-row', 'table-column-group', 'table-column' 'none'

8. Script and the DOM

Applications typically involve an element of interactivity implemented programmatically. This section defines some APIs that complement the APIs defined by the W3C DOM specifications.

8.1. Event listeners

In the ECMAScript DOM binding, the ECMAScript native Function type implements the EventListener interface such that invoking the handleEvent() method of the object invokes the function itself, with the evt argument as its only argument. If the function returns false, the event's preventDefault() method must then invoked. Exception: for historical reasons, for the HTML mouseover event, the preventDefault() method must be called when the function returns true instead.

In HTML, event handler attributes (such as onclick) are invoked as if they were functions implementing EventListener, with the argument called event. Such attributes are added as non-capture event listeners of the type given by their name (without the leading on prefix). Only attributes actually defined to exist by specifications implemented by the UA (e.g. HTML, Web Forms 2, Web Apps) are actually registered, however; for example if an author created an onfoo attribute, it would not be fired for foo events.

The scope chain for ECMAScript executed in HTML event handler attributes must link from the activation object for the handler, to its this parameter (the event target), to the element's form element if it is a form control, to the document, to the default view (the window).

This definition is intentionally backwards compatible with DOM Level 0. See also ECMA262 Edition 3, sections 10.1.6 and 10.2.3, for more details on activation objects. [ECMA262]

8.2. Bootstrapping the DOM and the Window interface

interface Window {
  readonly attribute Window            window;

  // (part of AbstractView interface)
  // readonly attribute Document          document;

  readonly attribute DOMString          mediaMode;

           attribute ErrorHandler       onerror;

  long setTimeout(in TimeoutHandler handler, in long timeout);
  long setTimeout(in DOMString code, in long timeout);
  long setTimeout(in DOMString code, in long timeout, in DOMString language);
  void clearTimeout(in long handle);

  long setInterval(in TimeoutHandler handler, in long timeout);
  long setInterval(in DOMString code, in long timeout);
  long setInterval(in DOMString code, in long timeout, in DOMString language);
  void clearInterval(in long handle);


};

interface ErrorHandler {
  void handleEvent(in DOMString errorMessage, in DOMString fileName, in DOMString lineNumber);
};

interface TimeoutHandler {
  void handleEvent();
};

The window interface represents the chrome into which the document is rendered.

In UAs that expose the DOM to ECMAScript [ECMA262] scripts, the global scope object must implement the Window interface described above.

The object implementing the Window interface must also implement the AbstractView interface. [DOM2VIEWS]

The following equality must hold (assuming appropriate casting has been applied, as required by the binding):

window.document.defaultView == window

In this equality, window is a property of the ECMAScript global object pointing at the global object itself, the document property of that object is the document attribute of the AbstractView interface implemented by the global object, and the defaultView property of that object is the defaultView attribute of the DocumentView interface. The object returned by the document property of the AbstractView interface must implement the Document interface as well.

The mediaMode attribute on the window object returns the string that represents the canvas' current rendering mode (screen, print, etc). This is a lowercase string, as defined by the CSS specification. [CSS21]

8.2.1. Error handling

The onerror attribute takes a reference to an object implementing the ErrorHandler interface. In ECMAScript, such an interface is implemented by any function that takes three arguments and returns a boolean value, as well as by the null value and the undefined value.

The function to which the onerror attributes points is invoked whenever a runtime script error occurs in the context of the window object, before the error is reported to the user. If the function is null or if the function returns true then the error is not reported to the user. If the function is undefined or if the function doesn't returns true, then the message is reported as normal.

The three arguments passed to the function are all DOMStrings; the first gives the message that the UA is considering reporting, the second gives the URI to the resource in which the error occured, and the third gives the line number in tha resource on which the error occured.

The initial value of onerror is undefined.

8.2.2. Timeouts

The setTimeout and setInterval methods allow authors to schedule timer-based events.

The setTimeout(handler, timeout) method takes a reference to a TimeoutHandler object and a length of time in milliseconds. It returns a handle to the timeout created, and then asynchronously waits timeout milliseconds and then invokes handleEvent() on the handler object.

In the ECMAScript binding, any Function object implements TimeoutHandler. Such functions are called in the global scope.

Alternatively, setTimeout(code, timeout[, language]) may be used. This variant takes a string instead of a TimeoutHandler object. That string is then parsed using the specified language (defaulting to ECMAScript if the third argument is omitted) and executed in the global scope.

The setInterval(...) variants work in the same way as the code>setTimeout variants except that the handler or code is invoked again every timeout milliseconds, not just the once.

The clearTimeout() and clearInteval() methods take one integer (the value returned by setTimeout and setInterval respectively) and cancel the specified timeout. When called with a value that does not correspond to an active timeout or interval, the methods must return without doing anything.

Timeouts must never fire while another script is executing.

8.3. Selecting elements

Both Documents and Elements shall also implement the GetElementsByClass interface:

interface GetElementsByClass {
  NodeList           getElementsByClass(in DOMString className1 [, in DOMString className2, ...] );
}

This interface defines one method, getElementsByClass(), which takes one or more strings representing classes and returns all the elements in that document or below that element that are of all those classes. HTML, XHTML, SVG and MathML elements define which classes they are in by having an attribute in the per-element partition with the name class containing a space-separated list of classes to which the element belongs. Other specifications may also allow elements in their namespaces to be labelled as being in specific classes. UAs must not assume that all attributes of the name class for elements in any namespace work in this way, however, and must not assume that such attributes, when used as global attributes, label other elements as being in specific classes.

Given the following XHTML fragment:

<div id="example">
 <p id="p1" class="aaa bbb"/>
 <p id="p2" class="aaa ccc"/>
 <p id="p3" class="bbb ccc"/>
</div>

A call to document.getElementById('example').getElementsByClassName('aaa') would return a NodeList with the two paragraphs p1 and p2 in it. A call to getElementsByClassName('ccc', 'bbb') would only return one node, however, namely p3.

We could also have a getElementBySelector() method, but it seems that it would be best to let the CSSWG define that.

The DOM IG indicated concerns about this interface, suggesting that DOM Traversal would be a better way of doing this.

All objects that implement the Node interface shall also implement the ElementTraversal interface:

// Originally defined in SVG 1.2 Appendix A
interface ElementTraversal {
  readonly attribute Element                 firstElementChild;
  readonly attribute Element                 lastElementChild;
  readonly attribute Element                 nextElementSibling;
  readonly attribute Element                 previousElementSibling;
};

The firstElementChild and lastElementChild attributes shall return the first element child and last element child (respectively) of their node. If there is no such child, they shall return null.

The nextElementSibling and previousElementSibling attributes shall return the first element to follow the current node and the first element to precede the current node (respectively). If there is no such element, they shall return null.

8.5. Serialization and parsed fragment replacement

This section will try to explain how document.write() actually works, and will define the innerHTML attribute, for both HTML and XML contexts. Wish us luck.

8.6. Alternate style sheets

// Introduced in DOM Level 2: [DOM2STYLE]
interface DocumentStyle {
  readonly attribute StyleSheetList   styleSheets;

  // New in this specification:
           attribute DOMString        selectedStylesheetSet;
  readonly attribute DOMString        lastStylesheetSet;
  readonly attribute DOMString        preferredStylesheetSet;
  readonly attribute DOMStringList    stylesheetSets;
  void                                enableStylesheetsForSet(in DOMString name);
};

For this interface, the DOMString values "null" and "the empty string" are distinct, and must not be considered equivalent.

The new members are defined as follows:

selectedStylesheetSet of type DOMString

This attribute indicates which style sheet set ([HTML4]) is in use. This attribute is live; changing the disabled attribute on style sheets directly will change the value of this attribute.

If all the sheets that are enabled have the same title (by case insensitive comparisons) then the value of this attribute shall be exactly equal to the title of the first enabled style sheet with a title in the styleSheets list. If style sheets from different sets are enabled, then the return value shall be null (there is no way to determine what the currently selected style sheet set is in those conditions). Otherwise, either all style sheets are disabled, or there are no alternate style sheets, and selectedStylesheetSet must return the empty string.

Setting this attribute to the null value shall have no effect.

Setting this attribute to a non-null value must call enableStylesheetsForSet() with that value as the function's argument, then set lastStylesheetSet to that value.

From the DOM's perspective, all views have the same selectedStylesheetSet. If a UA supports multiple views with different selected alternate style sheets, then this attribute (and the StyleSheet interface's disabled attribute) must return and set the value for the default view.

lastStylesheetSet of type DOMString, readonly

This property shall return the last value that selectedStylesheetSet was set to, or, if none, null.

preferredStylesheetSet of type DOMString, readonly

This attribute shall indicate the preferred style sheet set as set by the author. It is determined from the order of style sheet declarations and the Default-Style HTTP headers. [HTML4]. If there is no preferred style sheet set, this attribute must return the empty string. The case of this attribute must exactly match the case given by the author where the preferred style sheet is specified or implied. This attribute must never return null.

stylesheetSets of type DOMStringList, readonly

This must return the live list of the currently available style sheet sets. This list is constructed by enumerating all the style sheets for this document available to the implementation, in the order they are listed in the styleSheets attribute, adding the title of each style sheet with a title to the list, avoiding duplicates by dropping titles that match (case insensitively) titles that have already been added to the list.

enableStylesheetsForSet(name), method

Calling this method must change the disabled attribute on each StyleSheet object with a title attribute with a length greater than 0 in the styleSheets attribute, so that all those whose title matches the name argument are enabled, and all others are disabled. Title matches are case insensitive. Calling this method with the empty string disables all alternate and preferred style sheets (but does not change the state of persistent style sheets, that is those with no title attribute).

Calling this method with a null value must have no effect.

Style Sheets that have no title are never affected by this method. This method does not change the values of the lastStylesheetSet or preferredStylesheetSet attributes.

8.6.1. Dynamically adding new style sheets

If new style sheets with titles are added to the document, the UA must decide whether or not the style sheets should be initially enabled or not. How this happens depends on the exact state of the document at the time the style sheet is added, as follows.

8.6.1.1. Adding style sheets

First, if the style sheet is a preferred style sheet (it has a title, but is not marked as alternate), and there is no current preferred style sheet (the preferredStylesheetSet attribute is equal to the empty string) then the preferredStylesheetSet attribute is set to the exact value of this style sheet's title. (This changes the preferred style sheet set, which causes further changes — see below.)

Then, for all sheets, if any of the following is true, then the style sheet must be enabled:

Otherwise, the style sheet must be disabled.

8.6.1.2. Changing the preferred style sheet set

If the UA has the preferred style sheet set changed, for example if it receives a "Default-Style:" HTTP header after it receives HTTP "Link:" headers implying another preferred style sheet, then the preferredStylesheetSet attribute's value must be changed appropriately, and, if the lastStylesheetSet is null, the enableStylesheetsForSet() method must be called with the new preferredStylesheetSet value. (The lastStylesheetSet attribute is not changed.)

8.6.1.3. Examples

Thus, in the following HTML snippet:

<link rel="alternate stylesheet" title="foo" href="a">
<link rel="alternate stylesheet" title="bar" href="b">
<script>
  document.selectedStylesheetSet = 'foo';
  document.styleSheets[1].disabled = false;
</script>
<link rel="alternate stylesheet" title="foo" href="c">
<link rel="alternate stylesheet" title="bar" href="d">

...the style sheets that end up enabled are style sheets "a", "b", and "c", the selectedStylesheetSet attribute would return null, lastStylesheetSet would return "foo", and preferredStylesheetSet would return "".

Similarly, in the following HTML snippet:

<link rel="alternate stylesheet" title="foo" href="a">
<link rel="alternate stylesheet" title="bar" href="b">
<script>
  var before = document.preferredStylesheetSet;
  document.styleSheets[1].disabled = false;
</script>
<link rel="stylesheet" title="foo" href="c">
<link rel="alternate stylesheet" title="bar" href="d">
<script>
  var after = document.preferredStylesheetSet;
</script>

...the "before" variable will be equal to the empty string, the "after" variable will be equal to "foo", and style sheets "a" and "c" will be enabled. This is the case even though the first script block sets style sheet "b" to be enabled, because upon parsing the following <link> element, the preferredStylesheetSet is set and the enableStylesheetsForSet() method is called (since selectedStylesheetSet was never set explicitly, leaving lastStylesheetSet at null throughout), which changes which style sheets are enabled and which are not.

8.6.2. Interaction with the User Interface

The user interface of Web browsers that support style sheets should list the style sheet titles given in the stylesheetSets list, showing the selectedStylesheetSet as the selected style sheet set, leaving none selected if it is null or the empty string, and selecting an extra option "Basic Page Style" (or similar) if it is the empty string and the preferredStylesheetSet is the empty string as well.

Selecting a style sheet from this list should set the selectedStylesheetSet attribute.

8.6.2.1. Persisting the selected style sheet set

If UAs persist the selected style sheet set, they should use the value of the selectedStylesheetSet attribute, or if that is null, the lastStylesheetSet attribute, when leaving the page (or at some other time) to determine the set name to store. If that is null then the style sheet set should not be persisted.

When re-setting the style sheet set to the persisted value (which can happen at any time, typically at the first time the style sheets are needed for styling the document, after the <head> of the document has been parsed, after any scripts that are not dependent on computed style have executed), the style sheet set should be set by setting the selectedStylesheetSet attribute as if the user had selected the set manually.

This specification does not give any suggestions on how UAs should decide to persist the style sheet set or whether or how to persist the selected set across pages.

8.6.3. Future compatibility

Future versions of CSS may introduce ways of having alternate style sheets declared at levels lower than the top level, i.e. embedded within other style sheets. Implementations of this specification that also support this proposed declaration of alternate style sheets are expected to perform depth-first traversals of the styleSheets list, not simply enumerations of the styleSheets list that only contains the top level.

9. Multimedia

9.1. Graphics: The bitmap canvas

The canvas element represents a resolution-dependent bitmap canvas, which can be used for rendering graphs, game graphics, or other visual images on the fly.

When authors use the canvas element, they should also provide content that, when presented to the user, conveys essentially the same function or purpose as the bitmap canvas. This content may be placed as content of the canvas element.

Authors should not use the canvas element in a document when a more suitable element is available. For example, it is inappropriate to use a canvas element to render a page heading: if the desired presentation of the heading is graphically intense, it should be marked up using appropriate elements (typically h1) and then styled using CSS and supporting technologies such as XBL.

In non-visual media, the canvas element should be treated as an ordinary block-level element and the fallback content should therefore be used instead.

In non-interactive, static, visual media, if the canvas element has been previously painted on (e.g. if the page was viewed in an interactive visual media and is now being printed, or if some script that ran during the page layout process painted on the element), then the canvas element should be treated as a replaced block-level element with the current image and size. Otherwise, the element should be treated as an ordinary block-level element and the fallback content should therefore be used instead.

In interactive visual media, the canvas element is a block-level replaced element.

In CSS-aware user agents, this should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:

@namespace xh url(http://www.w3.org/1999/xhtml);
xh|canvas { display: block; }

The canvas element has two attributes to control the size of the coordinate space: height and width. These attributes each take a positive integer value (one digit in the range 1-9 followed by zero or more digits in the range 0-9, interpreted in base ten). If an attribute is missing, or if it has a value that does not match this syntax, then the default values are used instead. The width attribute defaults to 300, and the height attribute defaults to 200.

The intrinsic dimensions of the canvas element equal the size of the coordinate space, with the numbers interpreted in CSS pixels. However, the element can be sized arbitrarily by a style sheet. During rendering, the image is scaled to fit this layout size.

The size of the coordinate space does not necessarily represent the size of the actual bitmap that the user agent will use internally or during rendering. On high-definition displays, for instance, the user agent may internally use a bitmap with two device pixels per unit in the coordinate space, so that the rendering remains at high quality throughout.

If the width and height attributes are dynamically modified, the bitmap and any associated contexts must be cleared back to their initial state and reinitialised with the newly specified coordinate space dimensions.

The canvas element also supports the usemap and ismap attributes. These must be handled exactly as they would if the element was an img element. (See HTML4 section 13.6.1 (for usemap) and section 13.6.2 (for ismap.)

As with any replaced element, the CSS background properties do apply to canvas elements; they are rendered below the canvas image.

interface HTMLCanvasElement : HTMLImageElement {

  // returns the values of the width and height attributes, or the assumed
  // defaults if the attributes were not specified or invalid
  // sets the relevant content attributes on setting
  // (defined in HTMLImageElement)
  //       attribute long                    width;
  //       attribute long                    height;

  // returns a data: URI representing the current image as a PNG
  // does nothing on setting
  // (defined in HTMLImageElement)
  //       attribute DOMString               src;

  DOMObject getContext(in DOMString contextID);

};

To draw on the canvas, authors must first obtain a reference to a context using the getContext method of the canvas element.

This specification only defines one context, with the name "2d". If getContext() is called with that exact string, then the UA must return a reference to an object implementing CanvasRenderingContext2D. Other specifications may define their own contexts, which would return different objects.

Vendors may also define experimental contexts using the syntax vendorname-context, for example, moz-3d.

When the UA is passed an empty string or a string specifying a context that it does not support, then it must return null. String comparisons should be literal and case sensitive.

A future version of this specification will probably define a 3d context.

The alt DOM attribute shall return the same value as the textContent DOM attribute. On setting it must do nothing.

The src attribute must return a data: URI containing a representation of the image as a PNG file. [PNG] On setting it must do nothing.

The useMap and isMap DOM attributes inherited from the HTMLImageElement interface shall do the same as for img elements.

All the other DOM attributes — align, border, hspace, vspace, longDesc, and name — must do nothing on setting and return the empty string on getting.

9.1.1. The 2D context

When the getContext() method of a canvas element is invoked with 2d as the argument, a CanvasRenderingContext2D object is returned.

There is only one CanvasRenderingContext2D object per canvas, so calling the getContext() method with the 2d argument a second time must return the same object.

interface CanvasRenderingContext2D {

  // back-reference to the canvas
  readonly attribute HTMLCanvasElement       canvas;

  // state
  void save(); // push state on state stack
  void restore(); // pop state stack and restore state

  // transformations (default transform is the identity matrix)
  void scale(in float x, in float y);
  void rotate(in float angle);
  void translate(in float x, in float y);

  // compositing
           attribute float                   globalAlpha; // (default 1.0)
           attribute DOMString               globalCompositeOperation; // (default over)

  // colours and styles
           attribute DOMObject               strokeStyle; // (default black)
           attribute DOMObject               fillStyle; // (default black)
  CanvasGradient createLinearGradient(in float x0, in float y0, in float x1, in float y1);
  CanvasGradient createRadialGradient(in float x0, in float y0, in float r0, in float x1, in float y1, in float r1);
  CanvasPattern createPattern(in HTMLImageElement image, DOMString repetition);

  // line caps/joins
           attribute float                   lineWidth; // (default 1)
           attribute DOMString               lineCap; // "butt", "round", "square" (default "butt")
           attribute DOMString               lineJoin; // "round", "bevel", "miter" (default "miter")
           attribute float                   miterLimit; // (default 10)

  // shadows
           attribute float                   shadowOffsetX; // (default 0)
           attribute float                   shadowOffsetY; // (default 0)
           attribute float                   shadowBlur; // (default 0)
           attribute DOMString               shadowColor; // (default black)

  // rects
  void clearRect(in float x, in float y, in float w, in float h);
  void fillRect(in float x, in float y, in float w, in float h);
  void strokeRect(in float x, in float y, in float w, in float h);

  // path API
  void beginPath();
  void closePath();
  void moveTo(in float x, in float y);
  void lineTo(in float x, in float y);
  void quadraticCurveTo(in float cpx, in float cpy, in float x, in float y);
  void bezierCurveTo(in float cp1x, in float cp1y, in float cp2x, in float cp2y, in float x, in float y);
  void arcTo(in float x1, in float y1, in float x2, in float y2, in float radius);
  void rect(in float x, in float y, in float w, in float h);
  void arc(in float x, in float y, in float radius, in float startAngle, in float endAngle, in boolean clockwise);
  void fill();
  void stroke();
  void clip();

  // drawing images
  void drawImage(in HTMLImageElement image, in float dx, in float dy);
  void drawImage(in HTMLImageElement image, in float dx, in float dy, in float dw, in float dh);
  void drawImage(in HTMLImageElement image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh);

  // drawing text is not supported in this version of the API
  // (there is no way to predict what metrics the fonts will have,
  // which makes fonts very hard to use for painting)

};

interface CanvasGradient {
  // opaque object
  void addColorStop(in float offset, in DOMString color);
}

interface CanvasPattern {
  // opaque object
}

The canvas attribute returns the canvas element that the context paints on.

9.1.1.1. The canvas state

Each context maintains a stack of drawing states. Drawing states consist of:

The current path and the current bitmap are not part of the drawing state. The current path is persistent, and can only be reset using the beginPath() method. The current bitmap is a property of the canvas, not the context.

The save() method pushes a copy of the current drawing state onto the drawing state stack.

The restore() method pops the top entry in the drawing state stack, and resets the drawing state it describes. If there is no saved state, the method resets the context's drawing state to its initial values.

9.1.1.2. Transformations

The transformation matrix is applied to all drawing operations prior to their being rendered. It is also applied when creating the clip region.

When the context is created, the transformation matrix is initially the identity transform. It may then be adjusted using the three transformation methods.

The transformations are performed in reverse order. For instance, if a scale transformation that doubles the width is applied, followed by a rotation transformation that rotates drawing operations by a quarter turn, and a rectangle twice as wide as it is tall is then drawn on the canvas, the actual result will be a square.

The scale(x, y) method adds a scaling transformation to the transformation matrix. The x method represents the scale factor in the horizontal direction and the y factor represents the scale factor in the vertical direction.

The rotate(angle) method adds a rotation transformation to the transformation matrix. The angle method represents an anti-clockwise rotation angle expressed in radians.

The translate(x, y) method adds a translating transformation to the transformation matrix. The x method represents the translation distance in the horizontal direction and the y factor represents the translation distance in the vertical direction.

9.1.1.3. Compositing

All drawing operations are affected by the global compositing attributes, globalAlpha and globalCompositeOperation.

The globalAlpha attribute gives an alpha value that is applied to shapes and images before they are composited onto the canvas. The valid range of values is from 0.0 (fully transparent) to 1.0 (no additional transparency). If the attribute is set to values outside this range, they are ignored. When the context is created, the globalAlpha attribute initially has the value 1.0.

The globalCompositeOperation attribute sets how shapes and images are drawn onto the existing bitmap, once they have had globalAlpha and the current transformation matrix applied. It may be set to any of the values in the following list. In the descriptions below, the source image is the shape or image being rendered, and the destination image is the current state of the bitmap.

The source-* descriptions below don't define what should happen with semi-transparent regions.

source-atop
Display the source image wherever both images are opaque. Display the destination image wherever the destination image is opaque but the source image is transparent. Display transparency elsewhere.
source-in
Display the source image wherever both the source image and destination image are opaque. Display transparency elsewhere.
source-out
Display the source image wherever the source image is opaque and the destination image is transparent. Display transparency elsewhere.
source-over (default)
Display the source image wherever the source image is opaque. Display the destination image elsewhere.
destination-atop
Same as source-atop but using the destination image instead of the source image and vice versa.
destination-in
Same as source-in but using the destination image instead of the source image and vice versa.
destination-out
Same as source-out but using the destination image instead of the source image and vice versa.
destination-over
Same as source-over but using the destination image instead of the source image and vice versa.
darker
Display the sum of the source image and destination images, with color values approaching 0 as a limit.
lighter
Display the sum of the source image and destination image, with color values approaching 1 as a limit.
copy
Display the source image instead of the destination image.
xor
Exclusive OR of the source and destination images.
vendorName-operationName
Vendor-specific extensions to the list of composition operators should use this syntax.

If the user agent does not recognise the specified value, it must be ignored, leaving the value of globalCompositeOperation unaffected.

When the context is created, the globalCompositeOperation attribute initially has the value source-over.

9.1.1.4. Colours and styles

The strokeStyle attribute represents the colour or style to use for the lines around shapes, and the fillStyle attribute represents the colour or style to use inside the shapes.

Both attributes can be either strings, CanvasGradients, or CanvasPatterns. On setting, strings they should be parsed as CSS <color> values. [CSS3COLOR] If the value is a string but is not a valid colour, or is neither a string, a CanvasGradient, nor a CanvasPattern, then it must be ignored, and the attribute must retain its previous value.

On getting, if the value is a color, then: if it has alpha equal to 1.0, then the colour must be returned as an uppercase six-digit hex value, prefixed with a "#" character (U+0023), with the first two digits representing the red component, the next two digits representing the green component, and the last two digits representing the blue component. If the value has alpha less than 1.0, then the value must be returned in the CSS rgba() functional-notation format: the literal string rgba followed by an open parenthesis (U+0028), a base-ten integer in the range 0-255 representing the red component, a literal space and comma (U+0020 and U+002C), an integer for the green component, a space and a comma, an integer for the blue component, another space and comma, a zero (U+0030), a decimal point (U+002E), one or more digits in the range 0-9 representing the fractional part of the alpha value, and finally a close parenthesis (U+0029).

Otherwise, if it is not a color but a CanvasGradient or CanvasPattern, then an object supporting those interfaces must be returned. Such objects are opaque and therefore only useful for assigning to other attributes or for comparison to other gradients or patterns.

When the context is created, the strokeStyle and fillStyle attributes initially have the string value #000000.

There are two types of gradients, linear gradients and radial gradients, both represented by objects implementing the opaque CanvasGradient interface.

Once a gradient has been created, stops must be placed along it to define how the colours are distributed along the gradient. Between each such stop, the colours and the alpha component are interpolated over the RGBA space to find the colour to use at that offset. Immediately before the 0 offset and immediately after the 1 offset, transparent black stops are assumed.

The addColorStop(offset, color) method on the CanvasGradient interface adds a new stop to a gradient. If the offset is less than 0 or greater than 1 then an INDEX_SIZE_ERR exception is raised. If the color cannot be parsed as a CSS colour, then a SYNTAX_ERR exception is raised. Otherwise, the gradient is updated with the new stop information.

The createLinearGradient(x0, y0, x1, y1) method takes four arguments, representing the start point (x0, y0) and end point (x1, y1) of the gradient, in coordinate space units, and returns a linear CanvasGradient initialised with that line.

Linear gradients are rendered such that at the starting point on the canvas the colour at offset 0 is used, that at the ending point the color at offset 1 is used, that all points on a line perpendicular to the line between the start and end points have the colour at the point where those two lines cross, and that any points beyond the start or end points are a transparent black. (Of course, the colours are only painted where the shape they are being painted on needs them.)

The createRadialGradient(x0, y0, r0, x1, y1, r1) method takes six arguments, the first three representing the start circle with origin (x0, y0) and radius r0, and the last three representing the end circle with origin (x1, y1) and radius r1. The values are in coordinate space units. The method returns a radial CanvasGradient initialised with those two circles.

Radial gradients are rendered such that a cone is created from the two circles, so that at the circumference of the starting circle the colour at offset 0 is used, that at the circumference around the ending circle the color at offset 1 is used, that the circumference of a circle drawn a certain fraction of the way along the line between the two origins with a radius the same fraction of the way between the two radii has the colour at that offset, that the end circle appear to be above the start circle when the end circle is not completely enclosed by the start circle, and that any points not described by the gradient are a transparent black.

If a gradient has no stops defined, then the gradient is treated as a solid transparent black. Gradients are, naturally, only painted where the stroking or filling effect requires that they be drawn.

Support for actually painting gradients is optional. Instead of painting the gradients, user agents may instead just paint the first stop's colour. However, createLinearGradient() and createRadialGradient() must always return objects when passed valid arguments.

Patterns are represented by objects implementing the opaque CanvasPattern interface.

To create objects of this type, the createPattern(image, repetition) method is used. The first argument gives the image to use as the pattern. Modifying this image after calling the createPattern() method must not affect the pattern. The second argument must be a string with one of the following values: repeat, repeat-x, repeat-y, no-repeat. If the empty string or null is specified, repeat is assumed. If an unrecognised value is given, then the user agent must raise a SYNTAX_ERR exception. The method returns a CanvasPattern objecy suitably initialised.

Patterns are painted so that the first image is centered in the middle of the coordinate space, and images are then repeated horizontally to the left and right (if the repeat-x string was specified) or vertically up and down (if the repeat-y string was specified) or in all four directions all over the canvas (if the repeat string was specified). The images shall not be scaled by this process; one CSS pixel of the image is painted on one coordinate space unit. Of course, patterns are only actually painted where the stroking or filling effect requires that they be drawn.

Support for patterns is optional. If the user agent doesn't support patterns, then createPattern() must return null.

9.1.1.5. Line styles

The lineWidth attribute gives the default width of lines, in coordinate space units. On setting, zero and negative values are ignored, and leave the value unchanged.

When the context is created, the lineWidth attribute initially has the value 1.0.

The lineCap attribute defines the type of endings that UAs shall place on the end of lines. The three valid values are butt, round, and square. The butt value means that the end of each line is a flat edge perpendicular to the direction of the line. The round value means that a semi-circle with the diameter equal to the width of the line is then added on to the end of the line. The square value means that at the end of each line is a rectangle with the length of the line width and the width of half the line width, placed flat against the edge perpendicular to the direction of the line. On setting, any other value than the literal strings butt, round, and square are ignored and leave the value unchanged.

When the context is created, the lineCap attribute initially has the value butt.

The lineJoin attribute defines the type of corners that that UAs shall place where two lines meet. The three valid values are round, bevel, and miter.

On setting, any other value than the literal strings round, bevel and miter are ignored and leave the value unchanged.

When the context is created, the lineJoin attribute initially has the value miter.

The round value means that a filled arc connecting the corners on the outside of the join, with the diameter equal to the line width, and the origin at the point where the inside edges of the lines touch, is rendered at the join. The bevel value means that a filled triangle connecting those two corners with a straight line, the third point of the triangle being the point where the lines touch on the inside of the join, is rendered at the join. The miter value means that a filled four- or five-sided polygon is placed at the join, with two of the lines being the perpendicular edges of the joining lines, and the other two being continuations of the outside edges of the two joining lines, as long as required to intersect without going over the miter limit.

The miter length is the distance from the point where the lines touch on the inside of the join to the intersection of the line edges on the outside of the join. The miter limit is the maximum allowed ratio of the miter length to the line width. If the miter limit would be exceeded, then a fifth line is added to the polygon, connecting the two outside lines, such that the distance from the inside point of the join to the point in the middle of this fifth line is the maximum allowed value for the miter length.

The miter limit ratio can be explicitly set using the miterLimit attribute. On setting, zero and negative values are ignored, and leave the value unchanged.

When the context is created, the miterLimit attribute initially has the value 10.0.

9.1.1.6. Shadows

All drawing operations are affected by the four global shadow attributes. Shadows form part of the source image during composition.

The shadowColor attribute sets the colour of the shadow.

When the context is created, the shadowColor attribute initially is fully-transparent black.

The shadowOffsetX and shadowOffsetY attributes specify the distance that the shadow should be offset in the positive horizontal and positive vertical distance respectively. Their values are in coordinate space units.

When the context is created, the shadow offset attributes initially have the value 0.

The shadowBlur attribute specifies the number of coordinate space units that the blurring should cover. On setting, negative numbers are ignored and leave the attribute unmodified.

When the context is created, the shadowBlur attribute initially has the value 0.

Support for shadows is optional.

9.1.1.7. Shapes

There are three methods that immediately draw rectangles to the bitmap. They each take four arguments; the first two give the x and y coordinates of the top left of the rectangle, and the second two give the width and height of the rectangle, respectively.

Shapes are painted without affecting the current path, and are subject to transformations, shadow effects, global alpha, clipping paths, and global composition operators.

Negative values for width and height must cause the implementation to raise an INDEX_SIZE_ERR exception.

The clearRect() method clears the pixels in the specified rectangle to a fully transparent black, erasing any previous image.

The fillRect() method paints the specified rectangular area using the fillStyle.

The strokeRect() method draws a rectangular outline of the specified size using the strokeStyle, lineWidth, lineJoin, and (if appropriate) miterLimit attributes.

9.1.1.8. Paths

The context always has a current path. There is only one current path, it is not part of the drawing state.

A path has a list of subpaths and a current position. Each subpath consists of a list of points, some of which may be connected by straight and curved lines, and a flag indicating whether the subpath is closed or not.

The beginPath() method resets the list of subpaths to an empty list, and calls moveTo() with the point (0,0). When the context is created, a call to beginPath() is implied.

The moveTo(x, y) method sets the current position to the given coordinate and creates a new subpath with that point as its first (and only) point. If there was a previous subpath, and it consists of just one point, then that subpath is removed from the path.

The closePath() method adds a straight line from the current position to the first point in the last subpath and marks the subpath as closed, if the last subpath isn't closed, and if it has more than one point in its list of points. If the last subpath is not open or has only one point, it does nothing.

The lineTo(x, y) method adds the given coordinate (x, y) to the list of points of the subpath, and connects the current position to that point with a straight line. It then sets the current position to the given coordinate (x, y).

The quadraticCurveTo(cpx, cpy, x, y) method adds the given coordinate (x, y) to the list of points of the subpath, and connects the current position to that point with a quadratic curve with control point (cpx, cpy). It then sets the current position to the given coordinate (x, y).

The bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) method adds the given coordinate (x, y) to the list of points of the subpath, and connects the two points with a bezier curve with control points (cp1x, cp1y) and (cp2x, cp2y). It then sets the current position to the given coordinate (x, y).

The arcTo(x1, y1, x2, y2, radius) method adds an arc to the current path. The arc is given by the circle that has one point tangent to the line from the current position to point (x1, y1), one point tangent to the line from from the point (x1, y1) to the point (x2, y2), and that has radius radius. The points at which this circle touches these two lines are called the start and end tangent points respectively.

If the point (x2, y2) is on the line from the current position to point (x1, y1) then this method does nothing. Otherwise, the arc is the shortest path along the circle's circumference between those two points. If the first tangent point is not equal to the current position then the first tangent point is added to the list of points of the subpath and the current position is joined to that point by a straight line. Then, the second tangent point is added to the list of points and the two tangent points are joined by the arc described above. Finally, the current position is set to the second tangent point.

Negative or zero values for radius must cause the implementation to raise an INDEX_SIZE_ERR exception.

The arc(x, y, radius, startAngle, endAngle, clockwise) method adds an arc to the current path. The arc is given by the circle that has its origin at (x, y) and that has radius radius. The points at startAngle and endAngle along the circle, measured in radians anti-clockwise from the positive x-axis, are the start and end points. The arc is the path along the circumference of the circle from the start point to the end point going clockwise if the clockwise argument is true, and anti-clockwise otherwise.

The start point is added to the list of points of the subpath and the current position is joined to that point by a straight line. Then, the end point is added to the list of points and these last two points are joined by the arc described above. Finally, the current position is set to the end point.

Negative or zero values for radius must cause the implementation to raise an INDEX_SIZE_ERR exception.

The rect(x, y, w, h) method creates a new subpath containing just the rectangle with top left coordinate (x, y), width w and height h, and marks it as closed. It then calls moveTo with the point (0,0).

Negative values for w and h must cause the implementation to raise an INDEX_SIZE_ERR exception.

The fill() method fills each subpath of the current path in turn, using fillStyle, and using the non-zero winding number rule. Open subpaths are implicitly closed when being filled (without affecting the actual subpaths).

The stroke() method strokes each subpath of the current path in turn, using the strokeStyle, lineWidth, lineJoin, and (if appropriate) miterLimit attributes.

Paths, when filled or stroked, are painted without affecting the current path, and are subject to transformations, shadow effects, global alpha, clipping paths, and global composition operators.

The clip() method creates a new clipping path by calculating the intersection of the current clipping path and the area described by the current path, using the non-zero winding number rule. Open subpaths are implicitly closed thout affecting the actual subpaths).

When the context is created, the initial clipping path is the rectangle with the top left corner at (0,0) and the width and height of the coordinate space.

9.1.1.9. Images

To draw images onto the canvas, the drawImage method may be used.

This method is overloaded with three variants: drawImage(image, dx, dy), drawImage(image, dx, dy, dw, dh), and drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh). If not specified, the dw and dh arguments default to the values of sw and sh, interpreted such that one CSS pixel in the image is treated as one unit in the canvas coordinate space. If the sx, sy, sw, and sh arguments are omitted, they default to 0, 0, the image's intrinsic width in image pixels, and the image's intrinsic height in image pixels, respectively.

The image argument must be an instance of an HTMLImageElement. If the image is of the wrong type, the implementation must raise a TYPE_MISMATCH_ERR exception. If one of the sy, sw, sw, and sh arguments is outside the size of the image, or if one of the dw and dh arguments is negative, the implementation must raise an INDEX_SIZE_ERR exception.

When drawImage is invoked, the specified region of the image specified by the source rectangle (sx, sy, sw, sh) is painted on the regison of the canvas specified by the destination rectangle (dx, dy, dw, dh).

Images are painted without affecting the current path, and are subject to transformations, shadow effects, global alpha, clipping paths, and global composition operators.

All canvases implement HTMLImageElement, so canvas elements can be passed to the drawImage methods.

9.1.1.10. Drawing model

When a shape or image is painted, user agents shall follow these steps, in the order given (or act as if they do):

  1. The coordinates are transformed by the current transformation matrix.
  2. The shape or image is rendered, creating image A.
  3. The shadow is rendered from image A, creating image B.
  4. Image A is composited over image B creating the source image.
  5. The source image has its alpha adjusted by globalAlpha.
  6. Within the clip region, the source image is composited over the current canvas bitmap using the composition operator.

9.2. Sound

The Audio interface allows scripts to play sound clips.

There is no markup element that corresponds to Audio objects, they are only accessible from script.

User agents should allow users to dynamically enable and disable sound output, but doing so must not affect how Audio objects act in any way other than whether sounds are physically played back or not. For instance, sound files must still be downloaded, load events must still fire, and if two identical clips are started with a two second interval then when the sound is reenabled they must still be two seconds out of sync.

When multiple sounds are played simultaneously, the user agent must mix the sounds together.

interface Audio {
           attribute EventListener onload;
  void play();
  void loop();
  void loop(in unsigned long repeatCount);
  void stop();
}

Audio objects must also implement the EventTarget interface. [DOM3EVENTS]

In ECMAScript, an instance of Audio can be created using the Audio(uri) constructor:

var a = new Audio("test.wav");

The Audio() constructor takes a single argument, a URI (or IRI), which is resolved using the script context's window.location.href value as the base, and which returns an Audio object that will, at the completion of the current script, start loading that URI.

Once the URI is loaded, a load event must be fired on the Audio object.

Audio objects have a current position and a repeat count. Both are initially zero.

The Audio interface has the following members:

onload
An event listener that is invoked along with any other appropriate event listeners that are registered on this object when a load event is fired on it.
play()
Begins playing the sound at the current position, setting the repeat count to 1.
loop()
Begins playing the sound at the current position, setting the repeat count to infinity.
loop(repeatCount)
Begins playing the sound at the current position, setting the repeat count to repeatCount.
stop()
Stops playing the clip and resets the current position and repeat count to zero.

When playback of the sound reaches the end of the available data, its current position is reset to the start of the clip, and the repeat count is decreased by one (unless it is infinite). If the repeat count is greater than zero, then the sound is played again.

10. Communication

10.1. Server-sent DOM events

This section describes a mechanism for allowing servers to dispatch DOM events into documents that expect it.

10.1.1. The event-source element

To specify an event source in an HTML document authors use a new (empty) element event-source, with an attribute src="" that takes a URI (or IRI) to open as a stream and, if the data found at that URI is of the appropriate type, treat as an event source.

The event-source element may also have an onevent="" attribute. If present, the attribute must be treated as script representing an event handler registered as non-capture listener of events with name event and the namespace uuid:755e2d2d-a836-4539-83f4-16b51156341f or null, that are targetted at or bubble through the element.

UAs must also support all the common attributes on the event-source element.

10.1.2. The RemoteEventTarget interface

Any object that implements the EventTarget interface shall also implement the RemoteEventTarget interface.

interface RemoteEventTarget {
  void addEventSource(in DOMString src);
  void removeEventSource(in DOMString src);
};

The addEventSource(src) method shall register the URI (or IRI) specified in src as an event source on the object. The removeEventSource(src) method shall remove the URI (or IRI) specified in src from the list of event sources for that object. If a single URI is added multiple times, each instance must be handled individually. Removing a URI must only remove one instance of that URI. If the specified URI cannot be added or removed, the method must return without doing anything or raising an exception.

10.1.3. Processing model

When an event-source element in a document has a src attribute set, the UA should fetch the resource indicated by the attribute's value.

Similarly, when the addEventSource() method is invoked on an object, the UA should, at the completion of the script's current execution, fetch the resource identified by the method's argument (unless the removeEventSource() was called removing the URI from the list first).

When an event-source element is removed from the document, or when an event source is removed from the list of event sources for an object using the removeEventSource() method, the relevant connection must be closed (and not reopened unless the element is returned to the document or the addEventSource() method is called with the same URI again).

Should event-source elements be allowed to point to any remote server, or only origin hosts?

Since connections established to remote servers for such resources are expected to be long-lived, UAs should ensure that appropriate buffering is used. In particular, while line buffering may be safe if lines are defined to end with a single U+000A character, block buffering or line buffering with different expected line endings can cause delays in event dispatch.

In general, the semantics of the transport protocol specified by the "src" attribute must be followed. Clients should re-open event-source connections that get closed after a short interval (such as 5 seconds), unless they were closed due to problems that aren't expected to be resolved, as described in this section.

DNS errors must be considered fatal, and cause the user agent to not open any connection for the event-source.

HTTP 200 OK responses that have a Content-Type other than application/x-dom-event-stream must be ignored and must prevent the user agent from reopening the connection for that event-source. HTTP 200 OK responses with the right MIME type, however, should, when closed, be reopened after a small delay.

Resource with the type application/x-dom-event-stream must be processed line by line as described below.

HTTP 201 Created, 202 Accepted, 203 Non-Authoritative Information, and 206 Partial Content responses must be treated like HTTP 200 OK responses for the purposes of reopening event-source connections. They are, however, likely to indicate an error has occurred somewhere and may cause the user agent to emit a warning.

HTTP 204 No Content, and 205 Reset Content responses must be treated as if they were 200 OK responses with the right MIME type but no content, and should therefore cause the user agent to reopen the connection after a short delay.

HTTP 300 Multiple Choices responses should be handled automatically if possible (treating the responses as if they were 302 Moved Permanently responses pointing to the appropriate resource), and otherwise must be treated as HTTP 404 responses.

HTTP 301 Moved Permanently responses must cause the user agent to use the server specified URI instead of the one specified in the event-source's "src" attribute for future connections.

HTTP 302 Found, 303 See Other, and 307 Temporary Redirect responses must cause the user agent to use the server specified URI instead of the one specified in the event-source's "src" attribute for the next connection, but if the user agent needs to reopen the connection at a later point, it must once again start from the "src" attribute (or the last URI given by a 301 Moved Permanently response in complicated cases where such responses are chained).

HTTP 304 Not Modified responses should be handled like HTTP 200 OK responses, with the content coming from the user agent cache. A new connection attempt should then be made after a short wait.

HTTP 305 Use Proxy, HTTP 401 Unauthorized, and 407 Proxy Authentication Required should be treated transparently as for any other subresource.

HTTP 400 Bad Request, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 406 Not Acceptable, 408 Request Timeout, 409 Conflict, 410 Gone, 411 Length Required, 412 Precondition Failed, 413 Request Entity Too Large, 414 Request-URI Too Long, 415 Unsupported Media Type, 416 Requested Range Not Satisfiable, 417 Expectation Failed, 500 Internal Server Error, 501 Not Implemented, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout, and 505 HTTP Version Not Supported responses, and any other HTTP response code not listed here, should cause the user agent to stop trying to process this event-source element.

For non-HTTP protocols, UAs should act in equivalent ways.

10.1.4. The event stream format

The event stream MIME type is application/x-dom-event-stream.

The event stream must always be encoded as UTF-8. Line must always be terminated by a single U+000A line feed character.

The event stream format is (in pseudo-BNF):

<stream>  ::= <event>*
<event>   ::= [ <comment> | <command> | <field> ]* <newline>

<comment> ::= ';' <data> <newline>
<special> ::= ':' <data> <newline>
<field>   ::= <name> [ ':' <space>? <data> ]? <newline>

<name>    ::= one or more UNICODE characters other than ':', ';', and U+000A
<data>    ::= zero or more UNICODE characters other than U+000A
<space>   ::= a single U+0020 character (' ')
<newline> ::= a single U+000A character

Bytes that are not valid UTF-8 sequences must be interpreted as the U+FFFD REPLACEMENT CHARACTER.

The stream is parsed by reading everything line by line, in blocks separated by blank lines (blank lines are those consisting of just a single lone line feed character). Comment lines (those starting with the character ';') and command lines (those starting with the character ':') are ignored. Command lines are reserved for future use and should not be used.

For each non-blank, non-comment line, the field name is first taken. This is everything on the line up to but not including the first colon (':') or the line feed, whichever comes first. Then, if there was a colon, the data for that line is taken. This is everything after the colon, ignoring a single space after the colon if there is one, up to the end of the line. If there was no colon the data is the empty string.

Examples:

Field name: Field data
This is a blank field
1. These two lines: have the same data
2. These two lines:have the same data
1. But these two lines:  do not
2. But these two lines: do not

If a field name occurs multiple times, the data values for those lines are concatenated with a newline between them.

For example, the following:

Test: Line 1
Foo:  Bar
Test: Line 2

...is treated as having two fields, one called Test with the value Line 1\nLine 2 (where \n represents a newline), and one called Foo with the value Bar.

(Since any random stream of characters matches the above format, there is no need to define any error handling.)

10.1.5. Event stream interpretation

Once the fields have been parsed, they are interpreted as follows (these are case sensitive exact comparisons):

Once a blank line is reached, an event of the appropriate type is synthesized and dispatched to the appropriate node as described by the fields above. No event is dispatched until a blank line has been received.

If the Event field was omitted, then no event is synthesised and the data is ignored.

The following stream contains four blocks yet synthesises no events, since none of the blocks have a field called Event. (The first block has just a comment, the second block has two fields with names "load" and "Target" respectively, the third block is empty, and the fourth block has two comments.)

; test

load
Target: #image1


; if any real events follow this block, they will not be affected by
; the "Target" and "load" fields above.

10.1.6. The RemoteEvent interface

The RemoteEvent interface is defined as follows:

interface RemoteEvent : Event {
  readonly attribute DOMString       data;
  void               initRemoteEvent(in DOMString typeArg,
                                     in boolean canBubbleArg,
                                     in boolean cancelableArg,
                                     in DOMString dataArg);
  void               initRemoteEventNS(in DOMString namespaceURI,
                                       in DOMString typeArg,
                                       in boolean canBubbleArg,
                                       in boolean cancelableArg,
                                       in DOMString dataArg);
};

Events that use the RemoteEvent interface never have any default action associated with them.

10.1.7. Example

The following event description, once followed by a blank line:

Event: stock change
data: YHOO
data: -2
data: 10

...would cause an event stock change with the interface RemoteEvent to be dispatched on the event-source element, which would then bubble up the DOM, and whose data attribute would contain the string YHOO\n-2\n10 (where \n again represents a newline).

This could be used as follows:

<event-source src="http://stocks.example.com/ticker.php" id="stock">
<script type="text/javascript">
document.getElementById('stock').addEventListener('stock change',
  function () {
    var data = event.data.split('\n');
    updateStocks(data[0], data[1], data[2]);
  }, false);
</script>

...where updateStocks is a function defined as:

function updateStocks(symbol, delta, value) { ... }

...or some such.

10.2. Scripted HTTP: XMLHttpRequest

To allow scripts to programmatically connect back to their originating server via HTTP, the following interface may be used.

interface XMLHttpRequest {
           attribute EventListener           onreadystatechange;
  readonly attribute int                     readyState;
  void open(in DOMString method, in DOMString uri);
  void open(in DOMString method, in DOMString uri, in boolean async);
  void open(in DOMString method, in DOMString uri, in boolean async, in DOMString user);
  void open(in DOMString method, in DOMString uri, in boolean async, in DOMString user, in DOMString password);
  void setRequestHeader(in DOMString header, in DOMString value);
  void send();
  void send(in DOMString body);
  void send(in Document body);
  void abort();
  DOMString getAllResponseHeaders();
  DOMString getResponseHeader(in DOMString header);
  readonly attribute DOMString               responseText;
  readonly attribute Document                responseXML
  readonly attribute int                     status;
  readonly attribute DOMString               statusText;
};

XMLHttpRequest objects must also implement the EventTarget interface. [DOM3EVENTS]

In ECMAScript, an instance of XMLHttpRequest can be created using the XMLHttpRequest() constructor:

var r = new XMLHttpRequest();

The XMLHttpRequest interface has the following members:

onreadystatechange
An event listener that is invoked along with any other appropriate event listeners that are registered on this object when a readystatechange event is fired on it.
readyState
The state of the object. The values have the following meanings:
0 Uninitialised
The initial value.
1 Open
The open() method has been successfully called.
2 Sent
The send() method has been successfully called, but no data has yet been received.
3 Receiving
Data is being received, but the data transfer is not yet complete.
4 Loaded
The data transfer has been completed.
A readystatechange event shall immediately be dispatched at the object whenever the readyState attribute changes value. The readystatechange event must never be dispatched by the UA if the readyState attribute did not change. The readystatechange event has no default action.
open(method, uri, [async, [user, [password]]])
Initialises the object by remembering the method, uri, async (defaulting to true if omitted), user (defaulting to null if omitted), and password (defaulting to null if omitted) arguments, setting the readyState attribute to 1 (Open), resetting the responseText, responseXML, status, and statusText attributes to their initial values, and resetting the list of request headers.

The uri argument is resolved to an absolute URI using the script context's window.location.href value as the base.

Same-origin security restrictions should apply.

If the URI given to this method contains a username and a password (the latter potentially being the empty string), then these must be used if the user and password arguments are omitted. If the arguments are not omitted, they take precedence, even if they are null.

setRequestHeader(header, value)
If the readyState attribute has a value other than 1 (Open), raises an exception. Otherwise, the request header header is set to value. If the request header header had already been set, then the new value is concatenated to the existing value after a comma and a space.

The following script:

var r = new XMLHttpRequest;
r.open('get', 'demo.cgi');
r.setRequestHeader('X-Test', 'one');
r.setRequestHeader('X-Test', 'two');
r.send(null);

...would result in the following header being sent:

...
X-Test: one, two
...

The list of request headers must be reset when the open() method is called.

User agents must not set any headers other than the headers set by the author using this method, with the following exceptions:

In particular, UAs must not automatically set the Cache-Control or Pragma headers to defeat caching. [HTTP]

send([data])
If the readyState attribute has a value other than 1 (Open), raises an exception. Otherwise, sets the readyState attribute to 2 (Sent) and sends a request to uri using method method, authenticating using user and password as appropriate. If the async flag is set to false, then the method does not return until the request has completed. Otherwise, it returns immediately. (See: open().)

If the method is post or put, then the data passed to the send() method is used for the entity body. If data is a string, the data is encoded as UTF-8 for transmission. If the data is a Document, then the document is serialised using the encoding given by data.xmlEncoding, if specified, or UTF-8 otherwise. [DOM3CORE]

If the response is an HTTP redirect, then it should be transparently followed (unless it violates security or infinite loop precautions). Any other error (including a 401) must cause the object to use that error page as the response.

Once the final HTTP status line has been received, the readyState attribute should be set to to 3 (Receiving). When the request has completed loading, the readyState attribute should be set to 4 (Loaded).

abort
Cancels any network activity for which the object is responsible and returns readyState to 0 (Uninitialised).
getAllResponseHeaders()
If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), returns null. Otherwise, returns the HTTP headers that have been received so far for the last request sent, as a single string, with each header line separated by a CR (U+000D) LF (U+000A) pair. The status line is not included.

The following script:

var r = new XMLHttpRequest;
r.open('get', 'test.txt', false);
r.send();
alert(r.getAllResponseHeaders());

...should display a dialog with text similar to the following:

Date: Sun, 24 Oct 2004 04:58:38 GMT
Server: Apache/1.3.31 (Unix)
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8
getResponseHeader(header)
If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), returns an empty string. Otherwise, returns the value of the given HTTP header in the data received so far for the last request sent, as a single string. If more than one header of the given name was received, then the values should be concatenated, separated from each other by a comma and a space. If no headers of that name were received, then returns the empty string. Header names must be compared case-insensitively to the method argument (header).
responseText
If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), returns an empty string. Otherwise, returns the body of the data received so far, interpreted using the character encoding specified in the response, or UTF-8 if no character encoding was specified. Invalid bytes must be converted to U+FFFD.
responseXML
If the readyState attribute has a value other than 4 (Loaded), returns null. Otherwise, if the Content-Type header is either text/xml, application/xml, or ends in +xml, returns an object that implements the Document interface representing the parsed document. If the document was not an XML document, or if the document could not be parsed (due to an XML well-formedness error or unsupported character encoding, for instance), returns null.
status
If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), raises an exception. Otherwise, returns the HTTP status code (typically 200 for a successful connection).
statusText
If the readyState attribute has a value other than 3 (Receiving) or 4 (Loaded), raises an exception. Otherwise, returns the HTTP status text sent by the server after the status code.

If an exception is raised due to an attribute or method being used when readyState has an inappropriate value, it should be a INVALID_STATE_ERR DOM Exception.

HTTP requests sent from multiple different XMLHttpRequest objects in succession should be pipelined into shared HTTP connections.

10.3. Network connections

This section needs much more work before being ready for review. At the moment it mostly consists of a place for ideas to be described.

To enable Web applications to communicate with each other in local area networks, and to maintain bidirectional communications with their originating server, this specification introduces the Connection interface.

This interface does not allow for raw access to the underlying network. For example, this interface could not be used to implement an IRC client.

interface Connection {
  readonly attribute DOMString network;
  readonly attribute DOMString peer;
           attribute EventListener onopen;
           attribute ConnectionReadEventListener onread;
           attribute EventListener onclose;
  readonly attribute int readyState;
  void send(in DOMString data);
  void disconnect();
};

interface ConnectionReadEvent : Event {
  readonly attribute DOMString data;
  readonly attribute DOMString source;
  void               initUIEvent(in DOMString typeArg, 
                                 in boolean canBubbleArg, 
                                 in boolean cancelableArg, 
                                 in DOMString dataArg);
  void               initUIEventNS(in DOMString namespaceURI, 
                                   in DOMString typeArg, 
                                   in boolean canBubbleArg, 
                                   in boolean cancelableArg, 
                                   in DOMString dataArg);
};

Connection objects must also implement the EventTarget interface. [DOM3EVENTS]

In ECMAScript, an instance of Connection can be created using one of the connection constructors:

TCPConnection(subdomain, port)

Establishes a TCP connection to the specified subdomain using the specified port. If the subdomain is null or the empty string, the connection shall be established to the script context's origin host (window.location.host). Otherwise, the subdomain string is prepended to the window.location.host string with a dot separating the two strings, and if that is a valid host name, the connection shall be established to that host. If the window.location.host is not a valid host, or if prepending the subdomain does not yield an valid host, then a security exception should be thrown.

If the port is not equal to 80 or greater than 1024, raises a security exception. Otherwise, the given port shall be used to establish a connection.

Returns a Connection object with its network attribute set to host used and its peer attribute set to "host:port".

LocalBroadcastConnection(topic)

Prompts the user to confirm that a connection should be made. Such a prompt could look like this:

|:: New Connection :::::::::::::::::::::::::::::::::::::::::|
|                                                           |
|  Would you like to open a connection called "Chess" for   |
|  this Web site?:                                          |
|                                                           |
|    example.org                                            |
|                                                           |
|  Select connection to use: [ Bluetooth      | v ]         |
|                                                           |
|                        (( Open connection ))  ( Cancel )  |
|___________________________________________________________|

Returns null if the prompt was cancelled. Otherwise, returns a Connection object with its network attribute set to topic and its peer attribute set to null, and begins broadcasting on the relevant network. (See: broadcast formats.)

LocalPeerConnection(topic)

Prompts the user to select a connection to make, which could look like this:

|:: New Connection :::::::::::::::::::::::::::::::::::::::::|
|                                                           |
|  Select the peer to connect to:                           |
|                                                           |
|    JohnSmith_Series60   via Bluetooth      (( Connect ))  |
|    Patrick's Phone      via Bluetooth       ( Connect )   |
|    John Smith           via UDP             ( Connect )   |
|                                                           |
|                                               ( Cancel )  |
|___________________________________________________________|

While the prompt is displayed, the UA should broadcast on all supported networks, as described below.

Returns null if the prompt was cancelled. Otherwise, returns a Connection object with its network attribute set to topic and its peer attribute set to a string uniquely identifying the selected peer, and opens a connection to that peer. (See: peer connection formats.)

The following script creates a connection to a local party line:

var a = new LocalBroadcastConnection("Party Line");
a.onread = function(s, f) { alert(f + ' wrote ' + s); }
a.send('hello');

...

Events: One event when the connection is first established, one event for when data is received, one event for when the connection is closed for good, one event for when the connection is cut temporarily, one event for when the connecton is restored.

When data is received for a connection, a read event must be fired on the Connection object, using the ConnectionReadEvent interface for the event. The event has no default action.

Data that is received during script execution (e.g. between the connection object being created — and thus the connection being established — and the current script completing, or during the execution of a read event handler) must be buffered, and read events queued up to be fired after the script has completed.

The data attribute of the event object contains the string representing the data received from the network.

For connections established using TCPConnection and LocalPeerConnection, the source attribute of the event is equal to the peer attribute of the connection object. For LocalBroadcastConnection connections, the source attribute of the event contains the string uniquely identifying the source of the message.

The onread attribute takes a reference to an object implementing the ConnectionReadEventListener interface. In ECMAScript, such an interface is implemented by any function that takes one or two arguments.

Whenever a read event is invoked on a Connection object, if the onread attribute is not null, then it is invoked along with any other appropriate event listeners registered on the object, except that instead of passing the function the event object, the first argument contains the event's data, and the second, if any, contains the event's source.

...

10.3.1. TCP connections

All TCP connections should have a handshake to ensure the server is expecting a TCPConnection. TCP connections should attempt to automatically re-connect when they get disconnected. All text is sent as UTF-8.

10.3.2. Broadcast formats

...

10.3.3. Peer connection formats

...

10.3.4. Announcing peer connections

...

10.4. Cross-document messaging

Web browsers, for security and privacy reasons, prevent documents in different domains from affecting each other; that is, cross-site scripting is disallowed.

While this is an important security feature, it prevents pages from different domains from communicating even when those pages are not hostile. This section introduces a messaging system that allows documents to communicate with each other regardless of their source domain, in a way designed to not enable cross-site scripting attacks.

10.4.1. Definitions

Any Document object that supports this cross-document messaging API must implement the DocumentMessaging interface.

interface DocumentMessaging {
  void postMessage(in DOMString message);
};

Such Document objects must also implement the EventTarget interface. [DOM3EVENTS]

The postMessage() method causes an event to be dispatched (as defined below). This event uses the following interface:

interface MessageEvent : Event {
  readonly attribute DOMString data;
  readonly attribute DOMString domain;
  readonly attribute DOMString uri;
  readonly attribute Document source;
  void initMessageEvent(in DOMString typeArg,
                        in boolean canBubbleArg,
                        in boolean cancelableArg,
                        in DOMString dataArg,
                        in DOMString domainArg,
                        in DOMString uriArg,
                        in DOMString documentArg); // raises exception
  void initMessageEventNS(in DOMString namespaceURI,
                          in DOMString typeArg,
                          in boolean canBubbleArg,
                          in boolean cancelableArg,
                          in DOMString dataArg,
                          in DOMString domainArg,
                          in DOMString uriArg,
                          in DOMString documentArg); // raises exception
};

10.4.2. Processing model

When a script invokes the postMessage() method on a document, the user agent must create an event that uses the MessageEvent interface, with the event name message in the uuid:7f37e11a-3a5c-4f3d-a82e-83b611439f37 namespace, which bubbles, is cancelable, and has no default action. The data attribute must be set to the value passed as the argument to the postMessage() method, the domain attribute must be set to the domain of the document that the script that invoked the methods is associated with, the uri attribute must be set to the URI of that document, and the source attribute must be set to the object representing that document.

Authors should check the domain attribute to ensure that messages are only accepted from domains that they expect to receive messages from. Otherwise, bugs in the author's message handling code could be exploited by hostile sites.

For example, if document A contains an object element that contains document B, and script in document A calls postMessage() on document B, then a message event will be fired on that element, marked as originating from document A. The script in document A might look like:

var o = document.getElementsByTagName('object')[0];
o.contentDocument.postMessage('Hello world');

To register an event handler for incoming events, the script would use addEventListener() (or similar mechanisms). For example, the script in document B might look like:

document.addEventListener('message', receiver, false);
function receiver(e) {
  if (e.domain == 'example.com') {
    if (e.data == 'Hello world') {
      e.source.postMessage('Hello');
    } else {
      alert(e.data);
    }
  }
}

This script first checks the domain is the expected domain, and then looks at the message, which it either displays to the user, or responds to by sending a message back to the document which sent the message in the first place.

Implementors are urged to take extra care in the implementation of this feature. It allows authors to transmit information from one domain to another domain, which is normally disallowed for security reasons. It also requires that UAs be careful to allow access to certain properties but not others.

The initMessageEvent() and initMessageEventNS() methods must raise a security exception when called from untrusted script. When called from other contexts, they initialise the event object as with other event interfaces.

11. Focus

When an element is focused, key events are targetted at that element instead of at the root element.

11.1. The tabindex Attribute

This section on the tabindex attribute needs to be checked for backwards-compatibility.

The tabindex attribute defined in HTML4 is extended to apply to all HTML elements by defining it as a common attribute.

The tabindex attribute specifies the relative order of elements for the purposes of sequential focus navigation. The name "tab index" comes from the common use of the "tab" key to navigate through the focusable elements. The term "tabbing" refers to moving forward through the focusable elements.

The tabindex attribute can take any integer (an optional hyphen-minus (U+002D) representing negativity followed by one or more digits in the range 0-9 interpreted as base ten).

A positive integer (including zero) specifies the index of the element in the current scope's tab order. Elements with the same index are sorted in document order for the purposes of tabbing.

A negative integer specifies that the element should be removed from the tab order. If the element does normally take focus, it may still be focused using other means (e.g. it could be focussed by a click).

Other values are ignored, as if the attribute was absent. Certain elements may default absent tabindex attributes to zero, at the user agent's discretion. (In other words, some elements are focusable by default, and they are assumed to have tab index 0. Text fields will typically be in the tab order by default, for instance.)

When an element that does not normally take focus has the tabindex attribute specified with a positive value, then it is added to the tab order and is made focusable. When focused, the element matches the CSS :focus pseudo-class and key events are dispatched on that element when appropriate, just like focusing a link.

Since all HTML elements can thus be focused and unfocusd, the onfocus and onblur attributes shall also apply to all HTML elements.

11.2. The ElementFocus interface

The ElementFocus interface contains methods for moving focus to and from an element. It can be obtained from objects that implement the Elemnet interface using binding-specific casting methods.

interface ElementFocus {
           attribute long                    tabIndex;
  void focus();
  void blur();
};

The tabIndex DOM attribute reflects the value of the related content attribute. If the attribute is not present (or has an invalid value) then the DOM attribute should return the UA's default value for that element, typically either 0 (for elements in the tab order) or -1 (for elements not in the tab order).

The focus() and blur() methods focus and unfocus the element respectively, if the element is focusable.

11.3. The DocumentFocus interface

The DocumentFocus interface contains methods for moving focus around the document. It can be obtained from objects that implement the Document interface using binding-specific casting methods.

interface DocumentFocus {
  readonly attribute Element                 currentFocus;
  void moveFocusForward();
  void moveFocusBackward();
  void moveFocusUp();
  void moveFocusRight();
  void moveFocusDown();
  void moveFocusLeft();
};

The currentFocus attribute returns the element to which key events will be sent when the document receives key events.

The moveFocusForward method uses the 'nav-index' property and the tabindex attribute to find the next focusable element and focuses it.

The moveFocusBackward method uses the 'nav-index' property and the tabindex attribute to find the previous focusable element and focuses it.

The moveFocusUp method uses the 'nav-up' property and the tabindex attribute to find an appropriate focusable element and focuses it.

In a similar manner, the moveFocusRight, moveFocusDown, and moveFocusLeft methods use the 'nav-right', 'nav-down', and 'nav-left' properties (respectively), and the tabindex attribute, to find an appropriate focusable element and focus it.

The 'nav-index', 'nav-up', 'nav-right', 'nav-down', and 'nav-left' properties are defined in [CSS3UI].

12. Things that you can't do with this specification because they are better handled using other technologies that are further described herein

There are certain features that are not handled by this specification because a client side markup language is not the right level for them. This section covers some of the more common requests.

12.1. Localisation

If you wish to create localised versions of an HTML application, the best solution is to preprocess the files on the server, and then use HTTP content negotation to serve the appropriate language.

References

This section will be written in a future draft.

Acknowledgements

Thanks to Aaron Leventhal, Anne van Kesteren, Asbjørn Ulsberg, Ben Godfrey, Ben Meadowcroft, Bjoern Hoehrmann, Boris Zbarsky, Brad Fults, Brendan Eich, Chriswa, Darin Fisher, David Hyatt, Derek Featherstone, Doron Rosenberg, fantasai, Franck 'Shift' Quélain, Henri Sivonen, Håkon Wium Lie, James Graham, James Perrett, Jan-Klaas Kollhof, Joel Spolsky, Jukka K. Korpela, Kai Hendry, Lachlan Hunt, Laurens Holst, Maciej Stachowiak, Malcolm Rowe, Mark Nottingham, Mark Schenk, Martijn Wargers, Martin Honnen, Matthew Mastracci, Matthew Raymond, Matthew Thomas, Mattias Waldau, Max Romantschuk, Michael A. Nachbaur, Michael 'Ratt' Iannarelli, Mike Shaver, Mikko Rantalainen, Olav Junker Kjær, Shaun Inman, Steven Garrity, Stuart Parmenter, Tantek Çelik, Thomas O'Connor, Vladimir Vukićević, and everyone on the WHATWG mailing list for their useful and substantial comments.

Special thanks to Richard Williamson for creating the first implementation of canvas in Safari, from which the canvas feature was designed.

Special thanks also to the Microsoft employee who first invented the XMLHttpRequest interface.

Thanks also the Microsoft blogging community for some ideas, to the attendees of the W3C Workshop on Web Applications and Compound Documents for inspiration, and to the #mozilla crew, the #opera crew, and the #mrt crew for their ideas and support.