Index

CSSStyleDeclaration

author:$LastChangedBy: cthedot $
date:$LastChangedDate: 2007-08-08 16:14:03 +0200 (Mi, 08 Aug 2007) $
version:$LastChangedRevision: 206 $

CSSStyleDeclaration

A CSSStyleDeclaration contains all properties set in a CSSStyleRule or CSSPageRule.

Example:

/* a comment */
color: red;
/* properties might be set more than once for different UAs */
c\\olor: green;
background-color: #fff

attributes

cssText

a parsable textual representation of the declaration. See also:

getCssText(separator=None)
returns serialized property cssText, each property separated by given separator which may e.g. be u'' to be able to use cssText directly in an HTML style attribute. ";" is always part of each property (except the last one) and can not be set with separator!
length
The number of distince properties that have been explicitly in this declaration These are properties with the same normalname only. item() and length work on the same set here.
parentRule
The CSS rule that contains this declaration block or None if this CSSStyleDeclaration is not attached to a CSSRule.

methods

getProperties(name=None, all=False):
returns a list of Property objects set in this declaration in order they have been set e.g. in the original stylesheet

The following methods all have a parameter normalize which if set to False results in handling of name not being normalized. Default behaviour is to always access the effective property in this rule (the last set). An un-normalized name like c\\olor gives access to the property with this actual name. To work on all properties it is probably easiest to iterate directly over all properties or to use getProperties().

getPropertyCSSValue(self, name, normalize=True)
returns a CSSValue object
getPropertyValue(self, name, normalize=True)
returns the string value
getPropertyPriority(self, name, normalize=True)
returns the priority
removeProperty(self, name, normalize=True)
removes the property. Even if normlize=True only removes the last property with this name - not all.
setProperty(self, name, value, priority=None, normalize=True)
sets value and priority
item(index)
returns property at index. Same as length item works on effective properties only and not on the complete set!

random notes

CSS2Properties

CSSStyleDeclaration implements CSS2Properties so most CSS 2 properties may be used like:

declaration.color = 'red'
declaration.backgroundColor = '#000'

As some properties contain a "-" character these have to be used in camelcase instead!

cssutils implements only a subset of CSS2Properties so setting e.g. declaration.border = '1px solid red' does only set border but not border-style, border-color etc which it should. This may be implemented later.

iterable

CSSStyleDeclaration is iterable (experimental). The iterator returns all properties set in this style as objects with properties name, cssValue and priority. Calling CSSStyleDeclaration.item(index) on the other hand simply returns a property name and also only the normalized name (once). Example:

sheet = cssutils.parseString('a { color: red; c\olor: blue; left: 0 !important }')
for rule in sheet.cssRules:
    style = rule.style
    for property in style:
        name = property.name
        cssValue = property.cssValue
        priority = property.priority
        print name, '=', cssValue.cssText, priority

    # prints:
    # color = red
    # c\olor = blue
    # left = 0 !important

    for i in range(0, style.length):
        name = style.item(i)
        cssValue = style.getPropertyCSSValue(name)
        priority = style.getPropertyPriority(name)
        print name, '=', cssValue.cssText , priority

    # prints:
    # color = blue
    # left = 0 !important

Property

A Property is used in a CSSStyleDeclaration but also in a MediaQuery object. Only in the latter case a value is optional and a priority not used at all. As MediaQuery is not a finished spec so some details may still change.

A property has the following attributes:

cssText
a parsable textual representation of this property
name
of the property
normalname
normalized name of the property, e.g. "color" when name is "color"
cssValue
the relevant CSSValue instance for this property
value
the string value of the property, same as cssValue.cssText
priority
of the property (currently only !important or None)