WD-DOM-Level-2-19981228 Document Object Model (DOM) Level 2 Specification Version 1.0 W3C Working Draft 28 December, 1998 This version http://www.w3.org/TR/1998/WD-DOM-Level-2-19981228 http://www.w3.org/TR/1998/WD-DOM-Level-2-19981228/DOM2.ps http://www.w3.org/TR/1998/WD-DOM-Level-2-19981228/DOM2.pdf http://www.w3.org/TR/1998/WD-DOM-Level-2-19981228/DOM2.txt http://www.w3.org/TR/1998/WD-DOM-Level-2-19981228/DOM2.zip Latest version http://www.w3.org/TR/WD-DOM-Level-2 WG Chair Lauren Wood, SoftQuad Software Inc. Editors Vidur Apparao, Netscape Communications Corporation Mike Champion, Arbortext Arnaud Le Hors, W3C Tom Pixley, Netscape Communications Corporation Jonathan Robie, Texcel Research Peter Sharpe, SoftQuad Software Inc. Chris Wilson, Microsoft Lauren Wood, SoftQuad Software Inc. Status of this document This document is the first release of the Document Object Model Level 2. It is guaranteed to change; anyone implementing it should realize that we will not allow ourselves to be restricted by experimental implementations of Level 2 when deciding whether to change the specifications. This is a W3C Working Draft for review by W3C members and other interested parties. It is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by, or the consensus of, either W3C or members of the DOM working group. This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM WG members. Different chapters of the Document Object Model may have different editors. Comments on this document should be sent to the public mailing list www-dom@w3.org. Abstract This specification defines the Document Object Model Level 2, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. The Document Object Model Level 2 builds on the Document Object Model Level 1. Level 2 adds interfaces for a Cascading Style Sheets object model, an event model, and a query interface, amongst others. This first release of the Document Object Model Level 2 does not have all these interfaces. It contains interfaces for the Cascading Style Sheets object model, the Range object model, filters and iterators, and the Events object model. The other interfaces will be added in future versions of this specification. Table of contents * Expanded Table of Contents * Copyright Notice * Chapter 1: Document Object Model CSS * Chapter 2: Document Object Model Events * Chapter 3: Document Object Model Filters and Iterators * Chapter 4: Document Object Model Range * Appendix A: Contributors * Appendix B: Glossary * Appendix C: IDL Definitions * Appendix D: Java Language Binding * Appendix E: ECMA Script Language Binding * References * Index Expanded Table of Contents * Expanded Table of Contents * Copyright Notice * Chapter 1: Document Object Model CSS o 1.1. Overview of the DOM Level 2 CSS Interfaces o 1.2. Generic Style Sheet Interfaces o 1.3. CSS Fundamental Interfaces o 1.4. CSS Extended Interfaces o 1.5. Extensions to Level 1 Interfaces + 1.5.1. Document style sheets + 1.5.2. HTMLElement inline style + 1.5.3. HTMLStyleElement style sheet + 1.5.4. HTMLLinkElement style sheet o 1.6. Unresolved Issues * Chapter 2: Document Object Model Events o 2.1. Overview of the DOM Level 2 Event Model + 2.1.1. Terminology + 2.1.2. Requirements o 2.2. Description of event flow + 2.2.1. Basic event flow + 2.2.2. Event Capture + 2.2.3. Event bubbling + 2.2.4. Interaction between capturing and bubbling + 2.2.5. Event cancellation o 2.3. Event interfaces o 2.4. Event set definitions + 2.4.1. User Interface event types + 2.4.2. Mutation event types + 2.4.3. HTML event types * Chapter 3: Document Object Model Filters and Iterators o 3.1. Overview of the DOM Level 2 Filter and Iterator Interfaces + 3.1.1. Iterators + 3.1.2. Filters o 3.2. Formal Interface Definition o 3.3. NodeIterator o 3.4. Iterator Factory Methods o 3.5. Filters * Chapter 4: Document Object Model Range o 4.1. Introduction + 4.1.1. Motivation + 4.1.2. Basic Assumptions + 4.1.3. Notation o 4.2. Finding a Range's Position o 4.3. Partial and Complete Containment o 4.4. Creating a Range o 4.5. Changing a Range's Position o 4.6. Comparing Range End-Points o 4.7. Deleting Content with a Range o 4.8. Cloning Content o 4.9. Inserting Content o 4.10. Surrounding Content o 4.11. Miscellaneous Members o 4.12. Range behavior under document mutation + 4.12.1. Insertions + 4.12.2. Deletions o 4.13. Formal Description of the Range Interface * Appendix A: Contributors * Appendix B: Glossary * Appendix C: IDL Definitions o C.1. Document Object Model Level 2 CSS o C.2. Document Object Model Level 2 Events o C.3. Document Object Model Level 2 Filters and Iterators o C.4. Document Object Model Level 2 Range * Appendix D: Java Language Binding o D.1. Document Object Model Level 2 CSS o D.2. Document Object Model Level 2 Events o D.3. Document Object Model Level 2 Filters and Iterators o D.4. Document Object Model Level 2 Range * Appendix E: ECMA Script Language Binding o E.1. Document Object Model Level 2 CSS o E.2. Document Object Model Level 2 Events o E.3. Document Object Model Level 2 Filters and Iterators o E.4. Document Object Model Level 2 Range * References * Index Copyright Notice Copyright © 1998 World Wide Web Consortium , (Massachusetts Institute of Technology , Institut National de Recherche en Informatique et en Automatique , Keio University ). All Rights Reserved. Documents on the W3C site are provided by the copyright holders under the following license. By obtaining, using and/or copying this document, or the W3C document from which this statement is linked, you agree that you have read, understood, and will comply with the following terms and conditions: Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use: 1. A link or URI to the original W3C document. 2. The pre-existing copyright notice of the original author, if it doesn't exist, a notice of the form: "Copyright © World Wide Web Consortium , (Massachusetts Institute of Technology , Institut National de Recherche en Informatique et en Automatique , Keio University ). All Rights Reserved." 3. If it exists, the STATUS of the W3C document. When space permits, inclusion of the full text of this NOTICE should be provided. In addition, credit shall be attributed to the copyright holders for any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof. No right to create modifications or derivatives is granted pursuant to this license. THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF. The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders. 1. Document Object Model CSS Editors Vidur Apparao, Netscape Communications Corp. Chris Wilson, Microsoft 1.1. Overview of the DOM Level 2 CSS Interfaces The DOM Level 2 Cascading Style Sheets (CSS ) interfaces are designed with the goal of exposing CSS constructs to object model consumers. Cascading Style Sheets is a declarative syntax for defining presentation rules, properties and ancillary constructs used to format and render Web documents. This document specifies a mechanism to programmatically access and modify the rich style and presentation control provided by CSS (specifically CSS level two ). This augments CSS by providing a mechanism to dynamically control the inclusion and exclusion of individual style sheets, as well as manipulate CSS rules and properties. 1.2. Generic Style Sheet Interfaces This set of interfaces represents the generic notion of style sheets. While the goal of this specification is to represent CSS style sheets, these interfaces may be applied to other types of style sheets. Interface StyleSheet The StyleSheet interface is the abstract base interface for any type of style sheet. It represents a single style sheet associated with a structured document. In HTML, the StyleSheet interface represents either an external style sheet, included via the HTML LINK element, or an inline STYLE element. In XML, this interface represents an external style sheet, included via a style sheet processing instruction . IDL Definition interface StyleSheet { readonly attribute DOMString type; attribute boolean disabled; readonly attribute Node owningNode; readonly attribute StyleSheet parentStyleSheet; readonly attribute DOMString href; readonly attribute DOMString title; readonly attribute DOMString media; }; Attributes type This specifies the style sheet language for this style sheet. The style sheet language is specified as a content type (e.g. "text/css"). The content type is often specified in the owningNode. A list of registered content types can be found at ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/ . Also see the type attribute definition for the LINK element in HTML 4.0, and the type pseudo-attribute for the XML style sheet processing instruction . disabled false if the style sheet is applied to the document. true if it is not. owningNode The node that associates this style sheet with the document. For HTML, this may be the corresponding LINK or STYLE element. For XML, it may be the linking processing instruction. For included style sheets, this attribute has a value of null. parentStyleSheet For style sheet languages that support the concept of style sheet inclusion, this attribute represents the including style sheet, if one exists. If the style sheet is a top-level style sheet, or the style sheet language does not support inclusion, the value of the attribute is null. href If the style sheet is a linked style sheet, the value of its attribute is its location. For inline style sheets, the value of this attribute is null. See the href attribute definition for the LINK element in HTML 4.0, and the href pseudo-attribute for the XML style sheet processing instruction . title The advisory title. The title is often specified in the owningNode. See the title attribute definition for the LINK element in HTML 4.0, and the title pseudo-attribute for the XML style sheet processing instruction . media The intended destination medium for style information. It may be a single media descriptor or a comma-separated list. The media is often specified in the owningNode. See the media attribute definition for the LINK element in HTML 4.0, and the media pseudo-attribute for the XML style sheet processing instruction . Interface StyleSheetCollection The StyleSheetCollection interface provides the abstraction of an ordered collection of style sheets. IDL Definition interface StyleSheetCollection { readonly attribute unsigned long length; StyleSheet item(in unsigned long index); }; Attributes length The length or the size of the list. Methods item Used to retrieve a style sheet by ordinal index. Parameters index Index into the collection Return Value The style sheet at the index position in the StyleSheetCollection, or null if that is not a valid index. This method raises no exceptions. 1.3. CSS Fundamental Interfaces The interfaces within this section are considered fundamental, and must be implemented by all conforming applications of this specification. These interfaces represent CSS style sheets specifically. Interface CSSStyleSheet The CSSStyleSheet interface is a concrete interface used to represent a CSS style sheet i.e. a style sheet whose content type is "text/css". IDL Definition interface CSSStyleSheet : StyleSheet { readonly attribute CSSRuleCollection cssRules; unsigned long insertRule(in DOMString rule, in unsigned long index) raises(DOMException); void deleteRule(in unsigned long index) raises(DOMException); }; Attributes cssRules The collection of all CSS rules contained within the style sheet. This includes both rule sets and at-rules . Methods insertRule Used to insert a new rule into the style sheet. The new rule now becomes part of the cascade. Parameters rule The parsable text representing the rule. For rule sets this contains both the selector and the style declaration. For at-rules, this specifies both the at-identifier and the rule content. index The index within the style sheet's rule collection of the rule before which to insert the specified rule. If the specified index is equal to the length of the style sheet's rule collection, the rule will be added to the end of the style sheet. Return Value The index within the style sheet's rule collection of the newly inserted rule. Exceptions DOMException HIERARCHY_REQUEST_ERR: Raised if the rule cannot be inserted at the specified index e.g. if an @import rule is inserted after a standard rule set or other at-rule. INDEX_SIZE_ERR: Raised if the specified index is not a valid insertion point. SYNTAX_ERR: Raised if the specified rule has a syntax error and is unparsable. deleteRule Used to delete a rule from the style sheet. Parameters index The index within the style sheet's rule collection of the rule to remove. Exceptions DOMException INDEX_SIZE_ERR: Raised if the specified index does not correspond to a rule in the style sheet's rule collection. This method returns nothing. Interface CSSRuleCollection The CSSRuleCollection interface provides the abstraction of an ordered collection of CSS rules. IDL Definition interface CSSRuleCollection { readonly attribute unsigned long length; CSSRule item(in unsigned long index); }; Attributes length The length or the size of the list. Methods item Used to retrieve a CSS rule by ordinal index. The order in this collection represents the order of the rules in the CSS style sheet. Parameters index Index into the collection Return Value The style rule at the index position in the CSSRuleCollection, or null if that is not a valid index. This method raises no exceptions. Interface CSSRule The CSSRule interface is the abstract base interface for any type of CSS statement . This includes both rule sets and at-rules . IDL Definition interface CSSRule { // RuleType const unsigned short UNKNOWN_RULE = 0; const unsigned short STYLE_RULE = 1; const unsigned short IMPORT_RULE = 2; const unsigned short MEDIA_RULE = 3; const unsigned short FONT_FACE_RULE = 4; const unsigned short PAGE_RULE = 5; readonly attribute unsigned short type; attribute DOMString cssText; readonly attribute CSSStyleSheet parentStyleSheet; }; Definition group RuleType An integer indicating which type of rule this is. Defined Constants UNKNOWN_RULE The rule is a CSSUnknownRule. STYLE_RULE The rule is a CSSStyleRule. IMPORT_RULE The rule is a CSSImportRule. MEDIA_RULE The rule is a CSSMediaRule. FONT_FACE_RULE The rule is a CSSFontFaceRule. PAGE_RULE The rule is a CSSPageRule. Attributes type A code defining the type of the rule, as defined above. cssText The parsable textual representation of the rule. parentStyleSheet The style sheet that contains this rule. Interface CSSStyleRule The CSSStyleRule interface represents a single rule set in a CSS style sheet. IDL Definition interface CSSStyleRule : CSSRule { attribute DOMString selectorText; readonly attribute CSSStyleDeclaration style; }; Attributes selectorText The textual representation of the selector for the rule set. The implementation may have stripped out insignificant whitespace while parsing the selector. style The declaration-block of this rule set. Interface CSSMediaRule The CSSMediaRule interface represents a @media rule in a CSS style sheet. A @media rule can be used to delimit style rules for specific media types. IDL Definition interface CSSMediaRule : CSSRule { attribute DOMString mediaTypes; readonly attribute CSSRuleCollection cssRules; unsigned long insertRule(in DOMString rule, in unsigned long index) raises(DOMException); void deleteRule(in unsigned long index); }; Attributes mediaTypes A comma-separate list of media types for this rule. This attribute does not include the "@media" specifier. cssRules A collection of all CSS rules contained within the media block. Methods insertRule Used to insert a new rule into the media block. Parameters rule The parsable text representing the rule. For rule sets this contains both the selector and the style declaration. For at-rules, this specifies both the at-identifier and the rule content. index The index within the media block's rule collection of the rule before which to insert the specified rule. If the specified index is equal to the length of the media blocks's rule collection, the rule will be added to the end of the media block. Return Value The index within the media block's rule collection of the newly inserted rule. Exceptions DOMException HIERARCHY_REQUEST_ERR: Raised if the rule cannot be inserted at the specified index. e.g. if an @import rule is inserted after a standard rule set or other at-rule. INDEX_SIZE_ERR: Raised if the specified index is not a valid insertion point. SYNTAX_ERR: Raised if the specified rule has a syntax error and is unparsable. deleteRule Used to delete a rule from the media block. Parameters index The index within the media block's rule collection of the rule to remove. This method returns nothing. This method raises no exceptions. Interface CSSFontFaceRule The CSSFontFaceRule interface represents a @font-face rule in a CSS style sheet. The @font-face rule is used to hold a set of font descriptions. IDL Definition interface CSSFontFaceRule : CSSRule { readonly attribute CSSStyleDeclaration style; }; Attributes style The declaration-block of this rule. Interface CSSPageRule The CSSPageRule interface represents a @page rule within a CSS style sheet. The @page rule is used to specify the dimensions, orientation, margins, etc. of a page box for paged media. IDL Definition interface CSSPageRule : CSSRule { attribute DOMString selectorText; readonly attribute CSSStyleDeclaration style; }; Attributes selectorText The parsable textual representation of the page selector for the rule. style The declaration-block of this rule. Interface CSSImportRule The CSSImportRule interface represents a @import rule within a CSS style sheet. The @import rule is used to import style rules from other style sheets. IDL Definition interface CSSImportRule : CSSRule { attribute DOMString href; attribute DOMString media; readonly attribute CSSStyleSheet styleSheet; }; Attributes href The location of the style sheet to be imported. The attribute will not contain the "url(...)" specifier around the URI. media A comma-separated list of media types for which this style sheet may be used. styleSheet The style sheet referred to by this rule, if it has been loaded. The value of this attribute is null if the style sheet has not yet been loaded or if it will not be loaded (e.g. if the style sheet is for a media type not supported by the user agent). Interface CSSUnknownRule The CSSUnkownRule interface represents an at-rule not supported by this user agent. IDL Definition interface CSSUnknownRule : CSSRule { }; Interface CSSStyleDeclaration The CSSStyleDeclaration interface represents a single CSS declaration block . This interface may be used to determine the style properties currently set in a block or to set style properties explicitly within the block. IDL Definition interface CSSStyleDeclaration { attribute DOMString cssText; DOMString getPropertyValue(in DOMString propertyName); DOMString getPropertyPriority(in DOMString propertyName); void setProperty(in DOMString propertyName, in DOMString value, in DOMString priority) raises(DOMException); readonly attribute unsigned long length; DOMString item(in unsigned long index); }; Attributes cssText The parsable textual representation of the declaration block (including the surrounding curly braces). Setting this attribute will result in the parsing of the new value and resetting of the properties in the declaration block. Methods getPropertyValue Used the retrieve the value of a CSS property if it has been explicitly set within this declaration block. Parameters propertyName The name of the CSS property. See the CSS property index . Return Value Returns the value of the property if it has been explicitly set for this declaration block. Returns the empty string if the property has not been set or the property name does not correspond to a valid CSS2 property. This method raises no exceptions. getPropertyPriority Used to retrieve the priority of a CSS property (e.g. the "!important" qualifier) if the property has been explicitly set in this declaration block. Parameters propertyName The name of the CSS property. See the CSS property index . Return Value A string representing the priority (e.g. "!important") if one exists. The empty string if none exists. This method raises no exceptions. setProperty Used the set a property value and priority within this declaration block. Parameters propertyName The name of the CSS property. See the CSS property index . value The new value of the property. priority The new priority of the property (e.g. "!important"). Exceptions DOMException SYNTAX_ERR: Raised if the specified value has a syntax error and is unparsable. This method returns nothing. Attributes length The number of properties that have been explicitly set in this declaration block. Methods item Used to retrieve the properties that have been explicitly set in this declaration block. The order of the properties retrieved using this method does not have to be the order in which they were set. This method can be used to iterate over all properties in this declaration block. Parameters index Index of the property name to retrieve. Return Value The name of the property at this ordinal position. The empty string if no property exists at this position. This method raises no exceptions. 1.4. CSS Extended Interfaces The interfaces found within this section are not mandatory. They may be implemented by a DOM implementation as a convenience to the DOM script user. Interface CSS2Properties The CSS2Properties interface represents a convenience mechanism for retrieving and setting properties within a CSSStyleDeclaration. The attributes of this interface correspond to all the properties specified in CSS2 . Getting an attribute of this interface is equivalent to calling the getPropertyValue method of the CSSStyleDeclaration interface. Setting an attribute of this interface is equivalent to calling the setProperty method of the CSSStyleDeclaration interface. A compliant implementation is not required to implement the CSS2Properties interface. IDL Definition interface CSS2Properties { attribute DOMString azimuth; attribute DOMString background; attribute DOMString backgroundAttachment; attribute DOMString backgroundColor; attribute DOMString backgroundImage; attribute DOMString backgroundPosition; attribute DOMString backgroundRepeat; attribute DOMString border; attribute DOMString borderCollapse; attribute DOMString borderColor; attribute DOMString borderSpacing; attribute DOMString borderStyle; attribute DOMString borderTop; attribute DOMString borderRight; attribute DOMString borderBottom; attribute DOMString borderLeft; attribute DOMString borderTopColor; attribute DOMString borderRightColor; attribute DOMString borderBottomColor; attribute DOMString borderLeftColor; attribute DOMString borderTopStyle; attribute DOMString borderRightStyle; attribute DOMString borderBottomStyle; attribute DOMString borderLeftStyle; attribute DOMString borderTopWidth; attribute DOMString borderRightWidth; attribute DOMString borderBottomWidth; attribute DOMString borderLeftWidth; attribute DOMString borderWidth; attribute DOMString bottom; attribute DOMString captionSide; attribute DOMString clear; attribute DOMString clip; attribute DOMString color; attribute DOMString content; attribute DOMString counterIncrement; attribute DOMString counterReset; attribute DOMString cue; attribute DOMString cueAfter; attribute DOMString cueBefore; attribute DOMString cursor; attribute DOMString direction; attribute DOMString display; attribute DOMString elevation; attribute DOMString emptyCells; attribute DOMString cssFloat; attribute DOMString font; attribute DOMString fontFamily; attribute DOMString fontSize; attribute DOMString fontSizeAdjust; attribute DOMString fontStretch; attribute DOMString fontStyle; attribute DOMString fontVariant; attribute DOMString fontWeight; attribute DOMString height; attribute DOMString left; attribute DOMString letterSpacing; attribute DOMString lineHeight; attribute DOMString listStyle; attribute DOMString listStyleImage; attribute DOMString listStylePosition; attribute DOMString listStyleType; attribute DOMString margin; attribute DOMString marginTop; attribute DOMString marginRight; attribute DOMString marginBottom; attribute DOMString marginLeft; attribute DOMString markerOffset; attribute DOMString marks; attribute DOMString maxHeight; attribute DOMString maxWidth; attribute DOMString minHeight; attribute DOMString minWidth; attribute DOMString orphans; attribute DOMString outline; attribute DOMString outlineColor; attribute DOMString outlineStyle; attribute DOMString outlineWidth; attribute DOMString overflow; attribute DOMString padding; attribute DOMString paddingTop; attribute DOMString paddingRight; attribute DOMString paddingBottom; attribute DOMString paddingLeft; attribute DOMString page; attribute DOMString pageBreakAfter; attribute DOMString pageBreakBefore; attribute DOMString pageBreakInside; attribute DOMString pause; attribute DOMString pauseAfter; attribute DOMString pauseBefore; attribute DOMString pitch; attribute DOMString pitchRange; attribute DOMString playDuring; attribute DOMString position; attribute DOMString quotes; attribute DOMString richness; attribute DOMString right; attribute DOMString size; attribute DOMString speak; attribute DOMString speakHeader; attribute DOMString speakNumeral; attribute DOMString speakPunctuation; attribute DOMString speechRate; attribute DOMString stress; attribute DOMString tableLayout; attribute DOMString textAlign; attribute DOMString textDecoration; attribute DOMString textIndent; attribute DOMString textShadow; attribute DOMString textTransform; attribute DOMString top; attribute DOMString unicodeBidi; attribute DOMString verticalAlign; attribute DOMString visibility; attribute DOMString voiceFamily; attribute DOMString volume; attribute DOMString whiteSpace; attribute DOMString widows; attribute DOMString width; attribute DOMString wordSpacing; attribute DOMString zIndex; }; Attributes azimuth See the azimuth property definition in CSS2. background See the background property definition in CSS2. backgroundAttachment See the background-attachment property definition in CSS2. backgroundColor See the background-color property definition in CSS2. backgroundImage See the background-image property definition in CSS2. backgroundPosition See the background-position property definition in CSS2. backgroundRepeat See the background-repeat property definition in CSS2. border See the border property definition in CSS2. borderCollapse See the border-collapse property definition in CSS2. borderColor See the border-color property definition in CSS2. borderSpacing See the border-spacing property definition in CSS2. borderStyle See the border-style property definition in CSS2. borderTop See the border-top property definition in CSS2. borderRight See the border-right property definition in CSS2. borderBottom See the border-bottom property definition in CSS2. borderLeft See the border-left property definition in CSS2. borderTopColor See the border-top-color property definition in CSS2. borderRightColor See the border-right-color property definition in CSS2. borderBottomColor See the border-bottom-color property definition in CSS2. borderLeftColor See the border-left-color property definition in CSS2. borderTopStyle See the border-top-style property definition in CSS2. borderRightStyle See the border-right-style property definition in CSS2. borderBottomStyle See the border-bottom-style property definition in CSS2. borderLeftStyle See the border-left-style property definition in CSS2. borderTopWidth See the border-top-width property definition in CSS2. borderRightWidth See the border-right-width property definition in CSS2. borderBottomWidth See the border-bottom-width property definition in CSS2. borderLeftWidth See the border-left-width property definition in CSS2. borderWidth See the border-width property definition in CSS2. bottom See the bottom property definition in CSS2. captionSide See the caption-side property definition in CSS2. clear See the clear property definition in CSS2. clip See the clip property definition in CSS2. color See the color property definition in CSS2. content See the content property definition in CSS2. counterIncrement See the counter-increment property definition in CSS2. counterReset See the counter-reset property definition in CSS2. cue See the cue property definition in CSS2. cueAfter See the cue-after property definition in CSS2. cueBefore See the cue-before property definition in CSS2. cursor See the cursor property definition in CSS2. direction See the direction property definition in CSS2. display See the display property definition in CSS2. elevation See the elevation property definition in CSS2. emptyCells See the empty-cells property definition in CSS2. cssFloat See the float property definition in CSS2. font See the font property definition in CSS2. fontFamily See the font-family property definition in CSS2. fontSize See the font-size property definition in CSS2. fontSizeAdjust See the font-size-adjust property definition in CSS2. fontStretch See the font-stretch property definition in CSS2. fontStyle See the font-style property definition in CSS2. fontVariant See the font-variant property definition in CSS2. fontWeight See the font-weight property definition in CSS2. height See the height property definition in CSS2. left See the left property definition in CSS2. letterSpacing See the letter-spacing property definition in CSS2. lineHeight See the line-height property definition in CSS2. listStyle See the list-style property definition in CSS2. listStyleImage See the list-style-image property definition in CSS2. listStylePosition See the list-style-position property definition in CSS2. listStyleType See the list-style-type property definition in CSS2. margin See the margin property definition in CSS2. marginTop See the margin-top property definition in CSS2. marginRight See the margin-right property definition in CSS2. marginBottom See the margin-bottom property definition in CSS2. marginLeft See the margin-left property definition in CSS2. markerOffset See the marker-offset property definition in CSS2. marks See the marks property definition in CSS2. maxHeight See the max-height property definition in CSS2. maxWidth See the max-width property definition in CSS2. minHeight See the min-height property definition in CSS2. minWidth See the min-width property definition in CSS2. orphans See the orphans property definition in CSS2. outline See the outline property definition in CSS2. outlineColor See the outline-color property definition in CSS2. outlineStyle See the outline-style property definition in CSS2. outlineWidth See the outline-width property definition in CSS2. overflow See the overflow property definition in CSS2. padding See the padding property definition in CSS2. paddingTop See the padding-top property definition in CSS2. paddingRight See the padding-right property definition in CSS2. paddingBottom See the padding-bottom property definition in CSS2. paddingLeft See the padding-left property definition in CSS2. page See the page property definition in CSS2. pageBreakAfter See the page-break-after property definition in CSS2. pageBreakBefore See the page-break-before property definition in CSS2. pageBreakInside See the page-break-inside property definition in CSS2. pause See the pause property definition in CSS2. pauseAfter See the pause-after property definition in CSS2. pauseBefore See the pause-before property definition in CSS2. pitch See the pitch property definition in CSS2. pitchRange See the pitch-range property definition in CSS2. playDuring See the play-during property definition in CSS2. position See the position property definition in CSS2. quotes See the quotes property definition in CSS2. richness See the richness property definition in CSS2. right See the right property definition in CSS2. size See the size property definition in CSS2. speak See the speak property definition in CSS2. speakHeader See the speak-header property definition in CSS2. speakNumeral See the speak-numeral property definition in CSS2. speakPunctuation See the speak-punctuation property definition in CSS2. speechRate See the speech-rate property definition in CSS2. stress See the stress property definition in CSS2. tableLayout See the table-layout property definition in CSS2. textAlign See the text-align property definition in CSS2. textDecoration See the text-decoration property definition in CSS2. textIndent See the text-indent property definition in CSS2. textShadow See the text-shadow property definition in CSS2. textTransform See the text-transform property definition in CSS2. top See the top property definition in CSS2. unicodeBidi See the unicode-bidi property definition in CSS2. verticalAlign See the vertical-align property definition in CSS2. visibility See the visibility property definition in CSS2. voiceFamily See the voice-family property definition in CSS2. volume See the volume property definition in CSS2. whiteSpace See the white-space property definition in CSS2. widows See the widows property definition in CSS2. width See the width property definition in CSS2. wordSpacing See the word-spacing property definition in CSS2. zIndex See the z-index property definition in CSS2. 1.5. Extensions to Level 1 Interfaces (ED: This section will dissipate into other sections of the Level 2 DOM as they develop. These extensions are placed here until those other sections are prepared. ) 1.5.1. Document style sheets A collection of all stylesheets linked into or embedded in the document is exposed through the styleSheets attribute. In HTML, this collection contains both external style sheets, included via the LINK element, and inline style sheets, included via STYLE elements. In XML, this collection contains all external style sheets included via a style sheet processing instruction . interface Document2 : Document { readonly attribute StyleSheetCollection styleSheets; }; 1.5.2. HTMLElement inline style Inline style information attached to HTML elements is exposed through the style attribute. This represents the contents of the STYLE attribute for HTML elements. interface HTMLElement2 : HTMLElement { readonly attribute CSSStyleDeclaration style; }; 1.5.3. HTMLStyleElement style sheet The style sheet associated with an HTML STYLE element is accessible via the styleSheet attribute. interface HTMLStyleElement2 : HTMLStyleElement { readonly attribute StyleSheet styleSheet; }; 1.5.4. HTMLLinkElement style sheet The styleSheet associated with an HTML LINK element with a REL of "stylesheet" or "alternate stylesheet" is not accessible directly. This is because LINK elements are not used purely as a stylesheet linking mechanism. The styleSheet property on LINK elements with other relationships would be incongruous. 1.6. Unresolved Issues 1. The DOM Working Group is considering a way to represent comments that exist within a CSS style sheet. Our expectation is that absolute position of comments may not be maintained, but relative position (with respect to CSS rules and CSS properties) and the actual contents of the comment will be. 2. The DOM Working Group is considering a mechanism to allow users to retrieve the cascaded, computed and actual style for a specific element. 3. The DOM Working Group is considering a mechanism to allow users to change the cascaded style for a specific element. This would allow the style of an element to be changed without adding rules to existing style sheets or changing the style attribute of an element. In this way, the style for an element could be changed without participating in the cascade. 2. Document Object Model Events Editors Tom Pixley, Netscape Communications Corporation Chris Wilson, Microsoft Corporation 2.1. Overview of the DOM Level 2 Event Model The DOM Level 2 Event Model is designed with two main goals. The first goal is the design of a generic event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. Additionally, the specification will attempt to provide standard sets of events for user interface control and document mutation notifications, including defined contextual information for each of these event sets. The second goal of the event model is to provide a common subset of the current event systems used within Microsoft Internet Explorer 4.0 and Netscape Navigator 4.0. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible. 2.1.1. Terminology UI events User interface events. These events are generated by user interaction through an external device (mouse, keyboard, etc.) UI Logical events Device independent user interface events such as focus change messages or element triggering notifications. Mutation events Events caused by any action which modifies the structure of the document. Capturing The process by which an event can be handled by one of the event's target's ancestors before being handled by the event's target. Bubbling The process by which an event propagates upward through its ancestors after being handled by the event's target. Cancellable A designation for events which indicates that upon handling the event the client may choose to prevent the DOM implementation from processing any default action associated with the event. 2.1.2. Requirements The following constitutes the list of requirements for the DOM Level 2 Event Model. (ED: Not all of the requirements below are addressed in the current version of the specification. However, all of the requirements which derive from existing event systems should currently be met.) Requirements of event flow: * The model must support multiple event listeners on a single Node. * The model must support the ability to receive events both before and after the DOM implementation has processed the event allowing the action which triggered the event to take place. Requirements of event listener registration: * The model must define a programmatic mechanism of specifying event listeners. This mechanism must be rich enough to support custom events, chaining of multiple event listeners, and general event listener registration< * If additional methods of registering event listeners are defined they must be consistent with the programattic model for event listener registration. Consistent means it is possible to define a sequence of DOM API calls which would have the same result. * The model must define the interaction between the programmatic event registration mechanism and event listener registration within HTML tags defined in the HTML 4.0 Specification * The programmatic method of event listener registration should allow the client to specify whether to receive the event before or after it has been processed by the DOM implementation. * Tag based registration, style based registration, and programmatic registration must all be able to coexist together. The event model must define rules for interaction between them. Requirements of contextual event information: * The model must specify a mechanism for providing basic contextual information for any event. * The model must specify a mechanism to provide UI events with additional UI specific information. Requirements of event types: * The model must allow the creation of additional event sets beyond those specified within the DOM Level 2 Event Model specification. * The model must support UI events. * The model must define a set of UI logical events to allow reaction to UI input in a device independent way. One use of this is for accessibility. * The model must define a set of document mutation events which allow notification of any change to the document's structure. * The model should define a set of events to allow notification of changes to a document's style. 2.2. Description of event flow Event flow is the process through which the an event originates from the DOM implementation and is passed into the Document Object Model. The methods of event capture and event bubbling, along with various event listener registration techniques, allow the event to then be handled in a number of ways. It can be handled locally at the target Node level or centrally from a Node higher in the document tree. 2.2.1. Basic event flow Each event has a Node toward which the event is directed by the DOM implementation. This Node is the event target. When the event reaches the target, any event listeners registered on the Node are triggered. If neither event capture or event bubbling are in use for that particular event, the event flow process will complete after all listeners have been triggered. If event capture or event bubbling is in use, the event flow will be modified as described in the sections below. 2.2.2. Event Capture Event capture is the process by which an ancestor of the event's target can register to intercept events of a given type before they are received by the event's target. In existing implementations, the ability to capture is only available to certain container elements such as documents and windows. This constraint is not necessarily a requirement of the DOM event model. Capture does not occur by default and must be explicitly activated. A Node capable of event capture initiates the capture process by calling its captureEvent method, passing in the desired event type as an argument. Thereafter, when an event of the given type is dispatched toward a descendant of the capturing object, the event will trigger any event listeners of the appropriate type registered on the capturing Node before triggering any listeners registered on the target Node. In order for additional event handlers to receive an event once it has been captured, an explicit call must be made to the capturer's routeEvent method to continue processing of the event. The application then finds the next highest capturing Node in the direct ancestral hierarchy above the target and calls any listeners there. If no additional capturers exist, the event triggers the appropriate event listeners on the target Node. Although event capture is similar to the delegation based event model, it is different in two important respects. First, event capture only allows interception of events which are targetted at descendants of the capturing Node. It does not allow interception of events targetted to the capturer's ancestors, its siblings, or its sibling's descendants. Secondly, event capture is not specified for a specific Node, it is specified for a specific type of event. Once specified, event capture intercepts all events of the specified type targetted toward any of the capturer's descendants. Interface EventCapturer The EventCapturer interface is implemented by Node's which are designated as being able to capture events. IDL Definition interface EventCapturer { void captureEvent(in DOMString type); void releaseEvent(in DOMString type); void routeEvent(); }; Methods captureEvent This method is used when a capturing Node wishes to begin capturing a particular type of event. Parameters type The name of the event to be captured This method returns nothing. This method raises no exceptions. releaseEvent This method is used when a capturing Node wishes to cease capturing a particular type of event. Parameters type The name of the event to be released This method returns nothing. This method raises no exceptions. routeEvent This method is called during the handling of an event by a capturing Node to continue the event's flow to additional event handlers, or if none are present, to the event's target. This method has no parameters. This method returns nothing. This method raises no exceptions. 2.2.3. Event bubbling Events which are designated as bubbling will initially proceed with the same event flow as non-bubbling events. The event is dispatched to their target Node and any event listeners found there are triggered. Bubbling events then perform a check of the event's cancelBubble attribute. If the attribute is false, the event will then look for additional event listeners by following the Node's parent chain upward, checking for any event listeners registered on each successive Node. This upward propagation will continue all the way up to the Document unless either the bubbling process is prevented through use of the cancelBubble attribute or the rules of bubbling and capture interaction determine that bubbling should cease. An event handler may choose to prevent continuation of the bubbling process at any time by setting the cancelBubble attribute of the event object to true. Events will always propagate upward if not explicitly prevented from doing so through use of the cancelBubble property. It is important to note that in this aspect bubbling behaves differently than capturing which must explicitly continue propagation of the event flow. 2.2.4. Interaction between capturing and bubbling If both capturing and bubbling are used at the same time some effort is required to ensure that they don't interfere with each other, causing unintended behavior. When this situation occurs, events are still captured, routed, and bubbled normally. However, near the end of the bubbling stage, when the event reaches the Node by which it was originally captured, the event ceases bubbling. This behavior exists to prevent a single event handler from being triggered multiple times by a single event, once during event capture and again during event bubbling. 2.2.5. Event cancellation Some events are specified as cancellable. For these events, the DOM implementation generally has a default action associatiated with the event. Before processing these events, the implementation must check for event listeners registered to receive the event and dispatch the event to those listeners. These listeners then have the option of cancelling the implementation's default action or allowing the default action to proceed. Cancellation is accomplished by setting the event's returnValue attribute to false. 2.3. Event interfaces Interface Event The Event interface is used to provide contextual information about an event to the handler processing the event. An object which implements the Event interface is generally passed as the first parameter to an event handler. More specific context information is passed to event handlers by deriving additional interfaces from Event which contain information directly relating to the type of event they accompany. These derived interfaces are also implemented by the object passed to the event listener. IDL Definition interface Event { attribute DOMString type; attribute Node target; attribute boolean cancelBubble; attribute boolean returnValue; }; Attributes type The type property represents the event name as a string property. target The target property indicates the Node to which the event was originally dispatched. cancelBubble The cancelBubble property is used to control the bubbling phase of event propagation. If the property is set to true, the event will cease bubbling at the current level. Otherwise, the event will bubble up to its parent. returnValue If an event is cancellable, the returnValue property is checked by the DOM implementation after the event has been processed by its event handlers. If the returnValue is false, the DOM implementation does not execute any default actions associated with the event. Interface UIEvent The UIEvent interface provides specific contextual information associated with User Interface and Logical events. IDL Definition interface UIEvent : Event { attribute long screenX; attribute long screenY; attribute long clientX; attribute long clientY; attribute boolean altKey; attribute boolean ctrlKey; attribute boolean shiftKey; attribute unsigned long keyCode; attribute unsigned long charCode; attribute unsigned short button; }; Attributes screenX screenX indicates the horizontal coordinate at which the event occurred in relative to the origin of the screen coordinate system. screenY screenY indicates the vertical coordinate at which the event occurred relative to the origin of the screen coordinate system. clientX clientX indicates the horizontal coordinate at which the event occurred relative to the DOM implementation's client area. clientY clientY indicates the vertical coordinate at which the event occurred relative to the DOM implementation's client area. altKey altKey indicates whether the 'alt' key was depressed during the firing of the event. ctrlKey ctrlKey indicates whether the 'ctrl' key was depressed during the firing of the event. shiftKey shiftKey indicates whether the 'shift' key was depressed during the firing of the event. keyCode The value of keyCode holds the virtual key code value of the key which was depressed if the event is a key event. Otherwise, the value is zero. charCode charCode holds the value of the Unicode character associated with the depressed key if the event is a key event. Otherwise, the value is zero. button During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. 2.4. Event set definitions The DOM Level 2 Event Model allows a DOM implementation to support multiple sets of events. The model has been designed to allow addition of new event sets as is required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM will define a set of user interface events, a set of UI logical events, and a set of document mutation events. 2.4.1. User Interface event types The User Interface event set is composed of events listed in HTML 4.0 and additional events which are supported in both Netscape Navigator 4.0 and Microsoft Internet Explorer 4.0. click The click event occurs when the pointing device button is clicked over an element. This attribute may be used with most elements. o This event bubbles o This event is cancellable dblclick The dblclick event occurs when the pointing device button is double clicked over an element. This attribute may be used with most elements. o This event bubbles o This event is cancellable mousedown The mousedown event occurs when the pointing device button is pressed over an element. This attribute may be used with most elements. o This event bubbles o This event is cancellable mouseup The mouseup event occurs when the pointing device button is released over an element. This attribute may be used with most elements. o This event bubbles o This event is cancellable mouseover The mouseover event occurs when the pointing device is moved onto an element. This attribute may be used with most elements. o This event bubbles o This event is cancellable mousemove The mousemove event occurs when the pointing device is moved while it is over an element. This attribute may be used with most elements. o This event bubbles mouseout The mouseout event occurs when the pointing device is moved away from an element. This attribute may be used with most elements. o This event bubbles o This event is cancellable keypress The keypress event occurs when a key is pressed and released. This attribute may be used with most elements. o This event bubbles o This event is cancellable keydown The keydown event occurs when a key is pressed down. This attribute may be used with most elements. o This event bubbles o This event is cancellable keyup The keyup event occurs when a key is released. This attribute may be used with most elements. o This event bubbles o This event is cancellable resize The resize event occurs when a document is resized. o This event bubbles scroll The scroll event occurs when a document is scrolled. o This event bubbles 2.4.2. Mutation event types The mutation event set is currently under development. Although it is not included here it should be noted that it will be expected to function with the same event flow system described above. It will also provide contextual event information via the Event interface, although it is likely that it will derive a specialized Event interface for use with mutation events. 2.4.3. HTML event types The HTML event set is composed of events listed in HTML 4.0 and additional events which are supported in both Netscape Navigator 4.0 and Microsoft Internet Explorer 4.0. load The load event occurs when the DOM implementation finishes loading all content within a document, all frames within a FRAMESET, or an image. unload The unload event occurs when the DOM implementation removes a document from a window or frame. This attribute may be used with BODY and FRAMESET elements. abort The abort event occurs when page loading is stopped before an image has been allowed to completely load. This attribute applies to the IMG tag. o This event bubbles error The error event occurs when an image does not load properly or when an error occurs during script execution. This attribute applies to the IMG tag and to the BODY and FRAMESET tags. o This event bubbles select The select event occurs when a user selects some text in a text field. This attribute may be used with the INPUT and TEXTAREA elements. o This event bubbles change The change event occurs when a control loses the input focus and its value has been modified since gaining focus. This attribute applies to the following elements: INPUT, SELECT, and TEXTAREA. o This event bubbles submit The submit event occurs when a form is submitted. It only applies to the FORM element. o This event bubbles o This event is cancellable reset The reset event occurs when a form is reset. It only applies to the FORM element. o This event bubbles focus The focus event occurs when an element receives focus either via a pointing device or by tabbing navigation. This attribute may be used with the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON. blur The blur event occurs when an element loses focus either by the pointing device or by tabbing navigation. It may be used with the same elements as onfocus 3. Document Object Model Filters and Iterators Editors Mike Champion, Arbortext Jonathan Robie, Texcel 3.1. Overview of the DOM Level 2 Filter and Iterator Interfaces The DOM Level 2 Filter and Iterator interfaces extend the functionality of the DOM to allow simple and efficient traversal of document subtrees, node lists, or the results of queries. This proposal contains Filter and Iterator interfaces, but no query interfaces. A separate specification will be prepared for query interfaces, which will be query-language independent. 3.1.1. Iterators In several popular approaches to software design, iterators are considered a basic building block for building reusable software and software libraries. For instance, they are fundamental to the Design Patterns approach, STL, and the Java libraries. The main advantages of node iterators in the DOM are: 1. Abstracting out the way that specific data structures are navigated. Functions that use iterators can operate on any data structure without knowing the details of how that data structure is navigated; e.g., the same function could process the nodes in a document, a document subtree, or a nodelist. The function can keep asking for the next node without worrying about how that node is found. 2. Allowing more efficient navigation. Because an iterator hides the manner in which a data structure is navigated, it can use indexes or other supplementary data structures to allow more efficient navigation than might be possible by naively navigating from one node to the next. 3. Providing views for the most common ways applications want to navigate document structures. Some applications traverse only the element tree, others process additional nodes such as processing instructions or comments, others prefer yet another view. There is no one right way to navigate a document tree, but iterators provide a simple, efficient way to choose the most appropriate view of the document tree for a given application. An iterator allows the nodes of a data structure to be returned sequentially. When an iterator is first created, calling nextNode() returns the first node. When no more nodes are present, nextNode() returns a null. It is important to remember that DOM structures may change as a document is loaded - when nextNode() finds no more nodes, it is still quite possible that further nodes may be added in the next instant. Since iterators do not know how to predict the future, there is no way to check whether further nodes may be added at any given time.Mutation and Iterators Since the DOM permits editing, and an iterator may be active while the data structure it navigates is being edited, an iterator must behave gracefully in the face of change. (ED: The Working Group agrees on the principle that an iterator should "gracefully" adapt to changes in the underlying document, but not on the details of how this can be rigorously specified. This will be addressed in the next draft of the DOM Level 2 spec.Among the issues under consideration are: 1. Should all iterators be "live" or should there be separate interfaces or factory methods that specify whether the iterator attempts to adapt to document changes or not? 2. May we assume that the iterator is notified of impending changes before the underlying tree is changed so that it can fix itself up, or do we assume that the iterator "gracefully adapts" to changes when the next() method is called? 3. What is the cost/benefit justification of specifying a relatively simple fixup that may have undesirable (but easily understandable) behavior under some circumstances, versus specifying a more complex algorithm that has more generally desireable behavior? ) 3.1.2. Filters Filters allow the user to "filter out" nodes. Each filter contains a user-written function that looks at a node and determines whether or not it should be filtered out. To use a filter, you create an iterator that uses the filter. The iterator applies the filter to each node, and if the filter rejects the node, the iterator skips over the node as though it were not present in the document. Filters are easy to write, since they need not know how to navigate the structure on which they operate, and they can be reused for different kinds of iterators that operate on different data structures. Let's use a filter to write code to find the named anchors in an HTML document. In HTML, an HREF can refer to any element that has a NAME attribute. The first step is to write a filter that looks at a node and determines whether it is a named anchor: class NamedAnchorFilter implements NodeFilter { boolean acceptNode(Node n) { if (n instanceof Element) { Element e = n; if (n.getAttribute("NAME") != NULL) { return true; } } return false; } } To use this filter, create an instance of the filter and create an iterator using it: (ED: We need to specify the details of how this will work in ECMAScript, which does not have the concept of abstract interfaces or data types, more formally) NamedAnchorFilter naf; NodeIterator nit = document.createFilteredTreeIterator(naf); At this point, the iterator will show only the named anchors in the document. Writing equivalent code without filters would be marginally simpler, and no less efficient. The advantage of using filters is that it allows reuse. For instance, if you have another part of your program that needs to find the named anchors in a NodeList, you can use the filter the same way you used it for the document: NamedAnchorFilter naf; NodeIterator nit = nodelist.createFilteredTreeIterator(naf); 3.2. Formal Interface Definition Interface NodeIterator IDL Definition interface NodeIterator { Node nextNode(); void reset(); }; Methods nextNode Return Value The next Node in the set being iterated over, or NULL if there are no more members in that set. This method has no parameters. This method raises no exceptions. reset Resets the iterator to the same state as a new iterator would be if constructed by the same factory method with the same arguments as used to construct this iterator. This method has no parameters. This method returns nothing. This method raises no exceptions. Interface NodeFilter IDL Definition interface NodeFilter { boolean acceptNode(in Node n); }; Methods acceptNode Parameters n The node to check to see if it passes the filter or not. Return Value TRUE if a this node is to be passed through the filter and returned by the NodeIterator::nextNode() method, FALSE if this node is to be ignored.ABCDEF When the selected portion contains no content (both endpoints are at the same position) it will be shown as a bold caret ('^') as in A^BCDEF And when referring to a single end-point, it will be show as a bold asterisk ('*') as in A*BCDEF 4.2. Finding a Range's Position A Range has two end-points (the start and the end). Each end-point's position in a document (or document fragment) can be characterized by two quantities: a parent node and an offset relative to that parent node. The Range is considered to select the contiguous content of the document or document fragment contained between the two end-points. Note that a Range only selects within the document tree. In particular, the parent node of a Range's end-point must be an Element, Comment, ProcessingInstruction, EntityReference, CDATASection, Document, DocumentFragment or Text node and it must have a Document or DocumentFragment node as an ancestor. This requirement specifically excludes Attr, DocumentType, Entity and Notation nodes as ancestors of end-point parents. (ED: The Working Group is considering allowing Attr nodes as ancestors of end-point parents with the restriction that both end-points have the same Attr node as an ancestor. This would allow range operations on an attribute tree in the same manner as on a document tree.) The relationship between locations in the raw source document and in the Node tree interface of the DOM is illustrated in the following diagram: --------------------------------------------------------------------- [Range Example] --------------------------------------------------------------------- Range Example --------------------------------------------------------------------- In this diagram, four different Ranges are illustrated. Consider the red Range with end-points labelled s and e. This Range selects the entire P node. In the raw source, it is possible and convenient to specify the location of the end-points by using absolute offsets from the beginning of the document. In this case, the red Range could be said to select the content of the raw source document from after the 20th character to after the 36th character. There are several reasons why absolute offsets are not a useful way to specify end-points in the DOM tree. First of all, such absolute offsets are potentially very inefficient to calculate and maintain. Second, two different end-points in the tree can have the same absolute offset in the raw document as will be discussed below. And, finally, since they refer to the persisted state of the document, calculating the offsets would require the DOM to precisely specify how the document is persisted. For these reasons, the end-points are specified using a node and an offset within the children of that node. In the example above, the position represented by the end-point labelled s is within the BODY element. It is after the H1 element and before the P element so it corresponds to a position between the H1 and P children of BODY. The offset of an end-point within its containing node is 0 if it is before the first child, 1 if between the first and second child, and so on. So, for end-point s, the container node is BODY and the offset is 1. For end-points within text nodes, the offset is specified similarly but using character positions instead. For example, the end-point labelled s has a Text node as its container and an offset of 2 since it is between the second and third characters. The diagram and table illustrates the container nodes and offsets for the end-points of four Ranges. Notice that the corresponding end-points of purple and blue ranges appear to be identical in the raw document but that each is, in fact, represented distinctly in the DOM. This is an important feature of the Range since it means that an end-point of a Range can unambiguously represent every position within the document tree. When the parent node of an end-point is not a text node, the offset specifies a position between the child nodes. For example, an offset of 0 means that the end-point is before the first child, an offset of 1 means it is after the first child and before the second child, and so on. However, it is also often convenient to think of a Range as selecting a portion of the raw source document and many of the examples in this specification will be illustrated that way. The parents and offsets of the end-points can be accessed using the following read-only Range attributes: startParent; startOffset; endParent; endOffset; If both end-points of a Range have the same parent nodes and offsets then the Range is a degenerate selection, or collapsed Range. (This is often referred to as an insertion point in a user agent.) 4.3. Partial and Complete Containment A node is said to be partially contained by a Range if it is an ancestor of or equal to the containing node of one or both end-points of the Range. That is, if the node contains at least one end of the Range, then it is partially contained. For example, consider the green Range in Diagram 1, above. H1 is partially contained by that Range since the start end-point is within one of its children. And BODY is partially contained by the same Range since both end-points are contained within children of its children. A node is said to be completely contained by a Range if it is located between the the two end-points of the Range. In terms of the raw source document, a node would only be completely contained by a Range if its corresponding start-tag was located after the starting end-point of the Range and its end-tag was located before the end of the Range. In the examples in Diagram 1, above, the red Range completely contains the P node and the purple Range completely contains the text node containing the text "Blah xyz." 4.4. Creating a Range (ED: The factory method for creating a Range should be implemented by the document object. Since this involves a new method, it may either be added to the existing Document interface or a secondary interface implemented by the same object. The determination of where this method goes and how to deal with new methods on existing interfaces in backwardly compatible manner needs to be addressed by the Working Group as a whole.) A range is created by calling a method on the Document object: interface Document { interface Document { .... Range createRange(); } The initial state of the range returned from this method is such that its two end-points are equal and both are positioned at the beginning of the Document before any content. In other words, the parent node of each end-point is the Document node and the offset within that node is 0. Like some other objects created from the Document (like Nodes and DocumentFragments), Ranges created via a particular document instance are only compatible with content associated with that document, and cannot be used with other document instances. 4.5. Changing a Range's Position A Range's position can be specified by setting the parent and offset of each end-point with the setStart and setEnd methods. If one end-point of a Range is set to be positioned in content associated with a document fragment other than that in which the range is currently positioned, the range will be collapsed to the new location. This enforces the restriction that both end-points of a Range must be in the same document or fragment. Also, the start position is guaranteed to never be to the right of the end position. As a consequence of this, attempting to set the start to be to the right of the end will cause the end to be moved to the same position, resulting in a collapsed range at that location. The case for the end being before the start is similarly handled. It is also possible to set a Range's position relative to other nodes in the tree: void setStartBefore( in Node sibling ); void setStartAfter( in Node sibling ); void setEndBefore( in Node sibling ); void setEndAfter( in Node sibling ); The parent of the sibling node will become the parent of the end-point and the Range will be subject to the same restrictions as outlined above for setStart() and setEnd(). A Range can be collapsed to either end-point: void collapse ( in boolean toStart ); Passing TRUE to the parameter toStart will collapse the range to the range's start position, FALSE to the end. Testing if a Range is collapsed can be done by examining the isCollapsed attribute: readonly attribute boolean isCollapsed; Quite often one will want to cause a range to select everything under a node, possibly including the node itself: void selectNode ( in Node n ); void selectNodeContents ( in Node n ); For example: Before: ^ABC After range.selectNodeContents( FOO ): ABC After range.selectNode( FOO ): ABC 4.6. Comparing Range End-Points It is possible to compare two Ranges by comparing their end-points: int compareEndPoints(CompareHow how, Range sourceRange) where CompareHow is one of 4 values: StartToStart, StartToEnd, EndToEnd and EndToStart. The return value is -1, 0 or 1 depending on whether the corresponding end-point of the Range is less than, equal or greater than the corresponding end-point of sourceRange. Determining if one end-point is less than another requires examing a number of cases but, informally, one end-point is less than another if it corresponds to a location in the source document before the second end-point. This can be stated more precisely in terms of the DOM tree, as follows: If both end-points have the same parent node, then one end-point is less than the other if its offset is less the offset of the other end-point. If the end-points have different parent nodes, then there are three cases to consider. Let A and B be the two end-points. The first case to consider is when a child of the parent of A is the parent or an ancestor of the parent of B. In this case, A is less than B if the offset of A is less than or equal to the index of the child containing B. The second case is when a child of the parent of B is the parent or an ancestor of the parent of A. In this case, A is less than B if the index of the child containing A is less than the offset of B. The third case is when neither parent is an ancestor of the other end-point's parent. In this case, let N be the common ancestor of both A and B which has the greatest depth in the DOM tree. Then A is less than B if the index of the child of N which is an ancestor of the parent of A is less than the index of the child of N which is an ancestor of the parent of B. Comparing two end-points for equality is much more straightforward: Two end-points are equal to one another if and only if they have the same parents and both offsets are equal. And finally, determining if one end-point is greater than another can be stated in terms of the other two comparisons: A is greater than B if A is not equal to B and A is not less than B. Note that because the same location in the source document can correspond to two different locations in the DOM tree, it is possible for two end-points to not compare equal even though they would be equal in the source. For this reason, the informal definition above can sometimes be misleading. 4.7. Deleting Content with a Range One can delete the contents selected by a range with: void deleteContents ( ); The deletion of the contents selected by a range is pretty straight forward if the parent nodes for each endpoint is the same. For example: CD --> ^ Here, the range has endpoints (each endpoint expressed as a pair Node, Offset) of (FOO, 0) and (FOO, 1). Notice in this example that the MOO node was removed in its entirety. This is so because the MOO began and ended within the scope of the range's selection. Thus, any node which starts and ends within a range's selection is removed in its entirety. Also notice that the FOO tag was left untouched (other than its immediate content being modified). Thus, any node which starts and ends outside a range's selection is not affected. There are two other cases left to completely describe the effect on a document of the deleteContents operation: 1) ABCDE --> AB^E 2) XYZWQ --> X^WQ In case 1, the MOO node begins before the range's selection, while the MOO's end is contained within the ranges selection. Here, it is important to know that the deleteContents operation is structural, not textual. Stated differently, the deleteContents operation on a range does not remove the textual representation of its content, as though one were editing the document contents (including tags) in a text editor. While, as in this example, the textual representation of the range selection may include only one of the start- or end-tag representing an element, a deleteContents operation on that range will not result in a non-well formed document. A node is considered to be "partially" contained within a range if, in the textual representation of the range, only one of either its start- or end-tag is included in the range contents. In this case, a deleteContents operation will not remove the partially contained element. However, after the operation is completed, the (now collapsed) range will move outside the element. Specifically, if the range's original start point were before the node (in depth-first post-order) the range would collapse to a position before the node. If the range's original end point were after the node, the range would collapse to a position after the node. AB^E Now, notice that in this, false, example there is a begin tag for the MOO node, but no end tag. This is not representable by the DOM. All nodes in the DOM must have a definite begin and end. Thus, notice how the end tag of the MOO node effectively scooted to the left, outside the influence of the range's selection. This is so because only a part of the MOO node was deleted. If the begin of the MOO node was inside the selection of the range at the time of the deletion, then the MOO node would have been removed in it entirety. For case 2, instead of the later half of a node falling within the range, the first half is contained within the range. This is very similar to case 1, with the exception that the begin tag for BAR scoots to the right. To summarize these two cases where only a part of a node is selected, if the node begins in the selection, the begin tag, effectively, scoots to the right, if the node ends in the selection, the end tag, effectively, scoots left. In cases where the contents of a range should be extracted rather than deleted, the following method may be used: DocumentFragment extractContents ( ); The extractContents method does exactly what the deleteContents methods does, but it additionally places the deleted contents in a new DocumentFragment. Using the three examples above, the following illustrate the contents of the returned document fragment: CD --> CD ABCDE --> CD (MOO' is a clone of MOO) XYZWQ --> YZ (BAR' is a clone of BAR) It is important to note that nodes which are only partially contained by the range are cloned. Since part of such a node's contents must remain in the original document (or document fragment) and part of the contents must be moved to the new fragment, a clone of the partially contained node is brought along to the new fragment. Note that cloning does not take place for "completely" contained elements - these elements are directly moved to the new fragment. 4.8. Cloning Content The contents of a range may be duplicated using the following method: DocumentFragment cloneContents ( ); This method returns a document fragment that is similar to the one returned by the method extractContents. However, in this case, the original nodes and text content in the range are not deleted from the original document. Instead, all of the nodes and text content within the returned document fragment are cloned. 4.9. Inserting Content A node may be inserted into a range using the following method: void insertNode ( in Node n ); The insertNode method inserts the specified node into the document or document fragment in which the range resides. For this method, the end position of the range is ignored and the node is inserted at the start position of the range. The Node passed into this method can be a DocumentFragment. In that case, the contents of the fragment are inserted at the start position of the range, but the fragment itself is not. Note that if the Node represents the root of a sub-tree, the entire sub-tree is inserted. Note that the same rules that apply to the insertBefore method on the Node interface apply here. Specifically, the Node passed in will be removed from its existing position in the same document or another fragment. 4.10. Surrounding Content The insertion of a single element to subsume the content selected by range can be performed with: void surroundContents ( in Node n ); The surroundContents member differs from insertNode in that surroundContents causes all of the content selected by the range to become children of the node argument, while insertNode splices in existing content at the given point in the document. For example,calling surround contents with the node FOO yields: Before: ABCDE After surroundContents ( FOO ): ABCDE Effectively, the surroundContents member modifies the document such that the begin tag of the node argument to be placed at the beginning of the range, and the end tag of the node argument to be placed at the end of the range. Of course, tags are not really being manipulated, however the effect is the same thus giving meaning to this member's name: surroundContents. Another way of of describing the effect of this member is to decompose it in terms of other operations: 1. Remove the contents selected by the range with a call to extractContents, saving away the selected contents into a new document fragment. 2. Insert the node argument where the range is now collapsed (after the extraction) with insertNode 3. Insert the entire contents of the extracted contents under the node argument. 4. Select the node argument and all of its contents with selectNode. Because inserting a node in such a manor will be a common operation, surroundContents is provided to avoid the overhead of these four steps. The surroundContents method may not be invoked in cases where the range only partially contains a non-Text node. Specifically, if the first non-Text node ancestor of the two end-points of a range is different, surroundContents will fail. An example of a range for which surroundContents may not be invoked is: ABCDE If the node argument has any children, those children are removed before its insertion. Also, if the node argument is part of any existing content, it is also removed from that content before insertion. 4.11. Miscellaneous Members One can clone a range: Range cloneRange ( ); This creates a new range which selects exactly the same content of the range on which it was called. No content is affected by this operation. Because the end-points of a range do not have to necessarily share the same parent nodes, use: readonly attribute Node commonParent; to get the first node which is common to both endpoints. This is accomplished by walking up the parent chain of the two endpoints, locating the first node which is common. One can get a copy of all the text nodes (or partial text nodes) selected by a range with: domstring toString ( ); This does nothing more than simply concatenate all the textual content subsumed by the range. 4.12. Range behavior under document mutation As the document is mutated, the Ranges within the document need to be updated. For example, if both ends of a Range are within the same node and that node is removed from the document, then the Range would be invalid unless it is fixed up in some way. This section describes how Ranges are modified under document mutations so that they remain valid. There are two general principles which apply to Ranges under document mutation: The first is that all Ranges in a document will remain valid after any mutation operation and the second is that, loosely speaking, all Ranges will select the same portion of the document after any mutation operation, where that is possible. Any mutation of the document tree which affect Ranges can be considered to be a combination of basic delete and insertion operations. In fact, it can be convenient to think of those operations as being accomplished using the deleteContents() and insertNode() Range methods. (ED: I think we also have to think of merging of TextNodes as a separate operation. Although the merge can be considered to be a deletion followed by an insertion, a Range which selected a portion of the text in the nodes being deleted won't select the same content after the merge. I think it should.) 4.12.1. Insertions An insertion occurs at a single point in the document. Again, it is convenient to think of that point, called the insertion point, as the end-point of a Range. For any other Range in the document tree, consider each end-point. The only case in which the end-point will be changed after the insertion is when the end-point and the insertion point have the same parent Node and the offset of the insertion point is strictly less than the offset of the Range's end-point. In that case the offset of the Range's end-point will be increased so that it is between the same nodes or characters as it was before the insertion. Note that when content is inserted at an end point, it is ambiguous as to where the end point should reposition itself if it wants to maintain its original relative position. It has two choices: either at the start or end of the newly inserted content. We have chosen to neither change the parent nor offset of the end-point in this case which means that it will be positioned at the start of the newly inserted content. Examples: In these examples, the portion of the document selected by the Range before and after the insertion will be shown as bold text. Suppose the Range selects the following:

Abcd efgh XY blah ijkl

Consider the insertion of the text "inserted text" in the following locations: 1. Before the 'X':

Abcd efgh inserted textXY blah ijkl

2. After the 'X':

Abcd efgh Xinserted textY blah ijkl

3. After the 'Y':

Abcd efgh XYinserted text blah ijkl

4. After the 'h' in "Y blah":

Abcd efgh XY blahinserted text ijkl

Editor's NOTE:All of these results make intuitive sense except, perhaps, for example 2. where it might be expected that the result would be

Abcd efgh Xinserted textY blah ijkl

4.12.2. Deletions Any deletion from the document tree can be considered as a sequence of deleteContent() operations applied to a minimal set of disjoint Ranges. To specify how a Range is modified under deletions we need only consider what happens to a Range under a single deleteContent() operation of another Range. And, in fact, we need on consider what happens to a single end-point of the Range since both end-points will be modified using the same algorithm. If an end-point is within the content being deleted, then it will be moved after the deletion to the same location as the common end-point of the Range used to delete the contents. If an end-point is after the content being deleted then it is not affected by the deletion unless its parent node is also the parent node of one of the end-points of the range being deleted. If there is such a common parent, then the index of the end-point is modified so that the end-point maintains its position relative to the content of the parent. If an end-point is before the content being deleted then it is not affect by the deletion at all. Examples: In these examples, the portion of the document selected by the Range before and after the insertion will be shown as bold text and the content being deleted is underlined. When the Range after the deletion is an insertion point, it will be shown as '^'. Example 1. Before:

