`Index </index.txt>`_

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


.. contents::

CSSStyleDeclaration
===================
A CSSStyleDeclaration contains all properties set in a CSSStyleRule or CSSPageRule. It is iterable which yield all *effective* properties. It also supports ``in``.

Example::

    >>> css = r'''
        color: red;
        /* properties might be set more than once for different UAs */
        c\olor: green;
        background-color: #fff
        '''
    >>> s = cssutils.css.CSSStyleDeclaration(cssText=css)
    >>> for p in s:
    ...     print repr(p)
    cssutils.css.Property(name='c\\olor', value=u'green', priority=u'')
    cssutils.css.Property(name='background-color', value=u'#fff', priority=u'')

    >>> 'color' in s
    True


attributes
----------
cssText
    a parsable textual representation of the declaration. See also getCssText_

length
    The number of distinct properties that have been explicitly set
    in this declaration. These are properties with a different ``name``
    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
-------
.. _getCssText:

getCssText(separator=None)
    returns serialized property cssText, each property separated by
    given ``separator`` which may e.g. be ``u''`` to use
    cssText directly in an HTML style attribute. ";" is always part of
    each property (except the last one) and can **not** be changed by giving
    separator!

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 or the one with the highest priority). 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(all=True)``.

getProperty(name, normalize=True):
    returns the effective Property object.
setProperty(name, value, priority=None, normalize=True)
    sets/overwriters a property
removeProperty(name, normalize=True)
    removes the property with given ``name``.

    If ``normalize==True`` (DEFAULT) ``name`` will be normalized (lowercase, no simple escapes) so "color", "COLOR" or "C\olor" will all be equivalent. The effective Property value is returned and *all* Properties with ``Property.name == name`` are removed.

    If ``normalize==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!

getPropertyCSSValue(name, normalize=True)
    returns a CSSValue object
getPropertyValue(name, normalize=True)
    returns the string value
getPropertyPriority(name, normalize=True)
    returns the priority

item(index)
    returns property at index. Same as ``length`` item works on
    effective properties only and not on the complete set!

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.


Property
========
A Property is used in a ``CSSStyleDeclaration`` but also in a `MediaQuery <stylesheets.txt>`_ 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:

name
    normalized name of the property, e.g. "color" when name is "c\olor" (since 0.9.5)
literalname (since 0.9.5)
    original name of the property in the source CSS which is not normalized
    e.g. "c\olor"
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 u"important" (until 0.9.5 this was "!important") or None)

DEPRECATED normalname (since 0.9.5)
    normalized name of the property, e.g. "color" when name is "c\olor"