Package cssutils :: Package css :: Module cssstyledeclaration :: Class CSSStyleDeclaration
[hide private]
[frames] | no frames]

Class CSSStyleDeclaration

source code

                  object --+    
                           |    
cssproperties.CSS2Properties --+
                               |
                  object --+   |
                           |   |
                   util.Base --+
                               |
                              CSSStyleDeclaration

The CSSStyleDeclaration class represents a single CSS declaration block. This class may be used to determine the style properties currently set in a block or to set style properties explicitly within the block.

While an implementation may not recognize all CSS properties within a CSS declaration block, it is expected to provide access to all specified properties in the style sheet through the CSSStyleDeclaration interface. Furthermore, implementations that support a specific level of CSS should correctly handle CSS shorthand properties for that level. For a further discussion of shorthand properties, see the CSS2Properties interface.

Additionally the CSS2Properties interface is implemented.

Properties

cssText
The parsable textual representation of the declaration block (excluding 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. It also allows the insertion of additional properties and their values into the block.
length: of type unsigned long, readonly
The number of properties that have been explicitly set in this declaration block. The range of valid indices is 0 to length-1 inclusive.
parentRule: of type CSSRule, readonly
The CSS rule that contains this declaration block or None if this CSSStyleDeclaration is not attached to a CSSRule.
seq: a list (cssutils)
All parts of this style declaration including CSSComments
$css2propertyname

All properties defined in the CSS2Properties class are available as direct properties of CSSStyleDeclaration with their respective DOM name, so e.g. fontStyle for property 'font-style'.

These may be used as:

>>> style = CSSStyleDeclaration(cssText='color: red')
>>> style.color = 'green'
>>> print style.color
green
>>> del style.color
>>> print style.color # print empty string

Format

[Property: Value Priority?;]* [Property: Value Priority?]?

Nested Classes [hide private]

Inherited from util.Base (private): _prods

Instance Methods [hide private]
 
__init__(self, cssText=u'', parentRule=None, readonly=False)
Shortcut, sets CSSStyleDeclaration.cssText
source code
 
__contains__(self, nameOrProperty)
checks if a property (or a property with given name is in style
source code
 
__iter__(self)
iterator of set Property objects with different normalized names.
source code
 
__setattr__(self, n, v)
Prevent setting of unknown properties on CSSStyleDeclaration which would not work anyway.
source code
 
__nnames(self)
returns iterator for all different names in order as set if names are set twice the last one is used (double reverse!)
source code
 
_getP(self, CSSName)
(DOM CSS2Properties) Overwritten here and effectively the same as self.getPropertyValue(CSSname).
source code
 
_setP(self, CSSName, value)
(DOM CSS2Properties) Overwritten here and effectively the same as self.setProperty(CSSname, value).
source code
 
_delP(self, CSSName)
(cssutils only) Overwritten here and effectively the same as self.removeProperty(CSSname).
source code
 
_getCssText(self)
returns serialized property cssText
source code
 
_setCssText(self, cssText)
Setting this attribute will result in the parsing of the new value and resetting of all the properties in the declaration block including the removal or addition of properties.
source code
 
getCssText(self, separator=None)
returns serialized property cssText, each property separated by given separator which may e.g.
source code
 
_getParentRule(self) source code
 
_setParentRule(self, parentRule) source code
 
getProperties(self, name=None, all=False)
Returns a list of Property objects set in this declaration.
source code
 
getProperty(self, name, normalize=True)
Returns the effective Property object.
source code
 
getPropertyCSSValue(self, name, normalize=True)
Returns CSSValue, the value of the effective property if it has been explicitly set for this declaration block.
source code
 
getPropertyValue(self, name, normalize=True)
Returns the value of the effective property if it has been explicitly set for this declaration block.
source code
 
getPropertyPriority(self, name, normalize=True)
Returns the priority of the effective CSS property (e.g.
source code
 
removeProperty(self, name, normalize=True)
(DOM) Used to remove a CSS property if it has been explicitly set within this declaration block.
source code
 
setProperty(self, name, value=None, priority=u'', normalize=True)
(DOM) Used to set a property value and priority within this declaration block.
source code
 
item(self, index)
(DOM) Used to retrieve the properties that have been explicitly set in this declaration block.
source code
 
__repr__(self)
repr(x)
source code
 
__str__(self)
str(x)
source code

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__

Static Methods [hide private]

Inherited from util.Base (private): _normalize

Class Variables [hide private]

Inherited from cssproperties.CSS2Properties (private): _properties

Inherited from util.Base (private): _SHORTHANDPROPERTIES, _log

Properties [hide private]
  cssText
(DOM) A parsable textual representation of the declaration block excluding the surrounding curly braces.
  parentRule
(DOM) The CSS rule that contains this declaration block or None if this CSSStyleDeclaration is not attached to a CSSRule.
  length
(DOM) The number of distinct properties that have been explicitly in this declaration block.

Inherited from cssproperties.CSS2Properties: azimuth, background, backgroundAttachment, backgroundColor, backgroundImage, backgroundPosition, backgroundRepeat, border, borderBottom, borderBottomColor, borderBottomStyle, borderBottomWidth, borderCollapse, borderColor, borderLeft, borderLeftColor, borderLeftStyle, borderRight, borderRightColor, borderRightStyle, borderRightWidth, borderSpacing, borderStyle, borderTop, borderTopColor, borderTopStyle, borderTopWidth, borderWidth, bottom, captionSide, clear, clip, color, content, counterIncrement, counterReset, cue, cueAfter, cueBefore, cursor, direction, display, elevation, emptyCells, float, font, fontFamily, fontSize, fontStyle, fontVariant, fontWeight, height, left, letterSpacing, lineHeight, listStyle, listStyleImage, listStylePosition, listStyleType, margin, marginBottom, marginLeft, marginRight, marginTop, maxHeight, maxWidth, minHeight, minWidth, orphans, outline, outlineColor, outlineStyle, outlineWidth, overflow, padding, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pageBreakInside, pause, pauseAfter, pauseBefore, pitch, pitchRange, playDuring, position, quotes, richness, right, speak, speakHeader, speakNumeral, speakPunctuation, speechRate, stress, tableLayout, textAlign, textDecoration, textIndent, textTransform, top, unicodeBidi, verticalAlign, visibility, voiceFamily, volume, whiteSpace, widows, width, wordSpacing, zIndex

Inherited from object: __class__

Method Details [hide private]

__init__(self, cssText=u'', parentRule=None, readonly=False)
(Constructor)

source code 
cssText
Shortcut, sets CSSStyleDeclaration.cssText
parentRule
The CSS rule that contains this declaration block or None if this CSSStyleDeclaration is not attached to a CSSRule.
readonly
defaults to False
Overrides: object.__init__

__contains__(self, nameOrProperty)
(In operator)

source code 

checks if a property (or a property with given name is in style

name
a string or Property, uses normalized name and not literalname

__setattr__(self, n, v)

source code 

Prevent setting of unknown properties on CSSStyleDeclaration which would not work anyway. For these CSSStyleDeclaration.setProperty MUST be called explicitly!

TODO:
implementation of known is not really nice, any alternative?
Overrides: object.__setattr__

_getP(self, CSSName)

source code 

(DOM CSS2Properties) Overwritten here and effectively the same as self.getPropertyValue(CSSname).

Parameter is in CSSname format ('font-style'), see CSS2Properties.

Example:

>>> style = CSSStyleDeclaration(cssText='font-style:italic;')
>>> print style.fontStyle
italic
Overrides: cssproperties.CSS2Properties._getP

_setP(self, CSSName, value)

source code 

(DOM CSS2Properties) Overwritten here and effectively the same as self.setProperty(CSSname, value).

Only known CSS2Properties may be set this way, otherwise an AttributeError is raised. For these unknown properties setPropertyValue(CSSname, value) has to be called explicitly. Also setting the priority of properties needs to be done with a call like setPropertyValue(CSSname, value, priority).

Example:

>>> style = CSSStyleDeclaration()
>>> style.fontStyle = 'italic'
>>> # or
>>> style.setProperty('font-style', 'italic', '!important')
Overrides: cssproperties.CSS2Properties._setP

_delP(self, CSSName)

source code 

(cssutils only) Overwritten here and effectively the same as self.removeProperty(CSSname).

Example:

>>> style = CSSStyleDeclaration(cssText='font-style:italic;')
>>> del style.fontStyle
>>> print style.fontStyle # prints u''
Overrides: cssproperties.CSS2Properties._delP

_setCssText(self, cssText)

source code 

Setting this attribute will result in the parsing of the new value and resetting of all the properties in the declaration block including the removal or addition of properties.

DOMException on setting

  • NO_MODIFICATION_ALLOWED_ERR: (self) Raised if this declaration is readonly or a property is readonly.
  • SYNTAX_ERR: (self) Raised if the specified CSS string value has a syntax error and is unparsable.

getCssText(self, separator=None)

source code 
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!

getProperties(self, name=None, all=False)

source code 

Returns a list of Property objects set in this declaration.

name
optional name of properties which are requested (a filter). Only properties with this always normalized name are returned.
all=False

if False (DEFAULT) only the effective properties (the ones set last) are returned. If name is given a list with only one property is returned.

if True all properties including properties set multiple times with different values or priorities for different UAs are returned. The order of the properties is fully kept as in the original stylesheet.

getProperty(self, name, normalize=True)

source code 

Returns the effective Property object.

name
of the CSS property, always lowercase (even if not normalized)
normalize

if True (DEFAULT) name will be normalized (lowercase, no simple escapes) so "color", "COLOR" or "Color" will all be equivalent

If False may return NOT the effective value but the effective for the unnormalized name.

getPropertyCSSValue(self, name, normalize=True)

source code 

Returns CSSValue, the value of the effective property if it has been explicitly set for this declaration block.

name
of the CSS property, always lowercase (even if not normalized)
normalize

if True (DEFAULT) name will be normalized (lowercase, no simple escapes) so "color", "COLOR" or "Color" will all be equivalent

If False may return NOT the effective value but the effective for the unnormalized name.

(DOM) Used to retrieve the object representation of the value of a CSS property if it has been explicitly set within this declaration block. Returns None if the property has not been set.

(This method returns None if the property is a shorthand property. Shorthand property values can only be accessed and modified as strings, using the getPropertyValue and setProperty methods.)

cssutils currently always returns a CSSValue if the property is set.

for more on shorthand properties see
http://www.dustindiaz.com/css-shorthand/

getPropertyValue(self, name, normalize=True)

source code 

Returns the value of the effective property if it has been explicitly set for this declaration block. Returns the empty string if the property has not been set.

name
of the CSS property, always lowercase (even if not normalized)
normalize

if True (DEFAULT) name will be normalized (lowercase, no simple escapes) so "color", "COLOR" or "Color" will all be equivalent

If False may return NOT the effective value but the effective for the unnormalized name.

getPropertyPriority(self, name, normalize=True)

source code 

Returns the priority of the effective CSS property (e.g. the "important" qualifier) if the property has been explicitly set in this declaration block. The empty string if none exists.

name
of the CSS property, always lowercase (even if not normalized)
normalize

if True (DEFAULT) name will be normalized (lowercase, no simple escapes) so "color", "COLOR" or "Color" will all be equivalent

If False may return NOT the effective value but the effective for the unnormalized name.

removeProperty(self, name, normalize=True)

source code 

(DOM) Used to remove a CSS property if it has been explicitly set within this declaration block.

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 known CSS property

name
of the CSS property
normalize

if True (DEFAULT) name will be normalized (lowercase, no simple escapes) so "color", "COLOR" or "Color" will all be equivalent. The effective Property value is returned and all Properties with Property.name == name are removed.

If False may return NOT the effective value but the effective for the unnormalized name only. Also only the Properties with the literal name name are removed.

raises DOMException

  • NO_MODIFICATION_ALLOWED_ERR: (self) Raised if this declaration is readonly or the property is readonly.

setProperty(self, name, value=None, priority=u'', normalize=True)

source code 

(DOM) Used to set a property value and priority within this declaration block.

name

of the CSS property to set (in W3C DOM the parameter is called "propertyName"), always lowercase (even if not normalized)

If a property with this name is present it will be reset

cssutils also allowed name to be a Property object, all other parameter are ignored in this case

value
the new value of the property, omit if name is already a Property
priority
the optional priority of the property (e.g. "important")
normalize
if True (DEFAULT) name will be normalized (lowercase, no simple escapes) so "color", "COLOR" or "Color" will all be equivalent

DOMException on setting

  • SYNTAX_ERR: (self) Raised if the specified value has a syntax error and is unparsable.
  • NO_MODIFICATION_ALLOWED_ERR: (self) Raised if this declaration is readonly or the property is readonly.

item(self, index)

source code 

(DOM) 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.

index
of the property to retrieve, negative values behave like negative indexes on Python lists, so -1 is the last element

returns the name of the property at this ordinal position. The empty string if no property exists at this position.

ATTENTION: Only properties with a different name are counted. If two properties with the same name are present in this declaration only the effective one is included.

item() and length work on the same set here.

__repr__(self)
(Representation operator)

source code 

repr(x)

Overrides: object.__repr__
(inherited documentation)

__str__(self)
(Informal representation operator)

source code 

str(x)

Overrides: object.__str__
(inherited documentation)

Property Details [hide private]

cssText

(DOM) A parsable textual representation of the declaration block excluding the surrounding curly braces.
Get Method:
_getCssText(self) - returns serialized property cssText
Set Method:
_setCssText(self, cssText) - Setting this attribute will result in the parsing of the new value and resetting of all the properties in the declaration block including the removal or addition of properties.

parentRule

(DOM) The CSS rule that contains this declaration block or None if this CSSStyleDeclaration is not attached to a CSSRule.
Get Method:
_getParentRule(self)
Set Method:
_setParentRule(self, parentRule)

length

(DOM) The number of distinct properties that have been explicitly in this declaration block. The range of valid indices is 0 to length-1 inclusive. These are properties with a different name only. item() and length work on the same set here.
Get Method:
unreachable(self)