Abcd efgh The Range ijkl

After:

Abcd Range ijkl

Example 2. Before:

Abcd efgh The Range ijkl

After:

Abcd ^kl

Example 3. Before:

ABCD efgh The Range ijkl

After:

ABCD ange ijkl

Example 4. Before:

Abcd efgh The Range ijkl

After:

Abcd he Range ijkl

Example 5. Before:

Abcd efgh The Range ijkl

After:

Abcd ^kl

4.13. Formal Description of the Range Interface To summarize, here is the complete, formal description of the Range interface: Interface Range IDL Definition interface Range { readonly attribute Node startParent; readonly attribute long startOffset; readonly attribute Node endParent; readonly attribute long endOffset; readonly attribute boolean isCollapsed; readonly attribute Node commonParent; void setStart(in Node parent, in long offset) raises(RangeException); void setEnd(in Node parent, in long offset) raises(RangeException); void setStartBefore(in Node sibling) raises(RangeException); void setStartAfter(in Node sibling) raises(RangeException); void setEndBefore(in Node sibling) raises(RangeException); void setEndAfter(in Node sibling) raises(RangeException); void collapse(in boolean toStart); void selectNode(in Node n) raises(RangeException); void selectNodeContents(in Node n) raises(RangeException); typedef enum CompareHow_ { StartToStart, StartToEnd, EndToEnd, EndToStart } CompareHow; short compareEndPoints(in CompareHow how, in Range sourceRange) raises(DOMException); void deleteContents() raises(DOMException); DocumentFragment extractContents() raises(DOMException); DocumentFragment cloneContents(); void insertNode(in Node n) raises(DOMException, RangeException); void surroundContents(in Node n) raises(DOMException, RangeException); Range cloneRange(); DOMString toString(); }; Attributes startParent Node within which the range begins startOffset Offset in the starting node of the start of the range. endParent Node within which the range ends endOffset Offset in the ending node of the end of the range. isCollapsed TRUE if the range is collapsed commonParent The common ancestor node of the entire range Methods setStart Sets the attribute values describing the start of the range. Parameters parent The startNode value. This parameter must be non-null. offset The startOffset value. Exceptions RangeException NULL_PARENT_ERR: Raised if startNode is null. INVALID_NODE_TYPE_ERR: Raised if an ancestor of startNode is an Attr, Entity, Notation or DocumentType node. This method returns nothing. setEnd Sets the attributes describing the end of a range. Parameters parent The endNode value. This parameter must be non-null. offset The endOffset value. Exceptions RangeException NULL_PARENT_ERR: Raised if endNode is null. INVALID_NODE_TYPE_ERR: Raised if an ancestor of startNode is an Attr, Entity, Notation or DocumentType node. This method returns nothing. setStartBefore Sets the starting position before a node Parameters sibling Range starts before this node Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if an ancestor of sibling is an Attr, Entity, Notation or DocumentType node or if sibling itself is a Document or DocumentFragment node. This method returns nothing. setStartAfter Sets the starting position after a node Parameters sibling Range starts after this node Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if an ancestor of sibling is an Attr, Entity, Notation or DocumentType node or if sibling itself is a Document or DocumentFragment node. This method returns nothing. setEndBefore Sets the ending position of a range to be before a given node. Parameters sibling Range ends before this node Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if an ancestor of sibling is an Attr, Entity, Notation or DocumentType node or if sibling itself is a Document or DocumentFragment node. This method returns nothing. setEndAfter Sets the ending position of a range to be after a given node Parameters sibling Range ends after this node. Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if an ancestor of sibling is an Attr, Entity, Notation or DocumentType node or if sibling itself is a Document or DocumentFragment node. This method returns nothing. collapse Collapse a range onto one of the end points Parameters toStart If TRUE, collapses onto the starting node; if FALSE, collapses the range onto the ending node. This method returns nothing. This method raises no exceptions. selectNode Select a node and its contents Parameters n Node to select from Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if an ancestor of n is an Attr, Entity, Notation or DocumentType node or if n itself is a Document or DocumentFragment node. This method returns nothing. selectNodeContents Select the contents within a node Parameters n Node to select from Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if an ancestor of n is an Attr, Entity, Notation or DocumentType node. This method returns nothing. Type Definition CompareHow Enumeration CompareHow_ Enumerator Values StartToStart StartToEnd EndToEnd EndToStart Methods compareEndPoints Compare the end-points of two ranges in a document. Parameters how sourceRange Return Value -1, 0 or 1 depending on whether the corresponding end-point of the Range is less than, equal or greater than the corresponding end-point of sourceRange. Exceptions DOMException WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same document or document fragment. deleteContents Removes the contents of a range from the containing document or document fragment without returning a reference to the removed content. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the range is readonly or any of the nodes which contain any of the content of the range are readonly. This method has no parameters. This method returns nothing. extractContents Moves the contents of a range from the containing document or document fragment to a new DocumentFragment. Return Value A DocumentFragment containing the extracted contents. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the range is readonly or any of the nodes which contain any of the content of the range are readonly. This method has no parameters. cloneContents Duplicates the contents of a range Return Value A DocumentFragment containing contents equivalent to those of this range. This method has no parameters. This method raises no exceptions. insertNode inserts the specified node into the document or document fragment at the start end-point of the range. Parameters n The node to insert at the start end-point of the range Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if the parent or any ancestor of the start end-point of the range is readonly. RangeException INVALID_NODE_TYPE_ERR: Raised if n is an Attr, Entity, Notation, DocumentType or Document node. This method returns nothing. surroundContents Reparents the contents of the range to the given node and inserts the node at the location of the start end-point of the range. Parameters n The node to surround the contents with. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if the parent or any ancestor of the either end-point of the range is readonly. RangeException BAD_ENDPOINTS_ERR: Raised if the range only partially contains a node. INVALID_NODE_TYPE_ERR: Raised if n is an Attr, Entity, DocumentType, Notation, Document or DocumentFragment node. This method returns nothing. cloneRange Produces a new range whose end-points are equal to the end-points of the range. Return Value The duplicated range. This method has no parameters. This method raises no exceptions. toString Returns the contents of a range as a string. Return Value The contents of the range. This method has no parameters. This method raises no exceptions. Exception RangeException The Range object needs additional exception codes to those in DOM Level 1. These codes will need to be consolidated with other exceptions added to DOM Level 2. IDL Definition exception RangeException { unsigned short code; }; // RangeExceptionCode const unsigned short BAD_ENDPOINTS_ERR = 201; const unsigned short INVALID_NODE_TYPE_ERR = 202; const unsigned short NULL_PARENT_ERR = 203; Definition group RangeExceptionCode An integer indicating the type of error generated. Defined Constants BAD_ENDPOINTS_ERR If the end-points of a range do not meet specific requirements. If the parent of an end-point of a INVALID_NODE_TYPE_ERR range is being set using either a node with an ancestor of an invalid type or a node with an invalid type. NULL_PARENT_ERR If the parent of an end-point of a range is being set to null. Appendix A: Contributors Members of the DOM Working Group and Interest Group contributing to this specification were: Lauren Wood, SoftQuad Software Inc., chair Arnaud Le Hors, W3C, W3C staff contact Andy Heninger, IBM Bill Smith, Sun Bill Shea, Merrill Lynch Bob Sutor, IBM Chris Wilson, Microsoft David Brownell, Sun Don Park, Docuverse Eric Vasilik, Microsoft Gavin Nicol, INSO Jared Sorensen, Novell Joe Kesselman, IBM Joe Lapp, webMethods Jonathan Robie, Texcel Mike Champion, Arbortext Peter Sharpe, SoftQuad Software Inc. Ramesh Lekshmynarayanan, Merrill Lynch Ray Whitmer, iMall Rich Rollman, Microsoft Tom Pixley, Netscape Vidur Apparao, Netscape Appendix B: Glossary Editors Robert S. Sutor, IBM Research Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information. ancestor An ancestor node of any node A is any node above A in a tree model of a document, where "above" means "toward the root." API An API is an application programming interface, a set of functions or methods used to access some functionality. child A child is an immediate descendant node of a node. client application A [client] application is any software that uses the Document Object Model programming interfaces provided by the hosting implementation to accomplish useful work. Some examples of client applications are scripts within an HTML or XML document. COM COM is Microsoft's Component Object Model, a technology for building applications from binary software components. content model The content model is a simple grammar governing the allowed types of the child elements and the order in which they appear. See [XML ] context A context specifies an access pattern (or path): a set of interfaces which give you a way to interact with a model. For example, imagine a model with different colored arcs connecting data nodes. A context might be a sheet of colored acetate that is placed over the model allowing you a partial view of the total information in the model. convenience A convenience method is an operation on an object that could be accomplished by a program consisting of more basic operations on the object. Convenience methods are usually provided to make the API easier and simpler to use or to allow specific programs to create more optimized implementations for common operations. A similar definition holds for a convenience property. cooked model A model for a document that represents the document after it has been manipulated in some way. For example, any combination of any of the following transformations would create a cooked model: 1. Expansion of internal text entities. 2. Expansion of external entities. 3. Model augmentation with style-specified generated text. 4. Execution of style-specified reordering. 5. Execution of scripts. A browser might only be able to provide access to a cooked model, while an editor might provide access to a cooked or the initial structure model (also known as the uncooked model) for a document. CORBA CORBA is the Common Object Request Broker Architecture from the OMG . This architecture is a collection of objects and libraries that allow the creation of applications containing objects that make and receive requests and responses in a distributed environment. cursor A cursor is an object representation of a node. It may possess information about context and the path traversed to reach the node. data model A data model is a collection of descriptions of data structures and their contained fields, together with the operations or functions that manipulate them. deprecation When new releases of specifications are released, some older features may be marked as being deprecated. This means that new work should not use the features and that although they are supported in the current release, they may not be supported or available in future releases. descendant A descendant node of any node A is any node below A in a tree model of a document, where "above" means "toward the root." ECMAScript The programming language defined by the ECMA-262 standard. As stated in the standard, the originating technology for ECMAScript was JavaScript. Note that in the ECMAScript binding, the word "property" is used in the same sense as the IDL term "attribute." element Each document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements by an empty-element tag. Each element has a type, identified by name, and may have a set of attributes. Each attribute has a name and a value. [XML ] event propagation, also known as event bubbling This is the idea that an event can affect one object and a set of related objects. Any of the potentially affected objects can block the event or substitute a different one (upward event propagation). The event is broadcast from the node at which it originates to every parent node. equivalence Two nodes are equivalent if they have the same node type and same node name. Also, if the nodes contain data, that must be the same. Finally, if the nodes have attributes then collection of attribute names must be the same and the attributes corresponding by name must be equivalent as nodes. Two nodes are deeply equivalent if they are equivalent, the child node lists are equivalent are equivalent as NodeList objects, and the pairs of equivalent attributes must in fact be deeply equivalent. Two NodeList objects are equivalent if they have the same length, and the nodes corresponding by index are deeply equivalent. Two NamedNodeMap objects are equivalent if they are have the same length, they have same collection of names, and the nodes corresponding by name in the maps are deeply equivalent. Two DocumentType nodes are equivalent if they are equivalent as nodes, have the same names, and have equivalent entities and attributes NamedNodeMap objects. hosting implementation A [hosting] implementation is a software module that provides an implementation of the DOM interfaces so that a client application can use them. Some examples of hosting implementations are browsers, editors and document repositories. HTML The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents with generic semantics that are appropriate for representing information from a wide range of applications. [HTML 3.2 ] [HTML4.0 ] IDL An Interface Definition Language (IDL) is used to define the interfaces for accessing and operating upon objects. Examples of IDLs are the Object Management Group's IDL , Microsoft's IDL , and Sun's Java IDL . implementor Companies, organizations, and individuals that claim to support the Document Object Model as an API for their products. inheritance In object-oriented programming, the ability to create new classes (or interfaces) that contain all the methods and properties of another class (or interface), plus additional methods and properties. If class (or interface) D inherits from class (or interface) B, then D is said to be derived from B. B is said to be a base class (or interface) for D. Some programming languages allow for multiple inheritance, that is, inheritance from more than one class or interface. initial structure model Also known as the raw structure model or the uncooked model, this represents the document before it has been modified by entity expansions, generated text, style-specified reordering, or the execution of scripts. In some implementations, this might correspond to the "initial parse tree" for the document, if it ever exists. Note that a given implementation might not be able to provide access to the initial structure model for a document, though an editor probably would. interface An interface is a declaration of a set of methods with no information given about their implementation. In object systems that support interfaces and inheritance, interfaces can usually inherit from one another. language binding A programming language binding for an IDL specification is an implementation of the interfaces in the specification for the given language. For example, a Java language binding for the Document Object Model IDL specification would implement the concrete Java classes that provide the functionality exposed by the interfaces. method A method is an operation or function that is associated with an object and is allowed to manipulate the object's data. model A model is the actual data representation for the information at hand. Examples are the structural model and the style model representing the parse structure and the style information associated with a document. The model might be a tree, or a directed graph, or something else. object model An object model is a collection of descriptions of classes or interfaces, together with their member data, member functions, and class-static operations. parent A parent is an immediate ancestor node of a node. root node The root node is the unique node that is not a child of any other node. All other nodes are children or other descendents of the root node. [XML ] sibling Two nodes are siblings if they have the same parent node. string comparison When string matching is required, it is to occur as though the comparison was between 2 sequences of code points from the Unicode 2.0 standard. tag valid document A document is tag valid if all begin and end tags are properly balanced and nested. type valid document A document is type valid if it conforms to an explicit DTD. uncooked model See initial structure model. well-formed document A document is well-formed if it is tag valid and entities are limited to single elements (i.e., single sub-trees). XML Extensible Markup Language (XML) is an extremely simple dialect of SGML which is completely described in this document. The goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. [XML ] Appendix C: IDL Definitions This appendix contains the complete OMG IDL for the Level 1 Document Object Model definitions. The definitions are divided into CSS , Events , Filters and Iterators , and Range . C.1: Document Object Model Level 2 CSS css.idl: // File: css.idl #ifndef _CSS_IDL_ #define _CSS_IDL_ #include "dom.idl" #pragma prefix "dom.w3c.org" module css { typedef dom::DOMString DOMString; typedef dom::Node Node; interface CSSRuleCollection; interface CSSRule; interface CSSStyleDeclaration; interface StyleSheet { readonly attribute DOMString type; attribute boolean disabled; readonly attribute Node owningNode; readonly attribute StyleSheet parentStyleSheet; readonly attribute DOMString href; readonly attribute DOMString title; readonly attribute DOMString media; }; interface StyleSheetCollection { readonly attribute unsigned long length; StyleSheet item(in unsigned long index); }; interface CSSStyleSheet : StyleSheet { readonly attribute CSSRuleCollection cssRules; unsigned long insertRule(in DOMString rule, in unsigned long index) raises(DOMException); void deleteRule(in unsigned long index) raises(DOMException); }; interface CSSRuleCollection { readonly attribute unsigned long length; CSSRule item(in unsigned long index); }; interface CSSRule { // RuleType const unsigned short UNKNOWN_RULE = 0; const unsigned short STYLE_RULE = 1; const unsigned short IMPORT_RULE = 2; const unsigned short MEDIA_RULE = 3; const unsigned short FONT_FACE_RULE = 4; const unsigned short PAGE_RULE = 5; readonly attribute unsigned short type; attribute DOMString cssText; readonly attribute CSSStyleSheet parentStyleSheet; }; interface CSSStyleRule : CSSRule { attribute DOMString selectorText; readonly attribute CSSStyleDeclaration style; }; interface CSSMediaRule : CSSRule { attribute DOMString mediaTypes; readonly attribute CSSRuleCollection cssRules; unsigned long insertRule(in DOMString rule, in unsigned long index) raises(DOMException); void deleteRule(in unsigned long index); }; interface CSSFontFaceRule : CSSRule { readonly attribute CSSStyleDeclaration style; }; interface CSSPageRule : CSSRule { attribute DOMString selectorText; readonly attribute CSSStyleDeclaration style; }; interface CSSImportRule : CSSRule { attribute DOMString href; attribute DOMString media; readonly attribute CSSStyleSheet styleSheet; }; interface CSSUnknownRule : CSSRule { }; interface CSSStyleDeclaration { attribute DOMString cssText; DOMString getPropertyValue(in DOMString propertyName); DOMString getPropertyPriority(in DOMString propertyName); void setProperty(in DOMString propertyName, in DOMString value, in DOMString priority) raises(DOMException); readonly attribute unsigned long length; DOMString item(in unsigned long index); }; interface CSS2Properties { attribute DOMString azimuth; attribute DOMString background; attribute DOMString backgroundAttachment; attribute DOMString backgroundColor; attribute DOMString backgroundImage; attribute DOMString backgroundPosition; attribute DOMString backgroundRepeat; attribute DOMString border; attribute DOMString borderCollapse; attribute DOMString borderColor; attribute DOMString borderSpacing; attribute DOMString borderStyle; attribute DOMString borderTop; attribute DOMString borderRight; attribute DOMString borderBottom; attribute DOMString borderLeft; attribute DOMString borderTopColor; attribute DOMString borderRightColor; attribute DOMString borderBottomColor; attribute DOMString borderLeftColor; attribute DOMString borderTopStyle; attribute DOMString borderRightStyle; attribute DOMString borderBottomStyle; attribute DOMString borderLeftStyle; attribute DOMString borderTopWidth; attribute DOMString borderRightWidth; attribute DOMString borderBottomWidth; attribute DOMString borderLeftWidth; attribute DOMString borderWidth; attribute DOMString bottom; attribute DOMString captionSide; attribute DOMString clear; attribute DOMString clip; attribute DOMString color; attribute DOMString content; attribute DOMString counterIncrement; attribute DOMString counterReset; attribute DOMString cue; attribute DOMString cueAfter; attribute DOMString cueBefore; attribute DOMString cursor; attribute DOMString direction; attribute DOMString display; attribute DOMString elevation; attribute DOMString emptyCells; attribute DOMString cssFloat; attribute DOMString font; attribute DOMString fontFamily; attribute DOMString fontSize; attribute DOMString fontSizeAdjust; attribute DOMString fontStretch; attribute DOMString fontStyle; attribute DOMString fontVariant; attribute DOMString fontWeight; attribute DOMString height; attribute DOMString left; attribute DOMString letterSpacing; attribute DOMString lineHeight; attribute DOMString listStyle; attribute DOMString listStyleImage; attribute DOMString listStylePosition; attribute DOMString listStyleType; attribute DOMString margin; attribute DOMString marginTop; attribute DOMString marginRight; attribute DOMString marginBottom; attribute DOMString marginLeft; attribute DOMString markerOffset; attribute DOMString marks; attribute DOMString maxHeight; attribute DOMString maxWidth; attribute DOMString minHeight; attribute DOMString minWidth; attribute DOMString orphans; attribute DOMString outline; attribute DOMString outlineColor; attribute DOMString outlineStyle; attribute DOMString outlineWidth; attribute DOMString overflow; attribute DOMString padding; attribute DOMString paddingTop; attribute DOMString paddingRight; attribute DOMString paddingBottom; attribute DOMString paddingLeft; attribute DOMString page; attribute DOMString pageBreakAfter; attribute DOMString pageBreakBefore; attribute DOMString pageBreakInside; attribute DOMString pause; attribute DOMString pauseAfter; attribute DOMString pauseBefore; attribute DOMString pitch; attribute DOMString pitchRange; attribute DOMString playDuring; attribute DOMString position; attribute DOMString quotes; attribute DOMString richness; attribute DOMString right; attribute DOMString size; attribute DOMString speak; attribute DOMString speakHeader; attribute DOMString speakNumeral; attribute DOMString speakPunctuation; attribute DOMString speechRate; attribute DOMString stress; attribute DOMString tableLayout; attribute DOMString textAlign; attribute DOMString textDecoration; attribute DOMString textIndent; attribute DOMString textShadow; attribute DOMString textTransform; attribute DOMString top; attribute DOMString unicodeBidi; attribute DOMString verticalAlign; attribute DOMString visibility; attribute DOMString voiceFamily; attribute DOMString volume; attribute DOMString whiteSpace; attribute DOMString widows; attribute DOMString width; attribute DOMString wordSpacing; attribute DOMString zIndex; }; }; #endif // _CSS_IDL_ C.2: Document Object Model Level 2 Events events.idl: // File: events.idl #ifndef _EVENTS_IDL_ #define _EVENTS_IDL_ #include "dom.idl" #pragma prefix "dom.w3c.org" module events { typedef dom::DOMString DOMString; typedef dom::Node Node; interface EventCapturer { void captureEvent(in DOMString type); void releaseEvent(in DOMString type); void routeEvent(); }; interface Event { attribute DOMString type; attribute Node target; attribute boolean cancelBubble; attribute boolean returnValue; }; interface UIEvent : Event { attribute long screenX; attribute long screenY; attribute long clientX; attribute long clientY; attribute boolean altKey; attribute boolean ctrlKey; attribute boolean shiftKey; attribute unsigned long keyCode; attribute unsigned long charCode; attribute unsigned short button; }; }; #endif // _EVENTS_IDL_ C.3: Document Object Model Level 2 Filters and Iterators fi.idl: // File: fi.idl #ifndef _FI_IDL_ #define _FI_IDL_ #include "dom.idl" #pragma prefix "dom.w3c.org" module fi { typedef dom::Node Node; interface NodeIterator { Node nextNode(); void reset(); }; interface NodeFilter { boolean acceptNode(in Node n); }; }; #endif // _FI_IDL_ C.4: Document Object Model Level 2 Range range.idl: // File: range.idl #ifndef _RANGE_IDL_ #define _RANGE_IDL_ #include "dom.idl" #pragma prefix "dom.w3c.org" module range { typedef dom::Node Node; typedef dom::DocumentFragment DocumentFragment; typedef dom::DOMString DOMString; exception RangeException { unsigned short code; }; // RangeExceptionCode const unsigned short BAD_ENDPOINTS_ERR = 201; const unsigned short INVALID_NODE_TYPE_ERR = 202; const unsigned short NULL_PARENT_ERR = 203; interface Range { readonly attribute Node startParent; readonly attribute long startOffset; readonly attribute Node endParent; readonly attribute long endOffset; readonly attribute boolean isCollapsed; readonly attribute Node commonParent; void setStart(in Node parent, in long offset) raises(RangeException); void setEnd(in Node parent, in long offset) raises(RangeException); void setStartBefore(in Node sibling) raises(RangeException); void setStartAfter(in Node sibling) raises(RangeException); void setEndBefore(in Node sibling) raises(RangeException); void setEndAfter(in Node sibling) raises(RangeException); void collapse(in boolean toStart); void selectNode(in Node n) raises(RangeException); void selectNodeContents(in Node n) raises(RangeException); typedef enum CompareHow_ { StartToStart, StartToEnd, EndToEnd, EndToStart } CompareHow; short compareEndPoints(in CompareHow how, in Range sourceRange) raises(DOMException); void deleteContents() raises(DOMException); DocumentFragment extractContents() raises(DOMException); DocumentFragment cloneContents(); void insertNode(in Node n) raises(DOMException, RangeException); void surroundContents(in Node n) raises(DOMException, RangeException); Range cloneRange(); DOMString toString(); }; }; #endif // _RANGE_IDL_ Appendix D: Java Language Binding This appendix contains the complete Java bindings for the Level 2 Document Object Model. The definitions are divided into CSS , Events , Filters and Iterators , and Range . D.1: Document Object Model Level 2 CSS org/w3c/dom/css/StyleSheet.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface StyleSheet { public String getType(); public boolean getDisabled(); public void setDisabled(boolean disabled); public Node getOwningNode(); public StyleSheet getParentStyleSheet(); public String getHref(); public String getTitle(); public String getMedia(); } org/w3c/dom/css/StyleSheetCollection.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface StyleSheetCollection { public int getLength(); public StyleSheet item(int index); } org/w3c/dom/css/CSSStyleSheet.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSStyleSheet extends StyleSheet { public CSSRuleCollection getCssRules(); public int insertRule(String rule, int index) throws DOMException; public void deleteRule(int index) throws DOMException; } org/w3c/dom/css/CSSRuleCollection.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSRuleCollection { public int getLength(); public CSSRule item(int index); } org/w3c/dom/css/CSSRule.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSRule { // RuleType public static final short UNKNOWN_RULE = 0; public static final short STYLE_RULE = 1; public static final short IMPORT_RULE = 2; public static final short MEDIA_RULE = 3; public static final short FONT_FACE_RULE = 4; public static final short PAGE_RULE = 5; public short getType(); public String getCssText(); public void setCssText(String cssText); public CSSStyleSheet getParentStyleSheet(); } org/w3c/dom/css/CSSStyleRule.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSStyleRule extends CSSRule { public String getSelectorText(); public void setSelectorText(String selectorText); public CSSStyleDeclaration getStyle(); } org/w3c/dom/css/CSSMediaRule.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSMediaRule extends CSSRule { public String getMediaTypes(); public void setMediaTypes(String mediaTypes); public CSSRuleCollection getCssRules(); public int insertRule(String rule, int index) throws DOMException; public void deleteRule(int index); } org/w3c/dom/css/CSSFontFaceRule.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSFontFaceRule extends CSSRule { public CSSStyleDeclaration getStyle(); } org/w3c/dom/css/CSSPageRule.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSPageRule extends CSSRule { public String getSelectorText(); public void setSelectorText(String selectorText); public CSSStyleDeclaration getStyle(); } org/w3c/dom/css/CSSImportRule.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSImportRule extends CSSRule { public String getHref(); public void setHref(String href); public String getMedia(); public void setMedia(String media); public CSSStyleSheet getStyleSheet(); } org/w3c/dom/css/CSSUnknownRule.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSUnknownRule extends CSSRule { } org/w3c/dom/css/CSSStyleDeclaration.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSSStyleDeclaration { public String getCssText(); public void setCssText(String cssText); public String getPropertyValue(String propertyName); public String getPropertyPriority(String propertyName); public void setProperty(String propertyName, String value, String priority) throws DOMException; public int getLength(); public String item(int index); } org/w3c/dom/css/CSS2Properties.java: package org.w3c.dom.css; import org.w3c.dom.*; public interface CSS2Properties { public String getAzimuth(); public void setAzimuth(String azimuth); public String getBackground(); public void setBackground(String background); public String getBackgroundAttachment(); public void setBackgroundAttachment(String backgroundAttachment); public String getBackgroundColor(); public void setBackgroundColor(String backgroundColor); public String getBackgroundImage(); public void setBackgroundImage(String backgroundImage); public String getBackgroundPosition(); public void setBackgroundPosition(String backgroundPosition); public String getBackgroundRepeat(); public void setBackgroundRepeat(String backgroundRepeat); public String getBorder(); public void setBorder(String border); public String getBorderCollapse(); public void setBorderCollapse(String borderCollapse); public String getBorderColor(); public void setBorderColor(String borderColor); public String getBorderSpacing(); public void setBorderSpacing(String borderSpacing); public String getBorderStyle(); public void setBorderStyle(String borderStyle); public String getBorderTop(); public void setBorderTop(String borderTop); public String getBorderRight(); public void setBorderRight(String borderRight); public String getBorderBottom(); public void setBorderBottom(String borderBottom); public String getBorderLeft(); public void setBorderLeft(String borderLeft); public String getBorderTopColor(); public void setBorderTopColor(String borderTopColor); public String getBorderRightColor(); public void setBorderRightColor(String borderRightColor); public String getBorderBottomColor(); public void setBorderBottomColor(String borderBottomColor); public String getBorderLeftColor(); public void setBorderLeftColor(String borderLeftColor); public String getBorderTopStyle(); public void setBorderTopStyle(String borderTopStyle); public String getBorderRightStyle(); public void setBorderRightStyle(String borderRightStyle); public String getBorderBottomStyle(); public void setBorderBottomStyle(String borderBottomStyle); public String getBorderLeftStyle(); public void setBorderLeftStyle(String borderLeftStyle); public String getBorderTopWidth(); public void setBorderTopWidth(String borderTopWidth); public String getBorderRightWidth(); public void setBorderRightWidth(String borderRightWidth); public String getBorderBottomWidth(); public void setBorderBottomWidth(String borderBottomWidth); public String getBorderLeftWidth(); public void setBorderLeftWidth(String borderLeftWidth); public String getBorderWidth(); public void setBorderWidth(String borderWidth); public String getBottom(); public void setBottom(String bottom); public String getCaptionSide(); public void setCaptionSide(String captionSide); public String getClear(); public void setClear(String clear); public String getClip(); public void setClip(String clip); public String getColor(); public void setColor(String color); public String getContent(); public void setContent(String content); public String getCounterIncrement(); public void setCounterIncrement(String counterIncrement); public String getCounterReset(); public void setCounterReset(String counterReset); public String getCue(); public void setCue(String cue); public String getCueAfter(); public void setCueAfter(String cueAfter); public String getCueBefore(); public void setCueBefore(String cueBefore); public String getCursor(); public void setCursor(String cursor); public String getDirection(); public void setDirection(String direction); public String getDisplay(); public void setDisplay(String display); public String getElevation(); public void setElevation(String elevation); public String getEmptyCells(); public void setEmptyCells(String emptyCells); public String getCssFloat(); public void setCssFloat(String cssFloat); public String getFont(); public void setFont(String font); public String getFontFamily(); public void setFontFamily(String fontFamily); public String getFontSize(); public void setFontSize(String fontSize); public String getFontSizeAdjust(); public void setFontSizeAdjust(String fontSizeAdjust); public String getFontStretch(); public void setFontStretch(String fontStretch); public String getFontStyle(); public void setFontStyle(String fontStyle); public String getFontVariant(); public void setFontVariant(String fontVariant); public String getFontWeight(); public void setFontWeight(String fontWeight); public String getHeight(); public void setHeight(String height); public String getLeft(); public void setLeft(String left); public String getLetterSpacing(); public void setLetterSpacing(String letterSpacing); public String getLineHeight(); public void setLineHeight(String lineHeight); public String getListStyle(); public void setListStyle(String listStyle); public String getListStyleImage(); public void setListStyleImage(String listStyleImage); public String getListStylePosition(); public void setListStylePosition(String listStylePosition); public String getListStyleType(); public void setListStyleType(String listStyleType); public String getMargin(); public void setMargin(String margin); public String getMarginTop(); public void setMarginTop(String marginTop); public String getMarginRight(); public void setMarginRight(String marginRight); public String getMarginBottom(); public void setMarginBottom(String marginBottom); public String getMarginLeft(); public void setMarginLeft(String marginLeft); public String getMarkerOffset(); public void setMarkerOffset(String markerOffset); public String getMarks(); public void setMarks(String marks); public String getMaxHeight(); public void setMaxHeight(String maxHeight); public String getMaxWidth(); public void setMaxWidth(String maxWidth); public String getMinHeight(); public void setMinHeight(String minHeight); public String getMinWidth(); public void setMinWidth(String minWidth); public String getOrphans(); public void setOrphans(String orphans); public String getOutline(); public void setOutline(String outline); public String getOutlineColor(); public void setOutlineColor(String outlineColor); public String getOutlineStyle(); public void setOutlineStyle(String outlineStyle); public String getOutlineWidth(); public void setOutlineWidth(String outlineWidth); public String getOverflow(); public void setOverflow(String overflow); public String getPadding(); public void setPadding(String padding); public String getPaddingTop(); public void setPaddingTop(String paddingTop); public String getPaddingRight(); public void setPaddingRight(String paddingRight); public String getPaddingBottom(); public void setPaddingBottom(String paddingBottom); public String getPaddingLeft(); public void setPaddingLeft(String paddingLeft); public String getPage(); public void setPage(String page); public String getPageBreakAfter(); public void setPageBreakAfter(String pageBreakAfter); public String getPageBreakBefore(); public void setPageBreakBefore(String pageBreakBefore); public String getPageBreakInside(); public void setPageBreakInside(String pageBreakInside); public String getPause(); public void setPause(String pause); public String getPauseAfter(); public void setPauseAfter(String pauseAfter); public String getPauseBefore(); public void setPauseBefore(String pauseBefore); public String getPitch(); public void setPitch(String pitch); public String getPitchRange(); public void setPitchRange(String pitchRange); public String getPlayDuring(); public void setPlayDuring(String playDuring); public String getPosition(); public void setPosition(String position); public String getQuotes(); public void setQuotes(String quotes); public String getRichness(); public void setRichness(String richness); public String getRight(); public void setRight(String right); public String getSize(); public void setSize(String size); public String getSpeak(); public void setSpeak(String speak); public String getSpeakHeader(); public void setSpeakHeader(String speakHeader); public String getSpeakNumeral(); public void setSpeakNumeral(String speakNumeral); public String getSpeakPunctuation(); public void setSpeakPunctuation(String speakPunctuation); public String getSpeechRate(); public void setSpeechRate(String speechRate); public String getStress(); public void setStress(String stress); public String getTableLayout(); public void setTableLayout(String tableLayout); public String getTextAlign(); public void setTextAlign(String textAlign); public String getTextDecoration(); public void setTextDecoration(String textDecoration); public String getTextIndent(); public void setTextIndent(String textIndent); public String getTextShadow(); public void setTextShadow(String textShadow); public String getTextTransform(); public void setTextTransform(String textTransform); public String getTop(); public void setTop(String top); public String getUnicodeBidi(); public void setUnicodeBidi(String unicodeBidi); public String getVerticalAlign(); public void setVerticalAlign(String verticalAlign); public String getVisibility(); public void setVisibility(String visibility); public String getVoiceFamily(); public void setVoiceFamily(String voiceFamily); public String getVolume(); public void setVolume(String volume); public String getWhiteSpace(); public void setWhiteSpace(String whiteSpace); public String getWidows(); public void setWidows(String widows); public String getWidth(); public void setWidth(String width); public String getWordSpacing(); public void setWordSpacing(String wordSpacing); public String getZIndex(); public void setZIndex(String zIndex); } D.2: Document Object Model Level 2 Events org/w3c/dom/events/EventCapturer.java: package org.w3c.dom.events; import org.w3c.dom.*; public interface EventCapturer { public void captureEvent(String type); public void releaseEvent(String type); public void routeEvent(); } org/w3c/dom/events/Event.java: package org.w3c.dom.events; import org.w3c.dom.*; public interface Event { public String getType(); public void setType(String type); public Node getTarget(); public void setTarget(Node target); public boolean getCancelBubble(); public void setCancelBubble(boolean cancelBubble); public boolean getReturnValue(); public void setReturnValue(boolean returnValue); } org/w3c/dom/events/UIEvent.java: package org.w3c.dom.events; import org.w3c.dom.*; public interface UIEvent extends Event { public int getScreenX(); public void setScreenX(int screenX); public int getScreenY(); public void setScreenY(int screenY); public int getClientX(); public void setClientX(int clientX); public int getClientY(); public void setClientY(int clientY); public boolean getAltKey(); public void setAltKey(boolean altKey); public boolean getCtrlKey(); public void setCtrlKey(boolean ctrlKey); public boolean getShiftKey(); public void setShiftKey(boolean shiftKey); public int getKeyCode(); public void setKeyCode(int keyCode); public int getCharCode(); public void setCharCode(int charCode); public short getButton(); public void setButton(short button); } D.3: Document Object Model Level 2 Filters and Iterators org/w3c/dom/fi/NodeIterator.java: package org.w3c.dom.fi; import org.w3c.dom.*; public interface NodeIterator { public Node nextNode(); public void reset(); } org/w3c/dom/fi/NodeFilter.java: package org.w3c.dom.fi; import org.w3c.dom.*; public interface NodeFilter { public boolean acceptNode(Node n); } D.4: Document Object Model Level 2 Range org/w3c/dom/range/RangeException.java: package org.w3c.dom.range; import org.w3c.dom.*; public abstract class RangeException extends RuntimeException { public RangeException(short code, String message) { super(message); this.code = code; } public short code; // RangeExceptionCode public static final short BAD_ENDPOINTS_ERR = 201; public static final short INVALID_NODE_TYPE_ERR = 202; public static final short NULL_PARENT_ERR = 203; } org/w3c/dom/range/Range.java: package org.w3c.dom.range; import org.w3c.dom.*; public interface Range { public Node getStartParent(); public int getStartOffset(); public Node getEndParent(); public int getEndOffset(); public boolean getIsCollapsed(); public Node getCommonParent(); public void setStart(Node parent, int offset) throws RangeException; public void setEnd(Node parent, int offset) throws RangeException; public void setStartBefore(Node sibling) throws RangeException; public void setStartAfter(Node sibling) throws RangeException; public void setEndBefore(Node sibling) throws RangeException; public void setEndAfter(Node sibling) throws RangeException; public void collapse(boolean toStart); public void selectNode(Node n) throws RangeException; public void selectNodeContents(Node n) throws RangeException; public static final int StartToStart = 1; public static final int StartToEnd = 2; public static final int EndToEnd = 3; public static final int EndToStart = 4; public short compareEndPoints(int how, Range sourceRange) throws DOMException; public void deleteContents() throws DOMException; public DocumentFragment extractContents() throws DOMException; public DocumentFragment cloneContents(); public void insertNode(Node n) throws DOMException, RangeException; public void surroundContents(Node n) throws DOMException, RangeException; public Range cloneRange(); public String toString(); } Appendix E: ECMA Script Language Binding This appendix contains the complete ECMA Script binding for the Level 2 Document Object Model definitions. The definitions are divided into CSS , Events , Filters and Iterators , and Range . E.1: Document Object Model Level 2 CSS Object StyleSheet The StyleSheet object has the following properties: type This property is of type String. disabled This property is of type boolean. owningNode This property is of type Node. parentStyleSheet This property is of type StyleSheet. href This property is of type String. title This property is of type String. media This property is of type String. Object StyleSheetCollection The StyleSheetCollection object has the following properties: length This property is of type int. The StyleSheetCollection object has the following methods: item(index) This method returns a StyleSheet. The index parameter is of type unsigned long. Object CSSStyleSheet CSSStyleSheet has the all the properties and methods of StyleSheet as well as the properties and methods defined below. The CSSStyleSheet object has the following properties: cssRules This property is of type CSSRuleCollection. The CSSStyleSheet object has the following methods: insertRule(rule, index) This method returns a unsigned long. The rule parameter is of type DOMString. The index parameter is of type unsigned long. deleteRule(index) This method returns a void. The index parameter is of type unsigned long. Object CSSRuleCollection The CSSRuleCollection object has the following properties: length This property is of type int. The CSSRuleCollection object has the following methods: item(index) This method returns a CSSRule. The index parameter is of type unsigned long. Object CSSRule The CSSRule object has the following properties: type This property is of type short. cssText This property is of type String. parentStyleSheet This property is of type CSSStyleSheet. Object CSSStyleRule CSSStyleRule has the all the properties and methods of CSSRule as well as the properties and methods defined below. The CSSStyleRule object has the following properties: selectorText This property is of type String. style This property is of type CSSStyleDeclaration. Object CSSMediaRule CSSMediaRule has the all the properties and methods of CSSRule as well as the properties and methods defined below. The CSSMediaRule object has the following properties: mediaTypes This property is of type String. cssRules This property is of type CSSRuleCollection. The CSSMediaRule object has the following methods: insertRule(rule, index) This method returns a unsigned long. The rule parameter is of type DOMString. The index parameter is of type unsigned long. deleteRule(index) This method returns a void. The index parameter is of type unsigned long. Object CSSFontFaceRule CSSFontFaceRule has the all the properties and methods of CSSRule as well as the properties and methods defined below. The CSSFontFaceRule object has the following properties: style This property is of type CSSStyleDeclaration. Object CSSPageRule CSSPageRule has the all the properties and methods of CSSRule as well as the properties and methods defined below. The CSSPageRule object has the following properties: selectorText This property is of type String. style This property is of type CSSStyleDeclaration. Object CSSImportRule CSSImportRule has the all the properties and methods of CSSRule as well as the properties and methods defined below. The CSSImportRule object has the following properties: href This property is of type String. media This property is of type String. styleSheet This property is of type CSSStyleSheet. Object CSSUnknownRule CSSUnknownRule has the all the properties and methods of CSSRule as well as the properties and methods defined below. Object CSSStyleDeclaration The CSSStyleDeclaration object has the following properties: cssText This property is of type String. length This property is of type int. The CSSStyleDeclaration object has the following methods: getPropertyValue(propertyName) This method returns a DOMString. The propertyName parameter is of type DOMString. getPropertyPriority(propertyName) This method returns a DOMString. The propertyName parameter is of type DOMString. setProperty(propertyName, value, priority) This method returns a void. The propertyName parameter is of type DOMString. The value parameter is of type DOMString. The priority parameter is of type DOMString. item(index) This method returns a DOMString. The index parameter is of type unsigned long. Object CSS2Properties The CSS2Properties object has the following properties: azimuth This property is of type String. background This property is of type String. backgroundAttachment This property is of type String. backgroundColor This property is of type String. backgroundImage This property is of type String. backgroundPosition This property is of type String. backgroundRepeat This property is of type String. border This property is of type String. borderCollapse This property is of type String. borderColor This property is of type String. borderSpacing This property is of type String. borderStyle This property is of type String. borderTop This property is of type String. borderRight This property is of type String. borderBottom This property is of type String. borderLeft This property is of type String. borderTopColor This property is of type String. borderRightColor This property is of type String. borderBottomColor This property is of type String. borderLeftColor This property is of type String. borderTopStyle This property is of type String. borderRightStyle This property is of type String. borderBottomStyle This property is of type String. borderLeftStyle This property is of type String. borderTopWidth This property is of type String. borderRightWidth This property is of type String. borderBottomWidth This property is of type String. borderLeftWidth This property is of type String. borderWidth This property is of type String. bottom This property is of type String. captionSide This property is of type String. clear This property is of type String. clip This property is of type String. color This property is of type String. content This property is of type String. counterIncrement This property is of type String. counterReset This property is of type String. cue This property is of type String. cueAfter This property is of type String. cueBefore This property is of type String. cursor This property is of type String. direction This property is of type String. display This property is of type String. elevation This property is of type String. emptyCells This property is of type String. cssFloat This property is of type String. font This property is of type String. fontFamily This property is of type String. fontSize This property is of type String. fontSizeAdjust This property is of type String. fontStretch This property is of type String. fontStyle This property is of type String. fontVariant This property is of type String. fontWeight This property is of type String. height This property is of type String. left This property is of type String. letterSpacing This property is of type String. lineHeight This property is of type String. listStyle This property is of type String. listStyleImage This property is of type String. listStylePosition This property is of type String. listStyleType This property is of type String. margin This property is of type String. marginTop This property is of type String. marginRight This property is of type String. marginBottom This property is of type String. marginLeft This property is of type String. markerOffset This property is of type String. marks This property is of type String. maxHeight This property is of type String. maxWidth This property is of type String. minHeight This property is of type String. minWidth This property is of type String. orphans This property is of type String. outline This property is of type String. outlineColor This property is of type String. outlineStyle This property is of type String. outlineWidth This property is of type String. overflow This property is of type String. padding This property is of type String. paddingTop This property is of type String. paddingRight This property is of type String. paddingBottom This property is of type String. paddingLeft This property is of type String. page This property is of type String. pageBreakAfter This property is of type String. pageBreakBefore This property is of type String. pageBreakInside This property is of type String. pause This property is of type String. pauseAfter This property is of type String. pauseBefore This property is of type String. pitch This property is of type String. pitchRange This property is of type String. playDuring This property is of type String. position This property is of type String. quotes This property is of type String. richness This property is of type String. right This property is of type String. size This property is of type String. speak This property is of type String. speakHeader This property is of type String. speakNumeral This property is of type String. speakPunctuation This property is of type String. speechRate This property is of type String. stress This property is of type String. tableLayout This property is of type String. textAlign This property is of type String. textDecoration This property is of type String. textIndent This property is of type String. textShadow This property is of type String. textTransform This property is of type String. top This property is of type String. unicodeBidi This property is of type String. verticalAlign This property is of type String. visibility This property is of type String. voiceFamily This property is of type String. volume This property is of type String. whiteSpace This property is of type String. widows This property is of type String. width This property is of type String. wordSpacing This property is of type String. zIndex This property is of type String. E.2: Document Object Model Level 2 Events Object EventCapturer The EventCapturer object has the following methods: captureEvent(type) This method returns a void. The type parameter is of type DOMString. releaseEvent(type) This method returns a void. The type parameter is of type DOMString. routeEvent() This method returns a void. Object Event The Event object has the following properties: type This property is of type String. target This property is of type Node. cancelBubble This property is of type boolean. returnValue This property is of type boolean. Object UIEvent UIEvent has the all the properties and methods of Event as well as the properties and methods defined below. The UIEvent object has the following properties: screenX This property is of type long. screenY This property is of type long. clientX This property is of type long. clientY This property is of type long. altKey This property is of type boolean. ctrlKey This property is of type boolean. shiftKey This property is of type boolean. keyCode This property is of type int. charCode This property is of type int. button This property is of type short. E.3: Document Object Model Level 2 Filters and Iterators Object NodeIterator The NodeIterator object has the following methods: nextNode() This method returns a Node. reset() This method returns a void. Object NodeFilter The NodeFilter object has the following methods: acceptNode(n) This method returns a boolean. The n parameter is of type Node. E.4: Document Object Model Level 2 Range Object Range The Range object has the following properties: startParent This property is of type Node. startOffset This property is of type long. endParent This property is of type Node. endOffset This property is of type long. isCollapsed This property is of type boolean. commonParent This property is of type Node. The Range object has the following methods: setStart(parent, offset) This method returns a void. The parent parameter is of type Node. The offset parameter is of type long. setEnd(parent, offset) This method returns a void. The parent parameter is of type Node. The offset parameter is of type long. setStartBefore(sibling) This method returns a void. The sibling parameter is of type Node. setStartAfter(sibling) This method returns a void. The sibling parameter is of type Node. setEndBefore(sibling) This method returns a void. The sibling parameter is of type Node. setEndAfter(sibling) This method returns a void. The sibling parameter is of type Node. collapse(toStart) This method returns a void. The toStart parameter is of type boolean. selectNode(n) This method returns a void. The n parameter is of type Node. selectNodeContents(n) This method returns a void. The n parameter is of type Node. compareEndPoints(how, sourceRange) This method returns a short. The how parameter is of type CompareHow. The sourceRange parameter is of type Range. deleteContents() This method returns a void. extractContents() This method returns a DocumentFragment. cloneContents() This method returns a DocumentFragment. insertNode(n) This method returns a void. The n parameter is of type Node. surroundContents(n) This method returns a void. The n parameter is of type Node. cloneRange() This method returns a Range. toString() This method returns a DOMString. References DOM-Level-1 W3C (World Wide Web Consortium) DOM Level 1 Specification. See http://www.w3.org/TR/REC-DOM-Level-1 . XML W3C (World Wide Web Consortium) Extensible Markup Language (XML) 1.0. See http://www.w3.org/TR/REC-xml . HTML4.0 W3C (World Wide Web Consortium) HTML 4.0 Specification. See http://www.w3.org/TR/REC-html40 . Unicode The Unicode Consortium. The Unicode Standard, Version 2.0. Reading, Mass.: Addison-Wesley Developers Press, 1996. CORBA OMG (Object Management Group) The Common Object Request Broker: Architecture and Specification. See http://www.omg.org/corba/corbiiop.htm . Java Sun The Java Language Specification. See http://java.sun.com/docs/books/jls/ . ECMAScript ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. See http://www.ecma.ch/stand/ECMA-262.htm . Index BAD_ENDPOINTS_ERR 1 CSS2Properties 1 CSSFontFaceRule 1 CSSImportRule 1 CSSMediaRule 1 CSSPageRule 1 CSSRule 1 CSSRuleCollection 1 CSSStyleDeclaration 1 CSSStyleRule 1 CSSStyleSheet 1 CSSUnknownRule 1 Event 1 EventCapturer 1 FONT_FACE_RULE 1 IMPORT_RULE 1 INVALID_NODE_TYPE_ERR MEDIA_RULE 1 1 NULL_PARENT_ERR 1 NodeFilter 1 NodeIterator 1 PAGE_RULE 1 Range 1 RangeException 1 STYLE_RULE 1 StyleSheet 1 StyleSheetCollection 1 UIEvent 1 UNKNOWN_RULE 1 acceptNode 1 altKey 1 azimuth 1 background 1 backgroundAttachment 1 backgroundColor 1 backgroundImage 1 backgroundPosition 1 backgroundRepeat 1 border 1 borderBottom 1 borderBottomColor 1 borderBottomStyle 1 borderBottomWidth 1 borderCollapse 1 borderColor 1 borderLeft 1 borderLeftColor 1 borderLeftStyle 1 borderLeftWidth 1 borderRight 1 borderRightColor 1 borderRightStyle 1 borderRightWidth 1 borderSpacing 1 borderStyle 1 borderTop 1 borderTopColor 1 borderTopStyle 1 borderTopWidth 1 borderWidth 1 bottom 1 button 1 cancelBubble 1 captionSide 1 captureEvent 1 charCode 1 clear 1 clientX 1 clientY 1 clip 1 cloneContents 1 cloneRange 1 collapse 1 color 1 commonParent 1 compareEndPoints 1 content 1 counterIncrement 1 counterReset 1 cssFloat 1 cssRules 1, 2 cssText 1, 2 ctrlKey 1 cue 1 cueAfter 1 cueBefore 1 cursor 1 deleteContents 1 deleteRule 1, 2 direction 1 disabled 1 display 1 elevation 1 emptyCells 1 endOffset 1 endParent 1 extractContents 1 font 1 fontFamily 1 fontSize 1 fontSizeAdjust 1 fontStretch 1 fontStyle 1 fontVariant 1 fontWeight 1 getPropertyPriority 1 getPropertyValue 1 height 1 href 1, 2 insertNode 1 insertRule 1, 2 isCollapsed 1 item 1, 2, 3 keyCode 1 left 1 length 1, 2, 3 letterSpacing 1 lineHeight 1 listStyle 1 listStyleImage 1 listStylePosition 1 listStyleType 1 margin 1 marginBottom 1 marginLeft 1 marginRight 1 marginTop 1 markerOffset 1 marks 1 maxHeight 1 maxWidth 1 media 1, 2 mediaTypes 1 minHeight 1 minWidth 1 nextNode 1 orphans 1 outline 1 outlineColor 1 outlineStyle 1 outlineWidth 1 overflow 1 owningNode 1 padding 1 paddingBottom 1 paddingLeft 1 paddingRight 1 paddingTop 1 page 1 pageBreakAfter 1 pageBreakBefore 1 pageBreakInside 1 parentStyleSheet 1, 2 pause 1 pauseAfter 1 pauseBefore 1 pitch 1 pitchRange 1 playDuring 1 position 1 quotes 1 releaseEvent 1 reset 1 returnValue 1 richness 1 right 1 routeEvent 1 screenX 1 screenY 1 selectNode 1 selectNodeContents 1 selectorText 1, 2 setEnd 1 setEndAfter 1 setEndBefore 1 setProperty 1 setStart 1 setStartAfter 1 setStartBefore 1 shiftKey 1 size 1 speak 1 speakHeader 1 speakNumeral 1 speakPunctuation 1 speechRate 1 startOffset 1 startParent 1 stress 1 style 1, 2, 3 styleSheet 1 surroundContents 1 tableLayout 1 target 1 textAlign 1 textDecoration 1 textIndent 1 textShadow 1 textTransform 1 title 1 toString 1 top 1 type 1, 2, 3 unicodeBidi 1 verticalAlign 1 visibility 1 voiceFamily 1 volume 1 whiteSpace 1 widows 1 width 1 wordSpacing 1 zIndex 1