+++ /dev/null
-<?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>PropertyConsts Description</title>
- <authors>
- <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/>
- </authors>
- </header>
- <body>
- <section>
- <title>Introduction</title>
- <p>
- <fork href= "../PropertyConsts.html" >This class</fork>, and
- the singleton object which is <fork href=
- "../PropertyConsts.html#pconsts" >generated by the static
- initializer</fork>, is essentially a repository of the static
- data from the property classes of
- <code>org.apache.fop.fo.property</code>, and a common point of
- access for the methods of those classes.
- </p>
- </section>
- <section>
- <title>Common static data</title>
- <p></p>
- </section>
- </body>
-</document>
-
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
- "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-cocoon2/src/documentation/xdocs/dtd/book-cocoon-v10.dtd">
-
-<book software="FOP"
- title="FOP Alternative Design Properties Notes"
- copyright="@year@ The Apache Software Foundation"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- >
- <menu label="Index">
- <menu-item label="FOP Home" href="../../index.html"/>
- <menu-item label="Alt Design" href="../index.html"/>
- </menu>
- <menu label="Alt properties">
- <menu-item label="Introduction" href="index.html"/>
- <menu-item label="Classes overview" href="classes-overview.html"/>
- <menu-item label="PropertyConsts" href="PropertyConsts-class.html"/>
- <menu-item label="Simple Properties" href="simple-properties.html"/>
- <menu-item label="getInitialValue" href="getInitialValue.html"/>
- <menu-item label="Enumerated data" href="enumerated-values.html"/>
- <menu-item label="Property parsing" href="propertyExpressions.html"/>
- </menu>
-</book>
+++ /dev/null
-<?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>Property classes overview</title>
- <authors>
- <person id="pbw" name="Peter B. West"
- email="pbwest@powerup.com.au"/>
- </authors>
- </header>
- <body>
- <section>
- <title>Properties: packages</title>
- <section>
- <title>org.apache.fop.fo</title>
- <dl>
- <dt>
- <fork href="PropNames.html"><em>PropNames</em></fork>
- </dt>
- <dd>
- This class maintains an array of <fork href=
- "PropNames.html#propertyNames" >property names</fork>,
- synchronized to a complete set of property name <fork
- href= "PropNames.html#NO_PROPERTY" >constants</fork> for
- indexing property-based arrays. It includes methods to
- <fork href= "PropNames.html#getPropertyName" >convert an
- index to a name</fork> and to <fork href=
- "PropNames.html#getPropertyIndex" >convert a property name
- to an index</fork>.
- </dd>
-
- <dt>
- <fork href= "PropertyConsts-class.html"
- ><em>PropertyConsts</em></fork>
- </dt>
- <dd>
- A singleton instance of <code>PropertyConsts</code> is
- created by the static initializer of the <fork href=
- "PropertyConsts.html#pconsts" >pconsts</fork> field.
- Working from the <property> indices defined in
- PropNames, the methods in this class collect and supply
- the values of fields defined in <property> objects
- into arrays.<br/>
-
- The heart of this class in the method <fork href=
- "PropertyConsts.html#setupProperty" >setupProperty</fork>,
- which constructs the <property> name from the index,
- instantiates a singleton of the appropriate class, and
- extracts static fields by reflection from that instance
- into the arrays of field values.
- </dd>
-
- <dt>
- <fork href= "PropertySets.html"
- ><em>PropertySets</em></fork>
- </dt>
- <dd>
- This class provides a number of
- <code>ROBitSet</code>s representing many of the sets
- of properties defined in <em>Section 7</em> of the
- specification. Note that the <em>Border</em>,
- <em>Padding</em> and <em>Background</em> sets are
- defined separately.
- </dd>
-
- <dt><fork href= "FOPropertySets.html"
- ><em>FOPropertySets</em></fork></dt>
- <dd>
- This class provides a number of
- <code>ROBitSet</code>s representing sets of
- properties which are applicable in particular subtrees
- of the FO tree. These sets are provided so that other
- properties can be ignored during processing of the
- subtrees.
- </dd>
-
- <dt><fork href= "ShorthandPropSets.html"
- ><em>ShorthandPropSets</em></fork></dt>
- <dd>
- This class contains arrays of <fork href=
- "ShorthandPropSets.html#shorthands" >shorthand property
- indices</fork> and <fork href=
- "ShorthandPropSets.html#compounds" >compound property
- indices</fork>, and <code>ROBitSet</code>s representing
- the expansion sets of these shorthands and compounds.
- Various methods useful in the expansion of these
- properties are also included.
- </dd>
-
- <dt>
- <fork href= "FOAttributes.html"
- ><em>FOAttributes</em></fork>
- </dt>
- <dd>
- This class manages the attribute set that is associated
- with a SAX <code>startElement</code> event. <em>fo:</em>
- namespace attributes are entered into a
- <code>HashMap</code>, indexed by the <em>fo:</em>
- <property> index. As other namespaces are
- encountered, the values are entered into
- namespace-specific <code>HashMap</code>s, indexed by the
- <em>local name</em> of the attribute.
- </dd>
-
- </dl>
- </section>
- <section>
- <title>org.apache.fop.fo.properties</title>
- <dl>
- <dt><em>Property</em></dt>
- <dd>
- The base class for all individual <property>
- classes. There are 320 properties in all.
- </dd>
- <dt><em>ColumnNumber</em></dt>
- <dd>
- The actual <property> class with the lowest index
- number, followed in the index order by properties
- required for further processing, e.g. FontSize.
- </dd>
- <dt><em>....</em></dt>
- <dd>....</dd>
- <dt><em>Background</em></dt>
- <dd>
- First in index order of the remainining shorthand
- properties, followed in index order by all other
- remaining shorthands.
- </dd>
- <dt><em>....</em></dt>
- <dd>....</dd>
- <dt><em>AbsolutePosition</em></dt>
- <dd>
- First in index order of the remaining properties.
- Within this ordering, compound properties precede their
- expansion properties, and corresponding relative
- properties precede corresponding absolute properties.
- </dd>
- <dt><em>....</em></dt>
- <dd>....</dd>
- <dt><em>ZIndex</em></dt>
- <dd>
- The <property> class with the highest index
- number.
- </dd>
- </dl>
- </section>
- <section>
- <title>org.apache.fop.fo.expr</title>
- <dl>
- <dt><fork href= "PropertyTokenizer.html"
- ><em>PropertyTokenizer</em></fork></dt>
- <dd>
- The tokenizer for the <property> expression parser.
- Defines a set of <fork href= "PropertyTokenizer.html#EOF"
- >token constants</fork> and returns these with associated
- token values.
- </dd>
-
- <dt><fork href= "PropertyParser.html"
- ><em>PropertyParser</em></fork></dt>
- <dd>
- This extends <code>PropertyTokenizer</code>. It
- parses <property> expressions on the basis of the
- tokens passed to it by its superclass, generating
- <code>PropertyValue</code>s, including
- <code>PropertyValueList</code>s.
- </dd>
-
- <dt><em>PropertyException</em></dt>
- <dd>
- The basic class for all <property>-related
- exceptions. It extends
- <code>FOPException</code>. It is housed in this
- package by historical accident.
- </dd>
-
- <dt>
- <em>DataTypeNotImplementedException</em><br/>
- <em>FunctionNotImplementedException</em><br/>
- <em>PropertyNotImplementedException</em>
- </dt>
- <dd>
- A set of particular exceptions extending
- <code>PropertyException</code>. Also in this package
- by accident.
- </dd>
-
- </dl>
- </section>
- <section>
- <title>org.apache.fop.datatypes</title>
- <dl>
- <dt>
- <fork href= "PropertyValue.html"
- ><em>PropertyValue</em></fork>
- </dt>
- <dd>
- An <em>interface</em> which all
- <code>PropertyValue</code> classes must implement. In
- addition to a few methods, <code>PropertyValue</code>
- defines the set of <fork href=
- "PropertyValue.html#NO_TYPE" >constants</fork> which the
- <code>getType()</code> method may return; i.e. the valid
- set of <code>PropertyValue</code> types.
- </dd>
-
- <dt><em>AbstractPropertyValue</em></dt>
- <dd>
- An abstract implementation of the
- <code>PropertyValue</code> interface. Most actual
- property value classes extend
- <code>AbstractPropertyValue</code>.
- </dd>
-
- <dt><em>PropertyValueList</em></dt>
- <dd>
- This class extends <code>LinkedList</code> and implements
- <code>PropertyValue</code>. It is used whenever the
- process of resolving a property expression yields a list
- of <code>PropertyValue</code> elements; notably during the
- processing of shorthands and "compound" properties.
- </dd>
-
- <dt><em>StringType</em></dt>
- <dd>
- A basic type extending <code>AbstractPropertyValue</code>.
- Extended by <code>NCName</code>.
- </dd>
-
- <dt><em>NCName</em></dt>
- <dd>
- Extends <code>StringType</code> to represent
- NCName strings.
- </dd>
-
- <dt><em>EnumType</em></dt>
- <dd>
- Extends <code>AbstractPropertyValue</code> to represented
- enumerated types.
- </dd>
-
- <dt>
- <em>Other types</em>
- </dt>
- <dd>
- All other types extend one of the above classes.
- </dd>
-
- </dl>
- </section>
- <section>
- <title>org.apache.fop.datatypes.indirect</title>
- <dl>
- <dt><em>IndirectValue</em></dt>
- <dd>
- The base type for all indirect value types; extends
- <code>AbstractPropertyValue</code>.
- </dd>
- </dl>
- </section>
- </section>
- <p>
- <strong>Previous:</strong> <link href= "alt-properties.html"
- >alt.properties</link>
- </p>
- <!--
- <p>
- <strong>Next:</strong> <link href= "properties-classes.html"
- >Properties classes</link>
- </p>
- -->
- </body>
-</document>
-
+++ /dev/null
-<?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>Enumerated Data Values</title>
- </header>
- <body>
- <section>
- <title>Enumerated Data Values</title>
- <p>
- Property classes which allow enumerated data types must encode
- integer constants representing the enumeration tokens, and
- must provide a way of translating between the tokens and the
- integers, and <em>vice versa</em>. Depending on the number of
- tokens in an enumeration set, the mapping from token to
- integer is maintained in an array or a <code>HashMap</code>.
- The switch-over point from array to <code>HashMap</code> was
- determined by some highly implementation-dependent testing to
- be in the region of four to five elements.
- </p>
- <p>
- Many properties share common sets of enumeration tokens,
- e.g. those which allow color values, and those applying to
- borders and padding. A special case of enumerated value is
- the mapped numeric enumeration, in which a token maps to a
- Numeric value. These situations are discussed below.
- </p>
-
- <section>
- <title id="enum-property-array" >Array representation</title>
-
- <p>
- <fork href= "Direction.html" ><code
- >org.apache.fop.fo.properties.Direction</code></fork > is an
- example of a class which supports an enumerated value with a
- small set of tokens. The <fork href=
- "Direction.html#dataTypes" ><code>dataTypes</code></fork >
- field contains the <fork href= "Property.html#NOTYPE" ><code
- >ENUM</code> data type constant, defined in <code
- >Property</code></fork >. The enumeration integer constants
- are defined as <code>public static final int</code>
- values, <fork href= "Direction.html#LTR" ><code>LTR</code>
- and <code>RTL</code></fork >. Associating enumeration
- tokens with these integer constants occurs in the array
- <fork href= "Direction.html#rwEnums" ><code>String[]
- rwEnums</code></fork >, which is initialized with the token
- strings. By convention, zero is never used to represent a
- valid enumeration constant, anywhere in this code. It is,
- of course, critical that synchronization between <code
- >rwEnums</code> and the enumeration constants be
- maintained.`
- </p>
- <p>
- The publicly accessible mapping from enumeration token to
- enumeration constant is achieved through the method <fork
- href= "Direction.html#getEnumIndex" ><code>int
- getEnumIndex(String)</code></fork >. The corresponding
- mapping from enumeration constant to enumeration token is
- achieved through the method <fork href=
- "Direction.html#getEnumText" ><code>String
- getEnumText(int)</code></fork >.
- </p>
-
- </section>
-
- <section>
- <title id="enum-property-hashmap" >HashMap representation</title>
-
- <p>
- <fork href= "RenderingIntent.html" ><code
- >org.apache.fop.fo.properties.RenderingIntent</code></fork >
- is an example of a class which supports an enumerated value
- with a larger set of tokens. The <fork href=
- "RenderingIntent.html#dataTypes" ><code>dataTypes</code
- ></fork > field contains the <fork href=
- "Property.html#NOTYPE" ><code>ENUM</code> data type
- constant, defined in <code>Property</code></fork >.
- Enumeration integer constants are defined as <fork
- href= "RenderingIntent.html#PERCEPTUAL" ><code>public static
- final int</code></fork > values. Zero is never used to
- represent a valid enumeration constant. The enumeration
- tokens are stored in the array <fork href=
- "RenderingIntent.html#rwEnums" ><code>String[] rwEnums</code
- ></fork >, which is initialized with the token strings.
- Association of enumeration tokens with the integer constants
- occurs in the <code>HashMap</code> <fork href=
- "RenderingIntent.html#rwEnumHash" ><code> rwEnumHash</code
- ></fork >, which is initialized from the token array in a
- <code>static {}</code> initializer. It is, of course,
- critical that synchronization between <code>rwEnums</code>
- and the enumeration constants be maintained.`
- </p>
- <p>
- The publicly accessible mapping from enumeration token to
- enumeration constant is achieved through the method <fork
- href= "RenderingIntent.html#getEnumIndex" ><code>int
- getEnumIndex(String)</code></fork >. The corresponding
- mapping from enumeration constant to enumeration token is
- achieved through the method <fork href=
- "RenderingIntent.html#getEnumText" ><code>String
- getEnumText(int)</code></fork >.
- </p>
- </section>
- <section>
- <title id= "common-enum-values" >
- Factoring Out Common Enumeration Values
- </title>
- <p>
- When a number of properties support a common enumerated
- value, that value and its associated access methods may be
- factored out to a new class, which each of the properties
- then extends. An example of such a common super-class is
- <fork href= "BorderCommonStyle.html" ><code
- >BorderCommonStyle</code></fork >. Like a property with a
- normal HashMap representation of an enumerated value,
- BorderCommonStyle defines <fork href=
- "BorderCommonStyle.html#PERCEPTUAL" ><code>public static
- final int</code></fork > enumeration integer constants.
- Similarly, the enumeration tokens are stored in the array
- <fork href= "BorderCommonStyle.html#rwEnums" ><code
- >String[] rwEnums</code></fork >, and the association of
- enumeration tokens with the integer constants occurs in the
- <code>HashMap</code> <fork href=
- "BorderCommonStyle.html#rwEnumHash" ><code>
- rwEnumHash</code></fork >, initialized in a <code>static
- {}</code> initializer. The mapping methods <fork href=
- "BorderCommonStyle.html#getEnumIndex" ><code>int
- getEnumIndex(String)</code></fork > and <fork href=
- "BorderCommonStyle.html#getEnumText" ><code>String
- getEnumText(int)</code></fork > are also present.
- </p>
-
- <p>
- Notice, however, that the class has none of the static data
- constants described in the discussion of <link href=
- "simple-properties.html" >simple properties</link>. These
- values are defined in the individual sub-classes of this
- class, e.g. <fork href= "BorderLeftStyle.html" ><code
- >BorderLeftStyle</code></fork >. None of the above fields
- or methods occur, and <code>BorderLeftStyle</code> is left
- looking like an example of a simple property. The
- enumeration mapping methods are, however, available through
- the super-class <code>BorderCommonStyle</code>.
- </p>
-
- </section>
-
- <section>
- <title>Mapped Numeric Values</title>
- <p>
- In "normal" enumerated values, the token is, effectively,
- passed directly into the layout operation of the flow object
- to which the property is applied. Some enumerated values,
- however, generate a <code>Numeric</code> result. Their
- resolution involves mapping the token to the indicated
- <code>Numeric</code> value.
- </p>
- <p>
- An example is the <fork href= "BorderCommonWidth.html"
- ><code>BorderCommonWidth</code></fork > property. This,
- like the example of <link href= "#common-enum-values" ><code
- >BorderCommonStyle</code></link > above, also represents
- common enumerated values which have been factored out to
- form a super-class for particular properties. <code
- >BorderCommonWidth</code>, therefore, also defines <fork
- href= "BorderCommonWidth.html#THIN" ><code>enumeration
- constant values</code></fork > and an array of tokens. In
- this case, there is no <code>HashMap</code>, because of the
- limited number of tokens, but the mapping methods <fork
- href= "BorderCommonWidth.html#getEnumIndex" ><code>int
- getEnumIndex(String)</code></fork > and <fork href=
- "BorderCommonWidth.html#getEnumText" ><code>String
- getEnumText(int)</code></fork > are present.
- </p>
-
- <p>
- The added element in this property is the array <fork href=
- "BorderCommonWidth.html#mappedPoints" ><code>double[]
- mappedPoints</code></fork >. The entries in this array
- must by maintained in syncronization with the <fork href=
- "BorderCommonWidth.html#rwEnums" ><code>String[]
- rwEnums</code></fork > array of tokens and the set of <fork
- href= "BorderCommonWidth.html#THIN" >enumeration
- constants</fork >. The mapping from token to Numeric value
- is achieved by the <fork href=
- "BorderCommonWidth.html#getMappedLength" ><code>Numeric
- getMappedLength(FONode, int, int)</code></fork > method.
- </p>
- <p>
- <fork href= "BorderLeftWidth.html" ><code
- >BorderLeftWidth</code></fork > extends <fork href=
- "BorderCommonWidth.html" ><code>BorderCommonWidth</code
- ></fork >. It includes the basic static data, like <link
- href= "simple-properties.html" >simple properties</link>,
- and, in this case, the <fork href=
- "BorderLeftWidth.html#getInitialValue" ><code>PropertyValue
- getInitialValue(int)</code></fork > method to derive the
- initial value.
- </p>
- <section>
- <title>Deriving Mapped Numeric Values</title>
- <p>
- As usual with property values, the usual method of
- deriving a mapped numeric value is by calling the <fork
- href= "../PropertyConsts.html#getMappedNumeric" ><code
- >Numeric getMappedNumeric(FONode, int, int)</code></fork
- > method in <fork href= "../PropertyConsts.html#pconsts"
- ><code>pconsts</code></fork >. All properties which
- support a mapped numeric value must have a <code>Numeric
- getMappedNumeric(FONode, int)</code> method, which will
- be called through its singleton instance by the <code
- >PropertyConsts</code> method.
- </p>
- </section>
- </section>
- </section>
- </body>
-</document>
+++ /dev/null
-<?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>Generating Initial Values</title>
- <authors>
- <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/>
- </authors>
- </header>
- <body>
- <section>
- <title>Introduction</title>
- <p>
- The <link href= "property-data.html" >previous section</link>
- discussed the common data elements in the simplest examples of
- property classes. This section discusses more complex classes
- whose facilities are accessed only through various methods.
- </p>
- </section>
- <section>
- <title id= "initial-values" >
- Generating & Accessing Initial Values
- </title>
-
- <p>
- <fork href= "AutoRestore.html" ><code
- >org.apache.fop.fo.properties.AutoRestore</code ></fork> is an
- example of a the next most complex property class. In
- addition to all of the common static fields, these classes
- have initial data value types which require the dynamic
- generation of a PropertyValue instance.
- </p>
-
- <p>
- The method <fork href= "AutoRestore.html#getInitialValue"
- ><code >PropertyValue getInitialValue(int)</code ></fork >
- returns an instance of PropertyValue of the appropriate
- subclass containing the initial value for this property. Like
- the static data fields, this value is, in turn, stored in the
- array of initial values maintained in the <fork href=
- "../PropertyConsts.html" ><code >PropertyConsts</code ></fork>
- singleton <fork href= "../PropertyConsts.html#pconsts" ><code
- >pconsts</code ></fork>.` As with the fields, the first
- invocation of the method <fork href=
- "../PropertyConsts.html#setupProperty" ><code
- >setupProperty</code ></fork> on the property instantiates the
- singleton instance of the class, and stores that instance in
- the in the <fork href= "../PropertyConsts.html#properties"
- ><code >Property[] properties</code ></fork> array of <fork
- href= "../PropertyConsts.html#pconsts" ><code >pconsts</code
- ></fork>.
- </p>
-
- <p>
- Unlike the static data fields, however, the initial value is
- not immediately generated. It is generated by a call to <fork
- href= "../PropertyConsts.html#getInitialValue" ><code
- >PropertyValue getInitialValue(int)</code ></fork> in <fork
- href= "../PropertyConsts.html#pconsts" ><code >pconsts</code
- ></fork>. A side-effect of this call is to store the initial
- value in <fork
- href="../PropertyConsts.html#initialValues"><code
- >PropertyValue[] initialValues</code ></fork>.
- </p>
- <section>
- <title>Properties without
- <code>getInitialValue()</code></title>
- <p>
- What about property classes which have no
- <code>getInitialValue()</code> method? The simplest
- classes, e.g. <code>Character</code>, fall into this
- category. As <link href=
- "classes-overview.html#property-classes" >noted
- previously</link >, all of the property classes extend <code
- >org.apache.fop.fo.properties.Property</code >. <fork href=
- "Property.html" ><code >Property</code ></fork > provides a
- base <fork href= "Property.html#getInitialValue" ><code
- >PropertyValue getInitialValue(int)</code ></fork> method to
- which the simple classes fall back. Note that it is only
- valid for <code >NOTYPE_IT</code >, <code >AUTO_IT</code >,
- <code >NONE_IT</code > and <code >AURAL_IT</code > initial
- value types, so all classes which have any other initial
- value type must override this method.
- </p>
- </section>
- </section>
- </body>
-</document>
+++ /dev/null
-<?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>Implementing Properties</title>
- <authors>
- <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/>
- </authors>
- </header>
- <body>
- <section>
- <title>An alternative properties implementation</title>
- <note>
- The following discussion focusses on the relationship between
- Flow Objects in the Flow Object tree, and properties. There
- is no (or only passing) discussion of the relationship between
- properties and traits, and by extension, between properties
- and the Area tree.
- </note>
- <p>
- Property handling is complex and expensive. Varying numbers of
- properties <strong>apply</strong> to individual Flow Objects
- <strong>(FOs)</strong> in the <strong>FO tree </strong> but
- any property may effectively be assigned a value on any
- element of the tree. If that property is inheritable, its
- defined value will then be available to any children of the
- defining FO.
- </p>
- <note>
- <em>(XSL 1.0 Rec)</em> <strong>5.1.4 Inheritance</strong>
- ...The inheritable properties can be placed on any formatting
- object.
- </note>
- <p>
- Even if the value is not inheritable, it may be accessed by
- its children through the <code>inherit</code> keyword or the
- <code>from-parent()</code> core function, and potentially by
- any of its descendents through the
- <code>from-nearest-specified-value()</code> core function.
- </p>
- <p>
- In addition to the assigned values of properties, almost every
- property has an <strong>initial value</strong> which is used
- when no value has been assigned.
- </p>
- <section>
- <title>The history problem</title>
- <p>
- The difficulty and expense of handling properties comes from
- this univeral inheritance possibility. The list of properties
- which are assigned values on any particular <em>FO</em>
- element will not generally be large, but a current value is
- required for each property which applies to the <em>FO</em>
- being processed.
- </p>
- <p>
- The environment from which these values may be selected
- includes, for each <em>FO</em>, <strong>for each applicable
- property</strong>, the value assigned on this <em>FO</em>,
- the value which applied to the parent of this <em>FO</em>,
- the nearest value specified on an ancestor of this element,
- and the initial value of the property.
- </p>
- </section>
- <section>
- <title>The construction hierarchy</title>
- <p>
- Properties are resoved in the <strong>FO tree</strong> in a
- strictly hierarchical manner. Nodes are detected in the
- input in a <strong>pre-order</strong> traversal, and are
- built in the same order. This imples that there are two
- phases, or states, of property resolution and construction.
- Any particular FO node is either in a state of constructing
- its own subtree, or in a stable state where the subtree
- construction is complete. These states have differenct data
- requirements.
- </p>
- <dl>
- <dt>Subtree building</dt>
- <dd>
- In this state, all properties defined on this node, or any
- of its ancestors must be available to the subtree. In
- effect, any property defined on this node must be
- available to its descendants, as all properties defined on
- any ancestor are available to this node.
- </dd>
- <dt>Stable: subtree building complete</dt>
- <dd>
- In this state, only the properties <strong>applicable to
- this node</strong> need be available.
- </dd>
- </dl>
- </section>
- <section>
- <title>Representing properties: <property> classes</title>
- <section>
- <title>Class vs instance</title>
- <p>
- What information is required of <property> objects?
- More particularly, what information is particular to the
- <property> classes, and what to the instantiated
- objects? The answer to this question depend largely on
- how the <property> objects are used in the context
- of layout and Area tree construction. The approach taken
- in this implementation is that properties are simply flags
- on certain data values associated with FOs. The semantics
- of these flags are determined within the layout engine.
- </p>
- <p>
- Certain constant information attaches to individual
- <property> classes. This information is detailed in
- the descriptions of individual properties in <em>Section
- 7</em> of the specification. Such information is
- represented in <strong>class</strong> fields and data
- structures within the classes.
- </p>
- <p>
- The "instance" information content of a <property>
- is:
- </p>
- <ul>
- <li>
- explicitly, the <code>PropertyValue</code> datum of
- the property, and
- </li>
- <li>
- implicitly, the <strong>Flow Object</strong> to which
- the property is attached.
- </li>
- </ul>
- <p>
- Properties, then, serve essentially to link <em>FO
- instances</em> with <em>PropertyValue instances</em>,
- attaching certain invariant semantic markers to the
- PropertyValues in the process. In this implementation,
- these functions can be realised entirely within the
- <property> <strong>classes</strong> themselves,
- without the need to instantiate any objects. In practice,
- <strong><property> singletons</strong> are
- instantiated to make access to some invariants simpler.
- </p>
- </section>
- </section>
- <p>
- <strong>Next:</strong> <link href="classes-overview.html"
- >property classes overview.</link>
- </p>
- </section>
- </body>
-</document>
-
+++ /dev/null
-<?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>Property Expression Parsing</title>
- <authors>
- <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/>
- </authors>
- </header>
- <body>
- <section>
- <title>Property expression parsing</title>
- <p>
- The parsing of property value expressions is handled by two
- closely related classes: <fork href=
- "../PropertyTokenizer.html" ><code
- >org.apache.fop.fo.expr.PropertyTokenizer</code ></fork > and
- its subclass, <fork href= "../PropertyParser.html" ><code
- >org.apache.fop.fo.expr.PropertyParser</code ></fork >, and by
- refineParsing(int, FONode, PropertyValue) methods in the
- individual property classes.. <code >PropertyTokenizer</code
- >, as the name suggests, handles the tokenizing of the
- expression, handing <em>tokens</em> back to its subclass,
- <code >PropertyParser</code >. <code >PropertyParser</code >,
- in turn, returns a <code >PropertyValueList</code >, a list of
- <code >PropertyValue</code >s.
- </p>
- <p>
- The tokenizer and parser rely in turn on the datatype
- definition from the <code >org.apache.fop.datatypes</code >
- package and the datatype <code >static final int</code >
- constants from <code >PropertyConsts</code >.
- </p>
- <section>
- <title>Data types</title>
- <p>
- The data types currently defined in
- <code >org.apache.fop.datatypes</code > include:
- </p>
- <table>
- <tr><th colspan="2" >Numbers and lengths</th></tr>
- <tr>
- <th>Numeric</th>
- <td colspan="3" >
- The fundamental numeric data type. <em>Numerics</em> of
- various types are constructed by the classes listed
- below.
- </td>
- </tr>
- <tr>
- <td/>
- <th colspan="3" >Constructor classes for <em>Numeric</em></th>
- </tr>
- <tr>
- <td/><td>Angle</td>
- <td colspan="2" >In degrees(deg), gradients(grad) or
- radians(rad)</td>
- </tr>
- <tr>
- <td/><td>Ems</td>
- <td colspan="2" >Relative length in <em>ems</em></td>
- </tr>
- <tr>
- <td/><td>Frequency</td>
- <td colspan="2" >In hertz(Hz) or kilohertz(kHz)</td>
- </tr>
- <tr>
- <td/><td>IntegerType</td><td/>
- </tr>
- <tr>
- <td/><td>Length</td>
- <td colspan="2" >In centimetres(cm), millimetres(mm),
- inches(in), points(pt), picas(pc) or pixels(px)</td>
- </tr>
- <tr>
- <td/><td>Percentage</td><td/>
- </tr>
- <tr>
- <td/><td>Time</td>
- <td>In seconds(s) or milliseconds(ms)</td>
- </tr>
- <tr><th colspan="2" >Strings</th></tr>
- <tr>
- <th>StringType</th>
- <td colspan="3" >
- Base class for data types which result in a <em>String</em>.
- </td>
- </tr>
- <tr>
- <td/><th>Literal</th>
- <td colspan="2" >
- A subclass of <em>StringType</em> for literals which
- exceed the constraints of an <em>NCName</em>.
- </td>
- </tr>
- <tr>
- <td/><th>MimeType</th>
- <td colspan="2" >
- A subclass of <em>StringType</em> for literals which
- represent a mime type.
- </td>
- </tr>
- <tr>
- <td/><th>UriType</th>
- <td colspan="2" >
- A subclass of <em>StringType</em> for literals which
- represent a URI, as specified by the argument to
- <em>url()</em>.
- </td>
- </tr>
- <tr>
- <td/><th>NCName</th>
- <td colspan="2" >
- A subclass of <em>StringType</em> for literals which
- meet the constraints of an <em>NCName</em>.
- </td>
- </tr>
- <tr>
- <td/><td/><th>Country</th>
- <td>An RFC 3066/ISO 3166 country code.</td>
- </tr>
- <tr>
- <td/><td/><th>Language</th>
- <td>An RFC 3066/ISO 639 language code.</td>
- </tr>
- <tr>
- <td/><td/><th>Script</th>
- <td>An ISO 15924 script code.</td>
- </tr>
- <tr><th colspan="2" >Enumerated types</th></tr>
- <tr>
- <th>EnumType</th>
- <td colspan="3" >
- An integer representing one of the tokens in a set of
- enumeration values.
- </td>
- </tr>
- <tr>
- <td/><th>MappedEnumType</th>
- <td colspan="2" >
- A subclass of <em>EnumType</em>. Maintains a
- <em>String</em> with the value to which the associated
- "raw" enumeration token maps. E.g., the
- <em>font-size</em> enumeration value "medium" maps to
- the <em>String</em> "12pt".
- </td>
- </tr>
- <tr><th colspan="2" >Colors</th></tr>
- <tr>
- <th>ColorType</th>
- <td colspan="3" >
- Maintains a four-element array of float, derived from
- the name of a standard colour, the name returned by a
- call to <em>system-color()</em>, or an RGB
- specification.
- </td>
- </tr>
- <tr><th colspan="2" >Fonts</th></tr>
- <tr>
- <th>FontFamilySet</th>
- <td colspan="3" >
- Maintains an array of <em>String</em>s containing a
- prioritized list of possibly generic font family names.
- </td>
- </tr>
- <tr><th colspan="2" >Pseudo-types</th></tr>
- <tr>
- <td colspan="4" >
- A variety of pseudo-types have been defined as
- convenience types for frequently appearing enumeration
- token values, or for other special purposes.
- </td>
- </tr>
- <tr>
- <th>Inherit</th>
- <td colspan="3" >
- For values of <em>inherit</em>.
- </td>
- </tr>
- <tr>
- <th>Auto</th>
- <td colspan="3" >
- For values of <em>auto</em>.
- </td>
- </tr>
- <tr>
- <th>None</th>
- <td colspan="3" >
- For values of <em>none</em>.
- </td>
- </tr>
- <tr>
- <th>Bool</th>
- <td colspan="3" >
- For values of <em>true/false</em>.
- </td>
- </tr>
- <tr>
- <th>FromNearestSpecified</th>
- <td colspan="3" >
- Created to ensure that, when associated with
- a shorthand, the <em>from-nearest-specified-value()</em>
- core function is the sole component of the expression.
- </td>
- </tr>
- <tr>
- <th>FromParent</th>
- <td colspan="3" >
- Created to ensure that, when associated with
- a shorthand, the <em>from-parent()</em>
- core function is the sole component of the expression.
- </td>
- </tr>
- </table>
- </section>
- <section>
- <title>Tokenizer</title>
- <p>
- The tokenizer returns one of the following token
- values:
- </p>
- <source>
- static final int
- EOF = 0
- ,NCNAME = 1
- ,MULTIPLY = 2
- ,LPAR = 3
- ,RPAR = 4
- ,LITERAL = 5
- ,FUNCTION_LPAR = 6
- ,PLUS = 7
- ,MINUS = 8
- ,MOD = 9
- ,DIV = 10
- ,COMMA = 11
- ,PERCENT = 12
- ,COLORSPEC = 13
- ,FLOAT = 14
- ,INTEGER = 15
- ,ABSOLUTE_LENGTH = 16
- ,RELATIVE_LENGTH = 17
- ,TIME = 18
- ,FREQ = 19
- ,ANGLE = 20
- ,INHERIT = 21
- ,AUTO = 22
- ,NONE = 23
- ,BOOL = 24
- ,URI = 25
- ,MIMETYPE = 26
- // NO_UNIT is a transient token for internal use only. It is
- // never set as the end result of parsing a token.
- ,NO_UNIT = 27
- ;
- </source>
- <p>
- Most of these tokens are self-explanatory, but a few need
- further comment.
- </p>
- <dl>
- <dt>AUTO</dt>
- <dd>
- Because of its frequency of occurrence, and the fact that
- it is always the <em>initial value</em> for any property
- which supports it, AUTO has been promoted into a
- pseudo-type with its on datatype class. Therefore, it is
- also reported as a token.
- </dd>
- <dt>NONE</dt>
- <dd>
- Similarly to AUTO, NONE has been promoted to a pseudo-type
- because of its frequency.
- </dd>
- <dt>BOOL</dt>
- <dd>
- There is a <em>de facto</em> boolean type buried in the
- enumeration types for many of the properties. It had been
- specified as a type in its own right in this code.
- </dd>
- <dt>MIMETYPE</dt>
- <dd>
- The property <code >content-type</code > introduces this
- complication. It can have two values of the form
- <strong>content-type:</strong><em>mime-type</em>
- (e.g. <code >content-type="content-type:xml/svg"</code >) or
- <strong>namespace-prefix:</strong><em>prefix</em>
- (e.g. <code >content-type="namespace-prefix:svg"</code >). The
- experimental code reduces these options to the payload
- in each case: an <code >NCName</code > in the case of a
- namespace prefix, and a MIMETYPE in the case of a
- content-type specification. <code >NCName</code >s cannot
- contain a "/".
- </dd>
- </dl>
- </section>
- <section>
- <title>Parser</title>
- <p>
- The parser retuns a <code >PropertyValueList</code >,
- necessary because of the possibility that a list of
- <code >PropertyValue</code > elements may be returned from the
- expressions of soem properties.
- </p>
- <p>
- <code >PropertyValueList</code >s may contain
- <code >PropertyValue</code >s or other
- <code >PropertyValueList</code >s. This latter provision is
- necessitated for the peculiar case of of
- <em>text-shadow</em>, which may contain whitespace separated
- sublists of either two or three elements, separated from one
- another by commas. To accommodate this peculiarity, comma
- separated elements are added to the top-level list, while
- whitespace separated values are always collected into
- sublists to be added to the top-level list.
- </p>
- <p>
- Other special cases include the processing of the core
- functions <code >from-parent()</code > and
- <code >from-nearest-specified-value()</code > when these
- function calls are assigned to a shorthand property, or used
- with a shorthand property name as an argument. In these
- cases, the function call must be the sole component of the
- expression. The pseudo-element classes
- <code >FromParent</code > and
- <code >FromNearestSpecified</code > are generated in these
- circumstances so that an exception will be thrown if they
- are involved in expression evaluation with other
- components. (See Rec. Section 5.10.4 Property Value
- Functions.)
- </p>
- <p>
- The experimental code is a simple extension of the existing
- parser code, which itself borrowed heavily from James
- Clark's XT processor.
- </p>
- </section>
- </section>
- </body>
-</document>
-
+++ /dev/null
-<?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>Simple <property> Classes</title>
- <authors>
- <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/>
- </authors>
- </header>
- <body>
- <section>
- <title>Introduction</title>
- <p>
- An <link href= "../classes-overview.html" >overview of the
- properties and classes</link> involved in handling properties
- has already been given. This discussion will go in detail
- into the way data are represented within properties. Iit is
- important to keep in mind that the primary avenue of access to
- the data and the methods of property classes is the <fork
- href= "../PropertyConsts.html" ><code >PropertyConsts</code
- ></fork> class and its singleton object.
- </p>
- </section>
- <section>
- <title>Common data</title>
-
- <p>
- <fork href= "Character.html" ><code
- >org.apache.fop.fo.properties.Character</code ></fork> is an
- example of a basic property class. The data fields common to
- all properties are:
- </p>
-
- <dl>
- <dt>
- <code>final int dataTypes</code>
- </dt>
- <dd>
- This field defines the allowable data types which may be
- assigned to the property. The value is chosen from the data
- type constants defined in <fork href= "Property.html#NOTYPE"
- ><code >org.apache.fop.fo.properties.Property</code
- ></fork>, and may consist of more than one of those
- constants, bit-ORed together.
- </dd>
- <dt>
- <code >final int traitMapping</code >
- </dt>
- <dd>
- This field defines the mapping of properties to traits in
- the <code>Area tree</code>. The value is chosen from the
- trait mapping constants defined in <fork href=
- "Property.html#NO_TRAIT" ><code
- >org.apache.fop.fo.properties.Property</code ></fork>, and
- may consist of more than one of those constants, bit-ORed
- together.
- </dd>
- <dt>
- <code >final int initialValueType</code >
- </dt>
- <dd>
- This field defines the data type of the initial value
- assigned to the property. The value is chosen from the
- initial value type constants defined in <fork href=
- "Property.html#NOTYPE_IT" ><code
- >org.apache.fop.fo.properties.Property</code ></fork>. In
- the simplest property classes, such as
- <code>Character</code>, there is no defined initial value
- type.
- </dd>
- <dt>
- <code >final int inherited</code >
- </dt>
- <dd>
- This field defines the kind of inheritance applicable to the
- property. The value is chosen from the inheritance
- constants defined in <fork href= "Property.html#NO" ><code
- >org.apache.fop.fo.properties.Property</code ></fork>.
- </dd>
- </dl>
- </section>
- <section>
- <title>Accessing <property> Data Constants</title>
-
- <p>
- The constants above are generally accessed through the arrays
- maintained in the <fork href= "../PropertyConsts.html" ><code
- >PropertyConsts</code ></fork> singleton <fork href=
- "../PropertyConsts.html#pconsts" ><code >pconsts</code
- ></fork>. The first invocation of the method <fork href=
- "../PropertyConsts.html#setupProperty" ><code
- >setupProperty</code ></fork> on the property generates a
- <code >Class</code > instance for the class, and stores it in
- the array <fork href= "../PropertyConsts.html#classes" ><code
- >classes</code ></fork>. This <code>Class</code> object is
- used, in turn, to instantiate the singleton instance of the
- class, which is stored in the <fork href=
- "../PropertyConsts.html#properties" ><code >Property[]
- properties</code ></fork> array of <fork href=
- "../PropertyConsts.html#pconsts" ><code >pconsts</code
- ></fork>.
- </p>
-
- <p>
- <em>Reflection</em> methods are then used, via the same
- <code>Class</code> instance, to extract and store the static
- data fields. These arrays and associated access methods are:
- </p>
-
- <dl>
- <dt>
- <fork href= "../PropertyConsts.html#datatypes" ><code >int[]
- datatypes</code ></fork>
- </dt>
- <dd>
- <fork href= "../PropertyConsts.html#getDataTypes" ><code
- >int getDataTypes(int)</code ></fork>
- </dd>
- <dt>
- <fork href= "../PropertyConsts.html#traitMappings" ><code
- >int[] traitMappings</code ></fork>
- </dt>
- <dd>
- <em>No access method yet defined.</em>
- </dd>
- <dt>
- <fork href= "../PropertyConsts.html#initialValueTypes"
- ><code >int[] initialValueTypes</code ></fork>
- </dt>
- <dd>
- <fork href= "../PropertyConsts.html#getInitialValueTypes"
- ><code >int getInitialValueTypes(int)</code ></fork>
- </dd>
- <dt>
- <fork href= "../PropertyConsts.html#inherited" ><code >int[]
- inherited</code ></fork>
- </dt>
- <dd>
- <fork href= "../PropertyConsts.html#inheritance" ><code >int
- inheritance(int)</code ></fork>
- </dd>
- </dl>
- </section>
- </body>
-</document>
projects / xmlgraphics-fop.git / commitdiff