pbwest 2003/01/20 06:54:22
Added: src/documentation/content/design/alt.design/properties
enumerated-values.html
Log:
Code documentation
Revision Changes Path
1.1
xml-fop/src/documentation/content/design/alt.design/properties/enumerated-values.html
Index: enumerated-values.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Enumerated Data Values</title>
<style type= "text/css" >
body {
font-family: Verdana, Helvetica, sans-serif;
}
.note { border: solid 1px #7099C5; background-color: #f0f0ff; }
.note .label { background-color: #7099C5; color: #ffffff; }
.content {
padding: 5px 5px 5px 10px;
font : Verdana, Helvetica, sans-serif; font-size : 90%;
}
</style>
</head>
<body marginheight="0" marginwidth="0" topmargin="0" leftmargin="0" text="#000000"
bgcolor="#FFFFFF">
<div class="content">
<h1>Enumerated Data Values</h1>
<ul class="minitoc">
<li>
<a href="#N1000C">Enumerated Data Values</a>
<ul class="minitoc">
<li>
<a href="#N10020">Array representation</a>
</li>
<li>
<a href="#N1005C">HashMap representation</a>
</li>
<li>
<a href="#N1009D">
Factoring Out Common Enumeration Values
</a>
</li>
<li>
<a href="#N100DD">Mapped Numeric Values</a>
</li>
</ul>
</li>
</ul>
<a name="N1000C"></a>
<h3>Enumerated Data Values</h3>
<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 <span
class="codefrag">HashMap</span>. The switch-over point from
array to <span class="codefrag">HashMap</span> 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>
<a name="N10020"></a>
<h4>Array representation</h4>
<p>
<a href= "javascript:parent.displayCode(
'Direction.html#DirectionClass' )" ><span
class="codefrag">org.apache.fop.fo.properties.Direction</span></a>
is an example of a class which supports an enumerated value
with a small set of tokens. The <a href=
"javascript:parent.displayCode( 'Direction.html#dataTypes' )"
><span class="codefrag">dataTypes</span></a> field contains
the <a href= "javascript:parent.displayCode(
'Property.html#NOTYPE' )" ><span class="codefrag">ENUM</span>
data type constant, defined in <span
class="codefrag">Property</span></a>. The enumeration integer
constants are defined as <span class="codefrag">public static
final int</span> values, <a href=
"javascript:parent.displayCode( 'Direction.html#LTR') "><span
class="codefrag' )" >LTR</span> and <span
class="codefrag">RTL</span></a>. Associating enumeration
tokens with these integer constants occurs in the array <a
href= "javascript:parent.displayCode( 'Direction.html#rwEnums'
)" ><span class="codefrag">String[] rwEnums</span></a>, 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 <span class="codefrag">rwEnums</span> and the
enumeration constants be maintained.
</p>
<p>
The publicly accessible mapping from enumeration token to
enumeration constant is achieved through the method <a href=
"javascript:parent.displayCode( 'Direction.html#getEnumIndex'
)" ><span class="codefrag">int
getEnumIndex(String)</span></a>. The corresponding mapping
from enumeration constant to enumeration token is achieved
through the method <a href= "javascript:parent.displayCode(
'Direction.html#getEnumText' )" ><span class="codefrag">String
getEnumText(int)</span></a>.
</p>
<a name="N1005C"></a>
<h4>HashMap representation</h4>
<p>
<a href= "javascript:parent.displayCode(
'RenderingIntent.html#RenderingIntentClass' )" ><span
class="codefrag"
>org.apache.fop.fo.properties.RenderingIntent</span ></a> is
an example of a class which supports an enumerated value with
a larger set of tokens. The <a href=
"javascript:parent.displayCode(
'RenderingIntent.html#dataTypes' )" ><span
class="codefrag">dataTypes</span></a> field contains the <a
href= "javascript:parent.displayCode( 'Property.html#NOTYPE'
)" ><span class="codefrag">ENUM</span> data type constant,
defined in <span class="codefrag">Property</span></a>.
Enumeration integer constants are defined as <a href=
"javascript:parent.displayCode(
'RenderingIntent.html#PERCEPTUAL' )" ><span
class="codefrag">public static final int</span></a> values.
Zero is never used to represent a valid enumeration constant.
The enumeration tokens are stored in the array <a href=
"javascript:parent.displayCode( 'RenderingIntent.html#rwEnums'
)" ><span class="codefrag">String[] rwEnums</span></a>, which
is initialized with the token strings. Association of
enumeration tokens with the integer constants occurs in the
<span class="codefrag">HashMap</span> <a href=
"javascript:parent.displayCode(
'RenderingIntent.html#rwEnumHash"><span class="codefrag' )" >
rwEnumHash</span></a>, which is initialized from the token
array in a <span class="codefrag">static {}</span>
initializer. It is, of course, critical that synchronization
between <span class="codefrag">rwEnums</span> and the
enumeration constants be maintained.
</p>
<p>
The publicly accessible mapping from enumeration token to
enumeration constant is achieved through the method <a href=
"javascript:parent.displayCode(
'RenderingIntent.html#getEnumIndex' )" ><span
class="codefrag">int getEnumIndex(String)</span></a>. The
corresponding mapping from enumeration constant to enumeration
token is achieved through the method <a href=
"javascript:parent.displayCode(
'RenderingIntent.html#getEnumText' )" ><span
class="codefrag">String getEnumText(int)</span></a>.
</p>
<a name="N1009D"></a>
<h4 id="common-enum-values">
Factoring Out Common Enumeration Values
</h4>
<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 <a href=
"javascript:parent.displayCode(
'BorderCommonStyle.html#BorderCommonStyleClass' )" ><span
class="codefrag">BorderCommonStyle</span></a>. Like a
property with a normal HashMap representation of an enumerated
value, BorderCommonStyle defines <a href=
"javascript:parent.displayCode(
'BorderCommonStyle.html#HIDDEN' )" ><span
class="codefrag">public static final int</span></a>
enumeration integer constants. Similarly, the enumeration
tokens are stored in the array <a href=
"javascript:parent.displayCode(
'BorderCommonStyle.html#rwEnums' )" ><span
class="codefrag">String[] rwEnums</span></a>, and the
association of enumeration tokens with the integer constants
occurs in the <span class="codefrag">HashMap</span> <a href=
"javascript:parent.displayCode(
'BorderCommonStyle.html#rwEnumHash' )" ><span
class="codefrag"> rwEnumHash</span></a>, initialized in a
<span class="codefrag">static {}</span> initializer. The
mapping methods <a href= "javascript:parent.displayCode(
'BorderCommonStyle.html#getEnumIndex' )" ><span
class="codefrag">int getEnumIndex(String)</span></a> and <a
href= "javascript:parent.displayCode(
'BorderCommonStyle.html#getEnumText' )" ><span
class="codefrag">String getEnumText(int)</span></a> are also
present.
</p>
<p>
Notice, however, that the class has none of the static data
constants described in the discussion of <a
href="simple-properties.html">simple properties</a>. These
values are defined in the individual sub-classes of this
class, e.g. <a href= "javascript:parent.displayCode(
'BorderLeftStyle.html#BorderLeftStyleClass' )" ><span
class="codefrag">BorderLeftStyle</span></a>. None of the
above fields or methods occur, and <span
class="codefrag">BorderLeftStyle</span> is left looking like
an example of a simple property. The enumeration mapping
methods are, however, available through the super-class <span
class="codefrag">BorderCommonStyle</span>.
</p>
<a name="N100DD"></a>
<h4>Mapped Numeric Values</h4>
<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 <span class="codefrag">Numeric</span>
result. Their resolution involves mapping the token to the
indicated <span class="codefrag">Numeric</span> value.
</p>
<p>
An example is the <a href= "javascript:parent.displayCode(
'BorderCommonWidth.html#BorderCommonWidthClass' )" ><span
class="codefrag">BorderCommonWidth</span></a> property. This,
like the example of <a href="#common-enum-values"><span
class="codefrag">BorderCommonStyle</span></a> above, also
represents common enumerated values which have been factored
out to form a super-class for particular properties. <span
class="codefrag">BorderCommonWidth</span>, therefore, also
defines <a href= "javascript:parent.displayCode(
'BorderCommonWidth.html#THIN' )" ><span
class="codefrag">enumeration constant values</span></a> and an
array of tokens. In this case, there is no <span
class="codefrag">HashMap</span>, because of the limited number
of tokens, but the mapping methods <a href=
"javascript:parent.displayCode(
'BorderCommonWidth.html#getEnumIndex' )" ><span
class="codefrag">int getEnumIndex(String)</span></a> and <a
href= "javascript:parent.displayCode(
'BorderCommonWidth.html#getEnumText' )" ><span
class="codefrag">String getEnumText(int)</span></a> are
present.
</p>
<p>
The added element in this property is the array <a href=
"javascript:parent.displayCode(
'BorderCommonWidth.html#mappedPoints' )" ><span
class="codefrag">double[] mappedPoints</span></a>. The
entries in this array must by maintained in syncronization
with the <a href= "javascript:parent.displayCode(
'BorderCommonWidth.html#rwEnums' )" ><span
class="codefrag">String[] rwEnums</span></a> array of tokens
and the set of <a href= "javascript:parent.displayCode(
'BorderCommonWidth.html#THIN' )" >enumeration constants</a>.
The mapping from token to Numeric value is achieved by the <a
href= "javascript:parent.displayCode(
'BorderCommonWidth.html#getMappedLength' )" ><span
class="codefrag">Numeric getMappedLength(FONode, int,
int)</span></a> method.
</p>
<p>
<a href= "javascript:parent.displayCode(
'BorderLeftWidth.html#BorderLeftWidthClass' )" ><span
class="codefrag">BorderLeftWidth</span></a> extends <a href=
"javascript:parent.displayCode( 'BorderCommonWidth.html' )"
><span class="codefrag">BorderCommonWidth</span></a>. It
includes the basic static data, like <a
href="simple-properties.html">simple properties</a>, and, in
this case, the <a href= "javascript:parent.displayCode(
'BorderLeftWidth.html#getInitialValue' )" ><span
class="codefrag">PropertyValue getInitialValue(int)</span></a>
method to derive the initial value.
</p>
<a name="N10139"></a>
<h4>Deriving Mapped Numeric Values</h4>
<p>
As usual with property values, the usual method of deriving a
mapped numeric value is by calling the <a href=
"javascript:parent.displayCode(
'../PropertyConsts.html#getMappedNumeric' )" ><span
class="codefrag">Numeric getMappedNumeric(FONode, int,
int)</span></a> method in <a href=
"javascript:parent.displayCode(
'../PropertyConsts.html#pconsts' )" ><span
class="codefrag">pconsts</span></a>. All properties which
support a mapped numeric value must have a <span
class="codefrag">Numeric getMappedNumeric(FONode, int)</span>
method, which will be called through its singleton instance,
stored in the <a href= "javascript:parent.displayCode(
'PropertyConsts.html#properties' )" ><span class= "codefrag"
>properties</span ></a> array, by the <span
class="codefrag">PropertyConsts</span> method.
</p>
<p>
<strong>Previous:</strong> <a href= "getInitialValue.html"
>getInitialValue()</a>
</p>
<!--
<p>
<strong>Next:</strong> <a href= "getInitialValue.html"
>getInitialValue()</a>
</p>
-->
</div>
<table summary="footer" cellspacing="0" cellpadding="0" width="100%" height="20"
border="0">
<tr>
<td colspan="2" height="1" bgcolor="#4C6C8F"><img height="1"
width="1" alt="" src="../../../skin/images/spacer.gif"><a
href="../../../skin/images/label.gif"></a><a
href="../../../skin/images/page.gif"></a><a
href="../../../skin/images/chapter.gif"></a><a
href="../../../skin/images/chapter_open.gif"></a><a
href="../../../skin/images/current.gif"></a><a
href="../../..//favicon.ico"></a></td>
</tr>
<tr>
<td colspan="2" bgcolor="#CFDCED" class="copyright"
align="center"><font size="2" face="Arial, Helvetica,
Sans-Serif">Copyright © 1999-2002 The Apache
Software Foundation. All rights reserved.<script
type="text/javascript" language="JavaScript"><!--
document.write(" - "+"Last Published: " +
document.lastModified); // --></script></font></td>
</tr>
<tr>
<td align="left" bgcolor="#CFDCED" class="logos"></td><td
align="right" bgcolor="#CFDCED" class="logos"></td>
</tr>
</table>
</body>
</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
