Module io.sf.carte.css4j

Package io.sf.carte.doc.style.css

package io.sf.carte.doc.style.css
This package and its subpackages provide an implementation of the CSS Object Model API. The root css package essentially contains interface definitions (many derived from W3C) and generic classes.

Extended W3C CSSOM and SAC interfaces

There are two flavors of extended W3C interfaces in this library (those that extend previously existing W3C types, as opposed to those that are new ones):

  • Interfaces suffixed with a "2" (like CSSPrimitiveValue2) have new methods that -in the opinion of the author- are required to handle current CSS.
  • Interfaces that are prefixed with "Extended" offer additional functionality that you may or may not want to use.

Compliance with CSS specification(s)

Although this implementation attempts to follow the various CSS specifications, there are known deviations from what was specified by the W3C. Most of those differences arise from the fact that the W3C specifications are intended to be implemented by user agents, and not by tools like this library. One example is serialization.

Serialization and getCssText()

The CSSOM specification requires getCssText() to return the serialization of property declarations, following an algorithm that -whenever possible- builds shorthand properties from the longhands. However, this is inconvenient for most use cases of this library, so the getCssText() method returns the properties in a form that is close to what was specified with setCssText(), either longhands or shorthands.

The reason should be obvious: this library is generally not the final recipient for those declarations, but just middleware. If a CSS author specifies style in a certain way, he/she may be targeting more that one browser, but if this library produced its own shorthand constructions (and it has the logic to do that), that could break what was intended by the author. The library does remove obviously wrong declarations (and also redundant ones), however. The final result may not exactly reflect what was specified by the author, but is a good compromise.

Another deviation from the specification comes with the computed styles. Instead of returning the empty string (as the Working Group recommends), or a serialization of all the property name/value pairs known to the library (like some browser does), only those values that come from the cascade or are inherited from another element are included in both the item collection and getCssText(). Note that getPropertyCSSValue(String) and getPropertyValue(String) both return values for properties that are not included in the item collection, although this may seem counter-intuitive.

This approach has better flexibility for the different use cases of this library, and prevents potential problems (for example a downstream application not understanding all the properties in the declaration text, or re-parsing texts that are too large). Also, downstream users can check whether declared styles ended up in an element's computed style by just checking CSSStyleDeclaration.getLength().