FOTree is essentially a data structure. The processing that it does is essentially validating the data as it goes into the structure, and the mechanics of retrieving the data when it is called for by the client application. The following is a list of notable features in FOrayFOTree:

FOray FOTree uses a SAX-like event system to make the client application aware that data is ready. Currently, events are fired when a page-sequence is complete and when the whole document is complete. Clients can use or ignore these events as they see fit. A client can also request to have events fired when each FO object is complete. This gives the client the opportunity to manage the processing in a more “eager” manner if it wishes to. It is kind of like having the SAX concept and the DOM concept rolled into one package. If you want the view-one-piece-at-a-time approach (like SAX), request events for each FO object. If you want the let-me-see-the-whole-thing approach (like DOM), then simply respond to the end-of-document event. If you want something in between, respond to the end-of-page-sequence event.

The API for FOray FOTree is intended to be very straightforward. As expected, all of the FO objects are organized in a tree. Each parent in the tree knows all of its children (through the getChildren() method, and each child in the tree knows its parent (through the getParent() method.

In general, the FOTree is designed to be independent of the other document-processing modules, such as Layout, AreaTree, and Renderers. It is also designed to be independent of any particular implementation (i.e. it can be used by applications other than FOray), and to be reusable (i.e. it can be used by LayoutStrategy A, then used again by LayoutStrategy B). This means that, in general, FOTree clients can read data all they want from the FOTree, but should not write data to it. The one current exception to this rule is that each FObj encapsulates one Object instance called “shadow”, which can be used by an FOTree client to hold whatever data it likes. In general, this approach is deprecated, but we have made it available to handle some legacy code. We may discontinue this “feature” in the future. If this capability is critically important to your application for some reason, please let us know.

Please note that, although the “shadow” concept was added to handle layout-specific data, the current Pioneer layout strategy used by FORay still writes to some other fields within the FOray FOTree. This is a legacy issue, and these fields will be systematically removed in the future. In general, your application should not write to any field in the FOTree except for the shadow.

If you wish to reuse an already-built FOTree, and you are using shadow instances to cache data, you can use the FOTreeBuilder.resetShadow() method to set all of the shadow instances in the FOTree to null.

The API for properties and traits requires more explanation. For the most part, FOray does not expose property values to FOTree clients, instead exposing, where possible, the computed, refined “trait” values, which are suitable for creating an AreaTree. Methods for obtaining trait values start with the word “trait”. Virtually any trait can be requested from any FO object, although only some of them make sense. As the spec mentions, many trait names are derived directly from the name of the property which is its source. So, for example, to get the value of the column-width property, use the traitColumnWidth method(). Because some traits depend on actual Area Tree dimensions, those properties require parameters to be passed to them that provide that information.

If it seems unnatural to have FO Objects with “trait” properties, understand that the methods are really returning the applicable trait values that apply to areas generated by the FO Object.

The following are exceptions to the above trait method naming convetion:

• Abbreviated trait names. Abbreviations currently used include “IP” (inline-progression), “BP” (block-progression), “Min” (Minimum), “Opt” (Optimum), “Max” (Maximum) names.
• Traits stemming from compound properties, like inline-progression-dimension, have methods for each of their components, e.g. has traitIPDimensionMin(), traitIPDimensionOpt, and traitIPDimensionMax() methods.
• Traits stemming from Complex Property-to-Trait Mapping (as defined in Section 5.5 of the XSL-FO Standard 1.0). For example, the property text-decoration maps to the traits underline-score, underline-score-color, overline-score, overline-score-color, through-score, through-score-color, and blink. Trait values for these traits are obtained from traitUnderlineScore(), traitUnderlineScoreColor(), etc. There is no method for obtaining the raw text-decoration value.
• Some properties require more than one method to get the data. This is because we have (so far anyway) been able to find a way to return only one value, usually because of the complexity of the types of data stored in the property. Some of these may intrinsically need to be this way. Others may be this way for historical reasons, and can be changed in the future. In most cases, it probably means that we do not yet understand well enough all of the dependencies for this item:
  • alignment-adjust. First run traitAlignmentAdjust(). If the return value is PropertyKeyword.NOT_A_KEYWORD, then run traitAlignmentAdjustAmount() to get the alignment adjustment in millipoints.
  • text-align. First run traitTextAlign(). If the return value is PropertyKeyword.NOT_A_KEYWORD, then run traitTextAlignString() to get the alignment string.
  • play-during. There are four methods required to get the entire picture: traitPlayDuring() returns a String containing the URL; traitPlayDuringMix(), traitPlayDuringRepeat() and traitPlayDuringAuto() all return boolean values.

The following is intended to eventually be a comprehensive list of traits and the properties from which they are derived. Rows in the butterscotch color are those which do not have a one-to-one relationship between the two. Please note that this list is not currently complete or correct. It is being currently being used as a checklist by the developers.

Note: Although “width” and “height” do not have “trait” methods, they do have convenience “get” methods which map to the appropriate inline-progression-dimension or block-progression-dimension trait, depending on the writing mode. The same is true for margin-top, margin-bottom, margin-left, and margin-right, which map to one of space-before, space-after, start-indent, or end-indent, depending on the writing-mode.

• Consider detecting and storing patterns (i.e. templates or styles) that are indentical between different objects of the same type. For example, if two fo:block items have identical traits, they could share the same “style”. (This is an example of the GoF Flyweight pattern.)
• Consider replacing the FontState class with appropriate FObj trait methods. Alternatively, this effort could be part of the “style” initiative, i.e. rather than replace FontState, fix it so that multiple FObj instances can share the same FontState instance.
• Consider developing a scheme for explicitly supporting the concept of styles within the fo document itself. This would be a small step toward the idea of a replacement for XSLT as the intermediary between the semantic XML and the FO document.
• We need to systematically remove all non-shadow layout-related fields from FObj subclasses.