From ea6a9bf46cbec876403621fb4555555e9e507424 Mon Sep 17 00:00:00 2001 From: Keiron Liddle Date: Thu, 2 Jan 2003 12:59:30 +0000 Subject: [PATCH] updated some information git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195811 13f79535-47bb-0310-9956-ffa450edef68 --- .../content/xdocs/design/architecture.xml | 55 +++++++++--- .../content/xdocs/design/areas.xml | 85 +++++++++---------- .../content/xdocs/design/book.xml | 3 - .../content/xdocs/design/embedding.xml | 40 ++++++--- .../content/xdocs/design/extending.xml | 27 +++--- .../content/xdocs/design/fotree.xml | 7 +- 6 files changed, 128 insertions(+), 89 deletions(-) diff --git a/src/documentation/content/xdocs/design/architecture.xml b/src/documentation/content/xdocs/design/architecture.xml index f76fc9273..752bb394b 100644 --- a/src/documentation/content/xdocs/design/architecture.xml +++ b/src/documentation/content/xdocs/design/architecture.xml @@ -20,7 +20,7 @@ Introduction

The overall process is controlled by org.apache.fop.apps.Driver. -This class handles the FO Tree building, renderers, output and logging. +This class handles the FO Tree building, structure handler, renderers, output and logging.

The process in general is that the FO document is sent to the tree @@ -39,22 +39,55 @@ actually constructing the FO tree. The key SAX events used are

startElement(),

endElement() and characters().

-

All formatting objects derive from abstract class -org.apache.fop.fo.FONode. The other FO classes inherit from -FONode as follows:

+ +
+ Layout +

+The layout managers handle the layout. They take an FO tree and construct +the area tree. +The layout process involves finding out where line breaks and page +breaks should be made. The areas are then added to the page. The +static areas can the be done for all the static regions. +Completed pages are then added to the area tree, the area tree can +then deal with the page. +

+
+ +
+ Area Tree +

+The area tree is a data structure designed to hold the page areas. +These pages are then filled with the page regions and various areas. +The area tree is used primarily as a minimal structure that can be rendered +by the renderers. +

+

+The area tree is supported by an area tree model. This model +handles the adding of pages to the area tree. It also handles +page sequence starts, document level extensions, id references +and unresolved id areas. This model allows the pages to be handled +directly by a renderer or to store the pages for later use. +

+
Rendering

-This is a separate process. The render() method in -Driver is invoked (say, -by CommandLine) with the laid-out AreaTree and a -PrintWriter as arguments. -This actually calls the render() method in a specific implementation of -the Renderer interface, typically PDFRenderer or -AWTRenderer. +The renderer receives pages from the area tree and renders those pages. +If a renderer supports out of order rendering then it will either +render or prepare a page in the correct order. Otherwise the +pages are rendered in order. +The task of the renderer is to take the pages and output them to +the requested type. +In the case of the AWTRenderer it needs to be able to view any page. +

+

+When rendering a page it takes the page and renders each page region. +The main work for a renderer implementation is to handle the viewports +and inline areas. The inline areas need to be dran on the page in the +correct place.

diff --git a/src/documentation/content/xdocs/design/areas.xml b/src/documentation/content/xdocs/design/areas.xml index a7d4e4615..51b197534 100644 --- a/src/documentation/content/xdocs/design/areas.xml +++ b/src/documentation/content/xdocs/design/areas.xml @@ -15,15 +15,16 @@
Area Tree

-The code to implement the area tree will attempt to match the areas -defined in the specification. A number of optimisations may be possible -for similar areas and groups of areas. +The code to implement the area tree matches the areas +defined in the specification. This makes it easier to understand and +correspond with the specification.

