xmlgraphics-fop-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Xmlgraphics-fop Wiki] Update of "PropertyHandling" by AndreasDelmelle
Date Sat, 30 Jun 2007 11:47:26 GMT
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


Mime
View raw message