From dc63a685aedbed583428e5b5e893aab4aedafdd4 Mon Sep 17 00:00:00 2001 From: Peter Bernard West Date: Fri, 27 Dec 2002 07:50:16 +0000 Subject: [PATCH] Reworking properties documentation. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195804 13f79535-47bb-0310-9956-ffa450edef68 --- .../properties/classes-overview.xml | 276 ++++++++++++++ .../properties/enumerated-values.xml | 220 +++++++++++ .../alt.design/properties/getInitialValue.xml | 89 +++++ .../properties/propertyExpressions.xml | 342 ++++++++++++++++++ .../properties/simple-properties.xml | 146 ++++++++ 5 files changed, 1073 insertions(+) create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.xml create mode 100644 src/documentation/content/xdocs/design/alt.design/properties/simple-properties.xml diff --git a/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml b/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml new file mode 100644 index 000000000..b00a51d14 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml @@ -0,0 +1,276 @@ + + + + +
+ Property classes overview + + + +
+ +
+ 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: alt.properties +

+ + + + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml b/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml new file mode 100644 index 000000000..29a6760be --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml @@ -0,0 +1,220 @@ + + + + +
+ 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 by the PropertyConsts method. +

+
+
+
+ + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml b/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml new file mode 100644 index 000000000..4f5a1351d --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml @@ -0,0 +1,89 @@ + + + +
+ Generating Initial Values + + + +
+ +
+ 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 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. +

+ +

+ 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. A side-effect of this call is to store the initial + value in PropertyValue[] initialValues. +

+
+ Properties without + <code>getInitialValue()</code> +

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

+
+
+ + diff --git a/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.xml b/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.xml new file mode 100644 index 000000000..97b8b7d55 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.xml @@ -0,0 +1,342 @@ + + + + +
+ Property Expression Parsing + + + +
+ +
+ 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 + definition from the org.apache.fop.datatypes + package and the datatype static final int + constants from PropertyConsts. +

+
+ Data types +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Numbers and lengths
Numeric + The fundamental numeric data type. Numerics of + various types are constructed by the classes listed + below. +
+ Constructor classes for Numeric
AngleIn degrees(deg), gradients(grad) or + radians(rad)
EmsRelative length in ems
FrequencyIn hertz(Hz) or kilohertz(kHz)
IntegerType +
LengthIn centimetres(cm), millimetres(mm), + inches(in), points(pt), picas(pc) or pixels(px)
Percentage +
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. +
MappedEnumType + A subclass of EnumType. Maintains a + String with the value to which the associated + "raw" enumeration token maps. E.g., the + font-size enumeration value "medium" maps to + the String "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 +

+ The tokenizer returns one of the following token + values: +

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

+ 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 retuns a PropertyValueList, + necessary because of the possibility that a list of + PropertyValue elements may be returned from the + expressions of soem properties. +

+

+ PropertyValueLists may contain + PropertyValues or other + PropertyValueLists. This latter provision is + necessitated for the peculiar case of of + text-shadow, 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. +

+

+ 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.xml b/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.xml new file mode 100644 index 000000000..f73f56f48 --- /dev/null +++ b/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.xml @@ -0,0 +1,146 @@ + + + +
+ Simple <property> Classes + + + +
+ +
+ 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 getInitialValueTypes(int) +
+
+ int[] + inherited +
+
+ int + inheritance(int) +
+
+
+ + -- 2.39.5