Some notes on style design.
First we might focus on automatic styles and named styles as primary example for all styles. Most other styles as list styles behave similar and we may adapt most of the design.
Some question & answers to bring us all on the same level.
Q: What is a style?
A style is a collection of various style properties describing the format of an ODF element/component (e.g. color or font seize).
Q: Where can styles be used?
A: From XML/DOM perspective on all elements that have @*:style-name attribute, e.g. @text:style-name or @table:style-name.
In general on all elements that have text or paragraph children.
From DOC API perspective on most visible components.
Q: What is the difference between an automatic style and a named style?
The automatic style comes without name and is similar to the HTML inline style attached directly and unique to the element.
The automatic style is not reusable, as there is no key/name to access this style.
A automatic style might only inherit from a named style. The named style usually only from another named style.
Q: How are automatic & named styles designed in ODF?
In ODF each stylable element is aligned to a style:family, which has a fixed set of property sets.
There is the following relation ship:
– has –
– has –
N "style properties set"
– has –
M "single style property"
The relation between stylable element and style:family has been extracted from the spec and can be found in
To get an idea about the possible amount of styles to be set, take a look at the deprecated OdfStyleFamily.java found in
The most interesting case is the table:table-cell, which similar named @style:family value is related to three sets of style properties.
One for the cell, one for all paragraphs within the cell and one for the text within the cell.
Notable that all styles might contain a different fo:background-color style property, which all effect the layout.
Therefore the DOC layer needs the possibility to add background color in three different ways on a cell.
A automatic style might be handled internally as a named style without name for the stylable element.
Automatic style names are an ODF implementation detail and must not be part of the DOC API.
The large amount of single style properties provoke the idea to bundle those methods, instead of repeating them on all stylable elements/components.
Another argument for bundling is the reusage of style property sets grouped by a style family.
The contrary design is to add a method for every possible style format on the stylable element/component, e.g.
I drafted various versions of the bundled option and will discuss them with colleagues the next days:
// NULL might be used for automatic style
// THERE IS ALWAYS ONLY ONE TEXT/PARAGRAPH/CELL CONTAINER
// STYLE NULL EXCEPTION PROBLEM
Aside of the flood of methods that make an API hard to use, is my personal requirement that a user get as much help as
possible with applicable arguments on the methods. For instance, what can be set for a setBackgroundColor?
The fo:background-color style attribute should give sufficient information by its constructor, which could be related to the method.
The source code generation have to be improved to help us here.
In the end we will pick up our favorite design versions and generate prototypes by the generator to see how the JavaDoc API might look like in real-life.
Going to focus on source code generation the next days,