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

# Class CSSStyleDeclaration

source code

                      object --+
                               |
    cssproperties.CSS2Properties --+
                                   |
                  object --+       |
                           |       |
                   util.Base --+   |
                               |   |
                      util.Base2 --+
                                   |
                                  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
__getitem__(self, CSSName) Retrieve the value of property `CSSName` from this declaration. | source code
__setitem__(self, CSSName, value) Set value of property `CSSName`. | source code
__delitem__(self, CSSName) Delete property `CSSName` from this declaration. | 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 `util.Base2` (private): `_adddefaultproductions`, `_setSeq`, `_tempSeq` Inherited from `util.Base` (private): `_checkReadonly`, `_nexttoken`, `_parse`, `_splitNamespacesOff`, `_stringtokenvalue`, `_tokenize2`, `_tokensupto2`, `_tokenvalue`, `_type`, `_uritokenvalue`, `_valuestr` 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 `util.Base2`: `seq` 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__

### __getitem__(self, CSSName) (Indexing operator) | source code
Retrieve the value of property `CSSName` from this declaration. `CSSName` will be always normalized.

### __setitem__(self, CSSName, value) (Index assignment operator) | source code
Set value of property `CSSName`. `value` may also be a tuple of (value, priority), e.g. style['color'] = ('red', 'important') `CSSName` will be always normalized.

### __delitem__(self, CSSName) (Index deletion operator) | source code
Delete property `CSSName` from this declaration. If property is not in this declaration return u'' just like removeProperty. `CSSName` will be always normalized.

### _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)