The text layout framework
-------------------------
The data of the document is stored in a QTextDocument (with some resources set by the KoTextDocument helper class) The styles are stored in a KoStyleManager, and we have some other managers and helpers as needed.

The layout of that document is handled by the KoTextDocumentLayout class. It builds a series of KoTextLayoutRootArea which roughly corresponds to a page, but since this is completely abstract such a root area could also be the cell in a spreadsheet. For both the spreadsheet case and a normal textshape only a single root area is created, but for Words we can create many root areas.

A KoTextLayoutRootArea is a subclass of KoTextLayoutArea which is the main worker of text layout. Basically it represents the layout of a series of paragraphs. If there is a table in between the paragraphs it will create a new area, namely a KoTextLayoutTableArea.

A KoTextLayoutTableArea holds a KoTextLayoutArea for each of the cells.

Now if a table or paragraph is visible on more than one root area (page) then it is represented by one area for each page. So it is _not_ the same area but a new one that just start where the previous area ended (due to the page break).


How we create a new KoTextLayoutRootArea
----------------------------------------
The KoTextDocumentLayout doesn't just create a new KoTextLayoutRootArea whenever it needs to. First of all it keeps a list of the root areas it already have, and only that number of root ares is too small or large do we add/remove root areas.

The actual adding/removing of areas is done by the abstract class KoTextLayoutRootAreaProvider. It has a simple implementation in the TextShape that can only return one root area and that is it. It corresponds to there only being one textshape.

In Words every KWTextFrameSet has an own KWRootAreaProvider. This way headers, footers and the main text have different providers. The provider can depend on each other to allow layouting in a defined order.

In Calligra Sheets it would also be a simple provider with a root area corresponding to a cell.


Trigging of (re)layout
----------------------
In order to always have an up to date layout of the current QTextDocument we have a system of marking root areas as dirty.
A root area can be marked as dirty in several ways:
 * through KoTextDocumentLayout::documentChanged () which is called by Qt
   - this goes through all the root areas and marks them as dirty as needed
 * when any calls setDirty() on a root area (eg a shape does this when changing
   size og having collisions

When a root area is marked as dirty it asks the KoTextDocumentLayout to emit a signal (layoutIsDirty) which other people can react to. The plain TextShape just connects that signal to KoTextDocumentLayout::scheduleLayout(). This will schedule a layout for later using QTimer::singleShot. If multiple layouts are scheduled they will be compressed to one single layout run.

The KoTextDocumentLayout class provides the two methods layout() and scheduleLayout(). The first allows synchronous and the second asynchronous layouting.

On layouting all root areas are checked if they are dirty. Those who are will be relayouted. If a root area is relayouted then the change may effect other root areas. This will be detected cause every root area keeps information where content started and ended using the FrameIterator class.


FrameIterator and TableIterator
-------------------------------

Iterators are used to mark positions within a QTextDocument. Every root area has a start- and end-iterator that presents a view on a part of the document.

The start-iterator of a root area is the end-iterator of the previous root area.

During layouting every root area becomes dirty and will be relayouted if the start-iterator doesn't match any longer to the end-iterator of the previous root area. This makes it possible to propagate changes within a root area as result of a relayout forward.
