You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-commits@xmlgraphics.apache.org by vm...@apache.org on 2003/04/22 05:52:37 UTC
cvs commit: xml-fop/src/documentation/content/xdocs/design properties.xml
vmote 2003/04/21 20:52:36
Modified: src/documentation/content/xdocs/design properties.xml
Log:
Pretty-print and white-space changes only.
Revision Changes Path
1.6 +118 -144 xml-fop/src/documentation/content/xdocs/design/properties.xml
Index: properties.xml
===================================================================
RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/design/properties.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- properties.xml 22 Apr 2003 03:48:50 -0000 1.5
+++ properties.xml 22 Apr 2003 03:52:36 -0000 1.6
@@ -1,54 +1,51 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<!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>
- <subtitle>Properties overview</subtitle>
- <authors>
- <person name="Karen Lease" email=""/>
- </authors>
- </header>
-
- <body>
-<p>During XML Parsing, the FO tree is constructed. For each FO object (some
+ <header>
+ <title>Properties</title>
+ <subtitle>Properties overview</subtitle>
+ <authors>
+ <person name="Karen Lease" email=""/>
+ </authors>
+ </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
+ <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>
-<p>The property datatypes are defined in the
+ <section>
+ <title>Property datatypes</title>
+ <p>The property datatypes are defined in the
org.apache.fop.datatypes package, except Number and String which are java
primitives. The FOP datatypes are:</p>
-<ul>
-<li>Number</li>
-<li>String</li>
-<li>ColorType</li>
-<li>Length (has several subclasses)</li>
-<li>CondLength (compound)</li>
-<li>LengthRange (compound)</li>
-<li>Space (compound)</li>
-<li>Keep (compound)</li>
-</ul>
-<p>The <em>org.apache.fop.fo.Property</em> class is the superclass for all
+ <ul>
+ <li>Number</li>
+ <li>String</li>
+ <li>ColorType</li>
+ <li>Length (has several subclasses)</li>
+ <li>CondLength (compound)</li>
+ <li>LengthRange (compound)</li>
+ <li>Space (compound)</li>
+ <li>Keep (compound)</li>
+ </ul>
+ <p>The <em>org.apache.fop.fo.Property</em> class is the superclass for all
Property subclasses. There is a subclass for each kind of property
datatype. These are named using the datatype name plus the word
Property, resulting in NumberProperty, StringProperty, and so
on. There is also a class EnumProperty which uses an <code>int</code>
primitive to hold enumerated values. There is no corresponding Enum
datatype class.</p>
-<p>The Property class provides a "wrapper" around any possible
+ <p>The Property class provides a "wrapper" around any possible
property value. Code manipulating property values (in layout for
example) usually knows what kind (or kinds) of datatypes are
acceptable for a given property and will use the appropriate accessor.</p>
-<p>The base Property class defines accessor methods for all FO property
+ <p>The base Property class defines accessor methods for all FO property
datatypes, such as getNumber(), getColorType(), getSpace(), getEnum(),
etc. It doesn't define
accessors for SVG types, since these are handled separately (at least
@@ -57,21 +54,20 @@
such as Length or ColorType. A subclass may also choose to return a
reasonable value for other accessor types. For example, a
SpaceProperty will return the optimum value if asked for a Length.</p>
- </section>
-
- <section>
- <title>Property Makers</title>
-<p>The Property class contains a nested class called
+ </section>
+ <section>
+ <title>Property Makers</title>
+ <p>The Property class contains a nested class called
<em>Maker</em>. This is the base class for all other property Makers. It
provides basic framework functionality which is overridden by the
code generated by properties.xsl from the *properties.xml files. In
particular it provides basic expression evaluation, using
PropertyParser class in the org.apache.fop.fo.expr package.</p>
-<p>Other Property subclasses such as LengthProperty define their own
+ <p>Other Property subclasses such as LengthProperty define their own
nested Maker classes (subclasses of Property.Maker). These handle
conversion from the Property subclass returned from expression
evaluation into the appropriate subclass for the property.</p>
-<p>For each generic or specific property definition in the
+ <p>For each generic or specific property definition in the
properties.xml files, a new subclass of one of the Maker classes is
created. Note that no new Property subclasses are created, only new
PropertyMaker subclasses. Once the property value has been parsed and
@@ -80,76 +76,68 @@
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
+ <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
+ </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,
+ </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
+ <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
+ <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
+ <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
+ <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
+ <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
+ </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
+ <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,
+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
@@ -158,81 +146,76 @@
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>
- <section>
- <title>Generic properties</title>
-<p>In the properties xml files, one can define generic property
+ </section>
+ <section>
+ <title>XML property specification format</title>
+ <section>
+ <title>Generic properties</title>
+ <p>In the properties xml files, one can define generic property
definitions which can serve as a basis for individual property
definitions. There are currently several generic properties defined in
foproperties.xml. An example is GenericColor, which defines basic properties
for all ColorType properties. Since the generic specification doesn't include
the inherited or default elements, these should be set in each property
which is based on GenericColor. Here is an example:</p>
-<p>
-<code>
- <property type='generic'>
+ <p>
+ <code><property type='generic'>
<name>background-color</name>
<use-generic>GenericColor</use-generic>
<inherited>false</inherited>
<default>transparent</default>
- </property>
-</code></p>
-<p>A generic property specification can include all of the elements
+ </property></code>
+ </p>
+ <p>A generic property specification can include all of the elements
defined for the property element in the DTD, including the description
of components for compound properties, and the specification of
keyword shorthands.</p>
-
-<p>Generic property specifications can be based on other generic
+ <p>Generic property specifications can be based on other generic
specifications.
An example is GenericCondPadding template which is based on the
GenericCondLength definition but which extends it by adding an inherited
element and a default value for the length component.</p>
-<p>
-Generic properties can specify enumerated values, as in the
+ <p>Generic properties can specify enumerated values, as in the
GenericBorderStyle template. This means that the list of values, which
is used by 8 properties (the "absolute" and "writing-mode-relative"
variants for each BorderStyle property) is only specified one time.</p>
-<p>
-When a property includes a "use-generic" element and includes no other
+ <p>When a property includes a "use-generic" element and includes no other
elements (except the "name" element), then no class is generated for the
property. Instead the generated mapping will associate this
property directly with an instance of the generic Maker.</p>
-<p>
-A generic class may also be hand-coded, rather than generated from the
+ <p>A generic class may also be hand-coded, rather than generated from the
properties file.
Properties based on such a generic class are indicated by the
attribute <code>ispropclass='true'</code> on the
<em>use-generic</em> element.</p>
-<p> This is illustrated by the SVG properties, most of
+ <p>This is illustrated by the SVG properties, most of
which use one of the Property subclasses defined in the
<em>org.apache.fop.svg</em>
package. Although all of these properties are now declared in
svgproperties.xml, no specific classes are generated. Classes are only
generated for those SVG properties which are not based on generic
classes defined in svg.</p>
- </section>
- <section>
- <title>Element-specific properties</title>
-<p>Properties may be defined for all flow objects or only for
+ </section>
+ <section>
+ <title>Element-specific properties</title>
+ <p>Properties may be defined for all flow objects or only for
particular flow objects. A PropertyListBuilder object will always look
first for a Property.Maker for the flow object before looking in the
general list. These are specified in the
<code>element-property-list</code> section of the properties.xml
files. The <code>localname</code> element children of this element specify for
which flow-object elements the property should be registered.</p>
-<p><em>NOTE</em>: All the properties for an object or set of objects
+ <p>
+ <em>NOTE</em>: All the properties for an object or set of objects
must be specified in a single element-property-list element. If the
same localname appears in several element lists, the later set of
properties will hide the earlier ones! Use the <em>ref</em>
functionality if the same property is to be used in different sets of
-element-specific mappings.
-</p>
- </section>
- <section>
- <title>Reference properties</title>
- <p>A property element may have a type attribute with the value
+element-specific mappings.</p>
+ </section>
+ <section>
+ <title>Reference properties</title>
+ <p>A property element may have a type attribute with the value
<code>ref</code>. The
content of the <em>name</em> child element is the name of the referenced
property (not its class-name!). This indicates that the property
@@ -245,10 +228,10 @@
than defining them again with a new name, the SVG properties simply
reference the defined FO properties. The generating mapping for the
SVG properties will use the FO Maker classes.</p>
- </section>
- <section>
- <title>Corresponding properties</title>
-<p>Some properties have both <em>absolute</em> and
+ </section>
+ <section>
+ <title>Corresponding properties</title>
+ <p>Some properties have both <em>absolute</em> and
<em>writing-mode-relative</em> forms. In general, the absolute forms
are equivalent to CSS properties, and the writing-mode-relative forms
are based on DSSSL. FO files may use either or both forms. In
@@ -256,26 +239,23 @@
was specified on the FO; otherwise the corresponding relative property
will be used if it was specified. However, a request for a relative
form will only use the specified relative value if the corresponding
-absolute value was <em>not</em> specified for that FO.
-</p>
-<p>Corresponding properties are specified in the properties.xml files
+absolute value was <em>not</em> specified for that FO.</p>
+ <p>Corresponding properties are specified in the properties.xml files
using the element <code>corresponding</code>, which has at least one
<code>propval</code> child and may have a <code>propexpr</code> child,
if the corresponding
value is calculated based on several other properties, as for
-<code>start-indent</code>.
-</p>
-<p><em>NOTE</em>: most current FOP code accesses the absolute variants
+<code>start-indent</code>.</p>
+ <p>
+ <em>NOTE</em>: most current FOP code accesses the absolute variants
of these properties, notably for padding, border, height and width
attributes. However it does use start-indent and end-indent, rather
-than the "absolute" margin properties.
-</p>
-</section>
- </section>
-
- <section>
- <title>Mapping</title>
-<p>The XSL script <code>propmap.xsl</code> is used to generate
+than the "absolute" margin properties.</p>
+ </section>
+ </section>
+ <section>
+ <title>Mapping</title>
+ <p>The XSL script <code>propmap.xsl</code> is used to generate
property mappings based on
both foproperties.xml and svgproperties.xml. The mapping classes
in the main fop packages simply load these automatically generated
@@ -284,16 +264,15 @@
object. However, for all generated classes, this method returns an
instance of the class itself (which is a subclass of Property.Maker)
and not an instance of a separate nested Maker class.</p>
-<p>For most SVG properties which use the SVG Property classes directly,
+ <p>For most SVG properties which use the SVG Property classes directly,
the generated mapper code calls the "maker" method of the SVG Property
class, which returns an instance of its nested Maker class.</p>
-<p>The property generation also handles element-specific property
+ <p>The property generation also handles element-specific property
mappings as specified in the properties XML files.</p>
- </section>
-
- <section>
- <title>Enumerated values</title>
-<p>For any property whose datatype is <code>Enum</code> or which
+ </section>
+ <section>
+ <title>Enumerated values</title>
+ <p>For any property whose datatype is <code>Enum</code> or which
contains possible enumerated values, FOP code may need to access
enumeration constants. These are defined in the interfaces whose name
is the same as the generated class name for the property,
@@ -302,7 +281,7 @@
interface defining the enumeration constants is always generated for
every property which uses the constants, even if the constants
themselves are defined in a generic class, as in BorderStyle.</p>
-<p>If a subproperty or component of a compound property has enumerated
+ <p>If a subproperty or component of a compound property has enumerated
values, the constants are defined in a nested interface whose name is
the name of the subproperty (using appropriate capitalization
rules). For example,
@@ -314,29 +293,26 @@
three nested interfaces, one for each component, and each defines
these two constants. An example of a reference in code to the constant
is <code>KeepTogether.WithinPage.AUTO</code>.</p>
-
- </section>
-
- <section>
- <title>Compound property types</title>
-<p>Some XSL FO properties are specified by compound datatypes. In the FO file,
+ </section>
+ <section>
+ <title>Compound property types</title>
+ <p>Some XSL FO properties are specified by compound datatypes. In the FO file,
these are defined by a group of attributes, each having a name of the
form <code>property.component</code>, for example
<code>space-before.minimum</code>. These are several compound
datatypes:</p>
-<ul>
-<li>LengthConditional, with components length and conditionality</li>
-<li>LengthRange, with components minimum, optimum, and maximum</li>
-<li>Space, with components minimum, optimum, maximum, precedence and
+ <ul>
+ <li>LengthConditional, with components length and conditionality</li>
+ <li>LengthRange, with components minimum, optimum, and maximum</li>
+ <li>Space, with components minimum, optimum, maximum, precedence and
conditionality </li>
-<li>Keep, with components within-line, within-column and within-page</li>
-</ul>
-<p>These are described in the properties.xml files using the element
+ <li>Keep, with components within-line, within-column and within-page</li>
+ </ul>
+ <p>These are described in the properties.xml files using the element
<code>compound</code> which has <code>subproperty</code> children. A subproperty element is much
like a property element, although it may not have an <code>inherited</code> child
-element, as only a complete property object may be inherited.
-</p>
-<p>Specific datatype classes exist for each compound property. Each
+element, as only a complete property object may be inherited.</p>
+ <p>Specific datatype classes exist for each compound property. Each
component of a compound datatype is itself stored as a Property
object. Individual components may be accessed either by directly
performing a get operation on the name, using the "dot" notation,
@@ -344,9 +320,7 @@
property, eg. <code>get("space-before").getOptimum()</code>.
In either case,
the result is a Property object, and the actual value may be accessed
-(in this example) by using the "getLength()" accessor.
-</p>
- </section>
- </body>
+(in this example) by using the "getLength()" accessor.</p>
+ </section>
+ </body>
</document>
-
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: fop-cvs-help@xml.apache.org