From b5f6238fe32893b52e9789abe4143040a51ea926 Mon Sep 17 00:00:00 2001 From: Peter Bernard West Date: Thu, 6 Mar 2003 05:23:01 +0000 Subject: [PATCH] Using .ehtml files git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196025 13f79535-47bb-0310-9956-ffa450edef68 --- .../alt.design/alt-design-frameset.html | 77 --- .../content/design/alt.design/codeframe.html | 14 - .../content/design/alt.design/logo.html | 93 ---- .../properties/PropertyConsts-class.ehtml | 89 ++++ .../design/alt.design/properties/book.xml | 23 + .../properties/classes-overview.ehtml | 356 ++++++++++++++ .../properties/enumerated-values.ehtml | 309 +++++++++++++ .../properties/getInitialValue.ehtml | 145 ++++++ .../design/alt.design/properties/index.xml | 153 ++++++ .../properties/propertyExpressions.ehtml | 437 ++++++++++++++++++ .../properties/simple-properties.ehtml | 245 ++++++++++ 11 files changed, 1757 insertions(+), 184 deletions(-) delete mode 100644 src/documentation/content/design/alt.design/alt-design-frameset.html delete mode 100644 src/documentation/content/design/alt.design/codeframe.html delete mode 100644 src/documentation/content/design/alt.design/logo.html create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.ehtml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/book.xml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/classes-overview.ehtml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.ehtml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.ehtml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/index.xml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.ehtml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/simple-properties.ehtml diff --git a/src/documentation/content/design/alt.design/alt-design-frameset.html b/src/documentation/content/design/alt.design/alt-design-frameset.html deleted file mode 100644 index c39dc2f1c..000000000 --- a/src/documentation/content/design/alt.design/alt-design-frameset.html +++ /dev/null @@ -1,77 +0,0 @@ - - - - Alt Design Frameset - - - - - - - - - - - diff --git a/src/documentation/content/design/alt.design/codeframe.html b/src/documentation/content/design/alt.design/codeframe.html deleted file mode 100644 index f92bfd93f..000000000 --- a/src/documentation/content/design/alt.design/codeframe.html +++ /dev/null @@ -1,14 +0,0 @@ - - - - Frame for Code Display - - - -

Frame for code display.

- - diff --git a/src/documentation/content/design/alt.design/logo.html b/src/documentation/content/design/alt.design/logo.html deleted file mode 100644 index 37d2650c6..000000000 --- a/src/documentation/content/design/alt.design/logo.html +++ /dev/null @@ -1,93 +0,0 @@ - - - - Logo for Properties - - - - - - - - diff --git a/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.ehtml new file mode 100644 index 000000000..2044d86f4 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.ehtml @@ -0,0 +1,89 @@ + + + + + PropertyConsts Description + + +
+

PropertyConsts Description

+

+ by Peter B. West +

+ + + +

Introduction

+

+ + This class, and the singleton object which is generated by the static + initializer, is essentially a repository of + <property> class instances and the static data from + those classes of org.apache.fop.fo.property. + The heart of this class is the method setupProperty. Whenever access to the data or + methods of a property class is required, this method in the + singleton must be called to ensure that an instance of the + property exists and that the static data from that instance + has been extracted. +

+ +
+
Note
+
+ An alternative to this requirement would be to pre-load all + of the individual property classes during the system + initialization phase. This is not done currently because of + the start-up expense of the required class loading for over + three hundred classes, and the relatively low added expense + of checking for the existence of a property instance before + every access. Given that FOP is increasingly used in a + server environment, it may prove acceptable in the long run + to change to pre-loading. +
+
+ +

+ The class name is generated and stored in the classNames array; a class instance is generated + from the name and stored in the classes array; and an instance of the class is + generated from the class object and stored in the properties array. +

+ +

+ The other data gathering facilities and access methods of this + class will be examined in conjunction with the various types + of property classes. +

+ +

+ Previous: Property classes overview +

+

+ Next: Simple property classes +

