 |  |
| |
This part of the book is a reference section that documents the interfaces, methods, and properties defined by the W3C Level 1 and Level 2 DOM standards. Intermediate and advanced programmers who are writing for the newest generation of standards-compliant web browsers will use this reference section, in conjunction with the core and client-side JavaScript references in Part III and Part IV. The introduction and sample reference page explain how to use and get the most out of this reference section. There are significant differences between this reference section and the other two, and you should read this introduction carefully so you can fully understand the reference information it contains.
Like the core and client-side references, this reference section is arranged alphabetically. The reference pages for the methods and properties of DOM interfaces are alphabetized by their full names, which include the names of the interfaces that define them. For example, if you want to read about the appendChild( ) method of the Node interface, you would look under "Node.appendChild," not just "appendChild."
To save space in this enlarged fourth edition of the book, properties in this reference section do not have reference pages of their own (all interfaces and methods do have their own reference pages, however). Instead, each property is completely documented in the reference page for the interface that defines it. For example, you can read about the tagName property of the Element interface in the "Element" reference page.
Sometimes you may find that you don't know the name of the interface that defines the method or property you want to look up, or you may not be sure which of the three reference sections to look up a class or interface in. Part VI of this book is a special index designed to help with these situations. Look up the name of a class, interface, method, or property, and it will tell you which reference section to look in and which class to look under in that section. For example, if you look up "Document," it will tell you that both the client-side and DOM reference sections have entries under that name. And if you look up the name "firstChild," it will tell you that firstChild is a property of Node, which you can read about in this DOM reference section.
Once you've found the reference page you're looking for, you shouldn't have much difficulty finding the information you need. Because the DOM standard is intended to work with languages other than JavaScript, however, it was written with typed languages (such as Java and C++) in mind. Although JavaScript is an untyped language, the property and method type information defined by the standard is still quite useful and is included in the reference pages in this section. This means that method and property synopses in this section use a syntax that is more like Java than like JavaScript. What follows is a sample reference page titled "Sample Entry" that demonstrates the structure of each reference page and explains how to interpret the information presented in each section. Even if you are already well familiar with the third edition of this book, take the time to read this page before diving into the DOM reference section.
| Sample Entry | how to read DOM reference pages |
Availability
Inherits from
Every reference entry begins with a title block like that above. The entries are alphabetized by title. The short description, shown next to the title, gives you a quick summary of the item documented in the entry; it can help you quickly decide if you're interested in reading the rest of the page.
The information in the "Availability" section tells you what level and what module of the DOM standard defines the interface or method. Since properties do not have their own reference pages, they do not have availability information. If the availability of a property is different from the availability of the interface that defines it, this fact is noted in the description of the property.
DOM interfaces can inherit properties and methods from other interfaces. If a DOM interface inherits from another interface, the inheritance hierarchy is shown in the "Inherits from" section. For example, the "Inherits from" information for the HTMLElement interface looks like this:
Node 
Element HTMLElement
This indicates that HTMLElement inherits from the Element interface, which in turn inherits from the Node interface. When you see this section, you may also want to look up the other listed interfaces.
This section contains the opposite of the "Inherits from" information: it lists any interfaces that inherit from this one. For example, the "Subinterfaces" section of the reference page for the Element interface specifies that HTMLElement is a subinterface of Element and inherits Element's methods and properties.
The modular structure of the DOM standard means that some interfaces have been broken into multiple separate interfaces, so that implementations have to implement only the interfaces that are part of the modules they support. It is common for an object that implements one interface (such as Document) to also implement several other simple interfaces (such as DocumentCSS, DocumentEvent, and DocumentViews) that provide functionality specific to other modules. When an interface has minor interfaces that are intended to be implemented along with it, those minor interfaces are listed in this section.
Some DOM interfaces define a set of constants that serve as the values for a property or as the arguments to a method of that interface. The Node interface, for example, defines important constants to serve as the set of legal values for the nodeType property of all Document nodes. When an interface defines constants, they are listed and documented in this section. The listings include the type, the name, and the value (in that order) of each constant. See the Section section for a discussion of the syntax used in these listings. Note that constants are static properties of the interface itself, not of instances of that interface.
If the reference page documents an interface, this section lists and documents the properties defined by that interface. Each entry in the list specifies the name and type of the property and may also include other keywords that provide additional information about the property. Note that in this Java-style syntax, the name of the property comes last, and all the information that precedes the name provides type and other information about the property. For example, the HTMLTableElement and HTMLTableCellElement interfaces define properties that include the following:
If the reference page documents an interface, this section lists the names of the interface's methods and provides a short description of each. Full documentation for each method is found in a separate reference page.
If the reference page documents a method, this section presents the method signature or synopsis. This section uses a Java-style syntax to specify (in order):
The type of the method return value, or void if the method does not return anything.
The name of the method.
The type and name (in that order) of each argument of the method. These are presented as a comma-separated list of argument types and names within parentheses. If the method does not take any arguments, you simply see the parentheses: ( ).
The types of exceptions, if any, that the method can throw.
For example, the "Synopsis" section of the Node.insertBefore( ) method looks like this:
Node insertBefore(Node newChild,
Node refChild)
throws DOMException;You can glean the following information from this synopsis: the name of the method is "insertBefore"; it returns a Node object; the first argument is a Node object and specifies the "newChild" (presumably the one to be inserted); the second argument is also a Node object and specifies the "refChild" (presumably the node before which the other is inserted); and the method may, in some circumstances, throw an exception of type DOMException.
The subsections that follow the synopsis provide additional information about the arguments, return value, and exceptions of the method. See also the Section section for more information about the Java-style syntax used here to specify the types of method arguments.
If a method has arguments, the "Synopsis" section is followed by an "Arguments" subsection that lists the names of the arguments and describes each one. Note that argument names are listed in italics, to indicate that they are not to be typed literally but instead represent some other value or JavaScript expression. To continue with the previous example, the "Arguments" section of Node.insertBefore( ) looks like this:
The "Synopsis" section specifies the data type of the method's return value, and the "Returns" subsection provides additional information. If the method has no return value (i.e., if it is listed in the "Synopsis" section as returning void), this section is omitted.
This section explains the kinds of exceptions the method can throw and under what circumstances it throws them.
DOM reference pages use a Java-style syntax for specifying the types of constants, properties, method return values, and method arguments. This section provides more information about that syntax. Note that the reference pages themselves do not have "DOM Types" sections!
The general syntax is:
modifiers type name
The name of the constant, property, method, or method argument always comes last and is preceded by type and other information. The modifiers used in this reference section (note that these are not actually legal Java modifiers) are:
The types of DOM constants, properties, method return values, and method arguments do not always correspond directly to the types supported by JavaScript. For example, some properties have a type of short which specifies a 16-bit integer. Although JavaScript only has a single numeric type, this reference section uses the DOM type simply because it provides more information about what range of numbers are legal. The DOM types you will encounter in this reference section are:
Most reference pages contain a "Description" section, which is the basic description of the interface or method that is being documented. This is the heart of the reference page. If you are learning about an interface or method for the first time, you may want to skip directly to this section and then go back and look at previous sections such as "Synopsis," "Properties," and "Methods." If you are already familiar with an interface or method, you probably won't need to read this section and instead will just want to quickly look up some specific bit of information (such as the name of a property or the type of an argument from the "Properties" or "Arguments" sections).
In some pages, this section is no more than a short paragraph. In others, it may occupy a page or more. For some simple methods, the "Arguments," "Returns," and "Throws" sections document the method sufficiently by themselves, so the "Description" section is omitted.
Reference pages for some commonly used interfaces and methods include an example in this section to illustrate typical usage of the interface or method. Most pages do not contain examples, however -- you'll find those in first half of this book.
Most reference pages conclude with cross-references to related reference pages that may be of interest. Most of these cross-references are to other reference pages in this DOM reference section. Some are to individual property descriptions contained within an interface reference page, however, and others are to related reference pages in the client-side reference section or to chapters in the first two parts of the book.
Reference pages that document interfaces (but not those that document methods) may have additional paragraphs at the end of the "See Also" section. These are cross-references that show how the interface is used. A "Type of" paragraph lists properties whose values are objects that implement the interface. A "Passed to" paragraph lists methods that take an argument that implements the interface. A "Returned by" paragraph lists methods that return an object that implements the interface. These cross-references show how you can obtain an object of this interface and what you can do with it once you have obtained it.
| AbstractView | a window displaying a document |
In the DOM, a view is an object that displays a document in some way. The Window object of client-side JavaScript is such a view. This AbstractView interface is a very preliminary step toward standardizing some of the properties and methods of the Window object. It simply specifies that all View objects have a property named document that refers to the document they display. In addition, if an implementation supports CSS style sheets, all View objects also implement the ViewCSS interface and define a getComputedStyle( ) method for determining how an element is actually rendered in the view.
The document property gives every view a reference to the document it displays. The reverse is true also: every document has a reference to the view that displays it. If a DOM implementation supports the View module, the object that implements the Document interface also implements the DocumentView interface. This DocumentView interface defines a defaultView property that refers to the window in which the document is displayed.
This interface has the word "Abstract" in its name to emphasize the fact that it is merely the beginning of a standardized window interface. In order to be useful, future levels of the DOM standard will have to introduce a new interface that extends AbstractView and adds other properties or methods.
Document.defaultView
| AbstractView.getComputedStyle( ) | retrieve the CSS styles used to render an element |
CSSStyleDeclaration getComputedStyle(Element elt,
String pseudoElt);
A read-only CSSStyleDeclaration object (which typically also implements the CSS2Properties interface) that specifies the style information used to render the specified element in this view. Any length values queried from this object are always absolute or pixel values, not relative or percentage values.
An element in a document may obtain style information from an inline style attribute and from any number of style sheets in the style-sheet "cascade." Before the element can actually be displayed in a view, its style must be "computed" by extracting style information from the appropriate parts of the cascade.
This method allows access to those computed styles. By contrast, the style property of an element gives you access only to the inline styles of an element and tells you nothing about style-sheet attributes that apply to the element. Note that this method also provides a way to determine the actual pixel coordinates at which an element is rendered in this view.
getComputedStyle( ) is actually defined by the ViewCSS interface. In any DOM implementation that supports the View and CSS modules, any object that implements AbstractView always implements ViewCSS also. So, for simplicity, this method has been listed with AbstractView.
In Internet Explorer, similar functionality is available through the nonstandard currentStyle property of each HTMLElement object.
| Attr | an attribute of a document element |
Node Attr
An Attr object represents an attribute of an Element node. Attr objects are associated with Element nodes but are not directly part of the document tree (and have a null parentNode property). You can obtain an Attr object through the attributes property of the Node interface or by calling the getAttributeNode( ) method of the Element interface.
Attr objects are nodes, and the value of an Attr is represented by the child nodes of the Attr node. In HTML documents, this is simply a single Text node. In XML documents, however, Attr nodes may have both Text and EntityReference children. The value property provides a shortcut for reading and writing the value of an attribute as a String.
In most cases, the easiest way to work with element attributes is with the getAttribute( ) and setAttribute( ) methods of the Element interface. These methods use strings for attribute names and values and avoid the use of Attr nodes altogether.
Element.removeAttributeNode( ), Element.setAttributeNode( ), Element.setAttributeNodeNS( )
Document.createAttribute( ), Document.createAttributeNS( ), Element.getAttributeNode( ), Element.getAttributeNodeNS( ), Element.removeAttributeNode( ), Element.setAttributeNode( ), Element.setAttributeNodeNS( )
| CDATASection | a CDATA section in an XML document |
Node
CharacterData
Text
CDATASection
This infrequently used interface represents a CDATA section in an XML document. Programmers working with HTML documents never encounter nodes of this type and do not need to use this interface.
CDATASection is a subinterface of Text and does not define any properties or methods of its own. The textual content of the CDATA section is available through the nodeValue property inherited from Node or through the data property inherited from CharacterData. Although CDATASection nodes can often be treated in the same way as Text nodes, note that the Node.normalize( ) method does not merge adjacent CDATA sections.
Document.createCDATASection( )
| CharacterData | common functionality for Text and Comment nodes |
Node CharacterData
Comment, Text
CharacterData is the superinterface for Text and Comment nodes. Documents never contain CharacterData nodes; they contain only Text and Comment nodes. Since both of these node types have similar functionality, however, that functionality has been defined here so that both Text and Comment can inherit it.
| CharacterData.appendData( ) | append a string to a Text or Comment node |
void appendData(String arg)
throws DOMException;
This method throws a DOMException with a code of NO_MODIFICATION_ALLOWED_ERR if called on a node that is read-only.
This method appends the string arg to the end of the data property for this node.
| CharacterData.deleteData( ) | delete characters from a Text or Comment node |
void deleteData(unsigned long offset,
unsigned long count)
throws DOMException;
This method may throw a DOMException with one of the following code values:
This method deletes characters from this Text or Comment node, starting with the character at the position offset and continuing for count characters. If offset plus count is greater than the number of characters in the Text or Comment node, all characters from offset to the end of the string are deleted.
| CharacterData.insertData( ) | insert a string into a Text or Comment node |
void insertData(unsigned long offset,
String arg)
throws DOMException;
This method may throw a DOMException with one of the following code values in the following circumstances:
This method inserts the specified string arg into the text of a Text or Comment node at the specified position offset.
| CharacterData.replaceData( ) | replace characters of a Text or Comment node with a string |
void replaceData(unsigned long offset,
unsigned long count, String arg)
throws DOMException;
This method may throw a DOMException with one of the following code values in the following circumstances:
This method replaces count characters starting at position offset with the contents of the string arg. If the sum of offset and count is greater than the length of the Text or Comment node, all characters from offset on are replaced.
| CharacterData.substringData( ) | extract a substring from a Text or Comment node |
String substringData(unsigned long offset,
unsigned long count)
throws DOMException;
A string that consists of count characters of the Text or Comment node starting with the character at position offset.
This method may throw a DOMException with one of the following code values:
This method extracts the substring that starts at position offset and continues for count characters from the text of a Text or Comment node. This method is useful only when the amount of text contained by the node is larger than the maximum number of characters that can fit in a string in a browser's JavaScript implementation. In this case, a JavaScript program cannot use the data property of the Text or Comment node directly and must instead work with shorter substrings of the node's text. This situation is unlikely to arise in practice.
| Comment | an HTML or XML comment |
Node CharacterData Comment
A Comment node represents a comment in an HTML or XML document. The content of the comment (i.e., the text between <!-- and -->) is available through the data property inherited from the CharacterData interface or through the nodeValue property inherited from the Node interface. This content may be manipulated using the various methods inherited from CharacterData.
Document.createComment( )
| Counter | a CSS counter( ) or counters( ) specification |
This interface represents a CSS counter( ) or counters( ) value. Consult a CSS reference for more information.
CSSPrimitiveValue.getCounterValue( )
| CSS2Properties | convenience properties for all CSS2 attributes |
This interface defines a large number of properties: one property for each CSS attribute defined by the CSS2 specification. The property names correspond closely to the CSS attribute names, with minor changes required to avoid syntax errors in JavaScript. Multiword attributes that contain hyphens, such as "font-family," are written without hyphens in JavaScript, and each word after the first is capitalized: fontFamily. Also, the "float" attribute conflicts with the reserved word float, so it translates to the property cssFloat.
The complete set of properties is listed in the following table. Since the properties correspond directly to CSS attributes, no individual documentation is given for each property. See a CSS reference, such as Cascading Style Sheets: The Definitive Guide, by Eric A. Meyer (O'Reilly), for the meaning and legal values of each. All of the properties are strings. Setting any of these properties may throw the same exceptions, for the same reasons as a call to CSSStyleDeclaration.setProperty( ).
|
azimuth |
background |
backgroundAttachment |
backgroundColor |
|
backgroundImage |
backgroundPosition |
backgroundRepeat |
border |
|
borderBottom |
borderBottomColor |
borderBottomStyle |
borderBottomWidth |
|
borderCollapse |
borderColor |
borderLeft |
borderLeftColor |
|
borderLeftStyle |
borderLeftWidth |
borderRight |
borderRightColor |
|
borderRightStyle |
borderRightWidth |
borderSpacing |
borderStyle |
|
borderTop |
borderTopColor |
borderTopStyle |
borderTopWidth |
|
borderWidth |
bottom |
captionSide |
clear |
|
clip |
color |
content |
counterIncrement |
|
counterReset |
cssFloat |
cue |
cueAfter |
|
cueBefore |
cursor |
direction |
display |
|
elevation |
emptyCells |
font |
fontFamily |
|
fontSize |
fontSizeAdjust |
fontStretch |
fontStyle |
|
fontVariant |
fontWeight |
height |
left |
|
letterSpacing |
lineHeight |
listStyle |
listStyleImage |
|
listStylePosition |
listStyleType |
margin |
marginBottom |
|
marginLeft |
marginRight |
marginTop |
markerOffset |
|
marks |
maxHeight |
maxWidth |
minHeight |
|
minWidth |
orphans |
outline |
outlineColor |
|
outlineStyle |
outlineWidth |
overflow |
padding |
|
paddingBottom |
paddingLeft |
paddingRight |
paddingTop |
|
page |
pageBreakAfter |
pageBreakBefore |
pageBreakInside |
|
pause |
pauseAfter |
pauseBefore |
pitch |
|
pitchRange |
playDuring |
position |
quotes |
|
richness |
right |
size |
speak |
|
speakHeader |
speakNumeral |
speakPunctuation |
speechRate |
|
stress |
tableLayout |
textAlign |
textDecoration |
|
textIndent |
textShadow |
textTransform |
top |
|
unicodeBidi |
verticalAlign |
visibility |
voiceFamily |
|
volume |
whiteSpace |
widows |
width |
|
wordSpacing |
zIndex |
This interface defines one property for each CSS attribute defined by the CSS2 specification. If the DOM implementation supports this interface (which is part of the "CSS2" feature), all CSSStyleDeclaration objects also implement CSS2Properties. Reading one of the properties defined by this interface is equivalent to calling getPropertyValue( ) for the corresponding CSS attribute, and setting the value of one of these properties is equivalent to calling setProperty( ) for the corresponding attribute. The properties defined by CSS2Properties include properties that correspond to CSS shortcut attributes, and CSS2Properties handles these shortcut properties correctly.
| CSSCharsetRule | an @charset rule in a CSS style sheet |
CSSRule CSSCharsetRule
This interface represents an @charset rule in a CSS style sheet. Consult a CSS reference for details.
| CSSFontFaceRule | an @font-face rule in a CSS style sheet |
CSSRule
CSSFontFaceRule
This interface represents an @font-face rule in a CSS style sheet. Consult a CSS reference for details.
| CSSImportRule | an @import rule in a CSS style sheet |
CSSRule CSSImportRule
This interface represents an @import rule in a CSS style sheet. The styleSheet property represents the imported style sheet.
| CSSMediaRule | an @media rule in a CSS style sheet |
CSSRule CSSMediaRule
This interface represents an @media rule, and all of its nested rules, in a CSS style sheet. It defines methods that allow you to insert and delete nested rules. Consult a CSS reference for details.
| CSSMediaRule.deleteRule( ) | delete a rule in an @media block |
void deleteRule(unsigned long index)
throws DOMException;
This method throws a DOMException with one of the following code values in the following circumstances:
This method deletes the rule at the specified position in the cssRules array.
| CSSMediaRule.insertRule( ) | insert a new rule into an @media block |
unsigned long insertRule(String rule,
unsigned long index)
throws DOMException;
The value of the index argument.
This method throws a DOMException with one of the following code values in the following circumstances:
This method inserts the specified rule into the cssRules array at the specified index.
| CSSPageRule | an @page rule in a CSS style sheet |
CSSRule
CSSPageRule
This interface represents an @page rule in a CSS style sheet, which is typically used to specify the page layout for printing. Consult a CSS reference for details.
| CSSPrimitiveValue | a single CSS style value |
CSSValue CSSPrimitiveValue
The following constants are the legal values for the primitiveType property. They specify the type of the value and, for numeric values, the units in which the value is represented.
This subinterface of CSSValue represents a single CSS value. Contrast it with the CSSValueList interface, which represents a list of CSS values. The word "primitive" in the name of this interface is misleading; this interface can represent some complex types of CSS values, such as counters, rectangles, and colors.
The primitiveType property holds one of the previously defined constants and specifies the type of the value. The various methods defined by this interface allow you to query values of various types and also to set numeric and string values.
Counter, CSSValue, CSSValueList, Rect, RGBColor
RGBColor.blue, RGBColor.green, RGBColor.red, Rect.bottom, Rect.left, Rect.right, Rect.top
| CSSPrimitiveValue.getCounterValue( ) | return a Counter value |
Counter getCounterValue( )
throws DOMException;The Counter object that represents the value of this CSSPrimitiveValue.
This method throws a DOMException with a code of INVALID_ACCESS_ERR if the primitiveType property is not CSS_COUNTER.
This method returns a Counter object that represents a CSS counter. There is no corresponding setCounterValue( ), but you can modify the value by setting the properties of the returned Counter object.
| CSSPrimitiveValue.getFloatValue( ) | get a numeric value, possibly converting units |
float getFloatValue(unsigned short unitType)
throws DOMException;
The floating-point numeric value of this CSSPrimitiveValue, expressed in the specified units.
This method throws a DOMException with a code of INVALID_ACCESS_ERR if this CSSPrimitiveValue holds a non-numeric value, or if the value cannot be converted to the requested type of units. (See the next section for more about unit conversion.)
For CSSPrimitiveValue objects that hold numeric values, this method converts those values to the specified units and returns the converted values.
Only certain types of unit conversions are allowed. Lengths may be converted to lengths, angles to angles, times to times, and frequencies to frequencies. Obviously, however, a length measured in millimeters cannot be converted to a frequency measured in kilohertz. Also, not all lengths can be converted. Relative lengths (lengths measured in ems, exs, or pixels) can be converted to other relative lengths but cannot be converted to absolute lengths. Similarly, absolute lengths cannot be converted to relative lengths. Finally, percentage values cannot be converted to any other unit type, except for color percentage values, which express a percentage of 255 and can be converted to the CSS_NUMBER type.
| CSSPrimitiveValue.getRectValue( ) | return a Rect value |
Rect getRectValue( )
throws DOMException;The Rect object that represents the value of this CSSPrimitiveValue.
This method throws a DOMException with a code of INVALID_ACCESS_ERR if the primitiveType property is not CSS_RECT.
This method returns a Rect object that represents a CSS rectangle. There is no corresponding setRectValue( ) method, but you can modify the value by setting the properties of the returned Rect object.
| CSSPrimitiveValue.getRGBColorValue( ) | get the RGBColor value |
RGBColor getRGBColorValue( )
throws DOMException;The RGBColor object that represents the value of this CSSPrimitiveValue.
This method throws a DOMException with a code of INVALID_ACCESS_ERR if the primitiveType property is not CSS_RGBCOLOR.
This method returns an RGBColor object that represents a color. There is no corresponding setRGBColorValue( ) method, but you can modify the value by setting the properties of the returned RGBColor object.
| CSSPrimitiveValue.getStringValue( ) | query a CSS string value |
String getStringValue( )
throws DOMException;The string value of this CSSPrimitiveValue.
This method throws a DOMException with a code of INVALID_ACCESS_ERR if the primitiveType property is not CSS_STRING, CSS_URI, CSS_IDENT, or CSS_ATTR.
| CSSPrimitiveValue.setFloatValue( ) | set the numeric value |
void setFloatValue(unsigned short unitType,
float floatValue)
throws DOMException;
This method throws a DOMException with a code of NO_MODIFICATION_ALLOWED_ERR if the CSS attribute with which this value is associated is read-only. It throws a DOMException with a code of INVALID_ACCESS_ERR if that CSS attribute does not allow numeric values or does not allow values with the specified unitType.
This method specifies the unit type and numeric value for this CSSPrimitiveValue.
| CSSPrimitiveValue.setStringValue( ) | set the string value |
void setStringValue(unsigned short stringType,
String stringValue)
throws DOMException;
This method throws a DOMException with a code of NO_MODIFICATION_ALLOWED_ERR if the CSS attribute with which this value is associated is read-only. It throws a DOMException with a code of INVALID_ACCESS_ERR if that CSS attribute does not allow string values or does not allow values with the specified stringType.
This method sets the string value and string type for this CSSPrimitiveValue.
| CSSRule | a rule in a CSS style sheet |
CSSCharsetRule, CSSFontFaceRule, CSSImportRule, CSSMediaRule, CSSPageRule, CSSStyleRule, CSSUnknownRule
These constants represent the various types of rules that may appear in a CSS style sheet. They are the legal values of the type property, and they specify which of the above subinterfaces this object implements.
unsigned short UNKNOWN_RULE = 0; // CSSUnknownRule unsigned short STYLE_RULE = 1; // CSSStyleRule unsigned short CHARSET_RULE = 2; // CSSCharsetRule unsigned short IMPORT_RULE = 3; // CSSImportRule unsigned short MEDIA_RULE = 4; // CSSMediaRule unsigned short FONT_FACE_RULE = 5; // CSSFontFaceRule unsigned short PAGE_RULE = 6; // CSSPageRule
This interface defines properties that are common to all types of rules in CSS style sheets. No object directly implements this interface; instead, they implement one of the more specific subinterfaces listed earlier. The most important subinterface is probably CSSStyleRule, which describes a CSS rule that defines a document style.
CSSRule.parentRule, CSSStyleDeclaration.parentRule, CSSStyleSheet.ownerRule
CSSRuleList.item( )
| CSSRuleList | an array of CSSRule objects |
This interface defines a read-only ordered list (i.e., an array) of CSSRule objects. The length property specifies the number of rules in the list, and the item( ) method allows you to retrieve the rule at a specified position. In JavaScript, CSSRuleList objects behave like JavaScript arrays, and you can query an element from the list using square-bracket array notation instead of calling the item( ) method. (Note, however, that you cannot assign new nodes into a CSSRuleList using square brackets.)
CSSMediaRule.cssRules, CSSStyleSheet.cssRules
| CSSRuleList.item( ) | get the CSSRule at the specified position |
CSSRule item(unsigned long index);
The CSSRule object at the specified position, or null if index is not a valid position.
| CSSStyleDeclaration | a set of CSS style attributes and their values |
If the implementation supports the "CSS2" feature in addition to the "CSS" feature (as most web browsers do), all objects that implement this interface also implement the CSS2Properties interface. CSS2Properties provides commonly used shortcut properties for setting and querying the values of CSS attributes. See CSS2Properties for details.
This attribute represents a CSS style declaration block: a set of CSS attributes and their values, separated from each other by semicolons. The style declaration block is the portion of a style rule within curly braces in a CSS style sheet. The value of the HTML style attribute also constitutes a style declaration block.
The item( ) method and the length property allow you to loop through the names of all CSS attributes specified in this declaration block. In JavaScript, you can also simply treat the CSSStyleDeclaration object as an array and index it using square-bracket notation instead of calling the item( ) method explicitly. Once you have the names of the CSS attributes specified in this declaration, you can use other methods of this interface to query the values of those attributes. getPropertyValue( ) returns the value as a string, and getPropertyCSSValue( ) returns the attribute value as a CSSValue object. (Note that the DOM API refers to CSS style attributes as "properties." I use the term "attributes" here to avoid confusing them with JavaScript object properties.)
In most web browsers, every object that implements CSSStyleDeclaration also implements the CSS2Properties interface, which defines an object property for each CSS attribute defined by the CSS2 specification. You can read and write the values of these convenience properties instead of calling getPropertyValue( ) and setProperty( ).
CSSFontFaceRule.style, CSSPageRule.style, CSSStyleRule.style, HTMLElement.style
Document.getOverrideStyle( ), AbstractView.getComputedStyle( )
| CSSStyleDeclaration.getPropertyCSSValue( ) | return a CSS attribute value as an object |
CSSValue getPropertyCSSValue(String propertyName);
A CSSValue object that represents the value of the named attribute if it is explicitly specified in this style declaration, or null if the named attribute is not specified. This method also returns null if propertyName specifies a CSS shorthand attribute, since shorthand attributes specify more than one value and cannot be represented with CSSValue objects.
| CSSStyleDeclaration.getPropertyPriority( ) | get the priority of a CSS attribute |
String getPropertyPriority(String propertyName);
The string "important" if the named CSS attribute is explicitly specified in this declaration block and has the !important priority modifier. Returns the empty string otherwise.
| CSSStyleDeclaration.getPropertyValue( ) | get the value of a CSS attribute as a string |
String getPropertyValue(String propertyName);
The string value of the named CSS attribute, or the empty string if that attribute is not explicitly set in this declaration block.
This method returns the value of the named CSS attribute as a string. Unlike getPropertyCSSValue( ), this method works with shortcut attributes as well as regular attributes. See also the various convenience properties of the CSS2Properties interface.
| CSSStyleDeclaration.item( ) | get the CSS attribute name at the specified position |
String item(unsigned long index);
The name of the CSS attribute at index, or the empty string if index is negative or greater than or equal to the length property.
The CSSStyleDeclaration interface represents a collection of CSS style attributes and their values. This method allows you to query the name of the CSS attribute by position and, in conjunction with the length property, allows you to iterate through the set of CSS attributes specified in this style declaration. Note that the order of CSS attributes as returned by this method does not necessarily correspond to the order in which they appear in the document or style sheet source.
As an alternative to this item( ) method, JavaScript allows you to simply treat a CSSStyleDeclaration object as an array of CSS attribute names and use standard square-bracket array syntax to obtain the attribute name at a specified position.
| CSSStyleDeclaration.removeProperty( ) | delete a CSS attribute specification |
String removeProperty(String propertyName)
throws DOMException;
The value of the named CSS attribute as a string, or the empty string if the named attribute is not explicitly specified in this style declaration.
If this style declaration is read-only, this method throws a DOMException with a code of NO_MODIFICATION_ALLOWED_ERR.
This method deletes a named attribute from this style declaration block and returns the value of the attribute.
| CSSStyleDeclaration.setProperty( ) | set a CSS style attribute |
void setProperty(String propertyName,
String value,
String priority)
throws DOMException;
This method throws a DOMException with a code of SYNTAX_ERR if the specified value argument is malformed. It throws a DOMException with a code of NO_MODIFICATION_ALLOWED_ERR if the style declaration or the attribute being set is read-only.
This method adds the named CSS attribute with its value and priority to this style declaration, or, if the declaration already contains a value for the named attribute, it simply sets the value and priority for that existing attribute.
Using setProperty( ) to add a new CSS attribute to a style declaration may insert the new attribute at any position and may, in fact, totally shuffle the order of all existing attributes. Therefore, you should not use setProperty( ) while you are iterating through the set of attribute names with the item( ) method.
| CSSStyleRule | a style rule in a CSS style sheet |
CSSRule CSSStyleRule
This interface represents a style rule in a CSS style sheet. Style rules are the most common and important kinds of rules in style sheets: they specify style information that is to be applied to a specific set of document elements. selectorText is the string representation of the element selector for this rule, and style is a CSSStyleDeclaration object that represents the set of style names and values to apply to the selected elements.
| CSSStyleSheet | a CSS style sheet |
CSS StyleSheet CSSStyleSheet
This interface represents a CSS style sheet. The cssRules property lists the rules contained in the style sheet, and the insertRule( ) and deleteRule( ) methods allow you to add and delete rules from that list.
CSSImportRule.styleSheet, CSSRule.parentStyleSheet
DOMImplementation.createCSSStyleSheet( )
| CSSStyleSheet.deleteRule( ) | delete a rule from a style sheet |
void deleteRule(unsigned long index)
throws DOMException;
This method throws a DOMException with a code of INDEX_SIZE_ERR if index is negative or greater than or equal to cssRules.length. It throws a DOMException with a code of NO_MODIFICATION_ALLOWED_ERR if this style sheet is read-only.
This method deletes the rule at the specified index from the cssRules array.
| CSSStyleSheet.insertRule( ) | insert a rule into a style sheet |
unsigned long insertRule(String rule,
unsigned long index)
throws DOMException;
The value of the index argument.
This method throws a DOMException with one of the following code values in the following circumstances:
This method inserts (or appends) a new CSS rule at the specified index of the cssRules array of this style sheet.
| CSSUnknownRule | an unrecognized rule in a CSS style sheet |
CSS CSSRule CSSUnknownRule
This interface represents a rule in a CSS style sheet that the browser did not recognize and could not parse (typically because it is defined by a version of the CSS standard that the browser does not support). Note that this interface does not define any properties or methods of its own. The text of the unrecognized rule is available through the inherited cssText property.
| CSSValue | the value of a CSS style attribute |
CSSPrimitiveValue, CSSValueList
The following constants specify the valid values for the cssValueType property:
This interface represents the value of a CSS attribute. The cssText property gives the value in textual form. If the cssValueType property is CSSValue.CSS_PRIMITIVE_VALUE, this CSSValue object also implements the more specific CSSPrimitiveValue interface. If cssValueType is CSSValue.CSS_VALUE_LIST, this CSSValue represents a list of values and also implements the CSSValueList interface.
CSSPrimitiveValue, CSSValueList
CSSStyleDeclaration.getPropertyCSSValue( ), CSSValueList.item( )
| CSSValueList | a CSSValue that holds an array of CSSValue objects |
CSSValue CSSValueList
This interface represents an array of CSSValue objects and is itself a type of CSSValue. The item( ) method can be used to retrieve the CSSValue object at a specified position, but in JavaScript, it is easier to simply index the array using standard square-bracket notation.
The order of CSSValue objects in a CSSValueList array is the order in which they appear in the CSS style declaration. Some CSS attributes whose value is a CSSValueList may also have the value none. This special value translates into a CSSValueList object with a length of 0.
| CSSValueList.item( ) | get the CSSValue at the specified position |
CSSValue item(unsigned long index);
The CSSValue object at the specified position in this CSSValueList, or null if index is negative or is greater than or equal to length.