diff options
| author | William Victor Mote <vmote@apache.org> | 2003-04-22 03:48:50 +0000 |
|---|---|---|
| committer | William Victor Mote <vmote@apache.org> | 2003-04-22 03:48:50 +0000 |
| commit | 8cdfb6864aae467e60546f471cabcb02d01ff3d3 (patch) | |
| tree | 35582e16acda9768ad18b88dc4a1775b63c44a89 | |
| parent | 94c204d2d91d633b2d89a28f869691c1f65e5b73 (diff) | |
| download | xmlgraphics-fop-8cdfb6864aae467e60546f471cabcb02d01ff3d3.tar.gz xmlgraphics-fop-8cdfb6864aae467e60546f471cabcb02d01ff3d3.zip | |
Move content from design/understanding/properties.xml to design/properties.xml.
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196309 13f79535-47bb-0310-9956-ffa450edef68
4 files changed, 87 insertions, 109 deletions
diff --git a/src/documentation/content/xdocs/design/book.xml b/src/documentation/content/xdocs/design/book.xml index d61836598..6dbd600f9 100644 --- a/src/documentation/content/xdocs/design/book.xml +++ b/src/documentation/content/xdocs/design/book.xml @@ -26,7 +26,6 @@ understanding/book.xml, WHICH SEE FOR AN EXPLANATION. <menu-item label="Introduction" href="understanding/index.html"/> <menu-item label="XML Parsing" href="understanding/xml_parsing.html"/> <menu-item label="FO Tree" href="understanding/fo_tree.html"/> - <menu-item label="Properties" href="understanding/properties.html"/> </menu> <menu label="Extras"> <menu-item label="Images" href="understanding/images.html"/> diff --git a/src/documentation/content/xdocs/design/properties.xml b/src/documentation/content/xdocs/design/properties.xml index 797655f46..23142518b 100644 --- a/src/documentation/content/xdocs/design/properties.xml +++ b/src/documentation/content/xdocs/design/properties.xml @@ -12,6 +12,15 @@ </header> <body> +<p>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.</p> +<p>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.</p> <section> <title>Property datatypes</title> @@ -71,6 +80,84 @@ specific. Maker subclasses define such aspects as keyword substitutions, whether the property can be inherited or not, which enumerated values are legal, default values, corresponding properties and specific datatype conversions.</p> +<p> +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.</p> +</section> +<section> + <title>Processing the attribute list</title> +<p>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.</p> +</section> +<section> + <title>How the Property Maker works</title> +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> +</section> +<section> + <title>Structure of the PropertyList</title> +<p>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.</p> + +<p>The PropertyList itself provides various ways of looking up Property +values to handle such issues as inheritance and corresponding +properties. </p> + +<p>The main logic is:<br/>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. <br/>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.</p> </section> <section> <title>XML property specification format</title> diff --git a/src/documentation/content/xdocs/design/understanding/book.xml b/src/documentation/content/xdocs/design/understanding/book.xml index dd9c2589d..a37bd6e9a 100644 --- a/src/documentation/content/xdocs/design/understanding/book.xml +++ b/src/documentation/content/xdocs/design/understanding/book.xml @@ -30,7 +30,6 @@ PARENT DIRECTORY! <menu-item label="Introduction" href="index.html"/> <menu-item label="XML Parsing" href="xml_parsing.html"/> <menu-item label="FO Tree" href="fo_tree.html"/> - <menu-item label="Properties" href="properties.html"/> </menu> <menu label="Extras"> <menu-item label="Images" href="images.html"/> diff --git a/src/documentation/content/xdocs/design/understanding/properties.xml b/src/documentation/content/xdocs/design/understanding/properties.xml deleted file mode 100644 index 6e2348549..000000000 --- a/src/documentation/content/xdocs/design/understanding/properties.xml +++ /dev/null @@ -1,107 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> - -<document> - <header> - <title>Properties</title> - </header> - - <body> -<p>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.</p> -<p>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.</p> - -<section> - <title>Finding a Maker</title> -<p> -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.</p> -</section> - -<section> - <title>Processing the attribute list</title> -<p>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.</p> -</section> -<section> - <title>How the Property Maker works</title> -<p>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.</p> - -<p>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.</p> - -<p>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.</p> - -<p>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.</p> - -<p>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.</p> - -<p>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.</p> -</section> - -<section> - <title>Structure of the PropertyList</title> -<p>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.</p> - -<p>The PropertyList itself provides various ways of looking up Property -values to handle such issues as inheritance and corresponding -properties. </p> - -<p>The main logic is:<br/>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. <br/>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.</p> -</section> - - </body> -</document> - |