Properties

| Property Handling |
During XML Parsing, the FO tree is constructed. For each FO object (some subclass of FObj), the tree builder then passes the list of all attributes specified on the FO element to the handleAttrs method. This method converts the attribute specifications into a PropertyList. The actual work is done by a PropertyListBuilder (PLB for short). The basic idea of the PLB is to handle each attribute in the list in turn, find an appropriate "Maker" for it, call the Maker to convert the attribute value into a Property object of the correct type, and store that Property in the PropertyList.
| Finding a Maker |
The PLB finds a "Maker" for the property based on the attribute name and the element name. Most Makers are generic and handle the attribute on any element, but it's possible to set up an element-specific property Maker. The attribute name to Maker mappings are automatically created during the code generation phase by processing the XML property description files.
| Processing the attribute list |
The PLB first looks to see if the font-size property is specified, since it sets up relative units which can be used in other property specifications. Each attribute is then handled in turn. If the attribute specifies part of a compound property such as space-before.optimum, the PLB looks to see if the attribute list also contains the "base" property (space-before in this case) and processes that first.
| How the Property Maker works |
There is a family of Maker objects for each of the property datatypes, such as Length, Number, Enumerated, Space, etc. But since each Property has specific aspects such as whether it's inherited, its default value, its corresponding properties, etc. there is usually a specific Maker for each Property. All these Maker classes are created during the code generation phase by processing (using XSLT) the XML property description files to create Java classes. The Maker first checks for "keyword" values for a property. These are things like "thin, medium, thick" for the border-width property. The datatype is really a Length but it can be specified using these keywords whose actual value is determined by the "User Agent" rather than being specified in the XSL standard. For FOP, these values are currently defined in foproperties.xml. The keyword value is just a string, so it still needs to be parsed as described next. The Maker also checks to see if the property is an Enumerated type and then checks whether the value matches one of the specified enumeration values. Otherwise the Maker uses the property parser in the fo.expr package to evaluate the attribute value and return a Property object. The parser interprets the expression language and performs numeric operations and function call evaluations. If the returned Property value is of the correct type (specificed in foproperties.xml, where else?), the Maker returns it. Otherwise, it may be able to convert the returned type into the correct type. Some kinds of property values can't be fully resolved during FO tree building because they depend on layout information. This is the case of length values specified as percentages and of the special proportional-column-width(x) specification for table-column widths. These are stored as special kinds of Length objects which are evaluated during layout. Expressions involving "em" units which are relative to font-size _are_ resolved during the FO tree building however.
| Structure of the PropertyList |
The PropertyList extends HashMap and its basic function is to associate Property value objects with Property names. The Property objects are all subclasses of the base Property class. Each one simply contains a reference to one of the property datatype objects. Property provides accessors for all known datatypes and various subclasses override the accessor(s) which are reasonable for the datatype they store. The PropertyList itself provides various ways of looking up Property values to handle such issues as inheritance and corresponding properties. The main logic is: If the property is a writing-mode relative property (using start, end, before or after in its name), the corresponding absolute property value is returned if it's explicitly set on this FO. Otherwise, the writing-mode relative value is returned if it's explicitly set. If the property is inherited, the process repeats using the PropertyList of the FO's parent object. (This is easy because each PropertyList points to the PropertyList of the nearest ancestor FO.) If the property isn't inherited or no value is found at any level, the initial value is returned.
| References |
docs/design/properties.xml - a more detailed version of this (generated html in docs/html-docs/design/properties.html) src/codegen/properties.dtd - heavily commented DTD for foproperties.xml, but may not be completely up-to-date
| To Do |
| documentation |
explain PropertyManager vs. direct access Explain corresponding properties
| development |
Lots of properties are incompletely handled, especially funny kinds of keyword values and shorthand values (one attribute which sets several properties)

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.