`Index </index.txt>`_

========================
package ``cssutils.css``
========================

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

.. contents::


overview
========
Classes implementing `DOM Level 2 CSS <http://www.w3.org/TR/DOM-Level-2-Style/css.html>`_ and `CSS Module: Namespaces (W3C Working Draft 28 August 2006) <http://www.w3.org/TR/css3-namespace/>`_

:CSSStyleSheet_: Implements ``stylesheets.StyleSheet`` and is the *root* of a stylesheet.
:CSSRuleList: A list of CSSRule objects used in CSSStyleSheet_ and CSSMediaRule_
:CSSRule: Base class of all CSS rules, hardly useful itself
:CSSCharsetRule_: @charset rule
:CSSFontFaceRule_: @font-face rule (from v0.9.5a4)
:CSSImportRule_: @import rule
:CSSMediaRule_: @media rule
:CSSNamespaceRule_: @namespace rule
:CSSPageRule_: @page rule
:CSSStyleRule_: Main Rule with Selectors and ``CSSStyleDeclaration``
:`CSSStyleDeclaration <cssstyledeclaration.txt>`_: Containing a list of Properties
:`Property <cssstyledeclaration.txt#property>`_: A single property with name, value and priority information, used for properties in CSSStyleDeclaration and stylesheets.MediaQuery
:`CSSValue <values.txt>`_: A CSS value which might also be a CSSPrimitiveValue or CSSValueList.
:CSSComment: A comment anywhere in the stylesheet. Not in any official spec.

Shared Attributes
=================
.. _cssText:

cssText
    The textual representation of the rule or sheet (cssutils defined this property for CSSStyleSheet_ objects too).
atkeyword
    All @rules have this attribute which holds the literal atkeyword, e.g. ``@im\port``.

CSSStyleSheet
=============
The CSSStyleSheet contains all rules. It consists of the different rules defined above like CSSImportRule_ CSSStyleRule_ etc. It also defines the encoding of the style sheet used for serialization. The encoding might by set with an CSSCharsetRule_ rules or simpler with the encoding_ attribute. The serialized sheet may be obtained from cssText_. All rules are present in cssRules_, a stylesheet iterates on its rules so this might be easier. Namespaces are available via namespaces_, the actual namespace rules in the CSSNamespaceRule_ objects (do not rely on prefixes, see http://www.w3.org/TR/REC-xml-names/ how these work).

Attributes
----------
Also inherits properties from stylesheet.StyleSheet.

.. _cssRules:

cssRules
    A css::CSSRuleList of all CSS rules contained within the
    stylesheet.

.. _ownerRule:

ownerRule
    of type CSSRule, readonly (NOT IMPLEMENTED YET)

.. _encoding:

encoding (cssutils and CSSOM only)
    reflects the encoding of an @charset rule or 'utf-8' (default)
    if set to ``None``. If an explicit encoding of 'utf-8' is set an @charset rule is serialized, if encoding is ``None`` (and therefor also effectively 'utf-8') no @charset rule is serialized.

    Effectively using CSSCharsetRule directly is not needed anymore.

.. _namespaces:

namespaces: a dict like object (cssutils only)
    reflects set @namespace rules of this rule.
    A dict of {prefix: namespaceURI} mapping.

    Using CSSNamespaceRule directly is not really needed anymore (except if you want to add comments in these rules).

Methods
-------

.. _append:

add(self, rule)
    Adds a rule to the proper hierarchical position in the style sheet. Same as ``insertRule(rule, inOrder=True)`` but simpler.

.. _deleteRule:

deleteRule(self, index)
    Used to delete a rule from the style sheet.

.. _insertRule:

insertRule(rule, index=None, inorder=False)
    Used to insert a new rule into the style sheet. The new rule now
    becomes part of the cascade.

    Rule may be a string or a valid ``CSSRule`` or ``CSSRuleList``

.. _replaceUrls:

replaceUrls(replacer)
    Utility method to replace all ``url(urlstring)`` values in ``CSSImportRules`` and ``CSSStyleDeclaration`` objects (properties).

    ``replacer`` must be a function which is called with a single
    argument ``urlstring`` which is the current value of url()
    excluding ``url(`` and ``)``. It still may have surrounding
    single or double quotes though.

.. _setSerializer:

setSerializer(self, cssserializer)
    Sets the global Serializer used for output of all stylesheet
    output.

.. _setSerializerPref:

setSerializerPref(pref, value)
    Sets Preference of CSSSerializer used for output of this
    stylesheet. See cssutils.serialize.Preferences for possible
    preferences to be set.


CSSCharsetRule
==============
This rule is not really needed anymore as using  encoding_ of CSSStyleSheet_ is much easier.


CSSNamespaceRule
================
CSSNamespaceRule currently implements http://www.w3.org/TR/2006/WD-css3-namespace-20060828/. Dealing with these rules directly is not needed anymore, easier is the use of CSSStyleSheet namespaces_.

namespaceURI
    The namespace URI (a simple string!) which is bound to the given prefix. If no prefix is set (CSSNamespaceRule.prefix=='') the namespace defined by ``namespaceURI`` is set as the default namespace. This property is readonly to prevent making stylesheets invalid.
prefix
    The prefix used in the stylesheet for the given ``namespaceURI``. If prefix is empty ``namespaceURI`` sets the default namespace for the stylesheet.


CSSImportRule
=============
Used to import other CSS style sheets.

.. _href:

href
    The URI where the referenced sheet may be found. May be a string or ``url()`` value.
media
    The media information where the referenced style sheet should be used. See MediaList_ for more details.
name
    A name like a HTML named Stylesheet. (Not very useful yet.)
stylesheet
    The referenced CSSStyleSheet_. Currently always ``None`` as it is **not implemented**.


CSSMediaRule
============
Rules (mainly ``CSSStyleRule`` s) which are to be used for the given ``media`` only.

media
    A list of media types for this rule of type MediaList.
cssRules
    A css::CSSRuleList of all CSS rules contained within the
    media block.

CSSFontFaceRule
===============
Holds font related definitions. Hardly used in any CSS implementation, I only know PrinceXML which uses it to defined fonts.

style
    The declaration-block of this rule

CSSPageRule
===========
Holds page related definitions. Mainly useful for print sheets, used extensively in page defining applications like PrinceXML.

selectorText
    The parsable textual representation of the page selector for the rule.
style
    The declaration-block of this rule

CSSStyleRule
============
The CSSStyleRule object represents a ruleset specified (if any) in a CSS
style sheet. It provides access to a declaration block as well as to the
associated group of selectors.

selectorText
    The textual representation of the selector for the rule set.
selectorList: of type SelectorList (cssutils only)
    A list of all Selectors for the rule set.
style
    The declaration-block of this rule (see `CSSStyleDeclaration <cssstyledeclaration.txt>`_)


.. _MediaList: stylesheets.txt