[Xmlgraphics-fop Wiki] Update of "PropertyHandling" by AndreasDelmelle

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Xmlgraphics-fop Wiki" for change notification.

The following page has been changed by AndreasDelmelle:
http://wiki.apache.org/xmlgraphics-fop/PropertyHandling

------------------------------------------------------------------------------
  = Property Handling =
- This is currently only a placeholder to be hopefully later populated with some design details on the Property Handling subsystem. The current system is derived from http://xml.apache.org/fop/design/properties.html and the descriptions on that page are still relevant. However, the generation of the Property Handling related Java files from an XML input file as described in http://xml.apache.org/fop/design/properties.html has been abolished in the current version of the code.
-  * ["PropertyHandling/Percentages"]
  
+ == General Info ==
+ 
+ FOP's property subsystem is a component that is easily misunderstood. org.apache.fop.fo.properties.Property and its derived classes do not exactly correspond to FO properties, but rather, different ''types'' of FO properties. The mapping of a FO property name to a Property subclass is defined in org.apache.fop.fo.FO!PropertyMapping, a class that seems a bit intimidating at first glance...
+ 
+ == FOPropertyMapping ==
+ 
+ While the source file seems immense, all the code in there is only executed once for multiple FOP runs within the same virtual machine. What it gets to contain after this code has been executed, is a mapping of FO property names to one of the org.apache.fop.fo.properties.!PropertyMaker subclasses. Those !PropertyMakers have been customized to fit the behavior as mandated by or prescribed in the XSL-FO Recommendation for a given property, such as:
+  * which enums and/or value keywords are allowed as values: addEnum() and addKeyword()
+  * which shorthands can set the property: addShorthand()
+  * for shorthands, which custom parser to use: setDatatypeParser()
+  * which corresponding properties can set the property: setCorresponding()
+  * whether a property is inherited or not: setInherited()
+  * the default value: setDefault()
+ 
+ The customized !PropertyMakers in FO!PropertyMapping are used when the tree of FOs is built from the XML events coming in from the SAX Parser. 
+ In org.apache.fop.fo.FO!TreeBuilder.MainFOHandler.startElement() the current node's list of attributes is given to an instance of org.apache.fop.fo.!PropertyList, which uses the attribute names and FO!PropertyMapping to get to the right !PropertyMakers to convert each of the attribute values to the appropriate FOP-internal Property type.
+ 
+ == The PropertyMakers ==
+ 
+ There are two distinct points where !PropertyMakers are used:
+  * when an explicitly specified attribute value is converted to a Property: in the most basic case this is a call to !PropertyMaker.make(!PropertyList, String, FObj), a method that can be overridden by subclasses to cater for custom property parsing if the generic org.apache.fop.fo.expr.!PropertyParser does not suffice (see for example org.apache.fop.fo.properties.!FontProperty.Maker, which bypasses the generic space-based list parsing).
+ 
+  * when binding a !PropertyList to a FO:
+   * to supply initial values for a property that is applicable but was not specified
+   * to get to a native XSL-FO property that was explicitly set by a CSS shorthand (e.g. border-before-width and border); ideally, only the native XSL-FO properties are bound to the FOs
+   * to get to the ''relative'' property from an ''absolute'' one (e.g. space-before and margin-top)
+ 
+ == What about those PropertyLists? ==
+ 
+ !PropertyLists are relatively short-lived in most cases. The !PropertyList for the first fo:block in an fo:flow is released before the one for its sibling fo:block is created; only a reference to the parent is maintained. The only notable exception is the !PropertyList-ancestry of fo:retrieve-markers: that is preserved until layout, to be able to correctly deal with markers and property inheritance.
+ 
+ 
+ == Implementing an additional FO property in FOP without implementing a Property ==
+ 
+  * add a symbolic constant to org.apache.fop.fo.Constants.java: this will be used in the code that retrieves the right !PropertyMaker for the new Property
+  * register a !PropertyMaker for the property in org.apache.fop.fo.FO!PropertyMapping.java; implement a new one if necessary
+  * add an instance member to the applicable FOs, and bind it to the !PropertyList's Property which becomes available through the above two steps
+  * add the necessary code to the corresponding !LayoutManagers, Areas and/or Renderers to do something with the newly available property
+ 
+ == Percentages ==
+ see ["PropertyHandling/Percentages"]
+ 

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org