-Since the area tree will be used during the layout by the layout managers -it will need to store information that affects the layout. The information -such as spacing and keeps will be held in such a way that it can be -discarded once the layout is finalised. +The area tree is created by the layout managers once the layout is decided +for a page. Once a completed page is finished it can then be added to the +area tree. The area tree model can then handle the new page. The data in +the area tree must be minimal and independant. This means that the data +uses less memory and can be serialized to an output stream if needed.

Structure @@ -31,7 +32,7 @@ discarded once the layout is finalised. The area tree is a root element that has a list of page-viewport-areas. Each page viewport has a page-reference-area which holds the contents of the page. To handle the processing better FOP does not maintain a list -at the root level but lets another class handle each page as it is added. +at the root level but lets the area tree model handle each page as it is added.

@@ -52,25 +53,18 @@ reference areas. Since the layout is done inside a page, the page is created from the pagemaster with all the appropriate areas. The layout manager then uses the page to add areas into the normal flow reference areas -and floats and footnotes. After the layout of the body region -is complete then the other regions can be done. +and floats and footnotes. After adding the areas for the body region +then the other regions can be done layed out and added.

Block Areas

Block areas are created and/or returned by all top level elements -in the flow. These areas have keep and spacing information that -needs to be retained until the page is finalised. A block area -is stacked with other block areas in a particular direction, it -has a size and it contains either line areas made from a group -of inline areas or block areas. -

-

-A block area can also be split into two block areas by splitting -between two line areas or splitting between two block areas (or -groups) that are stacked in the block progression direction of -the page. The split may also be in a child block area. +in the flow. The spacing between block areas is handled by an +empty block area. A block area is stacked with other block +areas in a particular direction, it has a size and it contains +line areas made from a group of inline areas and/or block areas.

@@ -78,22 +72,22 @@ the page. The split may also be in a child block area.

A line areas is simply a collection of inline areas that are stacked in the inline progression direction. A line area has a height and -width. It also contains information about floats and footnotes -that are associated with the inline areas. +a start position. The line area is rendered by handling each inline +area.

A line area gets a set of inline areas added until complete then -it is justified and vertically aligned. If the line area contains -unresolved areas it will retain the justification information -until all areas are resolved. +it is justified and vertically alignedi when adding the areas. +If the line area contains unresolved areas then there will +be a line resolver that retains the justification information until +all areas in the line are resolved.

Inline Areas

There are a few different types of inline areas. All inline areas -have a height. Their width may be variable until the line is -finalised. +have a height and width.

Unresolved areas can reserve some space to allow for possible @@ -102,15 +96,13 @@ and finalised.

- Cloning + Repeated Areas

-Any subtree of the area tree should be cloneable so that for -areas that are repeated the area tree can simply be copied rather -than going through the layout again. This will only work if the -width is the same. -

-

-Resolveable areas may be converted into an unresolved form. +There are cases where the same subtree could be repeated in the area +tree. These areas will be returned by the same layout managers. +So it is possible to put a flag on the created areas so that +the subtree data can be cached in the output. Examples of this are: +static areas, table header/footer, svg.

@@ -130,23 +122,24 @@ flow areas added.
Block Area Classes

-The block areas typically hold either a set of line areas or a set of -block areas. The child areas are usually stacked in a particular -direction. +The block areas hold other block areas and/or line areas. The +child areas are stacked in a particular direction.

-Areas for tables and lists have their child block areas stacked -in different ways. Lists also can have spacing between the block -areas. +Areas for tables, lists and block container have their child +block areas stacked in different ways. These areas a placed +with an absolute positioning. The absolute positioning is where +the blocks are placed with an offset from the parent reference area.

Inline Area Classes

The inline areas are used to make up a line area. An inline area -typically has a height, width and some content. The alignment is -used for block progression direction displacement and to determine -the height of a line. +typically has a height, width and some content. The inline area +is offset from the baseline of the current line area. The content +of the inline area can be other inline areas or a simple atomic +object.

@@ -169,7 +162,7 @@ Line Inline

-The renderer will need to be able to: +A renderer implementation does the following: