pbwest 2002/12/26 23:50:16
Added: src/documentation/content/xdocs/design/alt.design/properties
classes-overview.xml enumerated-values.xml
getInitialValue.xml propertyExpressions.xml
simple-properties.xml
Log:
Reworking properties documentation.
Revision Changes Path
1.1
xml-fop/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml
Index: classes-overview.xml
===================================================================
<?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="[EMAIL PROTECTED]"/>
</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>
1.1
xml-fop/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml
Index: enumerated-values.xml
===================================================================
<?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>
1.1
xml-fop/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml
Index: getInitialValue.xml
===================================================================
<?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="[EMAIL PROTECTED]"/>
</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>
1.1
xml-fop/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.xml
Index: propertyExpressions.xml
===================================================================
<?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="[EMAIL PROTECTED]"/>
</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>
1.1
xml-fop/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.xml
Index: simple-properties.xml
===================================================================
<?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="[EMAIL PROTECTED]"/>
</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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
