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 &lt;property&gt; indices defined in
              PropNames, the methods in this class collect and supply
              the values of fields defined in &lt;property&gt; objects
              into arrays.<br/>
              
              The heart of this class in the method <fork href=
              "PropertyConsts.html#setupProperty" >setupProperty</fork>,
              which constructs the &lt;property&gt; 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>
              &lt;property&gt; 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 &lt;property&gt;
              classes.  There are 320 properties in all.
            </dd>
            <dt><em>ColumnNumber</em></dt>
            <dd>
              The actual &lt;property&gt; 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 &lt;property&gt; 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 &lt;property&gt; 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 &lt;property&gt; 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 &lt;property&gt;-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 &amp; 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 &lt;property&gt; 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 &lt;property&gt; 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]

Reply via email to