pbwest 2003/01/20 06:52:06
Added: src/documentation/content/design/alt.design/properties
introduction.html
Log:
Code documentation
Revision Changes Path
1.1
xml-fop/src/documentation/content/design/alt.design/properties/introduction.html
Index: introduction.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>Implementing Properties</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>Implementing Properties</h1>
<p>
<font size="-2">by Peter B. West</font>
</p>
<ul class="minitoc">
<li>
<a href="#N10014">An alternative properties implementation</a>
<ul class="minitoc">
<li>
<a href="#N10043">The history problem</a>
</li>
<li>
<a href="#N10061">The construction hierarchy</a>
</li>
<li>
<a href="#N10082">Representing properties: <property> classes</a>
</li>
</ul>
</li>
</ul>
<a name="N10014"></a>
<h3>An alternative properties implementation</h3>
<div class="frame note">
<div class="label">Note</div>
<div class="content">
The following discussion focusses on the relationship between
Flow Objects in the Flow Object tree, and properties. There
is no (or only passing) discussion of the relationship between
properties and traits, and by extension, between properties
and the Area tree.
</div>
</div>
<p>
Property handling is complex and expensive. Varying numbers of
properties <strong>apply</strong> to individual Flow Objects
<strong>(FOs)</strong> in the <strong>FO tree </strong> but
any property may effectively be assigned a value on any
element of the tree. If that property is inheritable, its
defined value will then be available to any children of the
defining FO.
</p>
<div class="frame note">
<div class="label">Note</div>
<div class="content">
<em>(XSL 1.0 Rec)</em> <strong>5.1.4 Inheritance</strong>
...The inheritable properties can be placed on any formatting
object.
</div>
</div>
<p>
Even if the value is not inheritable, it may be accessed by
its children through the <span class="codefrag">inherit</span>
keyword or the <span class="codefrag">from-parent()</span>
core function, and potentially by any of its descendents
through the <span
class="codefrag">from-nearest-specified-value()</span> core
function.
</p>
<p>
In addition to the assigned values of properties, almost every
property has an <strong>initial value</strong> which is used
when no value has been assigned.
</p>
<a name="N10043"></a>
<h4>The history problem</h4>
<p>
The difficulty and expense of handling properties comes from
this univeral inheritance possibility. The list of properties
which are assigned values on any particular <em>FO</em>
element will not generally be large, but a current value is
required for each property which applies to the <em>FO</em>
being processed.
</p>
<p>
The environment from which these values may be selected
includes, for each <em>FO</em>, <strong>for each applicable
property</strong>, the value assigned on this <em>FO</em>,
the value which applied to the parent of this <em>FO</em>,
the nearest value specified on an ancestor of this element,
and the initial value of the property.
</p>
<a name="N10061"></a>
<h4>The construction hierarchy</h4>
<p>
Properties are resoved in the <strong>FO tree</strong> in a
strictly hierarchical manner. Nodes are detected in the
input in a <strong>pre-order</strong> traversal, and are
built in the same order. This imples that there are two
phases, or states, of property resolution and construction.
Any particular FO node is either in a state of constructing
its own subtree, or in a stable state where the subtree
construction is complete. These states have differenct data
requirements.
</p>
<dl>
<dt>Subtree building</dt>
<dd>
In this state, all properties defined on this node, or any
of its ancestors must be available to the subtree. In
effect, any property defined on this node must be
available to its descendants, as all properties defined on
any ancestor are available to this node.
</dd>
<dt>Stable: subtree building complete</dt>
<dd>
In this state, only the properties <strong>applicable to
this node</strong> need be available.
</dd>
</dl>
<a name="N10082"></a>
<h4>Representing properties: <property> classes</h4>
<a name="N10087"></a>
<h4>Class vs instance</h4>
<p>
What information is required of property objects?
More particularly, what information is particular to the
property classes, and what to the instantiated
objects? The answer to this question depend largely on
how the property objects are used in the context
of layout and Area tree construction. The approach taken
in this implementation is that properties are simply flags
on certain data values associated with FOs. The semantics
of these flags are determined within the layout engine.
</p>
<p>
Certain constant information attaches to individual
property classes. This information is detailed in
the descriptions of individual properties in <em>Section
7</em> of the specification. Such information is
represented in <strong>class</strong> fields and data
structures within the classes.
</p>
<p>
The "instance" information content of a property
is:
</p>
<ul>
<li>
explicitly, the <span class="codefrag">PropertyValue</span> datum of
the property, and
</li>
<li>
implicitly, the <strong>Flow Object</strong> to which
the property is attached.
</li>
</ul>
<p>
Properties, then, serve essentially to link <em>FO
instances</em> with <em>PropertyValue instances</em>,
attaching certain invariant semantic markers to the
PropertyValues in the process. In this implementation,
these functions can be realised entirely within the
property <strong>classes</strong> themselves,
without the need to instantiate any objects. In practice,
<strong>property singletons</strong> are
instantiated to make access to some invariants simpler.
</p>
<p>
<strong>Next:</strong> <a href= "classes-overview.html"
>Property classes overview.</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]
