From: William Victor Mote Date: Tue, 22 Apr 2003 00:21:04 +0000 (+0000) Subject: Combine content of design/understanding/area_tree.xml into design/areas.xml. X-Git-Tag: Root_Temp_KnuthStylePageBreaking~1581 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=a2dedccdfd60614ea9610c47d57b982526ba5e40;p=xmlgraphics-fop.git Combine content of design/understanding/area_tree.xml into design/areas.xml. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196301 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/documentation/content/xdocs/design/areas.xml b/src/documentation/content/xdocs/design/areas.xml index 958ef3056..70039ea5b 100644 --- a/src/documentation/content/xdocs/design/areas.xml +++ b/src/documentation/content/xdocs/design/areas.xml @@ -24,6 +24,16 @@ 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.

+

The Area Tree is an internal representation of the result document. This +is a set of java classes that can put together a set of objects that +represent the pages and their contents.

+

This information is created by the layout managers and is rendered to the +output using a renderer.

+

The Area Tree follows the description of the area tree in the XSL:FO +specification.

+

The Area Tree consists of a set of pages, the actual implemenation places +these in +a set of page sequences.

Structure

@@ -35,7 +45,12 @@ at the root level but lets the area tree model handle each page as it is added.

Page -

+

A page consists of a page+viewport pair.

+

The PageViewPort and Page with the regions is created by the +LayoutMasterSet. The contents are then placed by the layout managers. Once +the layout of a page is complete then it is added to the Area Tree.

+

Inside the page is a set of RegionViewport+Region pairs for each region on +the page.

A page is made up of five area regions. These are before, start, body, end and after. Each region has a viewport and contains the areas produced from the children in the FO object heirarchy. @@ -57,6 +72,9 @@ then the other regions can be done layed out and added.

Block Areas +

Block level areas contain either other blocks or line areas (which is a +special block area).

+A block is either positoned or stacked with other block areas.

Block areas are created and/or returned by all top level elements in the flow. The spacing between block areas is handled by an @@ -92,6 +110,14 @@ Unresolved areas can reserve some space to allow for possible sizes once it is resolved. Then the line can be re-justified and finalised.

+

Inline areas are stacked in a line area. Inline areas are objects such as +character, viewport, inline-container, leader and space. A special inline +area Word is also used for a group of consecutive characters.

+

The image and instream foreign object areas are placed inside a viewport. +The leader (with use content) and unresolved page number areas are +resolved to other inline areas.

+

Once a LineArea is filled with inline areas then the inline areas need to +be aligned and adjusted to fill the line properly.

Repeated Areas @@ -103,6 +129,23 @@ the subtree data can be cached in the output. Examples of this are: static areas, table header/footer, svg.

+
+ Traits + +

A trait is information associated with an area. This could be information +such as text colour or is-first.

+

Traits provide information about an area. The traits are derived from +properties on the formatting object or are generated during the layout +process. Many of the layout traits do not have actual values but can be +derived from the Area Tree. Other traits that apply when rendering the +areas are set on the area. Since setting the same value on every area +would use a lot of memory then the traits are derived from default or +parent values.

+

A dominant trait on a block area is set, for example font colour, so that +every line area with the same dominant value can derive it. The text +inline areas then get the font colour set on the inline area or from the +line area or from the block area.

+
Classes

@@ -142,6 +185,54 @@ object.

+
+ Forward References +

The Area Tree maintains a set of mappings from the reference to pages.

+

The PageViewPort holds the list of forward references that need resolving +so that if a references is resolved during layout the page can be easily +found and then fixed. Once all the forward references are resolved then +the page is ready to be rendered.

+

To layout a page any areas that cannot be resolved need to reserve space. +Once the inline area is resolved then the complete line should be adjusted +to accomodate any change in space used by the area.

+
+ +
+ Caching +

We may need to cache pages due to forward references or when keeping all +pages.

+

This is done by serializing the Page. The PageViewport is retained to be +used as a key for page references and backward references. +The Page is serialized to an object stream and then all of the page +contents are released. The Page is then recoved by reading from the object +stream.

+

The PageViewport retains information about id areas for easy access.

+
+ +
+ Extensions +

The Area Tree holds the Output Document extensions. This is information +such as pdf bookmarks or other output document specific information that +is not handled by XSL:FO.

+

It is also possible to create custom areas that extend a normal area. The +actual data that is rendered could be set in a different way or depend on +resolving a forward reference.

+
+ +
+ Area Tree Handlers +

To handle different situations the handler for the Area Tree handles each +page as it is added.

+The RenderPagesModel sends the page directly to the renderer if the page +is ready to be rendered. Once a page is rendered it is discarded. +The StorePagesModel stores all the pages so that any page can be later +accessed.

+

The Area Tree retains the concept of page sequences (this is not in the +area tree in the spec) so that this information can be passed to the +renderer. This is useful for setting the title and organising the groups +of page sequences.

+
+
Rendering Area Tree

diff --git a/src/documentation/content/xdocs/design/book.xml b/src/documentation/content/xdocs/design/book.xml index 81c1be895..fceab0252 100644 --- a/src/documentation/content/xdocs/design/book.xml +++ b/src/documentation/content/xdocs/design/book.xml @@ -28,7 +28,6 @@ understanding/book.xml, WHICH SEE FOR AN EXPLANATION. -

diff --git a/src/documentation/content/xdocs/design/understanding/area_tree.xml b/src/documentation/content/xdocs/design/understanding/area_tree.xml deleted file mode 100644 index 69adee7f5..000000000 --- a/src/documentation/content/xdocs/design/understanding/area_tree.xml +++ /dev/null @@ -1,122 +0,0 @@ - - - - -
- Area Tree -
- - -
- Area Tree -

The Area Tree is an internal representation of the result document. This -is a set of java classes that can put together a set of objects that -represent the pages and their contents.

-

This information is created by the layout managers and is rendered to the -output using a renderer.

-

The Area Tree follows the description of the area tree in the XSL:FO -specification.

-

The Area Tree consists of a set of pages, the actual implemenation places -these in -a set of page sequences.

-
- -
- Pages -

A page consists of a page+viewport pair.

-

The PageViewPort and Page with the regions is created by the -LayoutMasterSet. The contents are then placed by the layout managers. Once -the layout of a page is complete then it is added to the Area Tree.

-

Inside the page is a set of RegionViewport+Region pairs for each region on -the page.

- - -
- Blocks -

Block level areas contain either other blocks or line areas (which is a -special block area).

-A block is either positoned or stacked with other block areas.

-
- -
- Inline Areas -

Inline areas are stacked in a line area. Inline areas are objects such as -character, viewport, inline-container, leader and space. A special inline -area Word is also used for a group of consecutive characters.

-

The image and instream foreign object areas are placed inside a viewport. -The leader (with use content) and unresolved page number areas are -resolved to other inline areas.

-

Once a LineArea is filled with inline areas then the inline areas need to -be aligned and adjusted to fill the line properly.

-
- -
- Traits - -

A trait is information associated with an area. This could be information -such as text colour or is-first.

-

Traits provide information about an area. The traits are derived from -properties on the formatting object or are generated during the layout -process. Many of the layout traits do not have actual values but can be -derived from the Area Tree. Other traits that apply when rendering the -areas are set on the area. Since setting the same value on every area -would use a lot of memory then the traits are derived from default or -parent values.

-

A dominant trait on a block area is set, for example font colour, so that -every line area with the same dominant value can derive it. The text -inline areas then get the font colour set on the inline area or from the -line area or from the block area.

-
- -
- Forward References -

The Area Tree maintains a set of mappings from the reference to pages.

-

The PageViewPort holds the list of forward references that need resolving -so that if a references is resolved during layout the page can be easily -found and then fixed. Once all the forward references are resolved then -the page is ready to be rendered.

-

To layout a page any areas that cannot be resolved need to reserve space. -Once the inline area is resolved then the complete line should be adjusted -to accomodate any change in space used by the area.

-
- -
- Caching -

We may need to cache pages due to forward references or when keeping all -pages.

-

This is done by serializing the Page. The PageViewport is retained to be -used as a key for page references and backward references. -The Page is serialized to an object stream and then all of the page -contents are released. The Page is then recoved by reading from the object -stream.

-

The PageViewport retains information about id areas for easy access.

-
- -
- Extensions -

The Area Tree holds the Output Document extensions. This is information -such as pdf bookmarks or other output document specific information that -is not handled by XSL:FO.

-

It is also possible to create custom areas that extend a normal area. The -actual data that is rendered could be set in a different way or depend on -resolving a forward reference.

-
- -
- Area Tree Handlers -

To handle different situations the handler for the Area Tree handles each -page as it is added.

-The RenderPagesModel sends the page directly to the renderer if the page -is ready to be rendered. Once a page is rendered it is discarded. -The StorePagesModel stores all the pages so that any page can be later -accessed.

-

The Area Tree retains the concept of page sequences (this is not in the -area tree in the spec) so that this information can be passed to the -renderer. This is useful for setting the title and organising the groups -of page sequences.

-
- - - - diff --git a/src/documentation/content/xdocs/design/understanding/book.xml b/src/documentation/content/xdocs/design/understanding/book.xml index af2828295..f2afa5d55 100644 --- a/src/documentation/content/xdocs/design/understanding/book.xml +++ b/src/documentation/content/xdocs/design/understanding/book.xml @@ -32,7 +32,6 @@ PARENT DIRECTORY! -