+
+ + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/book.xml b/src/documentation/content/xdocs/design/alt.design/properties/book.xml new file mode 100644 index 000000000..4cb6871b0 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/book.xml @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.ehtml new file mode 100644 index 000000000..c57b8727a --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.ehtml @@ -0,0 +1,356 @@ + + + + + Property classes overview + + + +
+

Property classes overview

+

+ by Peter B. West +

+ +

Properties: packages

org.apache.fop.fo

+
+
+ + PropNames +
+
+ This class maintains an array of property + names, synchronized to a complete set of property name + constants for indexing property-based arrays. It + includes methods to convert + an index to a name and to convert + a property name to an index. +
+
+ PropertyConsts +
+
+ A singleton instance of PropertyConsts is created by the static initializer + of the pconsts + 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.
The heart of this class in the method setupProperty, 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. +
+
+ PropertySets +
+
+ This class provides a number of ROBitSets representing many of the sets of + properties defined in Section 7 of the + specification. Note that the Border, Padding and Background sets are defined separately. +
+
+ FOPropertySets +
+
+ This class provides a number of ROBitSets 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. +
+
+ ShorthandPropSets +
+
+ This class contains arrays of shorthand property indices and compound property indices, and ROBitSets representing the expansion sets of these + shorthands and compounds. Various methods useful in the + expansion of these properties are also included. +
+
+ FOAttributes +
+
+ This class manages the attribute set that is associated with + a SAX startElement event. + fo: namespace attributes are entered into a HashMap, indexed by the + fo: property index. As other namespaces are + encountered, the values are entered into namespace-specific + HashMaps, indexed by + the local name of the attribute. +
+
+ +

org.apache.fop.fo.properties

+
+
+ Property +
+
+ The base class for all individual property classes. + There are 320 properties in all. +
+
+ ColumnNumber +
+
+ The actual property class with the lowest index + number, followed in the index order by properties required + for further processing, e.g. FontSize. +
+
+ .... +
+
....
+
+ Background +
+
+ First in index order of the remainining shorthand + properties, followed in index order by all other remaining + shorthands. +
+
+ .... +
+
....
+
+ AbsolutePosition +
+
+ 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. +
+
+ .... +
+
....
+
+ ZIndex +
+
+ The property class with the highest index + number. +
+
+ +

org.apache.fop.fo.expr

+
+
+ PropertyTokenizer +
+
+ The tokenizer for the property expression parser. Defines a + set of token + constants and returns these with associated token + values. +
+
+ PropertyParser +
+
+ This extends PropertyTokenizer. It parses property + expressions on the basis of the tokens passed to it by its + superclass, generating PropertyValues, including PropertyValueLists. +
+
+ PropertyException +
+
+ The basic class for all property-related exceptions. + It extends FOPException. It + is housed in this package by historical accident. +
+
+ DataTypeNotImplementedException +
+ FunctionNotImplementedException +
+ PropertyNotImplementedException +
+
+ A set of particular exceptions extending PropertyException. Also in this package + by accident. +
+
+ +

org.apache.fop.datatypes

+
+
+ PropertyValue +
+
+ An interface which all PropertyValue classes must implement. In addition + to a few methods, PropertyValue defines the set of constants which the getType() method may return; i.e. the valid set of + PropertyValue types. +
+
+ AbstractPropertyValue +
+
+ An abstract implementation of the PropertyValue interface. Most actual property value + classes extend AbstractPropertyValue. +
+
+ PropertyValueList +
+
+ This class extends LinkedList and implements PropertyValue. It is used whenever the process of + resolving a property expression yields a list of PropertyValue elements; notably + during the processing of shorthands and "compound" + properties. +
+
+ StringType +
+
+ A basic type extending AbstractPropertyValue. Extended by NCName. +
+
+ NCName +
+
+ Extends StringType to represent + NCName strings. +
+
+ EnumType +
+
+ Extends AbstractPropertyValue to represented enumerated + types. +
+
+ Other types +
+
+ All other types extend one of the above classes. +
+
+ +

org.apache.fop.datatypes.indirect

+
+
+ IndirectValue +
+
+ The base type for all indirect value types; extends + AbstractPropertyValue. +
+
+

+ Previous: Introduction +

+

+ Next: The PropertyConsts class +

+
+ + + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.ehtml new file mode 100644 index 000000000..7bc9ad758 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.ehtml @@ -0,0 +1,309 @@ + + + + + Enumerated Data Values + + + +
+

Enumerated Data Values

+ + + +

Enumerated Data Values

+

+ 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 vice versa. Depending on the number of + tokens in an enumeration set, the mapping from token to + integer is maintained in an array or a HashMap. The switch-over point from + array to HashMap was determined + by some highly implementation-dependent testing to be in the + region of four to five elements. +

+

+ 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. +

+ +

Array representation

+

+ + org.apache.fop.fo.properties.Direction + is an example of a class which supports an enumerated value + with a small set of tokens. The dataTypes field contains the ENUM data type constant, defined in + Property. The enumeration + integer constants are defined as public + static final int values, LTR and RTL. + Associating enumeration tokens with these integer constants + occurs in the array String[] rwEnums, 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 rwEnums and the + enumeration constants be maintained. +

+

+ The publicly accessible mapping from enumeration token to + enumeration constant is achieved through the method int getEnumIndex(String). The + corresponding mapping from enumeration constant to enumeration + token is achieved through the method String getEnumText(int). +

+ +

HashMap representation

+

+ + org.apache.fop.fo.properties.RenderingIntent is + an example of a class which supports an enumerated value with + a larger set of tokens. The dataTypes field contains the ENUM data type constant, defined in + Property. Enumeration + integer constants are defined as public static final int values. + Zero is never used to represent a valid enumeration constant. + The enumeration tokens are stored in the array String[] rwEnums, which is + initialized with the token strings. Association of + enumeration tokens with the integer constants occurs in the + HashMap rwEnumHash, which is initialized + from the token array in a static + {} initializer. It is, of course, critical that + synchronization between rwEnums + and the enumeration constants be maintained. +

+

+ The publicly accessible mapping from enumeration token to + enumeration constant is achieved through the method int getEnumIndex(String). The + corresponding mapping from enumeration constant to enumeration + token is achieved through the method String getEnumText(int). +

+ +

+ Factoring Out Common Enumeration Values +

+

+ 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 BorderCommonStyle. Like + a property with a normal HashMap representation of an + enumerated value, BorderCommonStyle defines public static final int + enumeration integer constants. Similarly, the enumeration + tokens are stored in the array String[] rwEnums, and the + association of enumeration tokens with the integer constants + occurs in the HashMap rwEnumHash, initialized in a + static {} initializer. The + mapping methods int getEnumIndex(String) and String getEnumText(int) + are also present. +

+

+ Notice, however, that the class has none of the static data + constants described in the discussion of simple properties. These + values are defined in the individual sub-classes of this + class, e.g. BorderLeftStyle. None of + the above fields or methods occur, and BorderLeftStyle is left looking like + an example of a simple property. The enumeration mapping + methods are, however, available through the super-class BorderCommonStyle. +

+ +

Mapped Numeric Values

+

+ 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 Numeric + result. Their resolution involves mapping the token to the + indicated Numeric value. +

+

+ An example is the BorderCommonWidth + property. This, like the example of BorderCommonStyle above, also + represents common enumerated values which have been factored + out to form a super-class for particular properties. BorderCommonWidth, therefore, also + defines enumeration constant values and an + array of tokens. In this case, there is no HashMap, because of the limited number + of tokens, but the mapping methods int getEnumIndex(String) and String getEnumText(int) + are present. +

+

+ The added element in this property is the array double[] mappedPoints. The + entries in this array must by maintained in syncronization + with the String[] rwEnums array of tokens + and the set of enumeration + constants. The mapping from token to Numeric value is + achieved by the Numeric getMappedLength(FONode, int, + int) method. +

+

+ + BorderLeftWidth + extends BorderCommonWidth. It includes + the basic static data, like simple properties, and, in + this case, the PropertyValue + getInitialValue(int) method to derive the initial + value. +

+ +

Deriving Mapped Numeric Values

+

+ As usual with property values, the usual method of deriving a + mapped numeric value is by calling the Numeric getMappedNumeric(FONode, int, + int) method in pconsts. All properties which + support a mapped numeric value must have a Numeric getMappedNumeric(FONode, int) + method, which will be called through its singleton instance, + stored in the properties array, by the PropertyConsts method. +

+ +

+ Previous: getInitialValue() +

+ + +
+ + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.ehtml new file mode 100644 index 000000000..3f539b0e6 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.ehtml @@ -0,0 +1,145 @@ + + + + + Generating Initial Values + + + +
+

Generating Initial Values

+

+ by Peter B. West +

+ + + +

Introduction

+

+ The previous section + 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. +

+ + +

+ Generating & Accessing Initial Values +

+

+ + org.apache.fop.fo.properties.AutoRestore is an + example of 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. +

+

+ The method PropertyValue getInitialValue(int) + 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 PropertyConsts singleton + pconsts.` As with the + fields, the first invocation of the method setupProperty on the property + instantiates the singleton instance of the class, and stores + that instance in the in the Property[] properties array of + pconsts. +

+

+ Unlike the static data fields, however, the initial value is + not immediately generated. It is generated by a call to PropertyValue + getInitialValue(int) in pconsts. This call, in turn, + locates the relevant instance of the particular property class + in the properties array of PropertyConsts, and invokes the getInitialValue() of that instance. + A side-effect of this call is to store the initial value in + PropertyValue[] + initialValues. +

+ +

Properties without + getInitialValue()

+

+ What about property classes which have no getInitialValue() method? The + simplest classes, e.g. Character, fall into this category. + As noted + previously, all of the property classes extend org.apache.fop.fo.properties.Property. + Property provides a base + PropertyValue + getInitialValue(int) method to which the simple + classes fall back. Note that it is only valid for NOTYPE_IT, AUTO_IT, NONE_IT and AURAL_IT initial value types, so all + classes which have any other initial value type must override + this method. +

+ +

+ Previous: Simple property classes +

+

+ Next: Enumerated values +

+ +
+ + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/index.xml b/src/documentation/content/xdocs/design/alt.design/properties/index.xml new file mode 100644 index 000000000..89f24a765 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/index.xml @@ -0,0 +1,153 @@ + + + + +
+ Implementing Properties + + + +
+ +
+ An alternative properties implementation + + 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. + +

+ Property handling is complex and expensive. Varying numbers of + properties apply to individual Flow Objects + (FOs) in the FO tree 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. +

+ + (XSL 1.0 Rec) 5.1.4 Inheritance + ...The inheritable properties can be placed on any formatting + object. + +

+ Even if the value is not inheritable, it may be accessed by + its children through the inherit keyword or the + from-parent() core function, and potentially by + any of its descendents through the + from-nearest-specified-value() core function. +

+

+ In addition to the assigned values of properties, almost every + property has an initial value which is used + when no value has been assigned. +

+
+ The history problem +

+ The difficulty and expense of handling properties comes from + this univeral inheritance possibility. The list of properties + which are assigned values on any particular FO + element will not generally be large, but a current value is + required for each property which applies to the FO + being processed. +

+

+ The environment from which these values may be selected + includes, for each FO, for each applicable + property, the value assigned on this FO, + the value which applied to the parent of this FO, + the nearest value specified on an ancestor of this element, + and the initial value of the property. +

+
+
+ The construction hierarchy +

+ Properties are resoved in the FO tree in a + strictly hierarchical manner. Nodes are detected in the + input in a pre-order 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. +

+
+
Subtree building
+
+ 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. +
+
Stable: subtree building complete
+
+ In this state, only the properties applicable to + this node need be available. +
+
+
+
+ Representing properties: <property> classes +
+ Class vs instance +

+ 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. +

+

+ Certain constant information attaches to individual + property classes. This information is detailed in + the descriptions of individual properties in Section + 7 of the specification. Such information is + represented in class fields and data + structures within the classes. +

+

+ The "instance" information content of a property + is: +

+
    +
  • + explicitly, the PropertyValue datum of + the property, and +
    • +
  • + implicitly, the Flow Object to which + the property is attached. +
    • +
+

+ Properties, then, serve essentially to link FO + instances with PropertyValue instances, + attaching certain invariant semantic markers to the + PropertyValues in the process. In this implementation, + these functions can be realised entirely within the + property classes themselves, + without the need to instantiate any objects. In practice, + property singletons are + instantiated to make access to some invariants simpler. +

+
+
+

+ Next: property classes overview. +

+
+ + + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.ehtml new file mode 100644 index 000000000..3df16afa5 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.ehtml @@ -0,0 +1,437 @@ + + + + + Property Expression Parsing + + + +
+

Property Expression Parsing

+

+ by Peter B. West +

+ + + +

Property expression parsing

+

+ The parsing of property value expressions is handled by two + closely related classes: org.apache.fop.fo.expr.PropertyTokenizer and its + subclass, org.apache.fop.fo.expr.PropertyParser, and by + refineParsing(int, FONode, + PropertyValue) methods in the individual property + classes. PropertyTokenizer, + as the name suggests, handles the tokenizing of the + expression, handing tokens back to its subclass, PropertyParser. PropertyParser, in turn, returns a PropertyValueList, a + list of PropertyValues. +

+

+ The tokenizer and parser rely in turn on the datatype + definitions from the org.apache.fop.datatypes package, which include the + PropertyValue datatype + constant definitions. +

+ +

Data types

+

+ The data types currently defined in + org.apache.fop.datatypes include: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Numbers and lengths
Numeric + The fundamental length data type. Numerics of + various types are constructed by the classes listed + below. +
Constructor classes for Numeric
EmsRelative length in ems
IntegerType
LengthIn centimetres(cm), millimetres(mm), + inches(in), points(pt), picas(pc) or pixels(px)
Percentage
Other Numeric + Other numeric vaues which do not interact with the + lengths represented by Numeric values. +
AngleIn degrees(deg), gradients(grad) or + radians(rad)
FrequencyIn hertz(Hz) or kilohertz(kHz)
TimeIn seconds(s) or milliseconds(ms)
Strings
StringType + Base class for data types which result in a String. +
Literal + A subclass of StringType for literals which + exceed the constraints of an NCName. +
MimeType + A subclass of StringType for literals which + represent a mime type. +
UriType + A subclass of StringType for literals which + represent a URI, as specified by the argument to + url(). +
NCName + A subclass of StringType for literals which + meet the constraints of an NCName. +
CountryAn RFC 3066/ISO 3166 country code.
LanguageAn RFC 3066/ISO 639 language code.
ScriptAn ISO 15924 script code.
Enumerated types
EnumType + An integer representing one of the tokens in a set of + enumeration values. +
MappedNumeric + A subclass of EnumType. Maintains a + Numeric with the value to which the associated + "raw" enumeration token maps. E.g., the + font-size enumeration value "medium" maps to + the Numeric "12pt". +
Colors
ColorType + Maintains a four-element array of float, derived from + the name of a standard colour, the name returned by a + call to system-color(), or an RGB + specification. +
Fonts
FontFamilySet + Maintains an array of Strings containing a + prioritized list of possibly generic font family names. +
Pseudo-types
+ A variety of pseudo-types have been defined as + convenience types for frequently appearing enumeration + token values, or for other special purposes. +
Inherit + For values of inherit. +
Auto + For values of auto. +
None + For values of none. +
Bool + For values of true/false. +
FromNearestSpecified + Created to ensure that, when associated with + a shorthand, the from-nearest-specified-value() + core function is the sole component of the expression. +
FromParent + Created to ensure that, when associated with + a shorthand, the from-parent() + core function is the sole component of the expression. +
+ +

Tokenizer

+

+ As mentioned above, the PropertyTokenizer hands tokens back to its subclass, PropertyParser. Most of these tokens are + self-explanatory, but a few need further comment. +

+
+ +
AUTO
+ +
+ Because of its frequency of occurrence, and the fact that it + is always the initial value 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. +
+ +
NONE
+ +
+ Similarly to AUTO, NONE has been promoted to a pseudo-type + because of its frequency. +
+ +
BOOL
+ +
+ There is a de facto 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. +
+ +
MIMETYPE
+ +
+ The property content-type + introduces this complication. It can have two values of the + form content-type:mime-type + (e.g. content-type="content-type:xml/svg") or + namespace-prefix:prefix + (e.g. content-type="namespace-prefix:svg"). The + experimental code reduces these options to the payload in + each case: an NCName in the + case of a namespace prefix, and a MIMETYPE in the case of a + content-type specification. NCNames cannot contain a "/". +
+ +
+ +

Parser

+

+ The parser returns a PropertyValueList, + necessary because of the possibility that a list of PropertyValue elements + may be returned from the expressions of some properties. +

+

+ + PropertyValueLists may contain + PropertyValues or other PropertyValueLists. This latter + provision is necessitated by some of the more peculiar + expression possibilities, e.g. font and + text-shadow. text-shadow 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. +

+

+ Other special cases include the processing of the core + functions from-parent() and + from-nearest-specified-value() + 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 FromParent and FromNearestSpecified 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.) +

+

+ The experimental code is a simple extension of the existing + parser code, which itself borrowed heavily from James + Clark's XT processor. +

+ +
+ + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.ehtml new file mode 100644 index 000000000..5df05bdd6 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.ehtml @@ -0,0 +1,245 @@ + + + + + Simple <property> Classes + + + +
+

Simple <property> Classes

+

+ by Peter B. West +

+ + + +

Introduction

+

+ An overview of the properties + and classes 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 PropertyConsts class and + its singleton object. +

+ + +

Common data

+

+ + org.apache.fop.fo.properties.Character + is an example of a basic property class. The data fields + common to all properties are: +

+
+ +
+ + final int dataTypes + +
+ +
+ 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 org.apache.fop.fo.properties.Property, + and may consist of more than one of those constants, + bit-ORed together. +
+ +
+ + final int traitMapping + +
+ +
+ This field defines the mapping of properties to traits in + the Area tree. The value is + chosen from the trait mapping constants defined in org.apache.fop.fo.properties.Property, + and may consist of more than one of those constants, + bit-ORed together. +
+ +
+ + final int initialValueType + +
+ +
+ 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 org.apache.fop.fo.properties.Property. + In the simplest property classes, such as Character, there is no defined + initial value type. +
+ +
+ + final int inherited + +
+ +
+ This field defines the kind of inheritance applicable to the + property. The value is chosen from the inheritance + constants defined in org.apache.fop.fo.properties.Property. +
+ +
+ + +

Accessing <property> Data Constants

+

+ The constants above are generally accessed through the arrays + maintained in the PropertyConsts singleton + pconsts. The first + invocation of the method setupProperty on the property + generates a Class instance for + the class, and stores it in the array classes. This Class object is used, in turn, to + instantiate the singleton instance of the class, which is + stored in the Property[] properties array of + pconsts. +

+

+ + Reflection methods are then used, via the same Class instance, to extract and store + the static data fields. These arrays and associated access + methods are: +

+
+ +
+ + int[] datatypes + +
+ +
+ + int getDataTypes(int) + +
+ +
+ + int[] traitMappings + +
+ +
+ + No access method yet defined. + +
+ +
+ + int[] initialValueTypes + +
+ +
+ + int + getInitialValueType(int) + +
+ +
+ + int[] inherited + +
+ +
+ + int inheritance(int) + +
+ +
+ +

+ Previous: PropertyConsts class +

+

+ Next: getInitialValue() +

+ +
+ + -- 2.39.5